vLLM 自定义 Logits Processor 实战:从批级接口到请求级适配器的完整指南

原创2026-09-06 12:26:051,852 阅读
文章标签:推理引擎模型推理服务人工智能大模型深度学习模型量化模型优化本地部署多模态

vLLM 自定义 Logits Processor 实战:从批级接口到请求级适配器的完整指南

本篇指南基于 vLLM 仓库中的 examples/features/logits_processor/README.md 及其配套示例脚本,讲解如何在离线推理中注入自定义 logits processor,在采样前改写模型的输出分布。读完本文,你将掌握三种官方示例模式——批级(batch-level)processor、请求级(request-level)processor 的包装、以及需要访问引擎配置的构造器增强包装——并能理解其底层的批状态同步机制、参数校验链路与平台兼容限制。

Logits processor 的定位是在每个 decode step 的 forward 之后、采样之前,对 batch 的 logits 张量(形状为 [batch_size, vocab_size])做任意修改,从而实现 token 屏蔽(token masking)、受限解码、自定义采样策略等受控生成行为。vLLM 出于效率考虑在批级处理 logits,因此如果你的 processor 天然只针对单个请求(例如依赖每请求自定义参数),就需要按仓库示例所示的方式做适配包装。

核心接口:LogitsProcessor 抽象基类与 BatchUpdate

自定义 processor 的实现依据是 vllm/v1/sample/logits_processor/interface.py 中定义的抽象基类 LogitsProcessor(见 LogitsProcessor 定义),它有四个必须关注的方法和一个可选钩子:

方法 说明
__init__(vllm_config, device, is_pin_memory) 构造器。vLLM 的接口要求这三个参数必须存在,即使不使用也要保留
apply(logits) 对整个 batch 的 logits 张量做修改,返回更新后的张量(允许就地修改)
update_state(batch_update) 在每次 forward 之前、批组成发生变化时被调用,用于同步每请求状态
is_argmax_invariant() 声明该 processor 是否影响贪心采样(temperature=0)下的 argmax 结果
validate_params(sampling_params)(类方法,可选) 校验采样参数,非法时可抛出 ValueError,引擎边界会将其转换为 VLLMValidationError,在线服务中表现为 HTTP 400

批状态变化的载体是 BatchUpdate 冻结数据类(BatchUpdate 定义):

  • batch_size:当前 persistent batch 中的请求数;
  • removed:被移除请求的批索引序列;
  • added:新增请求的四元组 (index, params, prompt_tok_ids, output_tok_ids)。注意 output_tok_ids 是该请求运行中输出 token 列表的引用,processor 通过它始终能看到最新的已生成 token;
  • moved:批内请求移动的三元组 (index 1, index 2, directionality),方向性区分单向移动(UNIDIRECTIONAL)与双向交换(SWAP)。

BatchUpdate 由 BatchUpdateBuilder 在调度过程中累积并生成;当批组成无变化时,update_state 收到的参数为 None。

注册方式:类对象、FQCN 字符串与插件入口

通过离线推理入口 LLM 的 logits_processors 参数注入自定义 processor(该参数定义见 entrypoints/llm.py):

from vllm import LLM

llm = LLM(
    model="facebook/opt-125m",
    logits_processors=[DummyLogitsProcessor],   # 传入类,而非实例
)

加载逻辑集中在 build_logitsprocs。从源码结构看,最终生效的 processor 集合按以下顺序拼接:

  1. 内建 processors:MinTokensLogitsProcessor、LogitBiasLogitsProcessor、MinPLogitsProcessor(BUILTIN_LOGITS_PROCESSORS),分别支撑 min_tokens、logit_bias、min_p 等采样参数;
  2. 插件形式的 processors:通过 entry point 组 vllm.logits_processors 从已安装包动态加载(_load_logitsprocs_plugins),便于以独立分发的形式提供 processor;
  3. 用户显式指定的 processors:logits_processors 参数可以是混合列表——既可以直接传入已加载的 LogitsProcessor 子类,也可以传完全限定类名字符串(FQCN),语法为 <module>:<type>,例如 "my_pkg.logitproc:MyProcessor",由 _load_logitsprocs_by_fqcns 负责导入并逐级定位类对象。

实例化时 vLLM 会对每个类调用 ctor(vllm_config, device, is_pin_memory),并把实例按 is_argmax_invariant() 的返回值分桶到 LogitsProcessors 容器的 argmax_invariant / non_argmax_invariant 两个列表中——这一分桶意味着在贪心采样路径下,argmax 不变的 processor 可以被跳过,属于接口设计上的性能考量。

