企业官网建设流程全解析

前阵子有人拿着一个知识库项目的日志来找我排查：粗排召回的结果看起来没什么问题，但进入精排之后，相关性分数整体漂移，严格按照固定阈值过滤的下游链路开始把一部分好结果丢掉了。查到最后发现，问题的根源不是模型权重，而是同一套 Reranker 在迁到基于 vLLM 的新部署方案之后，接口返回的分数语义变了，下游还在拿旧阈值硬套。这个案例让我意识到，Reranker 部署方案真正难的地方，往往不是把服务拉起来，而是模型兼容性、输出分数语义和容量评估这几个环节里藏着不少坑。下面这篇总结，我就把这段时间从选型、部署、联调到上线压测的完整记录整理出来，给正在评估 vLLM 这套路线的团队一份可以直接参考的实用版本。

1. 为什么要把精排模型迁到 vLLM：决策前先算清的账

1.1 常见精排部署姿势的瓶颈在哪里

大多数 RAG 系统的精排环节，现在还是用传统的办法在跑：把交叉编码器模型加载到一个 Python 进程里，或者套一个现成的精排推理容器，然后对外提供 HTTP 接口。内部实现往往是逐个请求或者小批量地做前向计算，模型占着显存，但并发一高，GPU 利用率却上不去。

我自己的压测里，一个参数规模在几亿级别的 Reranker，用这种传统方式部署，单请求带 64 个候选文档时，P99 延迟能做到 1 秒出头已经算不错了；并发从 8 路涨到 32 路时，吞吐几乎原地踏步，因为底层没有做动态批处理，多个请求的到来时间稍微错开一点，就各自为战，白白浪费了算力。

如果只是个人实验或者接口调用量很小，这完全不是问题。可一旦进入生产环境，多路召回、多租户并发、早晚高峰波动一起来，精排环节就会变成整个 RAG 链路的短板。

1.2 vLLM 提供了什么，又要求你接受什么

换成 vLLM 之后，最直观的变化是连续批处理。它能把不同时间到达的请求拼到同一个 batch 里，而不是等固定 batch 凑满再一起跑，这样每一轮 GPU 前向计算都能填得更满。再加上它统一的 HTTP 服务层和显存池化管理，Reranker 可以直接复用团队现有的调用、监控、告警体系，不需要再维护一套单独的精排服务。

为了让你更直观地做判断，我把常见精排管线和 vLLM 承载 Reranker 的差异整理成了表格：

但代价也很明确：vLLM 对模型结构有要求，不是随便一个 Reranker 权重丢进去就能跑；启动之后显存预占策略跟传统方式不同；输出分数语义的变化更是会让下游阈值逻辑失效。后面这几节，我会围绕这些问题展开细讲。

1.3 流量不大、更新频繁的场景，先别急着迁移

有几种情况我会劝你先别迁移。第一种，如果你的精排调用量很低，一天只有几万次，传统方案已经完全够用，迁移带来的吞吐提升感知不到，反而要承担适配成本。

第二种，模型更新非常频繁的情况。比如你每周都要用新数据重新训练 Reranker，并且希望训练完立刻热加载上线，vLLM 这套方案并不占优。vLLM 加载一个大模型权重需要经历权重读取、图构建、显存分配这几个阶段，频繁替换模型进程的成本比传统方式高不少。这种情况更适合保留轻量级的原生推理管线，把模型热更新做好。

第三种，延迟敏感且请求量小的场景。如果你的接口要求 P99 在几十毫秒以内，单请求携带的候选文档也不多，传统方案可能反而更轻快。vLLM 适合的是让 GPU 吃满、吞吐最大化的场景，而不是极致低延迟的小流量场景。

2. 兼容性排查：哪些 Reranker 能被 vLLM 正常加载

2.1 先看模型结构：vLLM 认的是 architectures 字段

vLLM 加载模型的机制，是读模型仓库里的config.json，根据里面的architectures字段决定用哪套模型实现去实例化。这个字段标注的是模型类名，比如BertForSequenceClassification、XLMRobertaForSequenceClassification，vLLM 的模型注册表里要有对应的实现，才能正常跑起来。

