Embedding and Reranking API允许通过 RESTful 接口以编程方式访问权限最新的 Voyage AI嵌入和重排名模型。本页概述了API及其功能。
有关详细信息和参数，请参阅API规范。
API密钥管理
您可以使用MongoDB Atlas管理Embedding 和 Reranking API的API密钥。这包括在组织和项目中创建和管理模型API密钥、监控使用情况以及配置速率限制。
要学习；了解详情，请参阅 模型API密钥。
注意
它被命名为模型API密钥，以区别于Atlas中的其他API密钥。使用此密钥的方式与使用其他模型提供商的API密钥的方式相同。
身份验证
对 Embedding and Reranking API 的所有请求都必须包含 Authorization 标头，其中包含使用持有令牌格式的模型API密钥。
Authorization: Bearer VOYAGE_API_KEY
使用客户端SDK 时，您可以在构建客户端时设立API密钥，并且 SDK 会代表您在每个请求中发送标头。当您直接与API集成时，您必须自己发送此标头。
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
要学习；了解有关API返回的错误的更多信息，请参阅API规范。
最佳实践
使用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__)"