Rerank API

Xếp hạng lại (rerank) một danh sách tài liệu theo mức liên quan tới câu hỏi. Dùng ngay sau bước tìm bằng Embeddings trong RAG: embeddings lọc nhanh ~50–100 đoạn gần nhất, rerank chấm điểm chính xác từng đoạn để chọn top 5–10 đưa vào prompt.

Endpoint

POST https://platform.beeknoee.com/v1/rerank

Request

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_KEY`	✅
`Content-Type`	`application/json`	✅

Body Parameters

Parameter	Type	Required	Description
`model`	string	✅	ID model rerank (VD: `voyageai/rerank-3-lite`, `cohere/rerank-v3.5`) — xem danh sách ở dưới
`query`	string	✅	Câu hỏi / truy vấn (tối đa 32.000 ký tự)
`documents`	array	✅	Danh sách tài liệu: chuỗi, hoặc object `{ "text": "..." }`. Tối đa 1.000 tài liệu, tổng ≤ 4.000.000 ký tự
`top_n`	number	❌	Chỉ trả N kết quả điểm cao nhất (mặc định: trả hết). Nhận cả tên `top_k` (SDK Voyage)
`return_documents`	boolean	❌	`true` ⇒ mỗi kết quả kèm lại chữ của tài liệu

Các trường max_chunks_per_doc, max_tokens_per_doc, rank_fields, truncation (SDK Cohere / Voyage hay gửi kèm) được chấp nhận nhưng bỏ qua.

Models & giá

Danh sách model + giá đầy đủ: Text & Embedding Models → tab Rerank. Rerank có 2 cách tính tiền, tuỳ model:

Cách tính	Model (ví dụ)	Đơn vị giá	Đếm thế nào
Theo token	Voyage `rerank-3` / `rerank-3-lite` / `rerank-2.5`, Qwen3 Reranker 8B	USD / 1M token đầu vào	token câu hỏi × số tài liệu + tổng token tài liệu
Theo lượt tìm	Cohere `rerank-v3.5` / `rerank-4-fast` / `rerank-4-pro`	USD / 1.000 lượt	1 lượt = 1 câu hỏi + tối đa 100 tài liệu; tài liệu (kèm câu hỏi) dài hơn ngữ cảnh của model bị cắt khúc, mỗi khúc tính như 1 tài liệu

💡 Chọn nhanh: nhiều tài liệu ngắn ⇒ model theo lượt tìm thường rẻ hơn (100 tài liệu chỉ tính 1 lượt). Ít tài liệu, hoặc tài liệu dài ⇒ model theo token.

Response

{
  "id": "rerank-6c1f2f8e-3b1a-4c55-9f0e-2a7d9b6a1c33",
  "object": "list",
  "model": "rerank-3-lite",
  "results": [
    { "index": 0, "relevance_score": 0.9187, "document": { "text": "Vé máy bay Hà Nội – Sài Gòn giá 1 triệu đồng" } },
    { "index": 2, "relevance_score": 0.4412, "document": { "text": "Hãng bay giảm giá vé cuối tuần" } }
  ],
  "usage": { "total_tokens": 61 }
}

results sắp theo relevance_score giảm dần; index là vị trí tài liệu trong mảng documents bạn gửi.
document chỉ có khi gửi return_documents: true.
usage = số đơn vị đã tính tiền: total_tokens (model theo token) hoặc search_units (model theo lượt tìm).

Ví dụ

cURL

curl https://platform.beeknoee.com/v1/rerank \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyageai/rerank-3-lite",
    "query": "vé máy bay giá rẻ",
    "documents": [
      "Vé máy bay Hà Nội – Sài Gòn giá 1 triệu đồng",
      "Hôm nay trời đẹp",
      "Hãng bay giảm giá vé cuối tuần"
    ],
    "top_n": 2,
    "return_documents": true
  }'

Python

import requests

resp = requests.post(
    "https://platform.beeknoee.com/v1/rerank",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "cohere/rerank-v3.5",
        "query": "chính sách hoàn tiền",
        "documents": ["Hoàn tiền trong 7 ngày nếu chưa dùng", "Giờ làm việc 8h-17h", "Liên hệ hỗ trợ qua email"],
        "top_n": 1,
    },
    timeout=60,
)
for r in resp.json()["results"]:
    print(r["index"], round(r["relevance_score"], 3))

Node.js

const res = await fetch('https://platform.beeknoee.com/v1/rerank', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'voyageai/rerank-3', query: 'cách đổi mật khẩu', documents, top_n: 5 }),
})
const { results } = await res.json()
const top = results.map(r => documents[r.index])

RAG: Embeddings → Rerank

🎬 Video hướng dẫn · Embeddings + Rerank: dựng RAG mini 40 dòng Python với Bee Platform Xem trên YouTube Tất cả video

# 1) Lọc nhanh bằng embeddings (vector đã lưu sẵn trong DB / vector store) — lấy 50 đoạn gần nhất
candidates = vector_store.search(embed(query), k=50)

# 2) Rerank chấm lại chính xác, giữ 5 đoạn tốt nhất cho prompt
ranked = requests.post(
    "https://platform.beeknoee.com/v1/rerank",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"model": "voyageai/rerank-3-lite", "query": query, "documents": [c.text for c in candidates], "top_n": 5},
).json()["results"]
context = "\n\n".join(candidates[r["index"]].text for r in ranked)

Lỗi thường gặp

HTTP	`error.code` / `type`	Ý nghĩa	Trừ tiền?
400	`invalid_request`	Thiếu `query`, `documents` rỗng / quá 1.000 tài liệu, tài liệu rỗng, `top_n` sai, hoặc model từ chối request — `message` ghi rõ lý do	❌ Không
400	`insufficient_balance`	Số dư không đủ cho ước tính lượt này	❌ Không
403	`insufficient_permissions`	API key bị giới hạn danh sách model, không gồm model này	❌ Không
404	`model_not_found`	Model không có / đã tắt — xem `GET /models/rerank` (gửi sai tên liên tục ⇒ 429)	❌ Không
429	`rate_limit_exceeded`	Vượt RPM/RPD của gói, hoặc model đang quá tải — thử lại sau `Retry-After` giây	❌ Không
502 / 503 / 504	`unknown_error` (`type: server_error`)	Model tạm lỗi / hết giờ — thử lại sau hoặc đổi model	❌ Không

Beeknoee tính tiền theo số token / lượt tìm thật sau khi xếp hạng xong (đúng số trong usage); trước khi gọi chỉ giữ chỗ theo ước tính (nghiêng về dư) rồi nhả lại. Lượt lỗi không bị trừ tiền.

Embeddings — Bước 1 của RAG: lọc nhanh bằng vector
Decisions — Phân loại / định tuyến bằng đáp án có xác suất
Chat Completions — Đưa top tài liệu đã xếp hạng vào prompt

Rerank API

Endpoint

POST https://platform.beeknoee.com/v1/rerank

Request

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_KEY`	✅
`Content-Type`	`application/json`	✅

