Cohere リランク形式（Rerank）

Cohere リランキング形式（Rerank）

本ページの概要

重要な注意事項

cohere の Rerank モデルのインターフェース形式は、Jina の Rerank モデルのインターフェース形式と同じです。

公式ドキュメント

Cohere Rerank

📝 はじめに

クエリとテキスト一覧が与えられると、リランキング API はクエリとの関連性に基づいてテキストを並べ替えます。各テキストには関連性スコアが付与され、順序付きの配列として結果が返されます。この機能は検索・検索取得アプリケーションに特に適しており、文書の並び順を最適化して、ユーザーがより早く関連情報を見つけられるようにします。

💡 リクエスト例

基本的なリランキングリクエスト ✅

curl https://4All API地址/v1/rerank \
  -H "Authorization: Bearer $4All API_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "アメリカの首都は何ですか？",
    "documents": [
      "ネバダ州の州都はカーソンシティです。",
      "北マリアナ諸島は太平洋上の一群の島々で、その首都はサイパン島です。",
      "ワシントンD.C.（ワシントン、または特別区とも呼ばれ、正式名称はコロンビア特別区）はアメリカの首都です。",
      "英語文法における大文字化は、単語の先頭に大文字を使うことです。英語の大文字の使い方は他言語とは異なります。",
      "アメリカが国家として成立する以前から、アメリカには死刑が存在していました。2017年時点で、50州のうち30州で死刑は合法です。"
    ],
    "top_n": 3
  }'

レスポンス例:

{
  "results": [
    {
      "index": 2,
      "relevance_score": 0.999071
    },
    {
      "index": 0,
      "relevance_score": 0.32713068
    },
    {
      "index": 1,
      "relevance_score": 0.1867867
    }
  ],
  "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
  "meta": {
    "api_version": {
      "version": "2",
      "is_experimental": false
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

構造化データの使用 ✅

curl https://4All API地址/v1/rerank \
  -H "Authorization: Bearer $4All API_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "初心者向けのコスパの良い一眼レフカメラを探しています",
    "documents": [
      "型号: Canon EOS 800D\n価格: 4299元\n功能: 2410万像素, 光学取景器, Wi-Fi\n適合人群: 初学者, 愛好者",
      "型号: Nikon D3500\n価格: 3099元\n功能: 2416万像素, 光学取景器, 長達1550張的電池續航\n適合人群: 新手, 学生",
      "型号: Sony A7III\n価格: 12999元\n功能: 2420万像素, 全画幅, 4K视频\n適合人群: 專業摄影师, 视频创作者"
    ],
    "max_tokens_per_doc": 512
  }'

レスポンス例:

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.918472
    },
    {
      "index": 0,
      "relevance_score": 0.854321
    },
    {
      "index": 2,
      "relevance_score": 0.423156
    }
  ],
  "id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa",
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

📮 リクエスト

エンドポイント

POST /v1/rerank

クエリとの関連性に基づいてテキスト一覧を再ランキングします。

認証方法

リクエストヘッダーに以下を含めて API キー認証を行います。

Authorization: Bearer $4All API_API_KEY

ここで、$4All API_API_KEY はあなたの API キーです。

リクエストヘッダーのパラメータ

X-Client-Name

タイプ: 文字列
必須: いいえ
説明: リクエストを送信するプロジェクト名。

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

model

タイプ: 文字列
必須: はい
説明: 使用するモデルの識別子。例: rerank-v3.5。

query

タイプ: 文字列
必須: はい
説明: 検索クエリのテキスト。ユーザーが入力する質問や問い合わせ内容です。

documents

タイプ: 文字列配列
必須: はい
説明: クエリと比較するテキスト一覧。最適な性能を得るには、1 回のリクエストで 1,000 件を超える文書を送らないことを推奨します。
注意事項:
長文書は max_tokens_per_doc で指定した値まで自動的に切り詰められます
構造化データは、最適な性能を得るために YAML 文字列として整形してください

top_n

タイプ: 整数
必須: いいえ
説明: 返される再ランキング結果の件数を制限します。指定しない場合は、すべての再ランキング結果が返されます。

max_tokens_per_doc

タイプ: 整数
必須: いいえ
デフォルト値: 4096
説明: 長文書は指定したトークン数まで自動的に切り詰められます。

📥 レスポンス

成功レスポンス

並び替え後の文書一覧を含むオブジェクトを返します。

results

タイプ: オブジェクト配列
説明: 関連性の高い順に並んだ、並び替え後の文書一覧
属性:
index : 整数、元の文書一覧における文書のインデックス
relevance_score : 浮動小数点数、関連性スコア。範囲は [0, 1]。1 に近いほどクエリとの関連性が高く、0 に近いほど関連性が低いことを示します

id

タイプ: 文字列
説明: リクエストの一意な識別子

warnings

タイプ: 文字列配列
必須: いいえ
説明: API が返す警告メッセージ

エラーレスポンス

リクエストに問題がある場合、API は以下の HTTP ステータスコードと対応するエラーを返すことがあります。

400 Bad Request : リクエスト形式またはパラメータの誤り
401 Unauthorized : 有効な API キーが提供されていない
403 Forbidden : このリソースへのアクセス権限がない
404 Not Found : 指定されたリソースが存在しない
422 Unprocessable Entity : リクエスト形式は正しいが、意味的なエラーを含む
429 Too Many Requests : リクエスト頻度が上限を超えている
500 Internal Server Error : サーバー内部エラー
503 Service Unavailable : サービスが一時的に利用できない

🌟 ベストプラクティス

文書準備の推奨事項

文書の長さ：各文書は簡潔でわかりやすく保ち、長くなりすぎないようにしてください。長文書は自動的に切り詰められます。
構造化データ：構造化データは YAML 文字列として整形すると、最適な性能が得られます。例: title: 商品名 price: 9999元 features: - 特徴1 - 特徴2
文書数：1 回のリクエストで 1,000 文書を超えないようにすると、最適な性能が得られます。

クエリの最適化

明確かつ具体的に：より正確なランキング結果を得るために、明確で具体的なクエリを作成してください。
あいまいなクエリを避ける：あまりにあいまいで一般的なクエリはできるだけ避けてください。関連性スコアの差が分かりにくくなることがあります。