很多 Reranker 模型在结构上属于交叉编码器，本质上就是 Transformer 编码器加一个分类头。vLLM 0.8.x 版本之后，对这类 Sequence Classification 模型的支持逐步稳定，社区里常见的以 XLM-RoBERTa 为基座的交叉编码器类模型，多数都能直接加载。但要注意，vLLM 官方文档里的支持列表一直在变，不同版本之间差异可能很大。如果你用的是比较老的版本，很多参数和端点都对不上，建议先升级到较新版本再尝试。

2.2 三条加载路径：原生支持、配置适配、兜底方案

我实际踩过几类模型之后，把可行的路径总结成三条，按照优先级排列。

第一条，原生支持路径。模型仓库自带标准的*ForSequenceClassification架构，配置也是标准的，那么直接用--task rerank指定任务类型就能加载，这是最省事的。

第二条，配置适配路径。有些模型仓库为了特殊处理，在config.json里标了自定义类名，或者trust_remote_code字段被设为true，vLLM 默认不认识。这时候可以优先去找作者提供的.vLLM 适配版本，很多模型作者会额外放一个适合推理框架加载的权重目录；找不到的话，就需要自己写一个小的适配类，把权重中的分类头参数映射到 vLLM 认识的结构里，然后在本地注册进去。这条路需要对模型源码有一定理解，适合有开发能力的团队。

第三条，兜底方案。如果上面两条都走不通，我的建议是暂时不要硬刚。可以先用原来的 Transformers 管线继续跑精排，把 vLLM 留给生成模型或者 embedding 模型，等有空再做权重转换。Reranker 只是链路里的一环，为了迁移它卡住整个上线节奏，不值得。

2.3 一套两分钟的模型预检清单

为了避免一上来就把服务拉起，然后看着日志里的报错发懵，我整理了一套两分钟的预检流程，每次接入新模型都先走一遍：

1. 下载模型权重后，先打开config.json，确认architectures字段是不是 vLLM 支持的标准分类模型类名。
2. 看是否存在trust_remote_code: true，有的话优先准备适配方案。
3. 去模型仓库看作者有没有提供转换后的推理版本，有就直接替换。
4. 用最小 demo 脚本先加载一次权重，打印出模型输出结构，确认分数在哪个字段，不要直接起完整服务。

这套流程跑完，至少能筛掉八成加载失败的问题。

3. 服务化部署全流程：启动参数、接口联调与离线打分封装

3.1 环境准备和启动命令逐参数说明

我的实际部署环境是单张普通数据中心显卡，约 24G 显存，Python 3.10，CUDA 12.1，vLLM 版本在 0.8.x。启动命令如下：

python -m vllm.entrypoints.openai.api_server \ --model /data/models/reranker \ --task rerank \ --served-model-name reranker \ --max-model-len 2048 \ --gpu-memory-utilization 0.6 \ --max-num-seqs 64 \ --enforce-eager \ --dtype half \ --port 8000

几个参数值得单独说明。--task rerank是让 vLLM 走序列分类分支的关键，不指定的话，有的版本会把它当作生成模型处理，出来的东西完全不对。--max-model-len 2048必须显式设置，因为 Reranker 模型不像生成模型那样有明确的上下文窗口，vLLM 可能会给出很大的默认值，导致显存预占虚高。--max-num-seqs 64控制单个 batch 内的最大序列数，防止高并发时一次性拼太多序列把显存打爆。--gpu-memory-utilization 0.6表示让 vLLM 预占显存池的 60%，如果这块卡只跑 Reranker，可以调到 0.8 以上；如果还要跟其他进程共用，就要再降一些。

--enforce-eager是我习惯加上的参数。它关掉了一些图优化，换取更低的显存占用和更快的启动速度。Reranker 是编码器模型，一次前向计算，不像生成模型那样对 decode 性能敏感，所以这个参数收益明显。--dtype half则把权重切到半精度，显存占用直接减半，对分数影响可以忽略。

3.2 在线 rerank 接口的请求返回结构

服务启动之后，vLLM 通常会在/v1/rerank或/rerank路径暴露重排接口，具体路径取决于版本。请求体结构大致如下：

curl http://localhost:8000/v1/rerank \ -H "Content-Type: application/json" \ -d '{ "model": "reranker", "query": "什么是注意力机制", "documents": [ "注意力机制是一种用于序列建模的技术。", "今天天气很好，适合出门散步。" ], "top_n": 2 }'

