池化模型¶

vLLM 还支持池化模型，包括嵌入模型、重排序模型和奖励模型。

在 vLLM 中，池化模型实现了 VllmModelForPooling 接口。这些模型使用 [Pooler][vllm.model_executor.layers.Pooler] 来提取输入最终的隐藏状态，然后将其返回。

注意

我们目前支持池化模型主要是为了方便。如兼容性矩阵所示，大多数 vLLM 功能不适用于池化模型，因为它们只在生成或解码阶段工作，因此性能提升可能不会很大。

如果模型没有实现此接口，您可以设置 --task 来告诉 vLLM 将模型转换为池化模型。

`--task`	模型类型	支持的池化任务
`embed`	嵌入模型	`encode`, `embed`
`classify`	分类模型	`encode`, `classify`, `score`
`reward`	奖励模型	`encode`

池化任务¶

在 vLLM 中，我们定义了以下池化任务和相应的 API

任务	API
`encode`	`encode`
`embed`	`embed`, `score`*
`classify`	`classify`
`score`	`score`

*如果模型不支持 score 任务，score API 将回退到 embed 任务。

vLLM 中的每个池化模型都根据 [Pooler.get_supported_tasks][vllm.model_executor.layers.Pooler.get_supported_tasks] 支持一个或多个这些任务。

默认情况下，分配给每个任务的池化器具有以下属性

任务	池化类型	归一化	Softmax
`encode`	`ALL`	❌	❌
`embed`	`LAST`	✅︎	❌
`classify`	`LAST`	❌	✅︎

这些默认值可能会被 vLLM 中模型的实现所覆盖。

加载 Sentence Transformers 模型时，我们尝试根据其 Sentence Transformers 配置文件 (modules.json) 覆盖默认值，该文件优先于模型的默认值。

您可以通过 --override-pooler-config 选项进一步自定义此设置，该选项优先于模型和 Sentence Transformers 的默认值。

注意

如果 vLLM 中模型的实现定义了不基于 PoolerConfig 的自有池化器，则上述配置可能会被忽略。

离线推理¶

LLM 类提供了多种用于离线推理的方法。有关初始化模型时的选项列表，请参阅配置。

`LLM.encode`¶

vLLM 中所有的池化模型都可以使用 encode 方法。它直接返回提取的隐藏状态，这对于奖励模型很有用。

from vllm import LLM

llm = LLM(model="Qwen/Qwen2.5-Math-RM-72B", task="reward")
(output,) = llm.encode("Hello, my name is")

data = output.outputs.data
print(f"Data: {data!r}")

`LLM.embed`¶

embed 方法为每个提示输出一个嵌入向量。它主要为嵌入模型设计。

from vllm import LLM

llm = LLM(model="intfloat/e5-mistral-7b-instruct", task="embed")
(output,) = llm.embed("Hello, my name is")

embeds = output.outputs.embedding
print(f"Embeddings: {embeds!r} (size={len(embeds)})")

代码示例可在此处找到： examples/offline_inference/basic/embed.py

`LLM.classify`¶

classify 方法为每个提示输出一个概率向量。它主要为分类模型设计。

from vllm import LLM

llm = LLM(model="jason9693/Qwen2.5-1.5B-apeach", task="classify")
(output,) = llm.classify("Hello, my name is")

probs = output.outputs.probs
print(f"Class Probabilities: {probs!r} (size={len(probs)})")

代码示例可在此处找到： examples/offline_inference/basic/classify.py

`LLM.score`¶

score 方法输出句子对之间的相似度分数。它为嵌入模型和交叉编码器模型设计。嵌入模型使用余弦相似度，交叉编码器模型在 RAG 系统中作为候选查询-文档对之间的重排序器。

注意

vLLM 只能执行 RAG 的模型推理组件（例如嵌入、重排序）。要在更高级别处理 RAG，您应该使用诸如 LangChain 之类的集成框架。

from vllm import LLM

llm = LLM(model="BAAI/bge-reranker-v2-m3", task="score")
(output,) = llm.score("What is the capital of France?",
                      "The capital of Brazil is Brasilia.")

score = output.outputs.score
print(f"Score: {score}")

代码示例可在此处找到： examples/offline_inference/basic/score.py

在线服务¶

我们的 OpenAI 兼容服务器提供了与离线 API 对应的端点

