埋め込みと再ランク付けAPI は、 RESTflu インターフェースを介して最新の Voyage AIの埋め込みと再ランク付けモデルへのプログラムによるアクセスを提供します。このページでは、 APIとその機能の概要を説明します。
詳細情報とパラメーターについては、API仕様を参照してください。
Tip
Embedding and Reranking API へのプロジェクトアクセスを制限する。
Atlas リソース ポリシーを作成して、組織内のすべてのプロジェクトまたは一部のプロジェクトの埋め込みと再ランクAPIへのアクセスを制限できます。詳細については、「 Atlas リソース ポリシー 」を参照してください
APIキーマネジメント
MongoDB Atlasを使用して、 埋め込みおよび再ランクAPIのAPIキーを管理します。これには、組織やプロジェクト全体でモデルAPIキーの作成と管理、使用状況のモニタリング、レート制限の設定が含まれます。
詳細については、モデルAPIキーを参照してください。
注意
Atlas の他のAPIキーと区別するために、モデルAPIキー という名前が付けられています。このキーは、他のモデルプロバイダーのAPIキーと同じ方法で使用します。
認証
埋め込みと再ランク付けAPIへのすべてのリクエストには、 Bearer トークン形式を使用するモデルAPIキーを持つ Authorization ヘッダーを含める必要があります。
Authorization: Bearer VOYAGE_API_KEY
クライアントSDK を使用する場合は、クライアントの構築時にAPIキーを設定し、SDK はすべてのリクエストでユーザーに代わって ヘッダーを送信します。APIと直接統合する場合は、このヘッダーを自分で送信する必要があります。
エンドポイント
注意
パブリック プレビュー
ヨーロッパ地理とそのエンドポイントである eu.ai.mongodb.com は、パブリック プレビュー機能として利用できます。機能および関連するドキュメントは、プレビュー期間中にいつでも変更される可能性があります。
The scope of your model API key determines the endpoint that you send requests to. A key scoped to a Geography works only against that Geography's endpoint, and an unscoped key works against the unscoped endpoint.
エンドポイント | 地理 |
|---|---|
| スコープが設定されていない。 Atlas はどの地域からのリクエストも処理できます。 |
| ヨーロッパ |
| 米国 |
スコープ付きエンドポイントはパターン <geography>.ai.mongodb.com に従います。ここでは、<geography> はリクエストで送信したモデルAPIキーの geography 値です。
If you send a scoped key to an endpoint that doesn't match its scope, the request fails. Atlas doesn't reroute the request to the endpoint that matches the key.
Scoped endpoints differ from the unscoped endpoint in the following ways:
Atlas は、スコープ指定されたエンドポイントに送信するトークンに対して 10% の回収漏れ費用を請求します。
Scoped endpoints require a paid usage tier and start at usage tier 1. To use a higher usage tier with a scoped endpoint, contact your account team. To learn more about usage tiers, see Usage Tiers.
Scoped endpoints have their own rate limits, which are lower than those of the unscoped endpoint. To learn more, see Geography Rate Limits.
Scoped endpoints don't serve every model. To check which endpoints serve a given model, see the Supported Endpoints column of the model tables in Model Deprecations, Lifecycle States, and Support.
To learn what a Geography is and when to use one, see Geographies for Voyage AI Inference.
JSON
すべてのエンティティはJSONで表されます。次のルールと規則が適用されます。
- コンテンツタイプリクエストヘッダー
- POSTリクエストでサーバーにJSONを送信する場合は、
Content-Type: application/jsonヘッダーを指定します。クライアント SDK はこれを自動的に取り扱います。 - 無効なリクエスト
- 無効なJSON、誤ったデータ型、または制約違反（トークン制限やバッチするサイズの超過など）を含むリクエストを作成しようとすると、サーバーは
400ステータス コードと問題を説明するエラー メッセージを返します。 - 数値を含むフィールドのフィールド名
- 数値を含むフィールドには、使用される単位を明確に把握するために名前が付けられます。例、測定単位を明確に示すために、
total_tokensやoutput_dimensionなどのフィールドにトークン数が指定されています。
レート制限と使用量の階層
埋め込みと再ランク付けAPI は、使用状況と最適なパフォーマンスを確保するためにレート制限を実装しています。レート制限はAPIキーごとに適用され、2 次元で測定されます。使用階層が進むにつれて、レート制限は増加します。
TPM（1 分あたりのトークン）: 1 分あたりに処理されるトークンの最大数
RPM（リクエスト 1 分あたり）: 1 分あたりのAPIリクエストの最大数
レート制限を超えると、 API は429（レート制限を超えた） HTTPステータス コードを返します。
支払い方法のない無料試用段階での上限は 3 RPM と 10K TPM です。より高いレート制限を利用するには、 アカウントに支払い方法を追加します 。
モデル | Tokens Per Min (TPM) | 1 分あたりのリクエスト数（RPM） |
|---|---|---|
| 16,000,000 | 2,000 |
| 8,000,000 | 2,000 |
| 3,000,000 | 2,000 |
| 3,000,000 | 2,000 |
| 2,000,000 | 2,000 |
| 4,000,000 | 2,000 |
| 2,000,000 | 2,000 |
使用階層 2 のレート制限は、使用階層 1 の 2 倍です。
モデル | Tokens Per Min (TPM) | 1 分あたりのリクエスト数（RPM） |
|---|---|---|
| 32,000,000 | 4,000 |
| 16,000,000 | 4,000 |
| 6,000,000 | 4,000 |
| 6,000,000 | 4,000 |
| 4,000,000 | 4,000 |
| 8,000,000 | 4,000 |
| 4,000,000 | 4,000 |
使用階層 3 のレート制限は、使用階層 1 の 3 倍です。
モデル | Tokens Per Min (TPM) | 1 分あたりのリクエスト数（RPM） |
|---|---|---|
| 48,000,000 | 6,000 |
| 24,000,000 | 6,000 |
| 9,000,000 | 6,000 |
| 9,000,000 | 6,000 |
| 6,000,000 | 6,000 |
| 12,000,000 | 6,000 |
| 6,000,000 | 6,000 |
使用階層の詳細については、使用階層を参照してください。
組織のカスタム レート制限を設定するには、 Atlas UI を使用します。詳細については、「レート制限の管理」を参照してください。
リクエストの作成
次の例では、 cURL を使用して埋め込みサービスにリクエストを行う方法を示しています。また、任意のプログラミング言語でHTTPクライアントを使用してAPIにアクセスすることもできます。
その他の使用例については、次のリソースを参照してください。
Voyage AIモデルへのアクセスHTTPリクエストとクライアントSDK の例
モデル固有の使用状況のモデルページ。
すべてのAPIエンドポイントの完全な詳細については、 API仕様 を参照してください。
curl \ --request POST 'https://ai.mongodb.com/v1/embeddings' \ --header "Authorization: Bearer $VOYAGE_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "input": [ "MongoDB is redefining what a database is in the AI era.", "Voyage AI embedding and reranking models are state-of-the-art." ], "model": "voyage-4-large" }'
Errors
APIによって返されるエラーの詳細については、API仕様を参照してください。
ベストプラクティス
APIを使用する場合は、次のベストプラクティスを考慮してください。
入力タイプの指定
セマンティック検索と取得のタスクの場合は、Voyage AIモデルがベクトルを作成する方法を最適化するために、input_type を query または document に設定します。このパラメーターを省略しないでください。
パラメーターは、埋め込みを生成する前に次のプロンプトを入力に追加します。
query: "サポート ドキュメントを検索するためのクエリを表します: "document: "検索用のドキュメントを表します: "
例
input_type="query" は、「Apple のテレカンがいつ予定されているか」を変換します。に「サポートドキュメントを取得するためのクエリを表現します。Apple のテレカンはいつ予定されていますか？
トラブルシューティング
Pythonクライアントを使用している場合は、バージョン 0.3.7 以降を使用する必要があります。Pythonクライアントインストールのバージョンを確認するには、ターミナルで次のコマンドを実行します。
python -c "import voyageai; print(voyageai.__version__)"