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

  
  本文档沉淀当前项目在电商搜索重排场景下的可复用实践，覆盖：
  
  - 环境准备与安装部署

  - `qwen3_vllm` 配置项与优化思路

  - 1000-doc 场景压测流程
  - 关键结论与推荐默认参数
  - 常见故障排查
  
  适用范围：
  

  - 重排后端：`services.rerank.backend: qwen3_vllm`
  - 模型：`Qwen/Qwen3-Reranker-0.6B`

  - 场景：query 较短（通常 < 100 tokens），doc 为商品标题或标题+简短描述，单请求 docs 约 1000 条
  
  ## 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 独立虚拟环境
  
  ```bash

  ./scripts/setup_reranker_venv.sh

  ```
  
  ### 2.2 基础检查
  
  ```bash
  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`）
  
  当前推荐基线：
  
  ```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 启停命令
  
  推荐统一使用：
  
  ```bash
  ./scripts/service_ctl.sh start reranker
  ./scripts/service_ctl.sh status reranker
  ./scripts/service_ctl.sh stop reranker
  ```
  
  也可直接运行原生脚本：
  
  ```bash
  ./scripts/start_reranker.sh

  ./scripts/service_ctl.sh stop reranker

  ```
  
  健康检查：
  
  ```bash
  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 使用一键压测脚本
  
  ```bash

  ./benchmarks/reranker/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 后很快退出
  
  排查顺序：
  
  ```bash
  ./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`