埋め込みと検索API の概要

APIキーマネジメント

MongoDB Atlasを使用して、 埋め込みおよび再ランクAPIのAPIキーを管理します。これには、組織やプロジェクト全体でモデルAPIキーの作成と管理、使用状況のモニタリング、レート制限の設定が含まれます。

詳細について学ぶには、Voyage AI モデル API キーを管理するを参照してください。

認証

埋め込みと再ランク付けAPIへのすべてのリクエストには、 Bearer トークン形式を使用するモデルAPIキーを持つ Authorization ヘッダーを含める必要があります。

Authorization: Bearer VOYAGE_API_KEY

クライアントSDK を使用する場合は、クライアントの構築時にAPIキーを設定し、SDK はすべてのリクエストでユーザーに代わって ヘッダーを送信します。APIと直接統合する場合は、このヘッダーを自分で送信する必要があります。

エンドポイント

モデル API キーのスコープによって、リクエストを送信するエンドポイントとなる接続されたデバイスが決定されます。地域にスコープされたキーは、その地域のエンドポイントとなる接続されたデバイスに対してのみ機能します。また、スコープされていないキーは、スコープされていないエンドポイントとなる接続されたデバイスに対して機能します。

スコープされたエンドポイントとなる接続されたデバイスは <geography>.ai.mongodb.com のパスワードなしに従います。ここで、<geography> はリクエストとともに送信する model API キーの geography の値です。

スコープと一致しないエンドポイントとなる接続されたデバイスにスコープ付きキーを送信すると、リクエストは失敗します。Atlas は、キーに一致するエンドポイントとなる接続されたデバイスにリクエストを再ルーティングしません。

スコープ付きエンドポイントとなる接続されたデバイスは、スコープなしエンドポイントとなる接続されたデバイスとは次の点で異なります。

• Atlas は、スコープされたエンドポイントとなる接続されたデバイスに送信するトークンに 10% のアップリフトを課します。

• スコープ付きエンドポイントとなる接続されたデバイスには有料の利用階層が必要となります。また、利用階層 1 から開始します。スコープされたエンドポイントとなる接続されたデバイスとともにより高い使用階層を使用するには、アカウントチームにお問い合わせください。学ぶには、使用階層を参照してください。

• スコープ付きのエンドポイントとなる接続されたデバイスには、固有のレート制限があります。これらの制限は、スコープなしのエンドポイントとなる接続されたデバイスのレート制限よりも低くなっています。詳細については、地理的レート制限を参照してください。

• Scoped エンドポイントとなる接続されたデバイスは、すべてのモデルをサポートしません。特定のモデルをサービスするエンドポイントとなる接続されたデバイスを確認するには、モデルの非推奨化、ライフサイクルステータス、およびサポート のモデルテーブルの「サポートされているエンドポイント」列を参照してください。

ジオグラフィーとは何か、いつ使用するかを学ぶには、Voyage AI インフェレンス用ジオグラフィーを参照してください。

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ステータス コードを返します。

使用階層の詳細については、使用階層を参照してください。

組織のカスタム レート制限を設定するには、 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を使用する場合は、次のベストプラクティスを考慮してください。

python -c "import voyageai; print(voyageai.__version__)"