DEPLOYMENT_AND_TUNING.md 8.06 KB
Edit Raw Blame History


Reranker 部署与性能调优手册（Qwen3-vLLM / Qwen3-GGUF）
本文档沉淀当前项目在电商搜索重排场景下的可复用实践，覆盖：


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


适用范围：


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

1. 环境基线
当前验证环境（2026-03-25）：


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、llama-cpp-python>=0.3.16、fastapi==0.135.1、uvicorn==0.41.0

2. 环境准备与安装
2.1 准备 reranker 独立虚拟环境
./scripts/setup_reranker_venv.sh qwen3_vllm


若使用 GGUF 并需要 CUDA：
./scripts/setup_reranker_venv.sh qwen3_gguf
PATH=/usr/local/cuda/bin:$PATH \
CUDACXX=/usr/local/cuda/bin/nvcc \
CMAKE_ARGS="-DGGML_CUDA=on" \
FORCE_CMAKE=1 \
./.venv-reranker-gguf/bin/pip install --no-cache-dir --force-reinstall --no-build-isolation llama-cpp-python==0.3.18

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__)"
./.venv-reranker-gguf/bin/python -c "import llama_cpp; print(llama_cpp.__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
        length_sort_mode: "char"  # char | token


GGUF / T4 剩余显存约 4.8~6GB 时，推荐基线：
services:
  rerank:
    backend: "qwen3_gguf"
    backends:
      qwen3_gguf:
        repo_id: "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF"
        filename: "*Q8_0.gguf"
        local_dir: "./models/reranker/qwen3-reranker-4b-gguf"
        cache_dir: "./model_cache"
        n_ctx: 384
        n_batch: 384
        n_ubatch: 128
        n_gpu_layers: 24
        flash_attn: true
        offload_kqv: true
        infer_batch_size: 8
        sort_by_doc_length: true
        length_sort_mode: "char"

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 即退出”的假阳性

4.4 GGUF / T4 小显存优化原则

Q8_0 权重约 4.28GB，但还要给 KV cache、CUDA 工作区和运行时碎片预留空间，不能按“模型大小 
当前业务是短 query + 商品标题，优先压缩 n_ctx；384 通常比默认长上下文更划算。
T4 小显存下先扫 n_gpu_layers，再尝试提高 n_ctx；infer_batch_size 在当前 GGUF 接入里主要是服务侧 work chunk，不是 llama.cpp 的真实算子 batch。
flash_attn: true、offload_kqv: true 默认保持开启；若 OOM，优先降低 n_gpu_layers。

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（看并发吞吐与尾延迟）


GGUF 建议扫描：


n_gpu_layers: 20 24 28
n_ctx: 320 384 448
infer_batch_size: 4 8 12（次要，仅影响服务侧 work chunk）
扫描顺序：先固定 n_ctx=384，找能稳定启动的最大 n_gpu_layers；再在显存允许时尝试 n_ctx=448；最后才微调 infer_batch_size


可通过环境变量覆盖：


BATCH_SIZES
C1_REQUESTS
C4_REQUESTS
TENANT_ID
RERANK_BASE

5.3 运行时临时覆盖服务参数
用于“同机对比不同参数”：


RERANK_VLLM_INFER_BATCH_SIZE
RERANK_VLLM_SORT_BY_DOC_LENGTH

6. 本轮关键结论
vLLM（2026-03-11，见 perf_reports/20260311/reranker_1000docs/report.md）：


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


GGUF（2026-03-25，本次接入）：


DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF 的 Q8_0 体积约 4.28GB，结合当前机器实测剩余显存约 4823 MiB，默认不采用激进的全量 GPU offload。
当前推荐默认值：n_ctx=384、n_batch=384、n_ubatch=128、n_gpu_layers=24、infer_batch_size=8。
若现场剩余显存更接近 6GB 且碎片较少，可优先尝试 n_gpu_layers=28；若启动失败，回退到 24 或 20。
由于当前工作区尚未缓存该 GGUF 权重，本次尚未完成真实吞吐压测；上线前需在部署机复跑一轮参数扫描并归档报告。

7. 生产建议

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

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
检查是否有其他进程占用同卡


GGUF 优先调整：


降低 n_gpu_layers
降低 n_ctx
降低 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