对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单

访问 Voyage AI模型

您可以使用 Embedding and Reranking API(可通过MongoDB Atlas获取)访问Voyage AI模型。使用以下方法访问权限API:

  • REST API:用于与语言无关的访问权限。

  • Python 客户端:官方客户端,易于使用。

  • TypeScript客户端:TypeScript 和JavaScript应用程序的官方客户端。

本页概述了如何访问权限API。有关API的完整详细信息,包括速率限制和使用层级,请参阅API参考。

Embedding and Reranking API使用API密钥来监控使用情况和管理权限。要创建和管理模型API密钥,请使用MongoDB Atlas用户界面。有关说明,请参阅管理 Voyage AI模型API密钥。

以下示例演示了如何通过REST API调用嵌入服务。该API支持来自任何编程语言的cURL 和HTTP请求。

身份验证是通过模型API密钥处理的,您必须将其作为持有者令牌包含在每个API请求的授权标头中。

要学习;了解更多信息,请参阅完整的API规范。

注意

公开预览版

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

如果您的模型API密钥的作用域为某个地理位置,请将请求发送到该地理位置的端点,而不是 ai.mongodb.com。请求正文、标头和响应格式保持不变。仅托管发生变化。

端点
地理

ai.mongodb.com

未指定作用域。 Atlas提供服务来自任何地理位置的请求。

eu.ai.mongodb.com

欧洲

us.ai.mongodb.com

United States

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

要调整前面的任何示例,请替换请求URL中的托管。示例,作用域为欧洲的键使用以下URL生成嵌入:

https://eu.ai.mongodb.com/v1/embeddings

限定作用域的键仅适用于其匹配的端点。向 us.ai.mongodb.comai.mongodb.com 发送欧洲范围的密钥失败。

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

要使用 pip 安装官方Python包:

pip install --upgrade voyageai

使用 --upgrade-U 选项安装最新版本的包。这使您访问权限最新的功能和错误修复。有关特定于模型的参数,请参阅每个模型页面的用法示例。

重要

您必须使用 0.3.7 或更高版本的Python客户端库。此版本增加了对嵌入和重新排名API的支持。

voyageai.Client 类提供了一个同步接口来调用 Voyage 的API。创建客户端对象并使用它来访问权限Voyage AI模型。

例子

以下示例展示了如何使用自定义设置初始化客户端并生成嵌入:

import voyageai
# Initialize the client with custom settings
vo = voyageai.Client(
api_key="<model-api-key>", # Or use VOYAGE_API_KEY environment variable
max_retries=3, # Retry up to 3 times on rate limit errors
timeout=30 # Timeout after 30 seconds
)
# Generate embeddings
result = vo.embed(
texts=["MongoDB is redefining what a database is in the AI era."],
model="voyage-4-large"
)
print(f"Embedding dimension: {len(result.embeddings[0])}")
print(f"Total tokens used: {result.total_tokens}")

下表描述了初始化客户端时可以传递的参数:

Parameter
类型
必需
说明

api_key

字符串

No

模型API密钥。默认为“无”。

如果为“无”,客户端将按以下顺序搜索API密钥:

  • voyageai.api_key_path,包含密钥的文件路径

  • 环境变量 VOYAGE_API_KEY_PATH,可设立为包含密钥的文件的路径

  • voyageai.api_key,这是 voyageai 模块的一个属性,可用于存储密钥

  • 环境变量 VOYAGE_API_KEY

注意: Python客户端根据API密钥格式自动将请求路由到正确的API终结点:

  • 在MongoDB Atlas中创建的模型API密钥会路由到 ai.mongodb.com 终结点。

  • 作用域为某个地理位置的模型API密钥会路由到该地理位置的端点,例如 eu.ai.mongodb.com

  • 在 Voyage 平台上创建的API密钥会路由到 api.voyageai.com 终结点。

您可以通过在创建客户端时设置 base_url 参数来覆盖此行为。

max_retries

整型

No

在出现速率限制错误或服务器临时不可用的情况下,每个API请求的最大重试次数。默认为 0。

客户端采用等待并重试策略来处理此类错误,并在达到最大重试限制时引发异常。默认下,客户端不会重试。

timeout

整型

No

中止请求之前等待API响应的最长时间(以秒为单位)。默认为“无”。

如果超过指定的超时时间,则请求将终止并引发超时异常。默认下,不实施任何超时约束。

base_url

字符串

No

API请求的自定义基本URL。默认下,客户端会根据提供的API密钥自动检测正确的终结点。

要使用 npm 安装官方 TypeScript包:

npm install voyageai

VoyageAIClient 类提供了一个异步接口,用于从 TypeScript 和JavaScript应用程序调用 Voyage 的API 。创建客户端对象并使用它来访问权限Voyage AI模型。

与Python客户端不同,TypeScript客户端默认向 Voyage 平台端点 ()https://api.voyageai.com/v1 发送请求。要将 Embedding and Reranking API与模型API密钥结合使用,请在创建客户端时将 environment选项设立为https://ai.mongodb.com/v1

例子

以下示例展示了如何初始化 Embedding and Reranking API的客户端并生成嵌入:

import { VoyageAIClient } from "voyageai";
// Initialize the client for the Embedding and Reranking API
const client = new VoyageAIClient({
apiKey: process.env.VOYAGE_API_KEY, // Model API key
environment: "https://ai.mongodb.com/v1",
maxRetries: 3, // Retry up to 3 times
timeoutInSeconds: 30 // Time out after 30 seconds
});
// Generate embeddings
const result = await client.embed({
input: ["MongoDB is redefining what a database is in the AI era."],
model: "voyage-4-large"
});
console.log(`Embedding dimension: ${result.data[0].embedding.length}`);
console.log(`Total tokens used: ${result.usage.totalTokens}`);

下表描述了初始化客户端时可以传递的选项:

选项
类型
必需
说明

apiKey

字符串

模型API密钥。如果不设立此选项,客户端将使用VOYAGE_API_KEY 环境变量。

environment

字符串

No

API请求的基本URL 。默认为 https://api.voyageai.com/v1,即 Voyage 平台端点。将此选项设置为 https://ai.mongodb.com/v1 可使用 Embedding and Reranking API。

maxRetries

数值

No

在出现速率限制错误或服务器临时不可用的情况下,每个API请求的最大重试次数。默认为 2。

客户端采用等待并重试策略来处理此类错误,并在达到最大重试限制时引发异常。

timeoutInSeconds

数值

No

中止请求之前等待API响应的最长时间(以秒为单位)。默认为 60。

如果请求超过指定的超时时间,客户端将终止请求并抛出超时异常。

headers

对象

No

随每个API请求发送的额外HTTP 头部。

embed 外,客户端还提供rerankmultimodalEmbedcontextualizedEmbed 方法。有关特定于模型的参数,请参阅每个模型页面的用法示例。