Skip to main content
POST
Rerank documents: bge-reranker-v2-m3
오른쪽의 플레이그라운드를 사용하여 엔드포인트를 직접 호출합니다: Bearer sk-your-api-keyAuthorization에 넣은 다음 전송을 누르십시오 — 예시 본문은 이미 채워져 있습니다.
모델 기능, 가격, 측정 데이터와 세 가지 주의 사항은 개요에 있습니다. Recall 크기 조정, chunking 및 임계값 전략은 RAG 튜닝 실전에 있습니다.

매개변수 참조

인식되지 않는 매개변수(max_chunks_per_doc, rank_fields, truncate, …)는 거부되지 않고 조용히 무시됩니다.

응답 참고 사항

  • index — 문서의 원래 위치입니다. 이는 사용자가 보낸 documents 배열에서의 위치입니다. 이를 사용해 자신의 문서 객체를 조회하십시오; 반환된 text를 기준으로 일치시키지 마십시오.
  • relevance_score — 범위 0–1. 단일 요청 내에서만 비교 가능합니다. 쿼리 간에는 비교할 수 없으며, 다국어 경우에서는 체계적으로 더 낮습니다. 개요의 임계값 논의를 참조하십시오.
  • results은 항상 relevance_score 내림차순으로 정렬되며; index 값은 완전하고 고유합니다.
  • 사용량은 prompt_tokens(query 1회 집계 + 모든 문서)와 total_tokens(query 쌍당 집계)에서 읽으십시오; input_tokens / output_tokens는 이 채널에서 항상 0입니다. 이번 라운드에서는 과금에서 어떤 필드가 청구되는지 확인할 수 없었습니다 — 콘솔 청구서를 기준으로 삼으십시오.

오류 코드

503에서는 먼저 모델 이름을 의심하십시오. 요청 본문을 파싱하지 못하면(예를 들어 Content-Type: text/plain), 게이트웨이는 model 필드를 읽지 않고 빈 모델 이름으로 동일한 503을 반환합니다. 이 경우 채널 장애처럼 보이지만 실제로는 그렇지 않습니다.
잘못된 경로는 404를 반환하지 않습니다. /rerank/v2/rerank(Cohere v2 SDK의 기본값) 모두 HTTP 200과 웹사이트의 HTML 홈페이지를 반환하며, 클라이언트 측에서는 파싱할 수 없는 응답으로 나타납니다. https://api.apiyi.com/v1/rerank만 유효한 경로입니다.

디버깅 노트

후보 수가 매우 적으면 점수 차이가 극단적입니다(첫 번째는 0.97, 두 번째는 0.12) 그리고 모델의 의사결정 경계가 어디에 있는지 아무것도 알려주지 않습니다. 1020개의 문서를 사용하고, 23개의 의도적인 방해 문서도 포함하십시오. 즉, 주제는 가깝지만 질문에는 답하지 않는 문서입니다. 그래야 귀하의 코퍼스에서의 점수 범위를 볼 수 있고, 어떤 임계값도 그 범위를 기준으로 해야 합니다.
영어 문서에 대한 중국어 질의는 정답에 0.003~0.3 정도만 나와도 될 수 있지만, 순서는 맞습니다. 이는 호출이 잘못된 것이 아니라 모델의 특성입니다. 절대값이 아니라 순서로 판단하십시오.
후보가 1개뿐이어도 P50에서 약 2초가 걸립니다. 이는 고정된 게이트웨이와 upstream 오버헤드입니다. 후보를 1개에서 100개로 늘려도 P50은 2.0초에서 3.8초로만 증가합니다. 따라서 지연시간을 줄이려고 후보 집합을 줄이지 마십시오. 예상보다 이득이 훨씬 작습니다.
upstream 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 channeldocument.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