Body Parameters

Parameter	Type	Required	Description
`model`	string	✅	ID model rerank (VD: `voyageai/rerank-3-lite`, `cohere/rerank-v3.5`) — xem danh sách ở dưới
`query`	string	✅	Câu hỏi / truy vấn (tối đa 32.000 ký tự)
`documents`	array	✅	Danh sách tài liệu: chuỗi, hoặc object `{ "text": "..." }`. Tối đa 1.000 tài liệu, tổng ≤ 4.000.000 ký tự
`top_n`	number	❌	Chỉ trả N kết quả điểm cao nhất (mặc định: trả hết). Nhận cả tên `top_k` (SDK Voyage)
`return_documents`	boolean	❌	`true` ⇒ mỗi kết quả kèm lại chữ của tài liệu

Các trường max_chunks_per_doc, max_tokens_per_doc, rank_fields, truncation (SDK Cohere / Voyage hay gửi kèm) được chấp nhận nhưng bỏ qua.

Models & giá

Danh sách model + giá đầy đủ: Text & Embedding Models → tab Rerank. Rerank có 2 cách tính tiền, tuỳ model:

Cách tính	Model (ví dụ)	Đơn vị giá	Đếm thế nào
Theo token	Voyage `rerank-3` / `rerank-3-lite` / `rerank-2.5`, Qwen3 Reranker 8B	USD / 1M token đầu vào	token câu hỏi × số tài liệu + tổng token tài liệu
Theo lượt tìm	Cohere `rerank-v3.5` / `rerank-4-fast` / `rerank-4-pro`	USD / 1.000 lượt	1 lượt = 1 câu hỏi + tối đa 100 tài liệu; tài liệu (kèm câu hỏi) dài hơn ngữ cảnh của model bị cắt khúc, mỗi khúc tính như 1 tài liệu

💡 Chọn nhanh: nhiều tài liệu ngắn ⇒ model theo lượt tìm thường rẻ hơn (100 tài liệu chỉ tính 1 lượt). Ít tài liệu, hoặc tài liệu dài ⇒ model theo token.

Response

