Reranker 模块

请求示例见 docs/QUICKSTART.md §3.5。扩展规范见 docs/DEVELOPER_GUIDE.md §7。部署与调优实战见 reranker/DEPLOYMENT_AND_TUNING.md。

---

Reranker 服务提供统一的 /rerank API，支持可插拔后端（BGE、Qwen3-vLLM、Qwen3-Transformers）。调用方通过 HTTP 访问，不关心具体后端。

特性

• 多后端：qwen3_vllm（默认，Qwen3-Reranker-0.6B + vLLM）、qwen3_transformers（纯 Transformers，无需 vLLM）、bge（兼容保留）
• 统一配置：config/config.yaml → services.rerank.backend / services.rerank.backends.<name>
• 文档去重、分数与输入顺序一致、FP16/GPU 支持（视后端）

目录与入口

• reranker/server.py：FastAPI 服务，启动时按配置加载一个后端
• reranker/backends/：后端实现与工厂
  • backends/__init__.py：get_rerank_backend(name, config)
  • backends/bge.py：BGE 后端
  • backends/qwen3_vllm.py：Qwen3-Reranker-0.6B + vLLM 后端
  • backends/qwen3_transformers.py：Qwen3-Reranker-0.6B 纯 Transformers 后端（官方 Usage 方式）
• reranker/bge_reranker.py：BGE 核心推理（被 bge 后端封装）
• reranker/config.py：服务端口、MAX_DOCS、NORMALIZE 等（后端参数在 config.yaml）

依赖

• 通用：torch、modelscope、fastapi、uvicorn（见项目 requirements.txt / requirements_ml.txt）
• Qwen3-vLLM 后端：vllm>=0.8.5、transformers>=4.51.0（仅当使用 backend: qwen3_vllm 时需 vLLM）
• Qwen3-Transformers 后端：transformers>=4.51.0、torch（无需 vLLM，适合 CPU 或小显存） bash ./scripts/setup_reranker_venv.sh

配置

• 后端选择：config/config.yaml 中 services.rerank.backend（qwen3_vllm | qwen3_transformers | bge），或环境变量 RERANK_BACKEND。
• 后端参数：services.rerank.backends.bge / services.rerank.backends.qwen3_vllm，例如：

services:
  rerank:
    backend: "qwen3_vllm"   # 或 bge
    backends:
      bge:
        model_name: "BAAI/bge-reranker-v2-m3"
        device: null
        use_fp16: true
        batch_size: 64
        max_length: 512
        cache_dir: "./model_cache"
        enable_warmup: true
      qwen3_vllm:
        model_name: "Qwen/Qwen3-Reranker-0.6B"
        max_model_len: 256
        infer_batch_size: 64
        sort_by_doc_length: true
        length_sort_mode: "char"  # char | token
        enable_prefix_caching: true
        enforce_eager: false
        instruction: "Given a web search query, retrieve relevant passages that answer the query"
      qwen3_transformers:
        model_name: "Qwen/Qwen3-Reranker-0.6B"
        instruction: "Given a web search query, retrieve relevant passages that answer the query"
        max_length: 8192
        batch_size: 64
        use_fp16: true
        tensor_parallel_size: 1
        gpu_memory_utilization: 0.8
        instruction: "Given a web search query, retrieve relevant passages that answer the query"

• 服务端口、请求限制等仍在 reranker/config.py（或环境变量 RERANKER_PORT、RERANKER_HOST）。

运行

./scripts/start_reranker.sh

该脚本会使用隔离环境 .venv-reranker；首次请先执行 ./scripts/setup_reranker_venv.sh。

性能压测（1000 docs）

./scripts/benchmark_reranker_1000docs.sh

输出目录：perf_reports/<date>/reranker_1000docs/。

API

Health

GET /health

Response 含 backend（当前后端名）、model、model_loaded、status。

Rerank

POST /rerank
Content-Type: application/json

{
  "query": "wireless mouse",
  "docs": ["logitech mx master", "usb cable", "wireless mouse bluetooth"]
}

Response:

{
  "scores": [0.93, 0.02, 0.88],
  "meta": {
    "input_docs": 3,
    "usable_docs": 3,
    "unique_docs": 3,
    "dedup_ratio": 0.0,
    "elapsed_ms": 12.4,
    "model": "BAAI/bge-reranker-v2-m3",
    "device": "cuda",
    "fp16": true,
    "batch_size": 64,
    "max_length": 512,
    "normalize": true,
    "service_elapsed_ms": 13.1
  }
}

Logging

The service uses standard Python logging. For structured logs and full output, run uvicorn with:

uvicorn reranker.server:app --host 0.0.0.0 --port 6007 --log-level info

Notes

• 无请求级缓存；输入按字符串去重后推理，再按原始顺序回填分数。
• 空或 null 的 doc 跳过并计为 0。
• Qwen3-vLLM 分批策略：docs 请求体可为 1000+，服务端会按 infer_batch_size 拆分；当 sort_by_doc_length=true 时，会先按文档长度排序后分批，减少 padding 开销，最终再按输入顺序回填分数。length_sort_mode 支持 char（默认，更快）与 token（更精确）。
• 运行时可用环境变量临时覆盖批量参数：RERANK_VLLM_INFER_BATCH_SIZE、RERANK_VLLM_SORT_BY_DOC_LENGTH、RERANK_VLLM_LENGTH_SORT_MODE。
• Qwen3-vLLM：参考 Qwen3-Reranker-0.6B，需 GPU 与较多显存；与 BGE 相比适合长文本、高吞吐场景（vLLM 前缀缓存）。
• Qwen3-Transformers：官方 Transformers Usage 方式，无需 vLLM；适合 CPU 或小显存，可选 attn_implementation: "flash_attention_2" 加速。