管理 Voyage AI模型API密钥

模型API密钥提供服务Embedding 和 Reranking API的身份验证和授权机制，启用您能够通过API访问权限Voyage AI模型。本页介绍如何在Atlas用户界面中创建和管理API密钥。

注意

它被命名为模型API密钥，以区别于Atlas中的其他API密钥。使用此密钥的方式与使用其他模型提供商的API密钥的方式相同。

创建和管理模型API密钥

您可以从Atlas用户界面中的组织和项目级别创建和管理模型API密钥。速率限制应用于API密钥，具体取决于您是在组织还是项目级别创建的。

所需权限

要创建、更新和删除模型API密钥，请执行以下操作：

在组织级别，您必须拥有Organization Owner访问权限。
在项目级别，您必须拥有对Atlas的Project Model Owner、Project Owner或更高访问权限。

要查看模型API密钥，请执行以下操作：

在组织和项目级别，您必须对Atlas拥有 Organization Read Only 或更高访问权限。
仅在项目级别，您必须对Atlas具有 Project Read Only 或更高访问权限。

有关每个角色权限的完整列表，请参阅组织和项目访问权限。

创建 API 密钥

在组织级别创建模型API密钥时，请将密钥链接到项目。创建密钥后，您无法更改密钥链接到的项目。速率限制应用于项目中的每个键。

注意

如果您通过Atlas创建模型API密钥（如以下过程所述），则该密钥将对发送至 ai.mongodb.com 端点的请求进行身份验证。相反，如果您直接通过 VoyageAI 创建密钥，则该密钥将对 https://api.voyageai.com/v1/embeddings 的请求进行身份验证。

您还可以在创建密钥时设立密钥的作用域。要学习；了解更多信息，请参阅 Key Scope。

要在组织级别创建模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
在组织级别，单击导航栏 Services 标题下的 Model API Keys。

创建模型API密钥。

单击 Create new model API key（连接）。
输入密钥的名称。
模型API密钥不能超过 250 个字符。
从下拉列表中选择一个项目以与API密钥链接。
从 Cloud provider 下拉列表中选择云提供商。
选择 any 以保留未确定范围的云维度。
可选。从 Geography 下拉列表中选择地理位置。
大多数键不需要地理位置。选择 any 以保留地理维度的范围。
Atlas显示所选范围的只读 API Endpoint。该密钥针对此端点进行身份验证。
单击 Create（连接）。

保存API密钥。

复制模型API密钥并将其存储在安全位置。
离开显示密钥的页面后，将无法再次查看。如果丢失，请创建一个新的。
单击 Done（连接）。

要在项目级别创建模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
在项目级别，单击导航栏 Services 标题下的 AI Model APIs。

创建模型API密钥。

如果尚未显示，请从导航栏中选择 Model API Keys。
单击 Create model API key（连接）。
输入密钥的名称。
模型API密钥不能超过 250 个字符。
从 Cloud provider 下拉列表中选择云提供商。
选择 any 以保留未确定范围的云维度。
可选。从 Geography 下拉列表中选择地理位置。
大多数键不需要地理位置。选择 any 以保留地理维度的范围。
Atlas显示所选范围的只读 API Endpoint。该密钥针对此端点进行身份验证。
单击 Create（连接）。

保存API密钥。

复制模型API密钥并将其存储在安全位置。
离开显示密钥的页面后，将无法再次查看。如果丢失，请创建一个新的。
单击 Done（连接）。

键范围

注意

公开预览版

欧洲地理位置及其端点 eu.ai.mongodb.com 作为公开预览功能提供。在预览期间，功能和相应的文档可能随时更改。

创建模型API密钥时，您需要提供一个 cloud 和一个 geography。它们共同设立了密钥的作用域，从而确定了密钥进行身份验证所针对的端点。

将任一值设置为 any 以使该维度保持无作用域。 cloud 和 geography 均设立为 any 的键是无作用域键，对 ai.mongodb.com 起作用。

端点	地理
`ai.mongodb.com`	未指定作用域。 Atlas提供服务来自任何地理位置的请求。
`eu.ai.mongodb.com`	欧洲
`us.ai.mongodb.com`	United States

限定范围的端点遵循 <geography>.ai.mongodb.com模式，其中 <geography> 是您随请求发送的模型API密钥的 geography 值。

要学习；了解什么是地理位置以及何时将键的范围限定为一个，请参阅用于 Voyage AI推断的地理位置。

确定键的范围时，请考虑以下事项：

创建密钥时，范围是固定的。要使用其他云或地理位置，删除该密钥并创建一个新密钥。对模型API密钥的 PATCH请求仅更改密钥的名称。
键前缀对范围进行编码。示例，作用域为欧洲的键以 al-eu- 开头。使用前缀来标识密钥的作用域，而无需重新创建密钥。
限定作用域的密钥需要付费使用层级。您无法在免费试用版中确定密钥的范围。要学习；了解更多信息，请参阅使用层级。

