您可以使用 Embedding and Reranking API(可通过MongoDB Atlas获取)访问Voyage AI模型。使用以下方法访问权限API:
REST API:用于与语言无关的访问权限。
Python 客户端:官方客户端,易于使用。
本页概述了如何访问权限API。有关API的完整详细信息,包括速率限制和使用层级,请参阅API参考。
API 密钥
Embedding and Reranking API使用API密钥来监控使用情况和管理权限。要创建和管理模型API密钥,请使用MongoDB Atlas用户界面。有关说明,请参阅管理 Voyage AI模型API密钥。
REST API
以下示例演示了如何通过REST API调用嵌入服务。该API支持来自任何编程语言的cURL 和HTTP请求。
身份验证是通过模型API密钥处理的,您必须将其作为持有者令牌包含在每个API请求的授权标头中。
要学习;了解更多信息,请参阅完整的API规范。
限定范围的端点
注意
公开预览版
欧洲地理位置及其端点 eu.ai.mongodb.com 作为公开预览功能提供。在预览期间,功能和相应的文档可能随时更改。
如果您的模型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 发送欧洲范围的密钥失败。
要学习;了解什么是地理位置以及何时将键的范围限定为一个,请参阅用于 Voyage AI推断的地理位置。
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模型。
与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}`);
下表描述了初始化客户端时可以传递的选项:
选项 | 类型 | 必需 | 说明 |
|---|---|---|---|
| 字符串 | 是 | |
| 字符串 | No | API请求的基本URL 。默认为 |
| 数值 | No | 在出现速率限制错误或服务器临时不可用的情况下,每个API请求的最大重试次数。默认为 2。 客户端采用等待并重试策略来处理此类错误,并在达到最大重试限制时引发异常。 |
| 数值 | No | 中止请求之前等待API响应的最长时间(以秒为单位)。默认为 60。 如果请求超过指定的超时时间,客户端将终止请求并抛出超时异常。 |
| 对象 | No | 随每个API请求发送的额外HTTP 头部。 |
除embed 外,客户端还提供rerank 、multimodalEmbed 和contextualizedEmbed 方法。有关特定于模型的参数,请参阅每个模型页面的用法示例。