vllm部署embedding模型

你已经有一批文档要建索引，想用 vLLM 把 embedding 模型挂成一个常驻服务，让检索端按 HTTP 调。真动手会发现卡点不在启动命令，而在于这个模型 vLLM 认不认、pooling 方式对不对、拿到的向量跟离线跑出来的是不是一套、并发一上来显存撑不撑得住。这篇按这四关给判断标准和排查顺序，具体数字和版本信息去站内对应页面核对。

你已经有一批文档要建索引，想让 embedding 模型常驻成一个服务，检索端按 HTTP 直接调。这个思路本身没问题，但别指望一条启动命令就收工。真正会卡住你的往往不是命令写错，而是四件事：这个模型 vLLM 认不认、向量输出方式和离线是不是一套、显存并发怎么估、上线前拿什么自查。

下面按这四关的顺序讲，每关都给判断标准和可执行动作。涉及具体数字、支持列表和参数档位，一律去站内对应页面核对当时的数字，别照搬别人博客里的结论，那些很可能已经过期。

先想清楚：embedding 该不该用 vLLM 起服务

先说结论性的判断：值不值得上这个方案，只看两个问题。有没有持续在线的调用？向量服务和生成模型要不要分开扩缩容？两个答案都是「是」，那就值得起；只要有一个长期是「否」，直接批量跑完更省心。

• 有持续在线的检索请求，且希望向量服务独立于生成模型横向扩缩容，这时候起服务才有意义
• 如果只是给一批文档建一次向量，直接写批量脚本跑完存进向量库，省掉服务进程和端口管理
• 如果你的检索栈已经把 embedding、向量库、重排封装成一个整体，不要绕过它直连底层服务，容易对不上集合名和版本
• 单机单用户、文档量小、查询零星，起服务是负收益，先跑通流程再说

什么情况下不适用：向量条数很小、查询频率很低、你又不打算做在线更新，那这套东西对你就是过度设计。反过来，什么时候必须拆开：生成模型和向量模型抢同一张卡的资源，或者一个要常驻一个要按需扩，这时候拆开是刚需。

第二关：确认这个 embedding 模型能不能被加载

加载前先搞清楚三件事：架构是不是被支持、pooling 方式是哪一种、有没有指令前缀。这三项直接决定你拿到的向量对不对。架构不支持，服务起不来；pooling 搞错，向量能出来但和离线对不上；前缀漏掉，检索质量会悄悄变差，且很难发现。

pooling 方式

把 token 级输出压成一条向量的规则，常见有对有效 token 取均值、取 CLS 位、取最后一个 token；同一套权重换个 pooling，向量空间就变了

指令前缀

有些模型要求查询和文档分别带不同的前缀文本，漏掉或写错，相似度分布会整体偏移

归一化

是否把向量缩放到单位长度；归一化前后算出的余弦和点积结果不一样，检索端必须知道用的是哪套

最大长度

超过这个长度的输入会被截断，截断位置不同，向量也不同

1. 查支持情况先看模型卡里声明的架构和 pooling，再对照 vLLM 的模型支持列表；支持列表会随版本变，去站内模型库页面核对当时的结论，不要凭印象
2. 跑极小样本拿几十条文本先跑一遍，把向量维度、是否归一化、前缀规则、截断长度四项记录下来，作为后面全量重建的基准
3. 交给离线脚本验一遍同一批文本用你原来离线的方式再算一次，比对维度和相似度排序；如果排序差得明显，先别往下走
4. 定下基准配置把上面四项写成一份配置文件，索引侧和查询侧共用，改动必须走版本管理

不适用的情况：模型是多向量输出，或者需要特殊的后处理步骤（比如拼接多个字段再编码），那大概率要走自定义代码路径，别指望标准接口直接跑通。这种时候先确认有没有现成方案，没有就评估自己写的成本。

第三关：把服务起起来，并让向量和离线一致

起服务时重点盯这几项参数：监听地址和端口、模型路径、精度档位、最大长度、pooling 与归一化选项、并发上限。参数含义别猜，去站内接口参数页面逐项对照，尤其是 pooling 和归一化这两项，选错了服务能起来但结果不对。

# 仅示意结构，具体参数名与取值以站内接口参数页为准
# 启动后先用 curl 打一条最小请求，确认返回结构和维度
curl -s http://127.0.0.1:<端口>/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"<模型名>","input":"测试文本"}'

一致性校验没通过就别切流量。做法很简单：拿同一批文本，离线算一遍、新服务算一遍，先比维度和模长，再比 top-k 检索的重合度。重合度不对，说明两边的向量根本不是一个空间，这时候切流量等于把索引作废。

