对于 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:

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

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

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

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

To learn more, see the full API specification.

如果您的模型 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.com 或 ai.mongodb.com 失败。

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

要使用 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模型。

Unlike the Python client, the TypeScript client sends requests to the Voyage platform endpoint (https://api.voyageai.com/v1) by default. To use the Embedding and Reranking API with your model API key, set the environment option to https://ai.mongodb.com/v1 when you create the client.

例子

以下示例展示了如何初始化 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 headers。

除了 embed 以外,客户端还提供了 rerank、multimodalEmbed 和 contextualizedEmbed 方法。对于模型特定参数,请参阅每个 模型页面 的使用示例。