Managed Inference and Agents API の /v1/embeddings

Table of Contents [expand]

リクエストボディパラメータ
リクエストヘッダー
応答形式
リクエストの例
応答の例

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2025年09月04日(木)

/v1/embeddings エンドポイントは、提供された一連の入力テキストに対するベクトル埋め込み (基本的には数字のリスト) を生成します。これらの埋め込みは、検索、分類、クラスタリングなどのさまざまなユースケースに合わせて最適化されます。入力の処理方法をカスタマイズし、ニーズに合わせてさまざまな埋め込みタイプを選択できます。

リクエストボディパラメータ

必須パラメータ

フィールド	型	説明	例
model	文字列	使用する埋め込みモデルの ID	`"cohere-embed-multilingual"`
input	配列	モデルが埋め込む単一の文字列または文字列の配列最大: `96` 文字列、それぞれ `2048` 文字推奨: 長さは文字列あたり `512` トークン未満	`["example string 1", "example string 2"]`

任意のパラメータ

フィールド	型	説明	デフォルト	例
input_type	列挙<文字列>	モデルに渡される入力の種類を指定します (入力に特別なトークンを付加)。次のいずれか: `search_document`、`search_query`、`classification`、 `clustering`	`"search_document"`	`"search_query"`
encoding_format	列挙<文字列>	出力のエンコード形式を決定します。次のいずれか: `raw` または `base64`	`"raw"`	`"base64"`
embedding_type	列挙<文字列>	返される埋め込みの種類を指定します (`float`、`int8`、`uint8`、`binary`、`ubinary`)	`"float"`	`"int8"`
allow_ignored_params	ブール値	エラーをスローする代わりに、リクエスト内のサポートされていないパラメータを無視します	`false`	`true`

リクエストヘッダー

次の例では、モデルリソースに "EMBEDDING" のエイリアスがあると仮定します (これは、--as EMBEDDING フラグを使用してモデルリソースを作成したことを意味します)。

ヘッダー	型	説明
`Authorization`	文字列	AI アドオンの ‘EMBEDDING_KEY’ の値 (API ベアラートークン)

推論の curl リクエストには、指定されたモデルの Heroku 推論キーを含む Authorization ヘッダーを含める必要があります。

応答形式

リクエストが成功すると、API は次の構造で JSON オブジェクトを返します。

フィールド	型	説明
object	文字列	応答の外部構造常に `"list"`
data	オブジェクトの配列	生成される埋め込みのリスト (入力ごとに 1 つ)
model	文字列	埋め込みを生成したモデルの ID
usage	オブジェクト	トークンの使用量に関するメタデータ (`prompt_tokens`、`total_tokens`)

埋め込みオブジェクト

data 配列内の各オブジェクトには以下が含まれます。

フィールド	型	説明
object	文字列	オブジェクトの種別常に `"embedding"`
index	整数	この埋め込みに対応する入力文字列のインデックス (0 から開始)
embedding	配列または文字列	埋め込みベクトル (`embedding_type` 型)

リクエストの例

/v1/embeddings curl リクエストの例を見てみましょう。

まず、このコマンドを使用して、Heroku 環境変数をローカル変数として設定します。

eval $(heroku config -a $APP_NAME --shell | grep '^EMBEDDING_' | sed 's/^/export /' | tee >(cat >&2))

次に、curl リクエストを送信します。

curl $EMBEDDING_URL/v1/embeddings \
 -H "Authorization: Bearer $EMBEDDING_KEY" \
 -d @- <<EOF
{
  "model": "$EMBEDDING_MODEL_ID",
  "input": "Hello, I am a long string (document) and I want to be turned into a searchable embedding vector! What fun!"
}
EOF

応答の例

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.014755249,
                0.017410278,
                ...
                -0.041992188,
                0.006137848
            ]
        }
    ],
    "model": "cohere-embed-multilingual",
    "usage": {
        "prompt_tokens": 29,
        "total_tokens": 29
    }
}

Categories