此外,每次提交请求时,引擎会遍历所有已加载的 processor 并调用其 validate_params(sampling_params) 做参数校验(validate_logits_processors_parameters)。

示例一:批级 processor(custom.py)

examples/features/logits_processor/custom.py 演示直接实现批级接口。示例中的 DummyLogitsProcessor 的行为是:当请求通过 SamplingParams.extra_args 传入 target_token 时,屏蔽除该 token 外的所有 logits,使每一步都只解码出目标 token。

python examples/features/logits_processor/custom.py

核心实现拆解:

from vllm import LLM, SamplingParams
from vllm.config import VllmConfig
from vllm.v1.sample.logits_processor import (
    BatchUpdate,
    LogitsProcessor,
)
from vllm.v1.sample.logits_processor.builtin import process_dict_updates


class DummyLogitsProcessor(LogitsProcessor):
    """Fake logit processor to support unit testing and examples"""

    @classmethod
    def validate_params(cls, params: SamplingParams):
        target_token: Any | None = params.extra_args and params.extra_args.get(
            "target_token"
        )
        if target_token is not None and not isinstance(target_token, int):
            raise ValueError(
                f"target_token value {target_token} {type(target_token)} is not int"
            )

    def __init__(
        self, vllm_config: VllmConfig, device: torch.device, is_pin_memory: bool
    ):
        self.req_info: dict[int, int] = {}   # 批索引 -> 目标 token id

    def is_argmax_invariant(self) -> bool:
        return False   # 屏蔽 token 会改变贪心采样的 argmax 结果

    def update_state(self, batch_update: BatchUpdate | None):
        def extract_extra_arg(params: SamplingParams) -> int | None:
            self.validate_params(params)
            return params.extra_args and params.extra_args.get("target_token")

        process_dict_updates(
            self.req_info,
            batch_update,
            # 根据请求细节计算 per-request 状态;返回 None 表示该
            # processor 不适用于此请求
            lambda params, _, __: extract_extra_arg(params),
        )

    def apply(self, logits: torch.Tensor) -> torch.Tensor:
        if not self.req_info:
            return logits

        # 保存目标位置的原值
        cols = torch.tensor(
            list(self.req_info.values()), dtype=torch.long, device=logits.device
        )
        rows = torch.tensor(
            list(self.req_info.keys()), dtype=torch.long, device=logits.device
        )
        values_to_keep = logits[rows, cols].clone()

        # 整行置 -inf,再恢复目标 token
        logits[rows] = float("-inf")
        logits[rows, cols] = values_to_keep

        return logits

几个实现要点值得注意:

  • process_dict_updates 工具函数(builtin.py 实现)是批级 processor 的状态同步脚手架:它按照 added → removed → moved 的顺序维护一个 dict[批索引, 状态]。你只需提供一个 new_state 回调——根据 SamplingParams(以及可选的 prompt ids、输出 ids)返回该请求的状态,返回 None 即表示 processor 对该请求不生效。新增、移除、交换请求都会自动反映到字典中,这正是批级接口能"只影响部分请求"的关键。
  • apply 的批量语义:logits 的第一维索引与 persistent batch 中的请求一一对应,因此通过 rows/cols 索引张量可以一次处理所有命中请求,避免逐请求循环。
  • 混合批构造:示例构造了 4 条 prompt,其中 50% 的请求携带 target_token(取值 128 与 67),其余请求不带该参数。由于 temperature=0.0,带参数的请求每步都输出同一个 token(如 token 67 在 OPT 词表中对应 also),不带参数的请求则正常贪心解码。示例头部 docstring 中给出的预期输出即体现了这种对比。
prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]
sampling_params_list = [
    SamplingParams(temperature=0.0, extra_args={"target_token": 128}),
    SamplingParams(temperature=0.0),
    SamplingParams(temperature=0.0, extra_args={"target_token": 67}),
    SamplingParams(temperature=0.0),
]

llm = LLM(model="facebook/opt-125m", logits_processors=[DummyLogitsProcessor])
outputs = llm.generate(prompts, sampling_params_list)

示例二:包装请求级 processor(custom_req.py)

如果你的 processor 是按"单请求"粒度编写的——比如经典的 f(output_ids, logits) -> logits 签名——直接塞给批级接口并不合适。examples/features/logits_processor/custom_req.py 演示了如何用 AdapterLogitsProcessor 基类(AdapterLogitsProcessor 实现)把它适配为批级 processor:

python examples/features/logits_processor/custom_req.py
from vllm.v1.sample.logits_processor import (
    AdapterLogitsProcessor,
    RequestLogitsProcessor,
)


class DummyPerReqLogitsProcessor:
    """请求级 processor:屏蔽除 target_token 外的所有 logits"""

    def __init__(self, target_token: int) -> None:
        self.target_token = target_token

    def __call__(
        self,
        output_ids: list[int],
        logits: torch.Tensor,
    ) -> torch.Tensor:
        val_to_keep = logits[self.target_token].item()
        logits[:] = float("-inf")
        logits[self.target_token] = val_to_keep
        return logits


class WrappedPerReqLogitsProcessor(AdapterLogitsProcessor):
    @classmethod
    def validate_params(cls, params: SamplingParams):
        target_token: Any | None = params.extra_args and params.extra_args.get(
            "target_token"
        )
        if target_token is not None and not isinstance(target_token, int):
            raise ValueError(f"target_token value {target_token} is not int")

    def is_argmax_invariant(self) -> bool:
        return False

    def new_req_logits_processor(
        self,
        params: SamplingParams,
    ) -> RequestLogitsProcessor | None:
        target_token: Any | None = params.extra_args and params.extra_args.get(
            "target_token"
        )
        if target_token is None:
            return None    # 未提供 target_token 的请求不应用该 processor
        return DummyPerReqLogitsProcessor(target_token)

适配器的使用约定(源码 docstring 明确要求):

  1. 子类化 AdapterLogitsProcessor;
  2. 实现抽象方法 new_req_logits_processor(params):根据该请求的 SamplingParams 返回一个定制化的请求级 processor 实例;返回 None 表示跳过该请求;
  3. 实现 is_argmax_invariant();
  4. 一般不需要覆写 __init__。

从 AdapterLogitsProcessor 的实现 看,基类替你完成了全部批级簿记:

  • update_state 内部仍走 process_dict_updates,其 new_state 回调调用你的 new_req_logits_processor,并把结果封装成 functools.partial 存进 req_info(批索引 → partial 的映射);
  • partial 会预填充已生成 token 列表作为入参。这里有一个签名自适应细节:如果请求级 processor 的 __call__ 接受 3 个参数(即 f(prompt_ids, output_ids, logits) 形式),基类会要求提供 prompt token ids 并一并传入;2 参形式则只传 output_ids;
  • apply 时逐行取 logits[req_idx] 交给对应请求的 processor,若返回了新张量则回填到原行。由于 partial 持有输出 token 列表的引用,processor 每步看到的 output_ids 始终是该请求截至当前的完整生成序列。

示例三:需要引擎配置的请求级包装(custom_req_init.py)

examples/features/logits_processor/custom_req_init.py 覆盖一种特殊场景:请求级 processor 在初始化阶段就需要引擎配置或设备信息(例如按平台类型启用/禁用)。此时子类必须覆写包装基类的 __init__(vllm_config, device, is_pin_memory),且覆写中应调用 super().__init__(...):

python examples/features/logits_processor/custom_req_init.py
class WrappedPerReqLogitsProcessor(AdapterLogitsProcessor):
    """示例:覆写 __init__ 以获取设备类型信息"""

    @classmethod
    def validate_params(cls, params: SamplingParams):
        target_token = params.extra_args and params.extra_args.get("target_token")
        if target_token is not None and not isinstance(target_token, int):
            raise ValueError(
                f"`target_token` has to be an integer, got {target_token}."
            )

    def __init__(
        self, vllm_config: VllmConfig, device: torch.device, is_pin_memory: bool
    ):
        super().__init__(vllm_config, device, is_pin_memory)
        self.is_cuda = device.type == "cuda"   # 在构造期固化平台判断

    def is_argmax_invariant(self) -> bool:
        return False

    def new_req_logits_processor(
        self,
        params: SamplingParams,
    ) -> RequestLogitsProcessor | None:
        if (
            not self.is_cuda
            or (
                target_token := params.extra_args
                and params.extra_args.get("target_token")
            )
            is None
        ):
            return None
        return DummyPerReqLogitsProcessor(target_token)

示例用"非 CUDA 平台自动禁用 processor"建模了一个真实需求:is_argmax_invariant() 与 new_req_logits_processor 的决策逻辑依赖 device。预期行为是——在 CUDA 设备上,带 target_token 的请求每步重复同一 token;而在非 CUDA 设备上,第 1、3 条请求会退化为正常贪心解码,因为 processor 对这些请求返回了 None。除构造器之外,脚本的 prompts / sampling_params_list / main() 结构与示例二完全一致,可直接对照阅读。

