管理 Voyage AI 模型 API 密钥

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

注意

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

创建和管理模型API密钥

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

所需权限

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

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

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

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

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

创建 API 密钥

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

注意

如果您通过 Atlas 创建模型 API 密钥（如以下步骤所述），则该密钥将验证对 ai.mongodb.com 终结点的请求。相反，通过 Voyage AI 直接创建的密钥将验证对 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（连接）。

关键范围

创建模型 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 值。

要了解什么是 Geography 以及何时将密钥范围限定为某个 Geography，请参阅 Voyage AI 推理的 Geography 区域。

在确定密钥范围时，请考虑以下内容：

在创建密钥时，范围是固定的。要使用不同的云或地理区域，删除密钥并创建新密钥。对模型 API 密钥的 PATCH 请求只会更改密钥的名称。
键前缀编码范围。示例，范围为欧洲的密钥以 al-eu- 开头。使用前缀确定密钥的作用域，无需重新创建它。
范围密钥需要付费使用层级。您不能在免费试用期间定义密钥的范围。要了解更多信息，请参阅使用层级。

您在地理信息可用之前创建的模型 API 密钥读取为 cloud=any 和 geography=any。这些密钥对 ai.mongodb.com 持续有效，并且不会被迁移。要使用范围，请创建新密钥。

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

您可以在组织级别配置资源策略，要求创建新模型 API 密钥必须在指定的云、指定的地理区域或两者中进行。为此，添加一条使用 Cedar 编写的 forbid 规则，该规则针对 Embedding and Reranking API 操作。

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

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

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

登录Atlas。

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

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

删除密钥。

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

后续步骤

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

来年

组织和项目访问权限