MongoDB Atlasで利用可能な埋め込みと再ランク付けAPIを使用して、Voyage AIモデルにアクセスできます。APIにアクセスするには、次のメソッドを使用します。
REST API: 言語に依存しないアクセス用。
Pythonクライアント: 簡単に使用できる公式クライアント。
Typescript クライアント: Typescript および JavaScript アプリケーション向けの公式クライアントです。
このページでは、 APIにアクセスする方法をまとめます。レート制限や使用階層など、 APIの完全な詳細については、API参照を参照してください。
API キー
Embedding and Reranking API は、API キーを使用して使用状況をモニターし、パーミッションを管理します。モデル API キーを作成および管理するには、MongoDB Atlas UI を使用します。手順については、Voyage AI モデル API キーを管理するを参照してください。
REST API
次の例では、REST API を介して埋め込みサービスを呼び出す方法を示します。API は、どのプログラミング言語からでも cURL と HTTP リクエストに対応しています。
認証はモデルAPIキーを通じて処理されます。このキーは、すべてのAPIリクエストの承認ヘッダーに Bearer トークンとして含める必要があります。
詳しくは、完全なAPI仕様を参照してください。
スコープ制限されたエンドポイントとなる接続されたデバイス
モデル API キーが地域にスコープされている場合は、ai.mongodb.com ではなく、その地域のエンドポイントとなる接続されたデバイスにリクエストを送信します。リクエストボディ、ヘッダー、およびレスポンス形式は変更されません。ホストのみが変更されます。
エンドポイント | 地理 |
|---|---|
| スコープ外。Atlas は、どの地域からのリクエストにも勤めることができます。 |
| ヨーロッパ |
| 米国 |
スコープされたエンドポイントとなる接続されたデバイスは <geography>.ai.mongodb.com のパスワードなしに従います。ここで、<geography> はリクエストとともに送信する model API キーの geography の値です。
前述の例のいずれかを適用するには、リクエスト URL のホストするを置き換えます。たとえば、ヨーロッパにスコープされたキーは、次の URL を使用して埋め込みを生成します。
https://eu.ai.mongodb.com/v1/embeddings
スコープのあるキーは、対応するエンドポイントとなる接続されたデバイスにのみ機能します。ヨーロッパにスコープされたキーを us.ai.mongodb.com または ai.mongodb.com へ送信すると失敗します。
Geography とは何か、およびキーをいつ Geography に関連付けるかを学ぶには、Voyage AI Inference のための Geography を参照してください。
Pythonクライアント
pip を使用して公式のPythonパッケージをインストールする方法
pip install --upgrade voyageai
パッケージの最新バージョンをインストールするには、--upgrade または -U オプションを使用します。これにより、最新の機能やバグ修正にアクセスできるようになります。モデル固有のパラメーターについては、各モデル ページの使用例を参照してください。
重要
Pythonクライアントライブラリのバージョン 0.3.7 以降を使用する必要があります。このバージョンでは、 埋め込みと再ランク付けAPIのサポートが追加されています。
voyageai.Clientクラスは、Vorage の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)にリクエストを送信します。モデルAPIキーでEmbedding and Reranking 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}`);
次の表には、クライアントを初期化する際に渡すことができるオプションが記述されています。
オプション | タイプ | 必須 | 説明 |
|---|---|---|---|
| 文字列 | はい | モデル APIキー。このオプションを設定しない場合、クライアントは |
| 文字列 | No | APIリクエストのベースURL。デフォルトはVoyageプラットフォームのエンドポイントとなる接続されたデバイスである |
| 番号 | No | レート制限エラーまたは一時サーバーが使用できない場合の、各APIリクエストの最大再試行回数。デフォルトは 2 です。 クライアントは、このようなエラーを取り扱うために待機再試行戦略を採用しており、最大再試行回数に達すると例外をスローします。 |
| 番号 | No | リクエストを中止する前にAPIからの応答を待機する最大時間(秒)。デフォルトは 60 です。 リクエストが指定されたタイムアウトを超過した場合、クライアントはリクエストを終了し、タイムアウト例外をスローします。 |
| オブジェクト | No | すべての API リクエストで送信する余計 HTTP headers。 |
embed に加えて、クライアントにはrerank、multimodalEmbed、およびcontextualizedEmbed メソッドがあります。モデル固有のパラメータについては、各モデル ページの使用例を参照してください。