Cohere Rerank Format

This page overview

Important note

The format of Cohere’s Rerank model API is the same as Jina’s Rerank model API.

Official documentation

Cohere Rerank

📝 Introduction

Given a query and a list of texts, the rerank API sorts the texts by relevance to the query. Each text is assigned a relevance score, producing an ordered array of results. This feature is especially useful for search and retrieval applications, where it can optimize document ranking and help users find relevant information faster.

💡 Request Examples

Basic rerank request ✅

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": [
      "内华达州的首府是卡森城。",
      "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
      "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
      "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
      "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
    ],
    "top_n": 3
  }'

Response example:

{
  "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
    }
  }
}

Using structured data ✅

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
  }'

Response example:

{
  "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
    }
  }
}

📮 Request

Endpoint

POST /v1/rerank

Re-rank a list of texts based on their relevance to the query.

Authentication

Include the following in the request header for API key authentication:

Authorization: Bearer $4All API_API_KEY

Where $4All API_API_KEY is your API key.

Request Header Parameters

X-Client-Name

Type: string
Required: No
Description: The name of the project initiating the request.

Request Body Parameters

model

Type: string
Required: Yes
Description: The model identifier to use, such as rerank-v3.5.

query

Type: string
Required: Yes
Description: The search query text. This is the user’s question or query.

documents

Type: string array
Required: Yes
Description: A list of texts to compare against the query. For best performance, do not send more than 1,000 documents in a single request.
Notes:
Long documents will be automatically truncated to the value specified by max_tokens_per_doc
Structured data should be formatted as a YAML string for best performance

top_n

Type: integer
Required: No
Description: Limits the number of reranked results returned. If not specified, all reranked results will be returned.

max_tokens_per_doc

Type: integer
Required: No
Default: 4096
Description: Long documents will be automatically truncated to the specified number of tokens.

📥 Response

Successful Response

Returns an object containing the ranked document list.

results

Type: array of objects
Description: The ranked document list, sorted in descending order of relevance
Properties:
index : integer, the index of the document in the original document list
relevance_score : float, relevance score in the range [0, 1]. Scores closer to 1 indicate high relevance to the query, while scores closer to 0 indicate lower relevance

id

Type: string
Description: Unique identifier for the request

warnings

Type: string array
Required: No
Description: Warning messages returned by the API

Error Responses

When something goes wrong with the request, the API may return the following HTTP status codes and corresponding errors:

400 Bad Request : Incorrect request format or parameters
401 Unauthorized : No valid API key provided
403 Forbidden : No permission to access this resource
404 Not Found : The requested resource does not exist
422 Unprocessable Entity : The request is well-formed but contains semantic errors
429 Too Many Requests : Request rate limit exceeded
500 Internal Server Error : Internal server error
503 Service Unavailable : Service temporarily unavailable

🌟 Best Practices

Document Preparation Recommendations

Document length: Keep each document concise and clear; avoid overly long content. Long documents will be automatically truncated.
Structured data: Format structured data as a YAML string for best performance. For example: title: Product Name price: 9999元 features: - Feature 1 - Feature 2
Document count: For best performance, do not exceed 1,000 documents per request.

Query Optimization

Be specific: Write clear, specific queries to get more accurate ranking results.
Avoid vague queries: Try to avoid overly vague or generic query terms, as they may produce less distinct relevance scores.

Understanding Relevance Scores

Relevance scores are normalized to the range [0, 1]:

Scores closer to 1 indicate high relevance to the query
Scores closer to 0 indicate low relevance

Note: You should not simply assume that a document with a score of 0.9 is twice as relevant as one with a score of 0.45. Relevance scores are a relative metric used for ranking, not absolute comparison.