MongoDB Atlasで利用可能な埋め込みと再ランク付けAPIを使用して、Voyage AIモデルにアクセスできます。APIにアクセスするには、次のメソッドを使用します。
REST API: 言語に依存しないアクセス用。
Pythonクライアント: 簡単に使用できる公式クライアント。
TypeScriptクライアント: TypeScript およびJavaScriptアプリケーション用の公式クライアント。
このページでは、 APIにアクセスする方法をまとめます。レート制限や使用階層など、 APIの完全な詳細については、API参照を参照してください。
API キー
埋め込みと再ランク付けAPI は、 APIキーを使用して使用状況を監視し、権限を管理します。モデルAPIキーを作成および管理するには、 MongoDB Atlas UI を使用します。手順については、「 Vyage AIモデルAPIキーの管理 」を参照してください。
REST API
次の例は、 REST API経由で埋め込みサービスを呼び出す方法を示しています。 API は、任意のプログラミング言語からの cURL およびHTTPリクエストをサポートします。
認証はモデルAPIキーを通じて処理されます。このキーは、すべてのAPIリクエストの承認ヘッダーに Bearer トークンとして含める必要があります。
詳しくは、完全なAPI仕様を参照してください。
スコープ付きエンドポイント
注意
パブリック プレビュー
ヨーロッパ地理とそのエンドポイントである eu.ai.mongodb.com は、パブリック プレビュー機能として利用できます。機能および関連するドキュメントは、プレビュー期間中にいつでも変更される可能性があります。
モデルAPIキーの範囲が地域に限定されている場合は、ai.mongodb.com ではなく、その地理のエンドポイントにリクエストを送信します。リクエスト本文、ヘッダー、応答形式は変更されません。ホストのみが変更されます。
エンドポイント | 地理 |
|---|---|
| スコープが設定されていない。 Atlas はどの地域からのリクエストも処理できます。 |
| ヨーロッパ |
| 米国 |
スコープ付きエンドポイントはパターン <geography>.ai.mongodb.com に従います。ここでは、<geography> はリクエストで送信したモデルAPIキーの geography 値です。
前述の例のいずれかを調整するには、リクエストURLのホストを置き換えます。例、ヨーロッパにスコープが設定されたキーは、次のURLを使用して埋め込みを生成します。
https://eu.ai.mongodb.com/v1/embeddings
スコープ指定されたキーは、一致するエンドポイントに対してのみ機能します。ヨーロッパ スコープのキーを us.ai.mongodb.com または ai.mongodb.com に送信すると失敗します。
地理とはどのようなものであり、キーのスコープを 1 に設定するタイミングについては、「 投票AI推論の地理的配置 」を参照してください。
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アプリケーションから Vyage のAPIを呼び出すための非同期インターフェースを提供します。クライアントオブジェクトを作成し、それを使用して Vyage AIモデルにアクセスします。
Pythonクライアントとは異なり、TypeScriptクライアントはデフォルトで リクエストを Vyage プラットフォーム エンドポイント(https://api.voyageai.com/v1 )に送信します。モデルAPIキーで埋め込みと再ランクAPIを使用するには、クライアントを作成する ときに、 environmenthttps://ai.mongodb.com/v1オプションを に設定します。
例
次の例は、埋め込みと再ランク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 。デフォルトは、Voageage プラットフォーム エンドポイントである |
| 番号 | No | レート制限エラーまたは一時サーバーが使用できない場合の、各APIリクエストの最大再試行回数。デフォルトは 2 です。 クライアントは、待機して再試行する戦略を使用してこのようなエラーを処理し、最大再試行制限に達すると例外をスローします。 |
| 番号 | No | リクエストを中止する前に、 APIからの応答を待つ最大時間(秒)。デフォルトは 60 です。 リクエストが指定されたタイムアウトを超えた場合、クライアントはリクエストを終了し、タイムアウトの例外をスローします。 |
| オブジェクト | No | すべてのAPIリクエストで送信する追加のHTTPヘッダー。 |
embedに加えて、クライアントはrerank 、multimodalEmbed 、contextualizedEmbed メソッドを提供します。モデル固有のパラメーターについては、各モデル ページの使用例を参照してください。