您可以使用 Embedding and Reranking API(可通过MongoDB Atlas获取)访问Voyage AI模型。使用以下方法访问权限API:
REST API: for language-agnostic access.
Python 客户端:官方客户端,易于使用。
TypeScript client: official client for TypeScript and JavaScript applications.
本页概述了如何访问权限API。有关API的完整详细信息,包括速率限制和使用层级,请参阅API参考。
API 密钥
Embedding and Reranking API 使用 API 密钥监控使用情况和管理权限。要创建和管理您的模型 API 密钥,请使用 MongoDB Atlas 用户界面。有关说明,请参阅 管理 Voyage AI 模型 API 密钥。
REST API
以下示例演示如何通过 REST API 调用嵌入服务。API 支持来自任何编程语言的 cURL 和 HTTP 请求。
身份验证是通过模型API密钥处理的,您必须将其作为持有者令牌包含在每个API请求的授权标头中。
To learn more, see the full API specification.
范围终结点
如果您的模型 API 密钥限定于某个地理区域,请将请求发送到该地理区域的终结点,而不是 ai.mongodb.com。请求主体、请求头和响应格式不变。只有托管发生变化。
端点 | 地理 |
|---|---|
| 未限定范围的。Atlas 可以为来自任何地理区域的请求提供服务。 |
| 欧洲 |
| 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 区域。
Python客户端
要使用 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 | 类型 | 必需 | 说明 |
|---|---|---|---|
| 字符串 | No | 模型API密钥。默认为“无”。 如果为“无”,客户端将按以下顺序搜索API密钥:
注意: Python客户端根据API密钥格式自动将请求路由到正确的API终结点:
您可以通过在创建客户端时设置 |
| 整型 | No | 在出现速率限制错误或服务器临时不可用的情况下,每个API请求的最大重试次数。默认为 0。 客户端采用等待并重试策略来处理此类错误,并在达到最大重试限制时引发异常。默认下,客户端不会重试。 |
| 整型 | No | 中止请求之前等待API响应的最长时间(以秒为单位)。默认为“无”。 如果超过指定的超时时间,则请求将终止并引发超时异常。默认下,不实施任何超时约束。 |
| 字符串 | No | API请求的自定义基本URL。默认下,客户端会根据提供的API密钥自动检测正确的终结点。 |
Typescript 客户端
要使用 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}`);
下表描述了在初始化客户端时可以传递的选项:
选项 | 类型 | 必需 | 说明 |
|---|---|---|---|
| 字符串 | 是 | 模型 API 密钥。如果您未设置此选项,客户端将使用 |
| 字符串 | No | API请求的基本URL 。默认为 |
| 数值 | No | 在出现速率限制错误或服务器临时不可用的情况下,每个API请求的最大重试次数。默认为 2。 客户端采用等待并重试策略来处理这类错误,并在达到最大重试限制时抛出异常。 |
| 数值 | No | 中止请求之前等待API响应的最长时间(以秒为单位)。默认为 60。 如果请求超出指定的超时时间,客户端将终止请求并抛出超时异常。 |
| 对象 | No | 随每个 API 请求发送的额外的 HTTP headers。 |
除了 embed 以外,客户端还提供了 rerank、multimodalEmbed 和 contextualizedEmbed 方法。对于模型特定参数,请参阅每个 模型页面 的使用示例。