返回结果里包含每个文档的相关性得分字段，不同小版本对这个字段的命名可能不同，可能是relevance_score也可能就是score。我建议拿到返回后先打印一遍完整结构，确认字段名和分数范围，再写下游解析逻辑。

这里有一个值得注意的细节：在线接口会自动完成 query 和 document 的 pair 拼接，不需要你自己处理特殊分隔符。但如果走离线方式，这里就非常容易出错，我在下一节细说。

3.3 离线批量打分的 Python 封装

在线接口适合交互式调用和中小流量。如果要给一批历史样本重新打分、做阈值重标定或者离线评测，在线方式效率太低，应该用 vLLM 的离线接口直接批量打分。

from vllm import LLM llm = LLM( model="/data/models/reranker", task="rerank", max_model_len=2048, enforce_eager=True, dtype="half", ) pairs = [ ("什么是注意力机制", "注意力机制是一种用于序列建模的技术。"), ("什么是注意力机制", "今天天气很好，适合出门散步。"), ] outputs = llm.embed(pairs, task="rerank") for out in outputs: score = out.outputs.score print(f"score: {score}")

需要提醒的是，score这个属性名在不同 vLLM 小版本里可能有差异，如果你在升级后取不到字段，可以打印dir(out.outputs)看看到底有什么。用这种离线方式，一次可以灌几千对样本进去，配合并发调用，跑完一轮历史数据只需要几分钟，后面做阈值重标定全靠它。

3.4 与生成模型同卡混部的实际体验

有朋友问过我，能不能把生成模型和 Reranker 放在同一个 vLLM 进程里跑。我的建议是不要这么做。两个模型的任务类型、上下文长度、batch 策略都不一样，塞进同一个实例会让调参互相牵制。分两个进程部署，各自设置不同的--gpu-memory-utilization，比如生成模型占 0.6，Reranker 占 0.3，反而更好管理。

如果卡不够，两个 vLLM 进程同卡部署也行，但要做好显存隔离。我有一个实际体验：分两个进程各占一部分显存池，高峰期的显存抖动还是会在一定程度上互相影响，nvidia-smi里的显存余量要留足 10% 左右的buffer。条件允许的话，我更建议单独拿一小块卡跑精排。

4. 切换后最容易被忽视的坑：分数语义、阈值重标定与截断

4.1 为什么同样输入，vLLM 打出来的分长得不一样

这是整篇文章最想让你注意的地方。传统精排部署工具为了使用方便，往往在输出之前对分类头的 logits 做一次 sigmoid 映射，把分数压到 0 到 1 之间，看起来像一个概率。很多团队的线上阈值，比如“低于 0.3 就过滤”，是按这个 0 到 1 分数卡出来的。

vLLM 的分类任务分支则更接近原始形态，返回的多半是分类头的 logits，取值范围可能是负数，可能是正数，绝对值大小也没有直接概率含义。排序逻辑不受影响，因为 logits 经过 sigmoid 之后是单调变换，顺序不变；但只要下游有绝对阈值判断，分数语义一变，旧阈值就完全失效了。

我举个例子说明差异：同一个 query-doc 对，传统工具输出0.021，说明相关性很低；换到 vLLM 后，打出来的分数是-3.75。如果你拿传统工具能接受的分数区间去硬套，第一个反应是“这分怎么这么小”，然后可能误判成模型坏了。实际上模型一点没坏，只是你需要对输出做一次映射，或者重新设定阈值。

4.2 阈值重标定：别拿旧阈值硬套新服务

我第一次切换的时候，过于自信，觉得排序模型只要相对顺序对就行，阈值那套逻辑可以由上层把分数排序后截取 topk 来兜底。结果发现下游还真有不少地方是直接按绝对分数过滤的，比如“候选文档相关性得分低于某个值就不进后续精排”，最终表现为返回结果质量波动。

正确的做法是，在切换后专门安排一次阈值重标定，流程如下：

1. 从线上日志里抽取两到三天的真实 query 和候选文档对，量级最好覆盖各种场景。
2. 用离线批量打分的方式，把全部样本重新打一遍，记录每个样本的 logits。
3. 画出分数分布，看相关和不相关样本的分界线大概在哪里。如果之前有标注数据，顺便算一下不同阈值下的准确率和召回率。
4. 根据分布重新设定过滤阈值，在小流量灰度一两天，观察结果质量指标是否稳定。

