> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Xếp hạng lại tài liệu

> Xếp hạng lại các tài liệu theo mức độ liên quan với một truy vấn

Xếp hạng lại các tài liệu bằng cách sử dụng các mô hình tương đồng ngữ nghĩa. Hữu ích cho việc cải thiện kết quả tìm kiếm và các ứng dụng RAG.

## Nội dung yêu cầu

**Timeout cho yêu cầu đồng bộ:** endpoint không phải chat này chờ model được định tuyến hoàn tất. Input lớn, audio dài, hoặc batch lớn có thể vượt quá mặc định 30s phổ biến của client, vì vậy hãy đặt timeout của HTTP client ít nhất là `120s`.

<ParamField body="model" type="string" required>
  ID của mô hình reranker cần sử dụng (ví dụ: `qwen3-vl-rerank`).
</ParamField>

<ParamField body="query" type="string" required>
  Truy vấn để xếp hạng các tài liệu dựa trên đó. Độ dài tối đa: `32,000` ký tự.
</ParamField>

<ParamField body="documents" type="array" required>
  Danh sách các tài liệu (chuỗi) cần xếp hạng lại. Giới hạn: tối đa `1,000` tài liệu, mỗi tài liệu tối đa `100,000` ký tự, và tổng số ký tự tài liệu tối đa `2,000,000`.
</ParamField>

<ParamField body="top_n" type="integer">
  Số lượng kết quả hàng đầu cần trả về. Mặc định là tất cả tài liệu. Phải tối thiểu là `1` và không được lớn hơn `documents.length`. Hiện TokenLab chưa áp dụng giới hạn công khai thấp hơn theo từng provider; nếu giới hạn này thay đổi, trang này sẽ được cập nhật trước khi áp dụng.
</ParamField>

<ParamField body="return_documents" type="boolean" default="false">
  Có bao gồm văn bản tài liệu gốc trong phản hồi hay không.
</ParamField>

## Phản hồi

<ResponseField name="results" type="array">
  Danh sách các tài liệu đã được xếp hạng kèm theo điểm số.

  Mỗi kết quả bao gồm:

  * `index` (integer): Chỉ mục tài liệu gốc
  * `relevance_score` (number): Điểm số liên quan (0-1)
  * `document` (string): Văn bản gốc (nếu `return_documents=true`)
</ResponseField>

<ResponseField name="model" type="string">
  Mô hình được sử dụng để xếp hạng lại.
</ResponseField>

<ResponseField name="usage" type="object">
  Thống kê mức sử dụng token.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/rerank" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3-vl-rerank",
      "query": "What is machine learning?",
      "documents": [
        "Machine learning is a subset of AI",
        "The weather is nice today",
        "Deep learning uses neural networks"
      ],
      "top_n": 2,
      "return_documents": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/rerank",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "qwen3-vl-rerank",
          "query": "What is machine learning?",
          "documents": [
              "Machine learning is a subset of AI",
              "The weather is nice today",
              "Deep learning uses neural networks"
          ],
          "top_n": 2
      }
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/rerank', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'qwen3-vl-rerank',
      query: 'What is machine learning?',
      documents: [
        'Machine learning is a subset of AI',
        'The weather is nice today',
        'Deep learning uses neural networks'
      ],
      top_n: 2
    })
  });

  const data = await response.json();
  console.log(data.results);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "model": "qwen3-vl-rerank",
          "query": "What is machine learning?",
          "documents": []string{
              "Machine learning is a subset of AI",
              "The weather is nice today",
              "Deep learning uses neural networks",
          },
          "top_n": 2,
      }
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/rerank", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)
      fmt.Println(result["results"])
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/rerank');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'qwen3-vl-rerank',
          'query' => 'What is machine learning?',
          'documents' => [
              'Machine learning is a subset of AI',
              'The weather is nice today',
              'Deep learning uses neural networks'
          ],
          'top_n' => 2
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data['results']);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "results": [
      {
        "index": 0,
        "relevance_score": 0.95,
        "document": "Machine learning is a subset of AI"
      },
      {
        "index": 2,
        "relevance_score": 0.82,
        "document": "Deep learning uses neural networks"
      }
    ],
    "model": "qwen3-vl-rerank",
    "usage": {
      "prompt_tokens": 45,
      "total_tokens": 45
    }
  }
  ```
</ResponseExample>