池化 API 与 LLM.encode 类似，适用于所有类型的池化模型。
嵌入 API 与 LLM.embed 类似，接受文本和多模态输入用于嵌入模型。
分类 API 与 LLM.classify 类似，适用于序列分类模型。
分数 API 与 LLM.score 类似，适用于交叉编码器模型。

Matryoshka 嵌入¶

Matryoshka 嵌入或 Matryoshka 表示学习 (MRL) 是一种用于训练嵌入模型的技术。它允许用户在性能和成本之间进行权衡。

警告

并非所有嵌入模型都使用 Matryoshka 表示学习进行训练。为避免滥用 dimensions 参数，对于尝试更改不支持 Matryoshka 嵌入的模型输出维度的请求，vLLM 会返回错误。

例如，在使用 BAAI/bge-m3 模型时设置 dimensions 参数将导致以下错误。

{"object":"error","message":"Model \"BAAI/bge-m3\" does not support matryoshka representation, changing output dimensions will lead to poor results.","type":"BadRequestError","param":null,"code":400}

手动启用 Matryoshka 嵌入¶

目前没有指定 Matryoshka 嵌入支持的官方接口。在 vLLM 中，如果 config.json 中的 is_matryoshka 为 True，则允许将输出更改为任意维度。使用 matryoshka_dimensions 可以控制允许的输出维度。

对于支持 Matryoshka 嵌入但未被 vLLM 识别的模型，请手动使用 hf_overrides={"is_matryoshka": True}, hf_overrides={"matryoshka_dimensions": [<allowed output dimensions>]}（离线）或 --hf_overrides '{"is_matryoshka": true}', --hf_overrides '{"matryoshka_dimensions": [<allowed output dimensions>]}'（在线）覆盖配置。

以下是一个启用 Matryoshka 嵌入来服务模型的示例。

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

离线推理¶

您可以通过使用 PoolingParams 中的 dimensions 参数来更改支持 Matryoshka 嵌入的嵌入模型的输出维度。

from vllm import LLM, PoolingParams

llm = LLM(model="jinaai/jina-embeddings-v3",
          task="embed",
          trust_remote_code=True)
outputs = llm.embed(["Follow the white rabbit."],
                    pooling_params=PoolingParams(dimensions=32))
print(outputs[0].outputs)

代码示例可在此处找到： examples/offline_inference/embed_matryoshka_fy.py

在线推理¶

使用以下命令启动 vLLM 服务器。

vllm serve jinaai/jina-embeddings-v3 --trust-remote-code

您可以通过使用 dimensions 参数来更改支持 Matryoshka 嵌入的嵌入模型的输出维度。

curl http://127.0.0.1:8000/v1/embeddings \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "Follow the white rabbit.",
    "model": "jinaai/jina-embeddings-v3",
    "encoding_format": "float",
    "dimensions": 32
  }'

预期输出

{"id":"embd-5c21fc9a5c9d4384a1b021daccaf9f64","object":"list","created":1745476417,"model":"jinaai/jina-embeddings-v3","data":[{"index":0,"object":"embedding","embedding":[-0.3828125,-0.1357421875,0.03759765625,0.125,0.21875,0.09521484375,-0.003662109375,0.1591796875,-0.130859375,-0.0869140625,-0.1982421875,0.1689453125,-0.220703125,0.1728515625,-0.2275390625,-0.0712890625,-0.162109375,-0.283203125,-0.055419921875,-0.0693359375,0.031982421875,-0.04052734375,-0.2734375,0.1826171875,-0.091796875,0.220703125,0.37890625,-0.0888671875,-0.12890625,-0.021484375,-0.0091552734375,0.23046875]}],"usage":{"prompt_tokens":8,"total_tokens":8,"completion_tokens":0,"prompt_tokens_details":null}}

一个 OpenAI 客户端示例可在此处找到： examples/online_serving/openai_embedding_matryoshka_fy.py

池化模型¶

池化任务¶

离线推理¶

LLM.encode¶

LLM.embed¶

LLM.classify¶

LLM.score¶

在线服务¶

Matryoshka 嵌入¶

手动启用 Matryoshka 嵌入¶

离线推理¶

在线推理¶

`LLM.encode`¶

`LLM.embed`¶

`LLM.classify`¶

`LLM.score`¶