# Qwen3-Reranker-0.6B GGUF 安装与调优

本文档覆盖 `qwen3_gguf_06b` 后端，对应模型：

- Hugging Face: `ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF`
- 文件: `qwen3-reranker-0.6b-q8_0.gguf`
- 本地目录: `./models/reranker/qwen3-reranker-0.6b-q8_0-gguf`

## 结论先看

这个后端已经接入完成，也能正常使用 GPU offload，但不适合当前项目的在线主链路场景。

目标场景是：

- 1 个 query
- 400 个商品标题
- 追求最短响应时间

实测最优配置下：

- GPU 显存占用约 `894 MiB`
- 400 titles 单请求延迟约 `265318 ms`

因此它更适合作为：

- 低显存 fallback
- 功能验证
- 本地离线实验

不建议作为在线低延迟 reranker 主 backend。

## 独立环境

`qwen3_gguf_06b` 使用独立 venv：

- backend: `qwen3_gguf_06b`
- venv: `.venv-reranker-gguf-06b`
- requirements: `requirements_reranker_qwen3_gguf_06b.txt`

安装：

```bash
./scripts/setup_reranker_venv.sh qwen3_gguf_06b
```

如果需要确认是 CUDA 版 `llama-cpp-python`：

```bash
./.venv-reranker-gguf-06b/bin/python - <<'PY'
import llama_cpp
print(llama_cpp.llama_supports_gpu_offload())
PY
```

预期输出：

```python
True
```

## 模型下载

推荐预先下载到本地，避免首次服务启动时在线拉取：

```bash
mkdir -p models/reranker/qwen3-reranker-0.6b-q8_0-gguf
curl -L --fail -C - \
  -o models/reranker/qwen3-reranker-0.6b-q8_0-gguf/qwen3-reranker-0.6b-q8_0.gguf \
  'https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf?download=true'
```

当前实测文件大小：

- `639153184` bytes

## 推荐配置

`config/config.yaml` 中建议保留：

```yaml
qwen3_gguf_06b:
  repo_id: "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF"
  filename: "qwen3-reranker-0.6b-q8_0.gguf"
  local_dir: "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf"
  cache_dir: "./model_cache"
  instruction: "Rank products by query with category & style match prioritized"
  n_ctx: 256
  n_batch: 256
  n_ubatch: 256
  n_gpu_layers: 999
  main_gpu: 0
  n_threads: 2
  n_threads_batch: 4
  flash_attn: true
  offload_kqv: true
  use_mmap: true
  use_mlock: false
  infer_batch_size: 32
  sort_by_doc_length: true
  length_sort_mode: "char"
  reuse_query_state: false
  enable_warmup: true
  verbose: false
```

## 调优结果

在当前机器上做了同机实测。标题文件来自 `/home/ubuntu/rerank_test/titles.1.8w`，查询为 `白色oversized T-shirt`。

80 titles：

- `n_ctx=256, reuse_query_state=true` -> `60108 ms`
- `n_ctx=256, reuse_query_state=false` -> `53383~56893 ms`
- `n_ctx=320, reuse_query_state=true` -> `60961 ms`
- `n_ctx=384, reuse_query_state=true` -> `56578 ms`
- `n_ctx=384, reuse_query_state=false` -> `57272 ms`
- `n_ctx=512, reuse_query_state=false` -> `60542 ms`
- `n_ctx=256, reuse_query_state=false, n_threads=4, n_threads_batch=8` -> `61228 ms`

400 titles：

- `n_ctx=256, n_batch=256, n_ubatch=256, n_gpu_layers=999, reuse_query_state=false`
  -> `265318 ms`

## 经验沉淀

这次接入最重要的结论不是“哪个小参数更快”，而是：

1. 这个 0.6B GGUF 权重虽然小，但当前后端实现仍是逐 doc 顺序打分。
2. 对在线 400-title 请求来说，串行打分本身就是主瓶颈。
3. `reuse_query_state` 在这个模型上没有带来收益，反而更慢。
4. `n_ctx` 拉大到 `384/512` 也没有带来实质收益，反而更慢或持平。
5. 这个 backend 的优势是低显存，不是低延迟。

如果目标是在线最短响应时间，优先级建议是：

1. `qwen3_vllm`
2. 其他真正支持高吞吐批处理的后端
3. `qwen3_gguf_06b` 仅作为低显存 fallback

## 验证命令

本地直连 backend 调优：

```bash
PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
  benchmarks/reranker/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
```

按服务方式启动：

```bash
RERANK_BACKEND=qwen3_gguf_06b ./scripts/start_reranker.sh
```