Qwen3-Reranker-0.6B GGUF — llama.cpp Reranking Fix
这是从官方 Qwen/Qwen3-Reranker-0.6B 重新转换的 llama.cpp GGUF。
本仓库解决了部分早期或通用 GGUF 转换在 llama.cpp /v1/rerank 中无法正确评分的问题：接口虽然能够调用，但所有文档的分数都接近零，显示为 0.0000，甚至产生错误排序。
This repository contains freshly converted llama.cpp GGUF files for Qwen/Qwen3-Reranker-0.6B. It fixes a failure found in some older or generic conversions where /v1/rerank returned near-zero scores and incorrect rankings.
文件 / Files
| 文件 | 格式 | 大小 | SHA-256 |
|---|
Qwen3-Reranker-0.6B-fixed-f16.gguf | F16 | 1,197,634,272 bytes | 15e38d12462f56791bed44d97bad3880028d6fccebe99db0498c9e613f4aaf1f |
Qwen3-Reranker-0.6B-fixed-Q8_0.gguf | Q8_0 | 639,153,312 bytes | 99bcc225f0a38b73059b31627d28131cbea9c11b7ca894e56b95621aac878d65 |
Q8_0 由本仓库的 F16 GGUF 使用同一份 llama.cpp 构建中的 llama-quantize 生成。
为什么需要重新转换
Qwen3-Reranker 不是普通的文本生成模型。它需要把 Query 与 Document 按 reranker 格式组成输入，并在最后位置比较 yes / no 分类输出，得到 0～1 的相关性分数。
部分较早的 GGUF 或通用转换没有正确保留或生成 llama.cpp reranking 所需的分类输出头与元数据。典型症状包括：
/v1/rerank 可以返回 HTTP 200，但全部分数接近 0；- 客户端保留四位小数后，所有文档都显示为
0.0000；
- 相关文档不能排在第一位；
- GGUF 加载后表现得像普通 Qwen3 对话模型，而不是 reranker。
旧转换的实际测试示例：
| 文档 | 原始分数 | 排名 |
|---|
| 显卡用于图形和并行计算（不相关） | 2.5976477777611348e-14 | 1 |
| 熊猫生活在中国并以竹子为食（相关） | 1.755434294906939e-19 | 2 |
| 法国首都是巴黎（不相关） | 5.623200945999332e-20 | 3 |
虽然这些值并非数学意义上的精确零，但对实际检索完全失效，而且排序错误。
重新转换的目的，是使用较新的 llama.cpp 转换逻辑，正确处理 reranker 所需的分类输出和 rank pooling 元数据，包括 llama.cpp 用于计算相关性分数的分类头。
修复后实测
测试环境：
- GPU：NVIDIA Tesla P100 PCIe 16GB
- llama.cpp：build
b9879 / commit 72874f559
- 模型：
Qwen3-Reranker-0.6B-fixed-Q8_0.gguf
- API：llama-server
/v1/rerank
测试 Query：
结果：
| 文档 | relevance_score | 排名 |
|---|
| 熊猫是一种生活在中国、主要吃竹子的熊科动物。 | 0.9938316345 | 1 |
| 显卡用于计算机图形和并行计算。 | 0.0017781574 | 2 |
| 法国的首都是巴黎。 | 0.0003044957 | 3 |
修复后的模型能够给相关文档高分、给不相关文档低分，并产生正确排序。
llama-server 启动示例
1llama-server \
2 -m ./Qwen3-Reranker-0.6B-fixed-Q8_0.gguf \
3 --alias Qwen3-Reranker-0.6B \
4 --host 0.0.0.0 \
5 --port 8092 \
6 -ngl 999 \
7 -c 20480 \
8 -np 1 \
9 -b 2048 \
10 -ub 1024 \
11 --embedding \
12 --pooling rank \
13 --reranking \
14 --flash-attn on
三个关键参数：
--reranking：启用 /rerank、/v1/rerank 等 reranking API；--embedding：启用内部特征输出，而不是普通文本生成；--pooling rank：使用分类输出计算每个 Query/Document 对的相关性分数。
API 调用示例
1curl http://127.0.0.1:8092/v1/rerank \
2 -H 'Content-Type: application/json' \
3 -d '{
4 "model": "Qwen3-Reranker-0.6B",
5 "query": "什么是熊猫？",
6 "top_n": 3,
7 "documents": [
8 "熊猫是一种生活在中国、主要吃竹子的熊科动物。",
9 "法国的首都是巴黎。",
10 "显卡用于计算机图形和并行计算。"
11 ]
12 }'
请使用 /v1/rerank，不要把该模型当作普通 embedding 模型调用 /v1/embeddings。
转换来源与过程
原始 Transformers 权重来自：
转换过程：
1python3 convert_hf_to_gguf.py \
2 /path/to/Qwen3-Reranker-0.6B \
3 --outtype f16 \
4 --outfile Qwen3-Reranker-0.6B-fixed-f16.gguf
5
6llama-quantize \
7 Qwen3-Reranker-0.6B-fixed-f16.gguf \
8 Qwen3-Reranker-0.6B-fixed-Q8_0.gguf \
9 Q8_0
兼容性与限制
- 建议使用较新的 llama.cpp；
- 这是 cross-encoder reranker，不是向量 embedding 模型；
- Q8_0 更节省磁盘和显存，F16 适合作为高精度参考或继续量化；
- 最长输入受 llama-server
--ctx-size 和模型上下文限制；
- 实际效果仍取决于检索任务、Query、Document 切分方式与指令。
License and attribution
The original model is released under the Apache License 2.0. This conversion keeps the same license and is not an official release by the Qwen team.
感谢 Qwen 团队与 llama.cpp 社区。本仓库仅发布格式转换与验证结果，不修改原模型训练权重所表达的能力。
