Reranker 部署与性能调优手册（Qwen3-vLLM）

本文档沉淀当前项目在电商搜索重排场景下的可复用实践，覆盖：

• 环境准备与安装部署
• qwen3_vllm 配置项与优化思路
• 1000-doc 场景压测流程
• 关键结论与推荐默认参数
• 常见故障排查

适用范围：

• 重排后端：services.rerank.backend: qwen3_vllm
• 模型：Qwen/Qwen3-Reranker-0.6B
• 场景：query 较短（通常

1. 环境基线

当前验证环境（2026-03-11）：

• GPU：Tesla T4 16GB
• Driver / CUDA：570.158.01 / 12.8
• Python：3.12.3
• 关键依赖：vllm==0.17.0、torch==2.10.0+cu128、transformers==4.57.6、fastapi==0.135.1、uvicorn==0.41.0

2. 环境准备与安装

2.1 准备 reranker 独立虚拟环境

./scripts/setup_reranker_venv.sh

2.2 基础检查

nvidia-smi
./.venv-reranker/bin/python -c "import torch; print(torch.cuda.is_available())"
./.venv-reranker/bin/python -c "import vllm, transformers; print(vllm.__version__, transformers.__version__)"

3. 部署与运行

3.1 配置（config/config.yaml）

当前推荐基线：

services:
  rerank:
    backend: "qwen3_vllm"
    backends:
      qwen3_vllm:
        model_name: "Qwen/Qwen3-Reranker-0.6B"
        engine: "vllm"
        max_model_len: 256
        tensor_parallel_size: 1
        gpu_memory_utilization: 0.36
        dtype: "float16"
        enable_prefix_caching: true
        enforce_eager: false
        infer_batch_size: 64
        sort_by_doc_length: true

3.2 启停命令

推荐统一使用：

./scripts/service_ctl.sh start reranker
./scripts/service_ctl.sh status reranker
./scripts/service_ctl.sh stop reranker

也可直接运行原生脚本：

./scripts/start_reranker.sh
./scripts/service_ctl.sh stop reranker

健康检查：

curl -sS http://127.0.0.1:6007/health

4. 核心优化点（已落地）

4.1 请求大小与推理 batch 解耦

• 调用方一次可传入 1000 docs（业务需求）
• 服务端按 infer_batch_size 自动拆批推理（模型效率需求）
• sort_by_doc_length: true：按长度排序后再分批

4.2 全局去重后回填

• 对 docs 进行全局去重（非“仅相邻去重”）
• 推理后按原请求顺序回填 scores，保证接口契约稳定

4.3 启动稳定性修复

• service_ctl.sh 对 reranker 使用独立启动路径
• 增加“稳定健康检查”（连续健康探测）避免“刚 healthy 即退出”的假阳性

5. 性能调优流程（标准流程）

5.1 使用一键压测脚本

./scripts/benchmark_reranker_1000docs.sh

输出目录：

• perf_reports/<date>/reranker_1000docs/*.json
• perf_reports/<date>/reranker_1000docs/report.md

5.2 常用参数扫描

默认扫描：

• infer_batch_size: 24 32 48 64
• 并发组：c=1（看单请求延迟）、c=4（看并发吞吐与尾延迟）

可通过环境变量覆盖：

• BATCH_SIZES
• C1_REQUESTS
• C4_REQUESTS
• TENANT_ID
• RERANK_BASE

5.3 运行时临时覆盖服务参数

用于“同机对比不同参数”：

• RERANK_VLLM_INFER_BATCH_SIZE
• RERANK_VLLM_SORT_BY_DOC_LENGTH

6. 本轮关键结论（2026-03-11）

基于报告：

• perf_reports/20260311/reranker_1000docs/report.md

结论：

• 对在线重排更重要的单请求延迟（c=1）指标，infer_batch_size=64 最优
• infer_batch_size=96 在更高并发下吞吐略高，但会牺牲单请求延迟稳定性
• 当前默认选择 infer_batch_size=64 作为平衡点

7. 生产建议

• 默认保持：infer_batch_size: 64、sort_by_doc_length: true
• 满足以下条件时可考虑提高到 96：业务以吞吐优先、可接受更高单请求延迟、已通过同机同数据压测验证收益
• 每次改动后都必须复跑 benchmark_reranker_1000docs.sh 并归档结果

8. 故障排查

8.1 start reranker 显示 healthy 后很快退出

排查顺序：

./scripts/service_ctl.sh status reranker
tail -n 200 logs/reranker.log
lsof -i :6007 -P -n

说明：

• 该类问题已在 scripts/service_ctl.sh 中通过 reranker 独立启动分支与稳定健康检查进行修复
• 若仍出现，优先检查 GPU 资源争用、vLLM 初始化失败或端口冲突

8.2 启动慢

现象：

• 首次启动会加载模型、torch.compile、CUDA graph capture，耗时较长

建议：

• 启动时预留足够健康检查窗口
• 避免频繁重启（编译缓存在 .runtime/reranker 下可复用）

8.3 OOM 或显存不足

优先调整：

• 降低 gpu_memory_utilization
• 降低 infer_batch_size
• 检查是否有其他进程占用同卡

9. 变更与验证清单

每次 reranker 调优改动后，至少完成：

• 配置变更已同步 config/config.yaml
• 文档变更已同步 reranker/README.md 与本手册
• 压测报告已归档到 perf_reports/<date>/reranker_1000docs/
• 启停验证通过：./scripts/service_ctl.sh start reranker、./scripts/service_ctl.sh status reranker、curl http://127.0.0.1:6007/health