Rerank API

与えられた複数の文書に対してクエリに適合する度合い(関連度)を計算しスコアの降順で返却するAPIです。

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

エンドポイント

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

サポートモデル

sarashina3-rerank

リクエストパラメータ

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

パラメータ	型	デフォルト	必須	説明
`query`	string	–	✅	クエリテキスト。
`documents`	array of string	–	✅	順位を並べ替えられるドキュメントのリスト。件数は1～20件の範囲で指定してください。クエリと各文書はペアごと（pairwise）にスコアを算出するため、クエリと各文書の組み合わせごとに、合計8,000トークン以下である必要があります。この制約を超過した場合は 400 Bad Request を返却します。なお、レスポンスの `usage.prompt_tokens` には全ペアのトークン数の合計が計上されます。
`task_type`	string	`GENERAL_RETRIEVAL`	–	次の Task Type の説明を参照してください。指定されていない場合 `GENERAL_RETRIEVAL` が使用されます。
`model`	string	–	✅	使用するモデル名 (例: `sarashina3-rerank`)
`query_instruction`	string	–	条件付き	`task_type` が `CUSTOMIZE` の場合は必須です（省略すると 400 Bad Request を返却します）。`query` の前に挿入する任意の指示文を指定できます。`task_type` が `CUSTOMIZE` 以外の場合、`query_instruction` の値は作用しません。

Task Type

以下のいずれかの task type を指定することができます。利用用途に最適な task type を指定してください。

task type	説明
`GENERAL_RETRIEVAL`	一般的な検索クエリに関連するドキュメントの取得に最適化されたリランキングを行います。
`GENERAL_QA`	質問に回答するドキュメントの検索に最適化されたリランキングを行います。
`NEWS_RETRIEVAL`	ニュース記事関連の文書取得に最適化されたリランキングを行います。
`SEMANTIC_SIMILARITY`	テキストの類似度を評価・判定することに最適化されたリランキングを行います。
`CUSTOMIZE`	特定の用途 (ECサイト、学術論文、FAQなど)に合わせて独自の指示(query_instruction)を設定し、リランキングの精度を最適化します。例えば、学術論文のドメインでは、「学術論文のタイトルに合った論文の内容を検索してください。」のように書きます。

利用例

リクエスト (cURL)

curl -H "Authorization: Bearer ${SARASHINA_API_KEY}" \
  -H "Content-Type: application/json" \
  "https://api.sarashina.ai/v1/rerank" \
  -d '{
    "query": "Sarashinaのテキスト埋め込みモデルはありますか?",
    "documents": [
      "更級日記は、平安時代中期に菅原孝標女によって書かれた回想録です。",
      "サラシナエンベディングは日本語言語モデルをベースにした日本語埋め込みモデルです。",
      "Sarashinaは、SB Intuitionsが開発した日本語大規模言語モデルです。これまでに7B, 13B, 70B, 8x70Bのモデルが公開されています。"
    ],
    "task_type": "GENERAL_RETRIEVAL",
    "model": "sarashina3-rerank"
  }'

レスポンス例

{
  "id": "rerank-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "list",
  "created": 1764896400,
  "model": "sarashina3-rerank",
  "data": [
    {
      "object": "reranked_document_list",
      "index": 0,
      "result": [
        {
          "document_id": 1,
          "score": 0.9999375343322754
        },
        {
          "document_id": 2,
          "score": 0.9996567964553833
        },
        {
          "document_id": 0,
          "score": 0.9228394627571106
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 157,
    "total_tokens": 157,
    "completion_tokens": 0,
    "prompt_tokens_details": null
  }
}

補足
document_id は documents 配列におけるインデックス番号を示し、score は対象ドキュメントと query との関連度スコアを表します。

レスポンス構造

Rerank API は、入力文書すべてのスコアを降順で返却します。（上位N件への絞り込みを行うパラメータはサポートしていません。絞り込みはクライアント側で行ってください。）

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

フィールド	型	説明
`id`	string	レスポンスの一意なID。
`object`	string	オブジェクトタイプ。常に `"list"` です。
`created`	integer	レスポンス生成時刻（Unix タイムスタンプ）。
`model`	string	使用されたモデル名。
`data`	Reranked Document List オブジェクトの配列	リランキング結果。リクエストごとに1要素です。
`usage`	usage オブジェクト	使用トークン数（`prompt_tokens`・`total_tokens` は全ペアのトークン数の合計で、`completion_tokens` は常に `0` です）。

Reranked Document List オブジェクト

フィールド	型	説明
`object`	string	オブジェクトタイプ。常に `"reranked_document_list"` です。
`index`	integer	リクエスト内でのインデックス。常に `0` です。
`result`	Document Score オブジェクトの配列	スコアの降順に並んだ全入力文書のスコア。

Document Score オブジェクト

フィールド	型	説明
`document_id`	integer	`documents` 配列における入力文書のインデックス番号（0始まり）。
`score`	number	クエリと文書の関連度を表すスコア。値域は [0, 1] です。

スコアの取り扱いについて

score はクエリと文書のペアごとに算出される関連度の指標であり、確率として校正されているわけではありません。絶対的な閾値によるフィルタリングには適さないため、順位付けのための指標（スコアの大小関係）として利用してください。
スコアは全体的に高い値に偏る傾向があり、クエリとの関連性が低い文書にも高いスコアが付く場合があります。上記のレスポンス例のように、スコアが 0.9 以上に密集することがあります。
同一のリクエストを再送した場合、スコアは決定的に（完全に一致する形で）返却されます。一方、文書リストの組み合わせ（バッチ構成）が異なる場合は、浮動小数点演算の非再現性により、同じクエリ・同じ文書の組み合わせでもスコアが 10⁻⁵ 程度変動することがあります。この変動幅は順位に影響を与えない範囲です。そのため、20件を超える文書をリクエスト分割して送信した場合でも、文書間のスコアは概ね比較可能です。
クエリが異なるリクエスト間でスコアを直接比較することは推奨されません。

Embeddings Translate