reranker/GGUF_INSTALL_AND_TUNING.md

# Qwen3 GGUF 安装与调优手册
本文档只覆盖 `qwen3_gguf` 后端，目标机器为当前项目实测环境：
- GPU: `Tesla T4 16GB`
- CUDA: `12.8`
- 模型: `DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF`
- 量化: `Q8_0`
---
## 1. 结论先看
当前这套代码里，GGUF 后端的主要瓶颈不是“显存没吃满”，而是 **llama.cpp 按 doc 顺序逐条打分**。因此最有效的优化策略是：
- 让模型层尽可能全部 offload 到 GPU
- 打开 `flash_attn` / `offload_kqv`
- 把 `n_ctx / n_batch / n_ubatch` 调到一个对短标题重排更合适的高效点
本轮在当前机器上的推荐配置是：
```yaml
qwen3_gguf:
  n_ctx: 512
  n_batch: 512
  n_ubatch: 512
  n_gpu_layers: 999
  n_threads: 2
  n_threads_batch: 4
  flash_attn: true
  offload_kqv: true
  infer_batch_size: 8
  sort_by_doc_length: true
  length_sort_mode: "char"
```
说明：
- `n_gpu_layers: 999` 在 llama.cpp 中等价于“尽可能全部层都 offload”
- 这台 T4 上，**即使全量 offload，当前模型也只占到约 `4.5 GiB` GPU 显存**
- 所以“允许 8G 显存”并不会自动带来更高速度；这个模型/后端在当前工作负载下已经接近“该用到的权重都上 GPU 了”
---
## 2. 独立环境
`qwen3_gguf` 必须使用自己的独立 venv：
- `qwen3_vllm` -> `.venv-reranker`
- `qwen3_gguf` -> `.venv-reranker-gguf`
安装命令：
```bash
./scripts/setup_reranker_venv.sh qwen3_gguf
```
脚本现在会自动做两件事：
1. 安装 GGUF 后端所需 Python 依赖
2. 在检测到 `/usr/local/cuda/bin/nvcc` 时，把 `llama-cpp-python` **重编译成 CUDA 版**
---
## 3. GPU 版验证
必须验证不是 CPU-only 版：
```bash
./.venv-reranker-gguf/bin/python - <<'PY'
import llama_cpp
print("supports_gpu_offload =", llama_cpp.llama_supports_gpu_offload())
PY
```
正确结果应为：
```text
supports_gpu_offload = True
```
还可以看动态库：
```bash
ldd .venv-reranker-gguf/lib/python3.12/site-packages/llama_cpp/lib/libllama.so | rg 'cuda|cublas|ggml-cuda'
```
应能看到：
- `libggml-cuda.so`
- `libcudart.so`
- `libcublas.so`
---
## 4. 模型下载
当前使用本地文件优先策略，模型放在：
```text
models/reranker/qwen3-reranker-4b-gguf/Qwen.Qwen3-Reranker-4B.Q8_0.gguf
```
若本地文件存在，后端会直接加载本地 GGUF，不再依赖启动时在线下载。
为了避免当前机器上 Hugging Face Xet 下载的 `416 Range Not Satisfiable` 问题，`start_reranker.sh` 已对 `qwen3_gguf` 默认设置：
```bash
HF_HUB_DISABLE_XET=1
```
---
## 5. 本地调优脚本
新增本地基准脚本：
```bash
PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
  scripts/benchmark_reranker_gguf_local.py --docs 64 --repeat 1
```
它会直接实例化 GGUF backend，输出：
- 模型加载耗时
- 当前进程 GPU 显存占用
- 单次 rerank 延迟
---
## 6. 本轮实测结果
测试条件：
- Query: `白色oversized T-shirt`
- Docs: `64` 条商品标题
- 本地脚本：`scripts/benchmark_reranker_gguf_local.py`
- 每组 1 次，重点比较相对趋势
结果：
### 6.1 保守配置
```text
n_ctx=384
n_batch=384
n_ubatch=128
n_gpu_layers=24
```
- GPU 显存：`2984 MiB`
- 64 docs 延迟：`74347.91 ms`
### 6.2 全量 offload
```text
n_ctx=384
n_batch=384
n_ubatch=128
n_gpu_layers=999
```
- GPU 显存：`4338 MiB`
- 64 docs 延迟：`51401.77 ms`
### 6.3 最优配置
```text
n_ctx=512
n_batch=512
n_ubatch=512
n_gpu_layers=999
```
- GPU 显存：`4564 MiB`
- 64 docs 延迟：`49116.10 ms`
### 6.4 其它尝试
`n_threads=4 / n_threads_batch=8`：
- GPU 显存：`4564 MiB`
- 64 docs 延迟：`49895.88 ms`
- 比推荐值略慢
`infer_batch_size=64`：
- GPU 显存：`4564 MiB`
- 64 docs 延迟：`50723.36 ms`
- 也略慢
### 6.5 API 级验证
在把推荐配置写入 `config/config.yaml` 并重启服务后，使用：
```bash
RERANK_BASE=http://127.0.0.1:6007 \
  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 64 --repeat 1 --query '白色oversized T-shirt'
```
得到：
- `64 docs`：`50177.22 ms`
再用：
```bash
RERANK_BASE=http://127.0.0.1:6007 \
  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 153 --repeat 1 --query '白色oversized T-shirt'
```
得到：
- `153 docs`：`115328.60 ms`
对比旧日志中的保守配置：
- 旧配置 `153 docs`：`153435.37 ms`
- 新配置 `153 docs`：`115328.60 ms`
改善幅度约：
- `24.8%`
---
## 7. 为什么没有吃到 8G
结论很重要：
- 当前最优配置已经是“尽可能全量层 offload”
- 该 `Q8_0` 模型在这套 llama.cpp / T4 / 短文本重排场景下，**实测只需要约 `4.5 GiB` GPU 显存**
- 继续为了“吃满 8G”去增大 `n_ctx`，不会明显提升吞吐，反而可能带来额外开销
所以本轮不是“显存太保守”，而是：
- 可 offload 的权重已经基本 offload 完了
- 真正拖慢响应的是 **逐 doc 顺序推理** 这一后端实现路径
---
## 8. 生产建议
### 8.1 当前建议
保留以下参数：
```yaml
n_ctx: 512
n_batch: 512
n_ubatch: 512
n_gpu_layers: 999
n_threads: 2
n_threads_batch: 4
flash_attn: true
offload_kqv: true
```
### 8.2 如果还嫌慢
优先级建议：
1. 缩小 `rerank_window`
2. 减少传入 doc 数
3. 若业务允许，切换到更适合高吞吐的后端
原因：
- 当前 GGUF 后端是本地单进程、逐 doc 打分
- 对长列表重排，它天然不如 vLLM / 云端 rerank API 擅长吞吐
---
## 9. 本轮落地文件
- `config/config.yaml`
- `scripts/setup_reranker_venv.sh`
- `scripts/start_reranker.sh`
- `scripts/benchmark_reranker_gguf_local.py`
- `reranker/GGUF_INSTALL_AND_TUNING.md`