• 检索端要固定输入格式：前缀、截断长度、是否做小写处理，这些规则写在调用侧，别依赖服务端默认值
• 换客户端 SDK 时最容易出的问题是调错端点，先确认对外暴露的是兼容路径还是原生路径
• 批量建索引和单条在线查询两条路都要测，两者的截断行为和延迟不一样
• 改了分词器或截断长度，等价于换了一套向量，必须全量重建索引

不适用的情况也要说清楚：如果你是在做实验、索引可以随时重建，那一致性校验可以放粗一点；但只要索引已经对外提供服务、重建成本高，这一步就不能省。

第四关：显存和并发怎么估，先算再压测

显存分三块看：权重常驻、单次前向的激活与批内张量、给并发留的余量。embedding 模型的输入长度分布通常比对话更极端，短文本和长文档混在一起，所以估算要按长度上限来，不能按平均长度拍脑袋。

1. 单并发测基线先用一条请求跑，记录延迟和显存占用，这是后面所有对比的基准
2. 逐步加并发控制并发往上加，观察 QPS 是否随并发近似线性上升；同时盯显存是否持续爬升不回落
3. 找拐点当 QPS 不再上升或延迟突然抬升，显存持续增长不释放，这个点就是当前配置的上限
4. 换配置重测限最大长度、按长度分桶批处理、调批大小、必要时降精度，每换一次都要重跑一致性校验，别只测吞吐

常用手段就那几个：限制最大长度、把长度接近的请求放到同一批、调整批大小上限、必要时降精度。前三个对结果没影响，最后一个可能影响向量质量，降完必须重新比对检索效果。至于你这张卡在某个模型和精度档位下能带多少并发，去站内部署测算页面按模型与量化档位核对当时的数字，别人机器上的结论参考价值有限。

把服务接进检索链路要注意什么

服务能跑通不代表链路接对了。第一步先确认对外暴露的接口形状：是兼容常见 SDK 的路径，还是原生路径。客户端换个 SDK 就可能调错端点，这是最常见的低级故障，排查起来却最费时间。

• 批量接口用于建索引，单条接口用于在线查询，两条路都要压一遍，确认截断和延迟符合预期
• 先怀疑切分策略和向量模型，检索质量不够时再考虑加重排；一上来堆组件会让问题定位变难
• 如果知识库工具自己管理向量库连接，别绕过它直连服务，否则集合名和版本会对不上
• 给向量服务单独设并发上限，避免和生成模型互相拖慢
• 把服务的健康检查接进检索端，失败时能感知到，而不是等报错才反应过来

不适用的情况：如果你的检索链路已经有一套成熟的网关和重试策略，那这套东西应该挂在网关后面，而不是让每个调用方自己处理超时和重试。

上线前的自查清单与常见坑

常见坑按出现频率排：改完参数忘了重建索引；多实例部署时两个实例参数不一致，请求打到哪个实例结果不一样；把生成模型和向量服务的并发混在同一张卡上互相抢资源；前缀规则只写在服务端默认值里，换个客户端就丢。

• 部署多实例时，用同一份配置启动，并在启动后打一条固定文本比对返回向量是否一致
• 把向量服务的失败降级成关键词检索或直接返回空结果，别让上层接口跟着挂
• 索引重建期间新旧服务可能并存，确保查询侧指向的是同一个版本
• 配置变更要有记录，方便回溯是哪次改动导致召回变化

出问题按这个顺序排查

1. 确认加载成功看服务是否真的把模型加载起来了，模型名和路径是否和你预期的一致，这一步能挡掉一半的低级问题
2. 打最小请求发一条最简单的请求，看返回结构、维度和状态码是否符合预期，先排除接口形状问题
3. 做一致性比对拿同一批文本分别走离线和线上，比对维度、模长和排序，用来区分是服务侧参数问题还是客户端格式问题
4. 看资源曲线看显存和延迟随时间的变化，区分是容量不够还是批处理配置不合理
5. 最后翻日志前四步都过不了再去看框架日志和报错细节，跳过前面直接翻日志通常会绕远

不适用的情况：如果一开始就确认权重本身不被支持，前面几步都会失败，这时候正确的动作是换模型或换框架，而不是继续调参数。把「支持性确认」放在第一步，就是为了避免在这种方向性问题上耗时间。

部署 embedding 服务，麻烦从来不在启动命令，而在向量是不是同一套、配置是不是同一份。