在 RAG（检索增强生成）系统里，召回只是第一步，**重排（Rerank）**才是决定答案质量的关键。
如果你已经完成了向量召回，却经常发现“看起来相关，但答案不准”，那基本就是重排环节没做好。

本文将带你从 0 到 1 完成一套可上线的部署方案：

• 使用 Qwen3-Reranker-0.6B 搭建 HTTP 推理服务
• 基于 FastAPI + Uvicorn 提供接口
• 使用 systemd 实现守护进程与开机自启
• 加上日志、自动重启、限权运行、性能调优和故障排查

目标读者：有 Linux 基础、会 Python、希望把 reranker 真正跑在生产机上的工程师。

---

一、为什么要把 Reranker 做成独立服务？

很多团队会把 reranker 直接嵌进应用进程，初期能跑，但一上量就会遇到：

1. 应用重启导致模型重复加载，冷启动慢
2. 无法统一监控模型服务状态
3. 线上出现异常难以自动恢复
4. 部署更新流程混乱（代码和模型绑死）

把 Qwen3-Reranker 单独服务化后，你能获得：

• 标准 HTTP API（便于多系统复用）
• 独立资源管理（CPU/GPU）
• 可观测（日志、状态、重启策略）
• systemd 管理（开机自启、崩溃拉起）

---

二、部署环境规划（建议）

本文以 Ubuntu 22.04 为例（Debian/CentOS 思路一致）：

• Python 3.10+
• CUDA 11.8/12.x（GPU 场景）
• 内存建议：16GB+
• 显存建议：8GB+（0.6B 模型通常压力不大，量化后更轻）
• 目录规划：/opt/qwen-reranker/：项目目录/opt/qwen-reranker/venv/：虚拟环境/opt/qwen-reranker/model/：本地模型目录/var/log/qwen-reranker/：服务日志（可选）

---

三、准备 Python 运行环境

bash

sudo mkdir -p /opt/qwen-reranker sudo chown -R $USER:$USER /opt/qwen-reranker cd /opt/qwen-reranker python3 -m venv venv source venv/bin/activate pip install -U pip

安装依赖（GPU 按你的 CUDA 版本安装 torch）：

bash

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install transformers accelerate fastapi uvicorn[standard] pydantic

如果你是 CPU 部署，可安装 CPU 版 torch，推理会慢一些，但可用。

---

四、下载 Qwen3-Reranker-0.6B 模型

你可以从 Hugging Face 或 ModelScope 拉取。
建议先在开发机确认模型可加载，再拷到服务器。

示例（以 Hugging Face 为例）：

bash

pip install huggingface_hub python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='Qwen/Qwen3-Reranker-0.6B', local_dir='/opt/qwen-reranker/model/Qwen3-Reranker-0.6B')"

如果你在内网或受限网络环境，建议提前离线下载并通过制品库分发。

---

五、编写推理服务（FastAPI）

在 /opt/qwen-reranker/app.py 写入如下代码：

python

import os import torch from typing import List from fastapi import FastAPI from pydantic import BaseModel from transformers import AutoTokenizer, AutoModelForSequenceClassification MODEL_PATH = os.getenv("MODEL_PATH", "/opt/qwen-reranker/model/Qwen3-Reranker-0.6B") DEVICE = "cuda" if torch.cuda.is_available() else "cpu" MAX_LENGTH = int(os.getenv("MAX_LENGTH", "512")) app = FastAPI(title="Qwen3-Reranker Service", version="1.0.0") tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True) model = AutoModelForSequenceClassification.from_pretrained( MODEL_PATH, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32, trust_remote_code=True ).to(DEVICE) model.eval() class RerankRequest(BaseModel): query: str documents: List[str] class RerankItem(BaseModel): index: int score: float document: str class RerankResponse(BaseModel): query: str results: List[RerankItem] @app.get("/health") def health(): return {"status": "ok", "device": DEVICE} @app.post("/rerank", response_model=RerankResponse) @torch.no_grad() def rerank(req: RerankRequest): pairs = [[req.query, d] for d in req.documents] inputs = tokenizer( pairs, padding=True, truncation=True, max_length=MAX_LENGTH, return_tensors="pt" ).to(DEVICE) logits = model(**inputs).logits.squeeze(-1) scores = torch.sigmoid(logits).detach().cpu().tolist() items = [ {"index": i, "score": float(s), "document": req.documents[i]} for i, s in enumerate(scores) ] items.sort(key=lambda x: x["score"], reverse=True) return {"query": req.query, "results": items}

本地启动测试

bash

source /opt/qwen-reranker/venv/bin/activate cd /opt/qwen-reranker uvicorn app:app --host 0.0.0.0 --port 8001

测试接口：

bash

curl -X POST "http://127.0.0.1:8001/rerank" \ -H "Content-Type: application/json" \ -d '{ "query":"什么是向量数据库？", "documents":[ "向量数据库用于存储和检索高维向量，常见于语义搜索。", "MySQL是一种关系型数据库。", "Reranker可以提升召回文档排序质量。" ] }'

如果返回按分数排序的结果，说明服务可用。

---

六、创建专用系统用户（推荐生产实践）

不要用 root 跑模型服务：

bash

