Embedding and Reranking API允许通过 RESTful 接口以编程方式访问权限最新的 Voyage AI嵌入和重排名模型。本页概述了API及其功能。
有关详细信息和参数，请参阅API规范。
提示
限制项目对 Embedding and Reranking API 的访问。
You can create an Atlas Resource Policy to restrict access to the Embedding and Reranking API for all or some projects in your organization. To learn more, see Atlas Resource Policies
API密钥管理
您可以使用MongoDB Atlas管理Embedding 和 Reranking API的API密钥。这包括在组织和项目中创建和管理模型API密钥、监控使用情况以及配置速率限制。
要了解更多，请参阅 管理 Voyage AI 模型 API 密钥。
注意
它被命名为模型API密钥，以区别于Atlas中的其他API密钥。使用此密钥的方式与使用其他模型提供商的API密钥的方式相同。
身份验证
对 Embedding and Reranking API 的所有请求都必须包含 Authorization 标头，其中包含使用持有令牌格式的模型API密钥。
Authorization: Bearer VOYAGE_API_KEY
使用客户端SDK 时，您可以在构建客户端时设立API密钥，并且 SDK 会代表您在每个请求中发送标头。当您直接与API集成时，您必须自己发送此标头。
端点
您的模型 API 密钥的范围决定了您向其发送请求的终结点。限定于地理位置的密钥仅适用于该地理位置的终结点，未限定范围的密钥适用于未限定范围的终结点。
端点 | 地理 |
|---|---|
| 未限定范围的。Atlas 可以为来自任何地理区域的请求提供服务。 |
| 欧洲 |
| United States |
范围终结点遵循模式 <geography>.ai.mongodb.com，其中 <geography> 是您随请求发送的模型 API 密钥的 geography 值。
如果您将范围密钥发送到其范围不匹配的终结点，则请求失败。Atlas 不会将请求重新路由到与密钥匹配的终结点。
范围终结点与非范围终结点在以下方面有所不同：
Atlas 对您发送到范围终结点的代币收取 10% 的附加费。
范围终结点需要付费的使用层级，并从使用层级 1 开始。要使用带有范围终结点的更高使用层级，请联系您的帐户团队。要了解有关使用层级的更多信息，请参阅 使用层级。
带范围的终结点有自己的速率限制，低于未带范围的终结点的速率限制。要了解更多，请参阅 地理限制速率。
范围终结点不对所有模型提供服务。要查看哪些终结点为特定模型提供服务，请参阅《模型废弃、生命周期状态和支持》中模型表的“支持的终结点”列。
要了解 Geography 是什么以及何时使用 Geography，请参阅 Voyage AI 推理的 Geography。
JSON
所有实体都以 JSON 表示。以下规则和惯例适用：
- 内容类型请求标头
- 当您通过 POST请求向服务器发送JSON时，请指定
Content-Type: application/json标头。客户端 SDK 会自动处理此问题。 - 无效请求
- 如果您尝试使用无效的JSON、不正确的数据类型或违反约束条件（例如超过令牌限制或批处理大小）创建请求，服务器将以
400状态代码和描述问题的错误消息进行响应。 - 包含数字的字段的字段名称
- 包含数值的字段的命名是为了消除所使用单位的歧义。示例，在
total_tokens和output_dimension等字段中指定词元计数，以明确测量单位。
速率限制和使用层级
Embedding and Reranking API实现速率限制，以确保公平使用和最佳性能。速率限制按API密钥应用，并以两个维度进行衡量。随着您在使用层级中前进，您的速率限制也会增加。
TPM（每分钟令牌数）：每分钟处理的最大令牌数
RPM (每分钟请求数)：每分钟最大API请求数
如果超过速率限制， API会返回 429（已超过速率限制） HTTP状态代码。
不带付款方式的免费试用费率限制为 3 RPM 和 10K TPM。要获得更高的费率限制，请为您的账户添加付款方式。
模型 | Tokens Per Min (TPM) | 每分钟请求数 (RPM) |
|---|---|---|
| 16,000,000 | 2 , 000 |
| 8,000,000 | 2 , 000 |
| 3,000,000 | 2 , 000 |
| 3,000,000 | 2 , 000 |
| 2,000,000 | 2 , 000 |
| 4,000,000 | 2 , 000 |
| 2,000,000 | 2 , 000 |
使用层级 2 的速率限制是使用层级 1 的两倍。
模型 | Tokens Per Min (TPM) | 每分钟请求数 (RPM) |
|---|---|---|
| 32,000,000 | 4 , 000 |
| 16,000,000 | 4 , 000 |
| 6,000,000 | 4 , 000 |
| 6,000,000 | 4 , 000 |
| 4,000,000 | 4 , 000 |
| 8,000,000 | 4 , 000 |
| 4,000,000 | 4 , 000 |
使用层级 3 的速率限制是使用层级 1 的三倍。
模型 | Tokens Per Min (TPM) | 每分钟请求数 (RPM) |
|---|---|---|
| 48,000,000 | 6 , 000 |
| 24,000,000 | 6 , 000 |
| 9,000,000 | 6 , 000 |
| 9,000,000 | 6 , 000 |
| 6,000,000 | 6 , 000 |
| 12,000,000 | 6 , 000 |
| 6,000,000 | 6 , 000 |
要学习；了解有关使用层级的更多信息，请参阅使用层级。
要为组织设立自定义速率限制，请使用Atlas用户界面。要学习；了解更多信息，请参阅管理速率限制。
提出请求
以下示例演示了如何使用 cURL 向嵌入服务发出请求。您还可以使用任何编程语言的HTTP客户端来访问API。
有关其他用法示例，请参阅以下资源：
访问 Voyage AI模型以获取HTTP请求和客户端SDK 示例
API specification，了解所有API终结点的完整详细信息。
curl \ --request POST 'https://ai.mongodb.com/v1/embeddings' \ --header "Authorization: Bearer $VOYAGE_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "input": [ "MongoDB is redefining what a database is in the AI era.", "Voyage AI embedding and reranking models are state-of-the-art." ], "model": "voyage-4-large" }'
Errors
To learn more about errors returned by the API, see the API specification.
最佳实践
使用API时请考虑以下最佳实践：
指定输入类型
对于语义搜索和检索任务，请将 input_type设立为 query 或 document，以优化 Voyage AI模型创建向量的方式。请勿省略此参数。
该参数会在生成嵌入之前将以下提示添加到您的输入中：
query: "Represent 用于检索支持文档的查询："document：“表示要检索的文档：”
例子
input_type="query" 转换“Apple 的会议通话何时安排？”进入“表示检索支持文档的查询：Apple 的电话会议何时安排？”
故障排除
如果您使用的是Python客户端，则必须使用 0.3.7 或更高版本。要检查Python客户端安装的版本，请在终端中运行以下命令：
python -c "import voyageai; print(voyageai.__version__)"