关键概念对照与源码佐证

批级 vs 请求级的选择:vLLM 在 persistent batch 上以批级处理 logits,这是吞吐效率的前提。若你的 processor 逻辑天然按请求隔离(如每请求一个约束求解器、一个 token 过滤器),推荐走 AdapterLogitsProcessor 路线,把批簿记交给基类;只有当你需要在多个请求的 logits 行间做联合计算(跨行归一化、批量掩码等)时,才值得直接实现批级 LogitsProcessor 接口并利用索引张量做批量操作。

SamplingParams.extra_args 传参约定:三个示例都通过 extra_args={"target_token": ...} 以请求粒度传递自定义参数。这是一个通用透传字典,vLLM 本身不消费其中的键,只负责原样带到 processor 侧;这也是为什么每个 processor 都要在 validate_params 中自行校验类型(示例中校验 target_token 必须是 int)。

DummyLogitsProcessor 参考实现:按示例脚本的说明,DummyLogitsProcessor 同时存在于一份测试参考实现中(vllm/test_utils.py),可以作为编写自定义 processor 的起点。本目录三个示例脚本内联了各自的简化版本,逻辑与其一致。

内建 processor 的对照参考:vLLM 内建的 MinPLogitsProcessor、LogitBiasLogitsProcessor、MinTokensLogitsProcessor 本身就展示了批级接口的最佳实践——例如 MinPLogitsProcessor 用 pinned CPU 张量 + 异步 H2D 拷贝批量同步每请求的 min_p 值,LogitBiasLogitsProcessor 用 async_tensor_h2d 把偏置压平为一维索引张量后一次性 logits[rows, cols] += bias。阅读它们对写出高性能自定义 processor 有直接参考价值。

使用限制与兼容性边界

以下限制均可在 build_logitsprocs 源码 及 _load_custom_logitsprocs 中确认:

  • Pooling 模型不支持:对 embedding/pooling 类模型初始化 logits_processors 会直接抛出 "Pooling models do not support custom logits processors." 的 ValueError,且此时跳过全部 logits processor 加载;
  • 与推测解码互斥:启用 speculative decoding 时,自定义 logits processor 会触发 ValueError(提示 "Custom logits processors are not supported when speculative decoding is enabled."),并且 min_p、logit_bias 参数在此模式下同样不生效(引擎仅保留 MinTokensLogitsProcessor 处理 min_tokens);
  • TPU 平台暂不支持:当前 V1 TPU 路径下 _load_custom_logitsprocs 直接返回空列表,自定义 logits processor 不会被加载;
  • 参数校验异常语义:validate_params 中抛出的 ValueError 会在引擎边界被转换为 VLLMValidationError,在线服务场景下对应 HTTP 400 响应,而不是进程级错误。

此外,logits_processors 参数本身允许"类对象 + FQCN 字符串"混合列表(如 [MyProcessor, "pkg.mod:AnotherProcessor"]),加载失败会带原始异常链抛出 RuntimeError,便于定位导入错误。

小结:文件清单与延伸阅读

围绕本主题,仓库中值得深入阅读的文件:

文件 作用
examples/features/logits_processor/README.md 本指南对应的原始说明文档
examples/features/logits_processor/custom.py 批级 processor 完整示例
examples/features/logits_processor/custom_req.py 请求级 processor 的适配器包装示例
examples/features/logits_processor/custom_req_init.py 构造期依赖引擎配置/设备的包装示例
vllm/v1/sample/logits_processor/interface.py LogitsProcessor 抽象基类与 BatchUpdate 定义
vllm/v1/sample/logits_processor/init.py 加载链、build_logitsprocs、AdapterLogitsProcessor
vllm/v1/sample/logits_processor/builtin.py 内建 processor 与 process_dict_updates 工具
vllm/v1/sample/logits_processor/state.py BatchUpdateBuilder 与 LogitsProcessors 容器
docs/features/logits_processors.md 面向用户的 Logits Processor 特性文档

落地路径建议:先复制 custom.py 的批级骨架把 apply/update_state 跑通,再按需切换到 custom_req.py 的适配器模式降低状态管理成本;如果构造期需要引擎信息,则参照 custom_req_init.py 覆写 __init__。编写前务必核对 pooling / 推测解码 / TPU 三类限制,并在 validate_params 中显式校验 extra_args 的类型与取值,这样自定义 processor 才能安全地进入 vLLM 的批采样流水线。

登录后查看全文
vllm