背景与目标

在实际检索增强生成（RAG）、搜索重排序、推荐系统中，Reranker 的稳定性和吞吐能力往往比模型规模本身更重要。

本文介绍一套 Production-ready 的 Reranker 部署方案，基于 vLLM 实现，目标是：

• 支持 Reranker 模型（案例已实测 Qwen3-Reranker系列）

• 同时覆盖：

  • 冷启动推理（Python 直调）

  • 热启动服务化部署（常驻 vLLM Server）

• 提供 稳定一致的 HTTP API

  • /v1/rerank

  • /v1/score

• 可直接用于 真实线上负载

该方案在设计上重点关注：
正确性、可复现性、工程稳定性。

---

目录

背景与目标

整体能力概述

支持的模型

项目结构说明

冷启动模式（Python 直调）

适用场景

运行方式

热启动模式（生产推荐）

1️⃣ 配置启动脚本

2️⃣ 启动服务

HTTP 接口说明

/v1/rerank

/v1/score

Python Client 使用示例

附：手动启动 vLLM（不使用脚本）

GPU 与性能调优建议

总结

---

整体能力概述

本项目提供的核心能力包括：

• 基于 vLLM 的 Reranker 服务化部署

• 冷启动 / 热启动两种使用模式

• 统一、稳定的 HTTP 接口

• 可复用的 Python Client

• 适配多 GPU / 单 GPU 场景

• 已在真实业务负载下验证

---

支持的模型

当前方案适用于 vLLM-Reranker 模型部署，包括但不限于：

• Qwen3-Reranker 系列（0.6B / 4B / 8B）

项目仓库已开源在GitHub社区：

# GitHub下载
git clone https://github.com/AnchorYYC/Reranker-vLLM-Deployment.git

本实例模型权重需提前下载，官方来源：

• Hugging Face：https://huggingface.co/Qwen

• ModelScope：https://modelscope.cn/models/

⚠️ 注意：模型权重 不包含在仓库中

---

项目结构说明

.
├── bench_rerank.py        # 并发 / 性能测试
├── env_utils.py           # 环境与模型路径配置
├── log/                   # vLLM 运行日志
├── main.py                # 示例入口
├── model_utils.py         # rerank / score 封装
├── resources.py           # HTTP Client（连接复用）
├── start_rerank.sh        # vLLM 服务启动脚本
├── vllm_usage.py          # 4B / 8B 示例
└── vllm_usage_tiny.py     # 0.6B 示例

代码结构刻意保持部署逻辑与客户端逻辑解耦，方便在不同环境复用。

---

冷启动模式（Python 直调）

适用场景

• 模型正确性验证

• 本地调试

• 快速实验

运行方式

export CUDA_VISIBLE_DEVICES=0
python vllm_usage_tiny.py   # 0.6B
# 或
python vllm_usage.py        # 4B / 8B

在 env_utils.py 中配置模型路径：

MODEL_PATH_TINY = "/path/to/qwen3-reranker-0.6b" 
MODEL_PATH = "/path/to/qwen3-reranker-4b-or-8b"

冷启动模式 不会启动 HTTP 服务

---

热启动模式（生产推荐）

1️⃣ 配置启动脚本

编辑 start_rerank.sh，重点参数：

• MODEL_PATH

• PORT

• CUDA_VISIBLE_DEVICES

• TP（Tensor Parallel 数量）

⚠️ TP 必须与 GPU 数量一致。

---

2️⃣ 启动服务

sh start_rerank.sh start

查看状态：

sh start_rerank.sh status

查看日志：

sh start_rerank.sh tail

---

HTTP 接口说明

服务启动后，vLLM 提供两个稳定接口，封装在 model_utils.py 中：

/v1/rerank

• 输入：query + documents

• 输出：按相关度排序后的文档及分数

• 适合：搜索 / RAG rerank

/v1/score

• 输入：query + documents

• 输出：与输入顺序一致的分数

• 适合：批量打分 / 特征计算

---

Python Client 使用示例

在 resources.py 中配置端口（需与服务一致）：

PORT = 11438 
LOCAL_BASE_URL = f"http://127.0.0.1:{PORT}/v1"

示例调用在：

# main.py
from resources import SharedResources
from model_utils import rerank, score

items, scores, raw = rerank(
    query="What is the capital of China?",
    documents=[...],
    top_n=5,
)

Client 内部使用 Session 复用，适合高并发调用。

---

附：手动启动 vLLM（不使用脚本）

export CUDA_VISIBLE_DEVICES=0

nohup vllm serve "${MODEL_PATH}" \
  --served-model-name "qwen3-reranker" \
  --task score \
  --port "11438" \
  --tensor-parallel-size "1" \
  --gpu-memory-utilization "0.85" \
  --max-model-len "4096" \
  --dtype "auto" \
  --enable-prefix-caching \
  --max-num-batched-tokens "24576" \
  --max-num-seqs "256" \
  --disable-log-stats \
  > vllm.log 2>&1 &

---

GPU 与性能调优建议

• GPU 数量 ≠ 吞吐线性提升

• 必须重点关注以下参数：

  • MAX_NUM_BATCHED_TOKENS

  • MAX_NUM_SEQS

  • GPU_MEMORY_UTILIZATION

强烈建议在扩容前先 benchmark。

---

总结

这套方案提供了：

• ✅ 生产可用的 Reranker vLLM 部署方式

• ✅ 冷启动 / 热启动双模式

• ✅ 清晰、稳定的 API 设计

• ✅ 工程实践导向，而非 Demo

如果你计划在 真实系统中使用 Reranker（RAG / 搜索 / 推荐），这是一套可以直接落地的基础方案（已实测Qwen3-Reranker系列模型）。