TokenLab

Văn bản

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 đến một truy vấn

POST
/v1/rerank

Sử dụng GET /v1/models?recommended_for=rerank để liệt kê các mô hình rerank hiện tại. Hãy sử dụng mô hình có thông tin chi tiết liệt kê thao tác rerank.

Xếp hạng lại 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.

Phần thân yêu cầu (Request Body)

Endpoint này trả về kết quả sau khi quá trình xếp hạng hoàn tất. Đối với các tập tài liệu lớn, hãy đặt thời gian chờ (timeout) của HTTP client tối thiểu là 120s.

modelstringbắt buộc

ID của mô hình reranker cần sử dụng (ví dụ: qwen3-vl-rerank).

querystringbắt buộc

Truy vấn dùng để xếp hạng các tài liệu. Độ dài tối đa: 32,000 ký tự.

documentsarraybắt buộc

Danh sách các tài liệu (chuỗi văn bản) 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ự của tất cả tài liệu không quá 2,000,000 ký tự.

top_ninteger

Số lượng kết quả hàng đầu cần trả về, từ 1 đến documents.length. Nếu bỏ qua, mô hình được chọn sẽ quyết định số lượng kết quả.

return_documentsbooleanmặc định: false

Có bao gồm nội dung văn bản gốc của tài liệu trong mỗi kết quả hay không. Chỉ gửi tham số này khi thông tin chi tiết của mô hình có liệt kê return_documents.

Phản hồi

resultsarray

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 của tài liệu gốc
  • relevance_score (number): Điểm liên quan. Phạm vi điểm phụ thuộc vào mô hình được chọn.
  • document (string): Văn bản gốc (nếu return_documents=true)
modelstring

Mô hình được sử dụng để xếp hạng lại. Xuất hiện khi có sẵn.

usageobject

Mức sử dụng được báo cáo cho yêu cầu, khi có sẵn: total_tokens, hoặc search_units đối với các mô hình tính phí theo từng lượt tìm kiếm.

Yêu cầu

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

Phản hồi

Response
{
  "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": {
    "total_tokens": 45
  }
}

Errors

Trạng tháiMã lỗiNguyên nhân
400invalid_requestMột trường bị thiếu, để trống hoặc vượt quá giới hạn ở trên. param sẽ chỉ định tên trường đó
400unsupported_endpointMô hình không được phát hành cho endpoint này

Xử lý các trạng thái khác theo hướng dẫn trong Xử lý lỗi API.

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json

application/json