vLLM 部署嵌入与重排模型：搭建 RAG 管道

用 vLLM 分别部署嵌入与重排模型，接入 RAG 的索引生成、候选召回、重排和服务联调流程，并说明模型选择、端点配置、验证方法与常见错误。

vLLM 可以分别部署嵌入模型和重排模型：嵌入端点包括 Cohere 风格的 /v2/embed 和 OpenAI 兼容的 /v1/embeddings，见 Pooling Models 文档。重排端点为 /rerank、/v1/rerank 和 /v2/rerank；按照 Scoring Usages 文档，它只承担嵌入生成和重排推理，索引、召回及流程编排仍由应用负责。单个服务进程一次只托管一个模型，因此嵌入与重排应拆成独立进程，并分配不同端口。

安装 vLLM 与准备运行环境

按 Quickstart 文档，运行前提是 Linux 和 Python 3.10 至 3.13。Windows 不受原生支持，GPU 安装文档给出的路径是在兼容 Linux 发行版中使用 WSL；使用 NVIDIA GPU 时，其计算能力须达到 7.5 或更高。

建议使用全新环境安装。Quickstart 给出的 uv 命令会创建 Python 3.12 虚拟环境，--torch-backend=auto 可根据已安装的 CUDA 驱动版本选择 PyTorch 索引：

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

部署嵌入模型

按 Embedding Usages 文档，虽然可以用 --convert embed 自动转换模型，但若要取得更好的嵌入结果，应优先选择专门按嵌入任务训练的模型。下面是文档提供的 Matryoshka 启动示例：

vllm serve Snowflake/snowflake-arctic-embed-m-v1.5 --hf-overrides '{"matryoshka_dimensions":[256]}'

这里的 --hf-overrides 手动允许 256 维输出。索引程序随后通过选定的嵌入端点生成向量，并把向量与文档标识、来源等元数据写入你自己的索引或向量存储。

部署重排模型

Scoring Usages 文档列出的 scoring 模型类型包括 cross-encoder、late-interaction 和 bi-encoder；重排接口采用 Jina AI 与 Cohere 的 API 形态。启动前先按项目当前兼容列表确认模型，不要假定任意生成模型都能作为重排模型加载。

如需明确指定 pooling 模式，可加入 --runner pooling；Pooling Models 文档同时说明，自动检测通常使这个参数并非必需。可使用下面的占位模板：

vllm serve YOUR_VALUE --runner pooling --port YOUR_VALUE

第一个 YOUR_VALUE 填模型 ID，第二个填与嵌入服务不同的端口。不要固定照抄示例模型名称，应以当前项目文档为准。

搭建 RAG 管道

应用侧可以按下面的职责拆分：

建立索引：切分文档，通过 /v1/embeddings 或 /v2/embed 生成向量，保存向量及定位原文所需的元数据。
召回候选：从自有索引中检索相关片段。向量数据库、过滤规则和候选数量由你的应用控制。
重排候选：把查询和召回片段提交给 /rerank、/v1/rerank 或 /v2/rerank，再按返回顺序整理结果。
组织生成：把重排后的上下文交给下游生成应用。这里描述的是管道结构，不代表这些编排能力由模型服务自动完成。

验证服务是否联通

先检查已启动的模型：

curl http://localhost:8000/v1/models

输出中应能找到当前进程实际加载的模型 ID。随后按照所选嵌入或重排 API 的当前请求结构发送一条最小请求：嵌入客户端应取得用于写入索引的向量，重排客户端应取得能够继续传给下游的排序结果。

检查重排服务时，要把客户端基础地址改为它的独立端口。若模型列表正常但业务请求失败，优先核对路径、请求结构和模型任务是否匹配。

常见故障

重排服务无法访问

单进程不能同时托管嵌入和重排模型。为两种角色分别启动进程，并确认端口没有冲突；客户端也应指向对应服务，而不是继续请求嵌入服务的端口。

修改嵌入维度时报错

根据 Embedding Usages 文档，不支持 Matryoshka Embeddings 的模型在请求改变输出维度时会返回错误。只有模型具备相应支持时，才能通过 --hf-overrides 手动开放目标维度。

显存参数没有按预期生效

vllm serve 参数参考说明，--max-model-len 覆盖提示词与输出 token 的总上下文长度；不设置时会从模型配置推导。另一个参数 --gpu-memory-utilization 未指定时默认使用 0.92，而且它是单实例限制。

同一 vllm serve 参数参考还说明，设置 --kv-cache-memory-bytes 后会覆盖 gpu_memory_utilization 的作用。同一 GPU 上的实例可以分别设置内存比例，但具体数值必须结合模型与实际运行状态判断，不能把参数示例当成容量保证。

本文步骤依据正文链接的官方文档整理，未运行或测量任何模型；使用前请按当前版本核对。