埋め込みと検索API の概要

APIキーマネジメント

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

詳しくは、モデルAPIキーを参照してください。

認証

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

Authorization: Bearer VOYAGE_API_KEY

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

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__)"