{
  "id": "rerank-6c1f2f8e-3b1a-4c55-9f0e-2a7d9b6a1c33",
  "object": "list",
  "model": "rerank-3-lite",
  "results": [
    { "index": 0, "relevance_score": 0.9187, "document": { "text": "Vé máy bay Hà Nội – Sài Gòn giá 1 triệu đồng" } },
    { "index": 2, "relevance_score": 0.4412, "document": { "text": "Hãng bay giảm giá vé cuối tuần" } }
  ],
  "usage": { "total_tokens": 61 }
}

results sắp theo relevance_score giảm dần; index là vị trí tài liệu trong mảng documents bạn gửi.
document chỉ có khi gửi return_documents: true.
usage = số đơn vị đã tính tiền: total_tokens (model theo token) hoặc search_units (model theo lượt tìm).

Ví dụ

cURL

curl https://platform.beeknoee.com/v1/rerank \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyageai/rerank-3-lite",
    "query": "vé máy bay giá rẻ",
    "documents": [
      "Vé máy bay Hà Nội – Sài Gòn giá 1 triệu đồng",
      "Hôm nay trời đẹp",
      "Hãng bay giảm giá vé cuối tuần"
    ],
    "top_n": 2,
    "return_documents": true
  }'

Python

import requests

resp = requests.post(
    "https://platform.beeknoee.com/v1/rerank",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "cohere/rerank-v3.5",
        "query": "chính sách hoàn tiền",
        "documents": ["Hoàn tiền trong 7 ngày nếu chưa dùng", "Giờ làm việc 8h-17h", "Liên hệ hỗ trợ qua email"],
        "top_n": 1,
    },
    timeout=60,
)
for r in resp.json()["results"]:
    print(r["index"], round(r["relevance_score"], 3))

Node.js

const res = await fetch('https://platform.beeknoee.com/v1/rerank', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'voyageai/rerank-3', query: 'cách đổi mật khẩu', documents, top_n: 5 }),
})
const { results } = await res.json()
const top = results.map(r => documents[r.index])

RAG: Embeddings → Rerank

# 1) Lọc nhanh bằng embeddings (vector đã lưu sẵn trong DB / vector store) — lấy 50 đoạn gần nhất
candidates = vector_store.search(embed(query), k=50)

# 2) Rerank chấm lại chính xác, giữ 5 đoạn tốt nhất cho prompt
ranked = requests.post(
    "https://platform.beeknoee.com/v1/rerank",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"model": "voyageai/rerank-3-lite", "query": query, "documents": [c.text for c in candidates], "top_n": 5},
).json()["results"]
context = "\n\n".join(candidates[r["index"]].text for r in ranked)

Lỗi thường gặp

HTTP	`error.code` / `type`	Ý nghĩa	Trừ tiền?
400	`invalid_request`	Thiếu `query`, `documents` rỗng / quá 1.000 tài liệu, tài liệu rỗng, `top_n` sai, hoặc model từ chối request — `message` ghi rõ lý do	❌ Không
400	`insufficient_balance`	Số dư không đủ cho ước tính lượt này	❌ Không
403	`insufficient_permissions`	API key bị giới hạn danh sách model, không gồm model này	❌ Không
404	`model_not_found`	Model không có / đã tắt — xem `GET /models/rerank` (gửi sai tên liên tục ⇒ 429)	❌ Không
429	`rate_limit_exceeded`	Vượt RPM/RPD của gói, hoặc model đang quá tải — thử lại sau `Retry-After` giây	❌ Không
502 / 503 / 504	`unknown_error` (`type: server_error`)	Model tạm lỗi / hết giờ — thử lại sau hoặc đổi model	❌ Không

Beeknoee tính tiền theo số token / lượt tìm thật sau khi xếp hạng xong (đúng số trong usage); trước khi gọi chỉ giữ chỗ theo ước tính (nghiêng về dư) rồi nhả lại. Lượt lỗi không bị trừ tiền.

Embeddings — Bước 1 của RAG: lọc nhanh bằng vector
Decisions — Phân loại / định tuyến bằng đáp án có xác suất
Chat Completions — Đưa top tài liệu đã xếp hạng vào prompt

Rerank API

Endpoint

Request

Headers

Body Parameters

Models & giá

Response

Ví dụ

cURL

Python

Node.js

RAG: Embeddings → Rerank

Lỗi thường gặp

Tiếp theo

Rerank API

Endpoint

Request

Headers

Body Parameters

Models & giá

Response

Ví dụ

cURL

Python

Node.js

RAG: Embeddings → Rerank

Lỗi thường gặp

Tiếp theo