メインコンテンツへスキップ
POST
Rerank documents: bge-reranker-v2-m3
右側のプレイグラウンドを使ってエンドポイントを直接呼び出せます: Authorization に Bearer sk-your-api-key を入れて、送信を押してください — 例の本文はすでに入力済みです。
モデルの機能、料金、測定データ、そして 3 つの注意点は 概要 にあります。Recall のサイジング、チャンク分割、しきい値戦略 は 実践での RAG チューニング にあります。

パラメータ参照

認識されないパラメータ(max_chunks_per_doc、rank_fields、truncate、…)は、拒否されるのではなく黙って無視されます。

レスポンスの注意事項

  • index — あなたが送信した documents 配列内でのドキュメントの元の位置です。これを使って 自分のドキュメントオブジェクトを参照してください。返された text では一致判定しないでください。
  • relevance_score — 範囲は 0–1 です。単一リクエスト内でのみ比較可能です。クエリ間では比較できず、 クロスリンガルの場合は体系的に低くなります。詳細は 概要のしきい値に関する議論 を参照してください。
  • results は常に relevance_score の降順でソートされます。index の値は完全で一意です。
  • prompt_tokens(クエリは 1 回 + すべてのドキュメントでカウント)と total_tokens(クエリは ペアごとにカウント)から使用量を読み取ってください。input_tokens / output_tokens はこのチャネルでは常に 0です。 今回は課金からどのフィールドが課金対象かを確認できませんでした — コンソールの請求書を正として扱ってください。

エラーコード

503 ではまずモデル名を疑ってください。 リクエストボディの解析に失敗する場合(たとえば Content-Type: text/plain)、ゲートウェイは model フィールドを読み取らず、空のモデル名のまま同じ 503 を返します。見た目はチャネル障害のようですが、実際は違います。
間違ったパスでも 404 にはなりません。 /rerank と /v2/rerank の両方(Cohere v2 SDK の デフォルト)は Web サイトの HTML ホームページ付きの HTTP 200 を返し、クライアント側では 解析できないレスポンスとして現れます。https://api.apiyi.com/v1/rerank だけが有効なパスです。

デバッグノート

候補数が非常に少ないと、スコア差は極端になります(1件目は0.97、2件目は0.12)し、モデルの判定境界がどこにあるのかは何もわかりません。10〜20件のドキュメントを使い、2〜3件の意図的なディストラクタ——トピックは近いが質問に答えていないもの——も含めてください。それによって、あなたのコーパスでのスコア範囲が分かります。しきい値はそれに基づいて決める必要があります。
中国語のクエリを英語のドキュメントに対して実行すると、正解のスコアは 0.003〜0.3 しか出ないことがありますが、順序は正しいです。これは呼び出しの不具合ではなく、モデル固有の挙動です。絶対値ではなく、順序で判断してください。
候補が1件でも、P50 では約2 s かかります。これはゲートウェイと上流側の固定オーバーヘッドです。 候補が1件から100件に増えても、P50 は 2.0 s から 3.8 s にしかなりません。 そのため、レイテンシを節約するために候補セットを小さくしないでください。効果は想像よりずっと小さいです。
上流側の TPM は 20,000 しかありません。100候補で反復すると、約15回の呼び出しで1分分の予算を使い切り、429 が返り始めます。代わりに10〜20候補でデバッグしてください。スコア分布を見るには十分で、クォータに作業を中断されずに済みます。 RAG 調整のクォータのセクションを参照してください。

承認

Authorization
string
header
必須

Add the Authorization: Bearer YOUR_API_KEY request header

ボディ

application/json
model
string
必須

Always bge-reranker-v2-m3 (case-sensitive; a wrong name returns 503)

例:

"bge-reranker-v2-m3"

query
string
必須

The search query. An empty string returns 400

documents
string[]
必須

Candidate documents. Plain string array only — passing Cohere-style [{"text": "..."}] objects returns 400. Cannot be empty. Keep to 100 or fewer.

top_n
integer

Return the top N results. Omitting it, or passing 0 or a negative number, returns all. Must be an integer — a string returns 400. Does not affect usage: every candidate is scored regardless.

例:

2

return_documents
boolean

Whether to echo the document text in results. Note: this parameter currently has no effect on this channel — document.text is always echoed. If response size matters, map results back by index yourself rather than relying on this flag to trim the payload.

例:

true

レスポンス

Rerank succeeded

results
object[]

Sorted by relevance_score, descending

usage
object

Token usage. This model consumes input tokens only