Apppublic

anhkhoiphan/rag-project-reranker

sourceHugging Faceupdated 3mo agoView on Hugging Face

0likes

App README

Reranker Service

Service FastAPI độc lập dùng để rerank các candidate chunks sau khi backend đã retrieve từ Qdrant.

Service này không biết về Qdrant, LangGraph, Redis, ingestion hay frontend. Nó chỉ nhận query + danh sách documents, chấm điểm lại và trả về thứ tự tốt hơn.

Vai Trò Trong Hệ Thống

Luồng retrieval của backend:

text

User query
-> Qdrant hybrid search lấy candidate child chunks
-> backend gửi candidate chunks sang reranker service
-> reranker service trả về rerank_score và rank_after
-> backend map kết quả về child chunks
-> nếu bật parent retrieval, backend group child chunks lên parent documents

Reranker hiện chạy ở cấp child chunk, không rerank full parent document.

Cấu Hình

Các biến môi trường chính:

env

RERANK_SERVICE_MODEL=BAAI/bge-reranker-base
RERANK_SERVICE_DEVICE=cpu
RERANK_SERVICE_MAX_LENGTH=512
RERANK_SERVICE_LAZY_LOAD=true

Model mặc định:

text

BAAI/bge-reranker-base

Model này nhẹ hơn các bản multilingual lớn, phù hợp hơn cho máy CPU hoặc máy có RAM hạn chế. Nếu triển khai trên server mạnh hơn, có thể cân nhắc model reranker khác.

Cài Dependencies

Chạy từ project root:

powershell

.venv\Scripts\python.exe -m pip install -r services\reranker\requirements.txt

Hoặc:

bash

pip install -r services/reranker/requirements.txt

Chạy Service

Windows PowerShell:

powershell

.venv\Scripts\python.exe -m uvicorn services.reranker.app:app --host 127.0.0.1 --port 8090

Bash:

bash

python -m uvicorn services.reranker.app:app --host 127.0.0.1 --port 8090

Health Check

powershell

curl http://127.0.0.1:8090/health

Response mẫu:

json

{
  "status": "ok",
  "model": "BAAI/bge-reranker-base",
  "device": "cpu",
  "provider": "reranker_service",
  "loaded": false
}

loaded=false là bình thường nếu RERANK_SERVICE_LAZY_LOAD=true và chưa có request /rerank nào.

Rerank Endpoint

Endpoint:

text

POST /rerank

Request:

json

{
  "query": "chính sách thúc đẩy bán ô tô điện",
  "documents": [
    {
      "id": "chunk_001",
      "text": "Nội dung candidate chunk",
      "metadata": {
        "doc_id": "policy"
      },
      "retrieval_score": 0.72,
      "rank_before": 1
    }
  ],
  "top_n": 5,
  "max_length": 512
}

Response:

json

{
  "model": "BAAI/bge-reranker-base",
  "results": [
    {
      "id": "chunk_001",
      "rerank_score": 0.91,
      "rank_before": 1,
      "rank_after": 1
    }
  ]
}

Service trả compact result, không trả lại toàn bộ text document. Backend chịu trách nhiệm map id về candidate chunk ban đầu.

Test Trực Tiếp Bằng PowerShell

powershell

$body = @{
  query = "chính sách thúc đẩy bán ô tô điện"
  documents = @(
    @{
      id = "test-1"
      text = "Chính sách thúc đẩy bán ô tô điện VinFast áp dụng cho các dòng xe điện."
      metadata = @{}
      retrieval_score = 0.5
      rank_before = 1
    }
  )
  top_n = 1
  max_length = 512
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8090/rerank" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

Lần đầu có thể chậm vì service phải load model.

Cấu Hình Backend Để Gọi Reranker

Trong .env của backend:

env

RERANK_ENABLED=true
RERANK_PROVIDER=remote_api
RERANK_TOP_K=10
RERANK_TOP_N=5
RERANK_API_URL=http://127.0.0.1:8090
RERANK_API_TIMEOUT=60
RERANK_FALLBACK_ON_ERROR=true

Nếu backend log có:

text

Remote reranker failed. Falling back to retrieval order

thì chat không bị crash. Backend sẽ dùng thứ tự retrieval ban đầu nếu RERANK_FALLBACK_ON_ERROR=true.

Benchmark

Chạy từ project root:

powershell

.venv\Scripts\python.exe scripts\benchmark_rerank.py --provider remote_api --api-url http://127.0.0.1:8090

Benchmark sẽ so sánh:

text

child-only retrieval
reranked child retrieval
parent document retrieval

Tests

powershell

.venv\Scripts\python.exe -m pytest tests

Deploy Lên HuggingFace Spaces

Cấu Trúc Space

Tạo một Docker Space mới trên HuggingFace và upload các file sau từ thư mục services/reranker/ trong monorepo:

text

Space repo/
├── Dockerfile
├── README.md          ← file này (có YAML frontmatter ở đầu)
├── __init__.py
├── app.py
├── model.py
├── schemas.py
└── requirements.txt

Tạo Space

1.Vào huggingface.co/new-space
2.Chọn Docker làm SDK
3.Chọn hardware phù hợp (CPU Basic đủ cho BAAI/bge-reranker-base)
4.Upload các file trên vào repo của Space

Biến Môi Trường (tuỳ chọn)

Có thể cấu hình qua Settings → Variables trong Space:

Variable	Mặc định	Mô tả
`RERANK_SERVICE_MODEL`	`BAAI/bge-reranker-base`	Model reranker từ HuggingFace Hub
`RERANK_SERVICE_DEVICE`	`cpu`	`cpu` hoặc `cuda`
`RERANK_SERVICE_BATCH_SIZE`	`1`	Số cặp (query, doc) xử lý mỗi lần
`RERANK_SERVICE_MAX_LENGTH`	`512`	Độ dài token tối đa mỗi đoạn văn
`RERANK_SERVICE_LAZY_LOAD`	`false`	`false` = load model khi khởi động

Model mặc định (BAAI/bge-reranker-base) được pre-download vào image lúc build. Nếu đổi model qua biến môi trường, lần khởi động đầu sẽ tải model từ Hub.

Build Argument

Để bake model khác vào image ngay lúc build (tránh download khi khởi động):

text

RERANK_SERVICE_MODEL=BAAI/bge-reranker-v2-m3

Đặt giá trị này trong Settings → Build arguments của Space.

Kết Nối Backend

Sau khi Space deploy xong, lấy URL của Space (dạng https://<username>-<space-name>.hf.space) và cập nhật .env của backend:

env

RERANK_ENABLED=true
RERANK_PROVIDER=remote_api
RERANK_API_URL=https://<username>-<space-name>.hf.space
RERANK_API_TIMEOUT=60
RERANK_FALLBACK_ON_ERROR=true

Tăng RERANK_API_TIMEOUT lên 60s vì cold-start của Space có thể chậm.

Health Check

bash

curl https://<username>-<space-name>.hf.space/health

Ghi Chú

—Reranker service nên chạy trước backend nếu RERANK_ENABLED=true.
—Nếu chạy CPU, tăng RERANK_API_TIMEOUT để tránh timeout ở lần load đầu.
—Nếu muốn test baseline không rerank, set RERANK_ENABLED=false trong backend.