Embeddings API

テキストを入力として、その意味を表現するベクトルを生成するAPIです。文章の意味検索、類似度判定、クラスタリング、RAGシステムの構築などに利用します。

API キーによる認証方法、エラーレスポンスの仕様ははじめに、レート制限の詳細はレート制限をあわせてご確認ください。

エンドポイント

POST https://api.sarashina.ai/v1/embeddings

サポートモデル

sarashina3-embedding

リクエストパラメータ

以下に定義されていないパラメータは無視されます。範囲外、サポート外の値を指定した場合、APIは 400 Bad Request を返却します。

パラメータ	型	デフォルト	必須	説明
`input`	string	–	✅	ベクトル化されるテキスト。内部のトークナイザーで8,000トークンまで入力可能です。8,000トークンを超える入力は 400 Bad Request となります。入力のトークン数は、レスポンスの `usage.prompt_tokens` で確認できます。なお、1リクエストで指定できるのは1テキストのみです（配列による一括指定はサポートしていません）。複数のテキストを処理する場合はリクエストを分けてください。
`task_type`	string	–	✅	次の Task Type の説明を参照してください。省略した場合、またはサポート外の値を指定した場合は 400 Bad Request（`task_type is invalid`）となります。
`model`	string	–	✅	使用するモデル名 (例: `sarashina3-embedding`)
`encoding_format`	string	`float`	–	指定しても無視され、常に float の数値配列が返却されます（`base64` 形式での返却はサポートしていません）。

Task Type

以下のいずれかの task type を指定することができます。利用用途に最適な task type を指定してください。検索（RAG など）で利用する場合、クエリ側（RETRIEVAL_QUERY / QUESTION_ANSWERING / FACT_VERIFICATION）と検索対象の文書側（RETRIEVAL_DOCUMENT）は対をなす組み合わせで指定してください。クエリ側の指定に迷った場合は RETRIEVAL_QUERY を選択してください。

task type	説明
`RETRIEVAL_DOCUMENT`	複数のタスクにおいて検索対象となるドキュメントに最適化されたembedding を行います。
`SEMANTIC_SIMILARITY`	テキストの類似性を評価することに最適化された embedding を行います。
`RETRIEVAL_QUERY`	一般的な検索クエリに最適化された embedding を行います。取得するドキュメントには RETRIEVAL_DOCUMENT を指定してください。
`QUESTION_ANSWERING`	質問に回答するドキュメントの検索に最適化された embedding を行います。取得するドキュメントには RETRIEVAL_DOCUMENT を指定してください。
`FACT_VERIFICATION`	クエリの主張が正しいか判断可能なドキュメントの取得に最適化された embedding を行います。取得するドキュメントには RETRIEVAL_DOCUMENT を指定してください。
`CLASSIFICATION`	ラベルに従ってテキストを分類することに最適化された embedding を行います。
`CLUSTERING`	類似性に基づいてテキストをクラスタリングすることに最適化された embedding を行います。

利用例

リクエスト (cURL)

curl -H "Authorization: Bearer ${SARASHINA_API_KEY}" \
  -H "Content-Type: application/json" \
  "https://api.sarashina.ai/v1/embeddings" \
  -d '{
    "input": "更科日記は、平安時代中期に菅原孝標女によって書かれた回想録です。",
    "task_type": "RETRIEVAL_QUERY",
    "model": "sarashina3-embedding"
  }'

レスポンス例

{
  "id": "embd-a1b2c3d4e5f600000000000000000000",
  "object": "list",
  "created": 1764896400,
  "model": "sarashina3-embedding",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        2.09375,
        6.09375,
        -8.71875,
        ...
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 54,
    "total_tokens": 54
  }
}

上記の embedding は一部省略です。実際のレスポンスには 1536 個の数値が含まれます。

レスポンス構造

Embeddings レスポンスオブジェクト

フィールド	型	説明
`id`	string	応答の一意な識別子（一意な文字列であることのみを保証します。プレフィックスなどの形式は将来変更される場合があります）
`object`	string	常に `"list"`
`created`	integer	応答が生成された時刻（UNIX タイムスタンプ、秒）
`model`	string	使用されたモデル名
`data`	array of Embedding object	埋め込みベクトルの配列。OpenAI 互換の構造のため、単一テキストを指定した場合も1要素の配列で返却されます
`usage`	object	トークン使用量（`prompt_tokens` と `total_tokens` を含む）

Embedding オブジェクト

data 配列の要素です。

フィールド	型	説明
`object`	string	常に `"embedding"`
`index`	integer	入力1件につき1要素のみ返却されるため、常に `0`
`embedding`	array of float	1536 次元の数値配列。類似度計算にはコサイン類似度を使用してください（ベクトルの類似度について）

ベクトルの類似度について

出力されるベクトルは正規化されていません（ノルムは 1 ではありません）。類似度の計算にはコサイン類似度を使用してください。内積を使用する場合は、事前にベクトルを正規化してください。

注意
ユークリッド距離などでは、各種タスクのスコアが下がる可能性があるので注意してください。

Chat Completions Rerank