sudo useradd -r -s /usr/sbin/nologin qwen sudo chown -R qwen:qwen /opt/qwen-reranker sudo mkdir -p /var/log/qwen-reranker sudo chown -R qwen:qwen /var/log/qwen-reranker

---

七、编写 systemd 服务文件

创建 /etc/systemd/system/qwen-reranker.service：

ini

[Unit] Description=Qwen3 Reranker API Service After=network-online.target Wants=network-online.target [Service] Type=simple User=qwen Group=qwen WorkingDirectory=/opt/qwen-reranker Environment=MODEL_PATH=/opt/qwen-reranker/model/Qwen3-Reranker-0.6B Environment=MAX_LENGTH=512 Environment=PYTHONUNBUFFERED=1 ExecStart=/opt/qwen-reranker/venv/bin/uvicorn app:app --host 0.0.0.0 --port 8001 --workers 1 Restart=always RestartSec=5 LimitNOFILE=65535 StandardOutput=journal StandardError=journal # 安全加固（可按需开启） NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true [Install] WantedBy=multi-user.target

参数说明（关键）

• Restart=always：异常退出自动拉起
• RestartSec=5：5 秒后重启，防止疯狂重启
• WorkingDirectory：确保相对路径、缓存路径正确
• User=qwen：最小权限原则
• After=network-online.target：网络就绪后启动，减少依赖失败

---

八、启动、设为开机自启、查看状态

bash

sudo systemctl daemon-reload sudo systemctl start qwen-reranker sudo systemctl enable qwen-reranker sudo systemctl status qwen-reranker

查看实时日志：

bash

journalctl -u qwen-reranker -f

重启服务：

bash

sudo systemctl restart qwen-reranker

停止服务：

bash

sudo systemctl stop qwen-reranker

---

九、接入 Nginx（可选但推荐）

生产环境一般不直接暴露 Uvicorn 端口。
可用 Nginx 做反向代理 + TLS + 访问控制：

nginx

server { listen 80; server_name reranker.yourdomain.com; location / { proxy_pass http://127.0.0.1:8001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300; } }

之后配合 Certbot 上 HTTPS，即可安全对外提供服务。

---

十、性能优化建议（非常关键）

1）批量请求优先

重排天然适合 batch。一次传 20~100 条文档，比单条多次请求更高效。

2）控制 max_length

max_length 过大，延迟和显存占用会明显升高。
常见可用范围：256~512。按业务文档长度调。

3）GPU 半精度

torch.float16 在大多数 GPU 场景下收益明显。
若精度敏感可回退 fp32。

4）并发策略

• 单卡建议先 workers=1，避免多进程重复占显存
• 高并发用“请求队列 + 批处理”而不是盲目加 workers

5）预热

服务启动后先打几次 /rerank 请求，减少首个线上请求冷启动抖动。

---

十一、常见故障排查

问题1：systemctl start 失败

先看日志：

bash

journalctl -u qwen-reranker -n 200 --no-pager

常见原因：

• 虚拟环境路径写错
• 模型目录权限不足
• Python 依赖缺失

---

问题2：服务反复重启

可能是显存不足导致进程 OOM。
处理：

• 降低 max_length
• 控制单次 documents 数量
• 检查是否多 worker 抢显存

---

问题3：响应很慢

排查顺序：

1. 是否 CPU 推理（/health 看 device）
2. 文档是否过长
3. 请求是否过于碎片化（没有 batch）
4. 是否与其他 GPU 任务抢资源

---

问题4：开机后未自启

检查：

bash

systemctl is-enabled qwen-reranker

若不是 enabled，重新执行：

bash

sudo systemctl enable qwen-reranker

---

十二、升级与发布流程建议

生产环境不要“在线改文件再重启”，建议标准化：

1. 新版本代码发布到 /opt/qwen-reranker/releases/vX.Y.Z/
2. current 软链接指向新版本
3. 验证后执行 systemctl restart
4. 失败则回滚软链接并重启

模型更新也建议版本化目录，例如：

• /opt/qwen-reranker/model/Qwen3-Reranker-0.6B-v1
• /opt/qwen-reranker/model/Qwen3-Reranker-0.6B-v2

通过修改 service 的 Environment=MODEL_PATH=... 来切换。

---

十三、给 RAG 系统的调用范式（实践建议）

典型链路是：

1. 召回 topK（如 50）
2. 调用 reranker 对 50 条打分
3. 取 topN（如 5~10）喂给 LLM 生成答案

建议你在调用侧保留：

• 原始召回分
• rerank 分
• 最终入模文档 ID

这样可以做线上效果分析（A/B 测试、误判回溯）。

---

结语

Qwen3-Reranker-0.6B 部署并不难，难的是把它变成“可运维、可扩展、可稳定运行”的线上服务。
通过本文这套 FastAPI + systemd 的方案，你已经具备了生产级基础能力：

• 服务可启动、可重启、可观测
• 系统重启后自动拉起
• 异常退出自动恢复
• 可按需优化延迟与吞吐

如果你下一步要做，我建议优先补两件事：

1. 增加鉴权（API Key / 内网白名单）
2. 增加指标监控（QPS、P95、错误率、GPU 利用率）

这样你的 reranker 服务就不再是“能跑的脚本”，而是“可持续交付的基础设施”。