这套流程看起来简单，但我始终建议把这一步写进项目排期里，不要临时做。因为一旦线上流量起来，再回头补标注和调阈值，成本和风险都会放大。

4.3 长文本截断与跨模型分数不可比的连带问题

除了分数归一化问题，还有两个隐藏坑值得提一下。

第一个是长文本截断。Reranker 的输入长度上限由--max-model-len控制。如果线上候选文档特别长，而后端只保留前 2048 个 token，一些关键信息被切掉，排序结果可能发生肉眼可见的漂移。我碰到过一次类似情况：某个长文档里结论性内容分布在中间位置，截断后模型完全不认为它相关。排查方式很简单，统计线上候选文档的 token 长度分布，把--max-model-len调到能覆盖 95% 以上样本的值即可。当然，代价是显存占用和延迟上升，需要做个折中。

第二个是跨模型分数不可比。如果你的系统同时存在多个精排模型，比如按业务线划分，或者新旧模型灰度并行，那么不同模型之间的分数没有可比性，千万不要放在同一个排序池子里混合用。我建议对每个模型单独做归一化或单独设定阈值，保证同一上下文内只使用同一套分数体系。

5. 性能实测与显存预估：单卡能扛多少并发，算给你看

5.1 压测设计：直接按线上请求形态打，别只压单条

给 Reranker 做压测，最容易犯的错误是单条请求发出去测延迟，实际上线后才发现完全不是一回事。精排请求的特点是单个请求里往往带几十甚至上百条候选文档，这意味着一次请求就是一次很大的 prefill 计算。压测应该直接按真实线上请求形态来，比如单请求携带 64 个候选文档，候选文档平均长度约 500 token，返回 top_n=10。

我用自建的 asyncio 压测脚本，分别压了 1、8、32、64 路并发。模型参数量约 5.6 亿，单张 24G 显存卡，结果如下：

对比旧方案，同样的请求形态，P99 在 1.2 秒以上，并发上到 16 路之后基本不再上涨，吞吐只有个位数。vLLM 的连续批处理在这里的效果非常明显，而且并发越高越能体现优势。

5.2 显存怎么估：权重、prefill buffer 与 batch 的关系

Reranker 是编码器模型，跟生成模型不一样，不需要累积 KV Cache。但它的显存需求并不等于权重大小，实际运行时要额外预留前向计算的激活空间和 vLLM 的显存池。

一个粗略的算法是：权重显存等于参数量乘以每个参数占用的字节数，半精度下约 2 字节，所以 5.6 亿参数的模型权重大约占 1.1GB。真正波动大的是单 batch 内同时吃进去的总 token 数。压测里单请求带 64 个文档、每个文档 500 token，一个 batch 里两个并发请求就相当于灌入了约 64000 token 的 prefill，显存自然被动拉高。

实际操作上，我不太建议做精确的公式推导，更实用的办法是：启动服务后跑一轮压测，观察nvidia-smi里的峰值显存，然后反推--max-num-seqs和--max-model-len该怎么设。如果显存余量太少，就先调低--max-num-seqs，因为它在不改变单请求语义的情况下限制了并发拼接规模。

5.3 实测结果与最终选型建议

从压测结果看，这套方案最适合的场景是：请求量有明确高峰波动，单请求携带候选文档较多，精排吞吐成为链路瓶颈。如果你的日均精排量低于十万次，旧方案完全扛得住，没必要迁移；如果单请求只带几条候选文档，延迟要求又在几十毫秒内，传统精排管线反而是更轻的选择。

如果真决定要用 vLLM 承载 Reranker，我给出的落地顺序是：先做模型预检，确认兼容性；再起服务，调通在线和离线两条打分链路；然后立刻安排历史样本的分数分布比对和阈值重标定；最后才是压测和容量规划。把前面这几步做扎实了，后续上线基本不会出大问题。

最后说点个人体会。这套方案在线上稳定跑了一段时间后，最让我意外的不是吞吐提升，而是分数语义那次返工。它让我养成了一个固定习惯：任何精排模型要迁移推理框架，第一件事永远不是看延迟和吞吐，而是把线上历史样本用新旧两条链路各打一遍，比对分数分布，再决定下游阈值和排序逻辑是否需要跟着改。如果你也正准备把 Reranker 迁到 vLLM，强烈建议把这一步写进排期，它能帮你省掉后面一大段返工时间。