在地理位置可用之前创建的模型API密钥读取为 cloud=any 和 geography=any。这些密钥在 ai.mongodb.com 后继续有效，不会迁移。要使用作用域，请创建一个新密钥。

使用资源策略限制模型API密钥范围

您可以在组织级别配置资源策略，要求在给定的云、给定的地理位置或两者中创建新模型API密钥。为此，添加一条用 Cedar 编写的针对嵌入和重新排名API动作的forbid 规则。

该策略管理密钥创建。它不限制使用现有密钥的位置。如果配置此策略，则用户将无法在允许的范围之外创建密钥。但是，该策略不会撤销已存在的密钥或重新调整其范围。这些密钥继续有效。要删除早于该策略的密钥，请参阅删除API密钥。

您可以使用 forbid 规则中的 unless 子句来允许特定范围。

示例：限制模型API密钥范围（但不包括例外）

forbid (principal, action == ResourcePolicy::Action::"project.aiModelAPI.modify", resource) unless { <exception> };

要将键限制为某个地理位置，请在 unless 子句中使用 context.aiModelApi.geography 属性。以下策略允许用户仅为欧洲地理位置创建模型API密钥：

示例：将模型API密钥限制为欧洲地理区域

forbid (principal, action == ResourcePolicy::Action::"project.aiModelAPI.modify", resource) unless { context.aiModelApi.geography == ResourcePolicy::Geography::"eu" };

要学习；了解有关设置资源策略的更多信息，请参阅Atlas资源策略概述。

查看API密钥

组织所有者可以查看和编辑组织级别的所有模型API密钥。项目所有者只能查看和编辑他们有权访问权限的项目的模型API密钥。

要在组织级别查看模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
在组织级别，单击导航栏 Services 标题下的 Model API Keys。

对于每个模型 API 密钥，该页面显示以下内容：

列名称	列值说明
Name	模型 API 密钥的名称。
Secret Key	与模型 API 密钥名称关联的编辑模型 API 密钥。
Created On (UTC)	用户创建模型 API 密钥的 UTC 日期。
Last Used (UTC)	模型 API 密钥上次使用的 UTC 日期。如果密钥是新密钥或从未使用，则值为 `Never`。
Project	与模型 API 密钥链接的项目名称。
Created By	创建密钥的用户名。
Actions	可以对密钥采取的操作。您可以单击：编辑模型 API 密钥。删除模型 API 密钥。

要在项目级别查看模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
在项目级别，单击导航栏 Services 标题下的 AI Model APIs。

对于每个模型 API 密钥，页面会显示有关该密钥的以下信息：

列名称	列值说明
Name	模型 API 密钥的名称。
Secret Key	与模型 API 密钥名称关联的编辑模型 API 密钥。
Created On (UTC)	用户创建模型 API 密钥的 UTC 日期。
Last Used (UTC)	模型 API 密钥上次使用的 UTC 日期。如果密钥是新密钥或从未使用，则值为 `Never`。
Project	与模型 API 密钥链接的项目名称。
Created By	创建密钥的用户名。
Actions	可以对密钥采取的操作。您可以单击：编辑模型 API 密钥。删除模型 API 密钥。

编辑API密钥

要在组织级别编辑模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
在组织级别，单击导航栏 Services 标题下的 Model API Keys。

编辑密钥。

在 Actions 列中，单击与要编辑的密钥相对应的按钮。
在 Edit Model API Key 页面中，修改模型API密钥的名称。
模型API密钥名称对于项目必须是唯一的，长度最多为 250 个字符。
单击 Save（保存）以应用更改。

要在项目级别编辑模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
在项目级别，单击导航栏 Services 标题下的 AI Model APIs。

编辑密钥。

在 Actions 列中，单击与要编辑的密钥相对应的按钮。
在 Edit Model API Key 页面中，修改模型API密钥的名称。
该名称在项目中必须是唯一的，长度最多为 250 个字符。
单击 Save（保存）以应用更改。

删除 API 密钥。

删除模型API密钥时， MongoDB会立即禁用该密钥并拒绝使用已删除密钥发出的任何API请求。删除密钥后，您将无法查看、恢复或修改它。

要在组织级别删除模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
在组织级别，单击导航栏 Services 标题下的 Model API Keys。

删除密钥。

在 Actions 列中，单击与要删除的密钥对应的按钮。
在确认模式中，单击 Delete key 以删除密钥。

要在项目级别删除模型API密钥，请完成以下步骤：

登录Atlas。

Go Atlas用户界面中的 AI Model APIs 页面。

如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
在项目级别，单击导航栏 Services 标题下的 AI Model APIs。

删除密钥。

在 Actions 列中，单击与要删除的密钥对应的按钮。
在确认模式中，单击 Delete key 以删除密钥。

后续步骤

创建模型API密钥后，您可以：

来年

组织和项目访问权限