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参照を参照してください。

埋め込みと再ランク付けAPI は、 APIキーを使用して使用状況を監視し、権限を管理します。モデルAPIキーを作成および管理するには、 MongoDB Atlas UI を使用します。手順については、「 Vyage AIモデルAPIキーの管理 」を参照してください。

次の例は、 REST API経由で埋め込みサービスを呼び出す方法を示しています。 API は、任意のプログラミング言語からの cURL およびHTTPリクエストをサポートします。

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

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

注意

パブリック プレビュー

ヨーロッパ地理とそのエンドポイントである eu.ai.mongodb.com は、パブリック プレビュー機能として利用できます。機能および関連するドキュメントは、プレビュー期間中にいつでも変更される可能性があります。

モデルAPIキーの範囲が地域に限定されている場合は、ai.mongodb.com ではなく、その地理のエンドポイントにリクエストを送信します。リクエスト本文、ヘッダー、応答形式は変更されません。ホストのみが変更されます。

エンドポイント
地理

ai.mongodb.com

スコープが設定されていない。 Atlas はどの地域からのリクエストも処理できます。

eu.ai.mongodb.com

ヨーロッパ

us.ai.mongodb.com

米国

スコープ付きエンドポイントはパターン <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推論の地理的配置 」を参照してください。

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アプリケーションから 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}`);

次の表では、クライアントを初期化するときに渡すことができるオプションについて説明します。

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

apiKey

文字列

はい

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

environment

文字列

No

APIリクエストのベースURL 。デフォルトは、Voageage プラットフォーム エンドポイントである https://api.voyageai.com/v1 になります。埋め込みと再ランクAPIを使用するには、このオプションを https://ai.mongodb.com/v1 に設定します。

maxRetries

番号

No

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

クライアントは、待機して再試行する戦略を使用してこのようなエラーを処理し、最大再試行制限に達すると例外をスローします。

timeoutInSeconds

番号

No

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

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

headers

オブジェクト

No

すべてのAPIリクエストで送信する追加のHTTPヘッダー。

embedに加えて、クライアントはrerankmultimodalEmbedcontextualizedEmbed メソッドを提供します。モデル固有のパラメーターについては、各モデル ページの使用例を参照してください。