AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。
Docs Menu

Voyage AIモデルへのアクセス

MongoDB Atlasで利用可能な埋め込みと再ランク付けAPIを使用して、Voyage AIモデルにアクセスできます。APIにアクセスするには、次のメソッドを使用します。

このページでは、 APIにアクセスする方法をまとめます。レート制限や使用階層など、 APIの完全な詳細については、API参照を参照してください。

Embedding and Reranking API は、API キーを使用して使用状況をモニターし、パーミッションを管理します。モデル API キーを作成および管理するには、MongoDB Atlas UI を使用します。手順については、Voyage AI モデル API キーを管理するを参照してください。

次の例では、REST API を介して埋め込みサービスを呼び出す方法を示します。API は、どのプログラミング言語からでも cURL と HTTP リクエストに対応しています。

認証はモデルAPIキーを通じて処理されます。このキーは、すべてのAPIリクエストの承認ヘッダーに Bearer トークンとして含める必要があります。

詳しくは、完全なAPI仕様を参照してください。

言語

モデル API キーが地域にスコープされている場合は、ai.mongodb.com ではなく、その地域のエンドポイントとなる接続されたデバイスにリクエストを送信します。リクエストボディ、ヘッダー、およびレスポンス形式は変更されません。ホストのみが変更されます。

エンドポイント
地理

ai.mongodb.com

スコープ外。Atlas は、どの地域からのリクエストにも勤めることができます。

eu.ai.mongodb.com

ヨーロッパ

us.ai.mongodb.com

米国

スコープされたエンドポイントとなる接続されたデバイスは <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 を参照してください。

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
タイプ
必須
説明

api_key

文字列

No

モデルAPIキー。デフォルトはなし。

指定しない場合、クライアントは次の順序でAPIキーを検索します。

  • voyageai.api_key_path、キーを含むファイルへのパス

  • 環境変数 VOYAGE_API_KEY_PATH。これは、次のキーを含むファイルへのパスに設定できます:

  • voyageai.api_key、 mongoDB モジュールの属性で、キーを保存するために使用できます

  • 環境変数 VOYAGE_API_KEY

注: Pythonクライアントは、 APIキー形式に基づいて正しいAPIエンドポイントとなる接続されたデバイスにリクエストを自動的にルーティングします。

  • MongoDB Atlasで作成されたモデルAPIキーは、ai.mongodb.com エンドポイントにルーティングされます。

  • モデル API キーが 地域にスコープされている場合、その地域のエンドポイントにルーティングされます。例えば eu.ai.mongodb.com です。

  • Vyage プラットフォームで作成された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モデルにアクセスします。

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}`);

次の表には、クライアントを初期化する際に渡すことができるオプションが記述されています。

オプション
タイプ
必須
説明

apiKey

文字列

はい

モデル APIキー。このオプションを設定しない場合、クライアントは VOYAGE_API_KEY 環境変数を使用します。

environment

文字列

No

APIリクエストのベースURL。デフォルトはVoyageプラットフォームのエンドポイントとなる接続されたデバイスであるhttps://api.voyageai.com/v1です。Embedding and Reranking APIを使用するには、このオプションをhttps://ai.mongodb.com/v1に設定します。

maxRetries

番号

No

レート制限エラーまたは一時サーバーが使用できない場合の、各APIリクエストの最大再試行回数。デフォルトは 2 です。

クライアントは、このようなエラーを取り扱うために待機再試行戦略を採用しており、最大再試行回数に達すると例外をスローします。

timeoutInSeconds

番号

No

リクエストを中止する前にAPIからの応答を待機する最大時間(秒)。デフォルトは 60 です。

リクエストが指定されたタイムアウトを超過した場合、クライアントはリクエストを終了し、タイムアウト例外をスローします。

headers

オブジェクト

No

すべての API リクエストで送信する余計 HTTP headers。

embed に加えて、クライアントにはrerank、multimodalEmbed、およびcontextualizedEmbed メソッドがあります。モデル固有のパラメータについては、各モデル ページの使用例を参照してください。