Transformers LogitsProcessorList 怎样组合生成分数处理规则

当生成任务同时需要“不能太早结束”“不要出现某些词”“还要让 beam search 使用可解释的分数”时，最容易出现的问题不是缺少某一个处理器，而是把规则散落在生成调用外，最后无法说明它们怎样共同改变候选 token。LogitsProcessorList 的作用很集中：它保存多个 LogitsProcessor，每次调用时按列表顺序把处理后的 scores 交给下一个处理器。

官方地址：https://huggingface.co/docs/transformers/en/internal/generation_utils

LogitsProcessorList 解决的是规则组合，不是模型本身

官方定义里，LogitsProcessor 是一个可以在生成过程中修改预测分数的抽象基类。它接收 input_ids 与 scores，返回形状仍为批次乘词表大小的处理后分数；LogitsProcessorList 则继承列表，并增加一个把这些处理器依次调用的方法。

因此可以把一次生成理解成三个边界：模型或生成器提供当前的 input_ids 和原始 scores；列表中的规则依次改写候选分数；生成策略再根据最终分数选择下一 token。列表本身不替换模型，也不改变 tokenizer 的词表。

先组合最小长度和禁用词规则

一个容易维护的组合可以从两个互不重复的目标开始：用 MinLengthLogitsProcessor 处理过早结束，用 NoBadWordsLogitsProcessor 屏蔽不允许出现的 token 序列。前者关注 EOS，后者关注指定序列；它们都不需要你手动改模型输出。

from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    LogitsProcessorList,
    MinLengthLogitsProcessor,
    NoBadWordsLogitsProcessor,
)

model_name = "distilbert/distilgpt2"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

bad_words = [" forbidden"]
bad_words_ids = [
    tokenizer(text, add_special_tokens=False).input_ids
    for text in bad_words
]

processors = LogitsProcessorList([
    MinLengthLogitsProcessor(
        min_length=32,
        eos_token_id=tokenizer.eos_token_id,
    ),
    NoBadWordsLogitsProcessor(
        bad_words_ids=bad_words_ids,
        eos_token_id=tokenizer.eos_token_id,
    ),
])

inputs = tokenizer("A short explanation:", return_tensors="pt")
outputs = model.generate(
    **inputs,
    logits_processor=processors,
    max_new_tokens=80,
)

# 只把生成结果交给 tokenizer 解码，便于观察规则组合后的文本。
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

这里的关键不在于参数数值，而在于对象边界。bad_words_ids 必须由同一个 tokenizer 产生，否则“禁用词”可能对应错误的 token 序列；eos_token_id 也应来自当前模型配置。代码块中的处理器只负责分数规则，模型仍然负责产生候选分数。

规则顺序决定最终分数

列表不是无序配置表。可以把它看成一串相邻的变换：第一个处理器收到原始 scores，返回值进入第二个处理器，直到最后一个处理器返回结果。一个规则若把某个位置设为负无穷，后续规则通常不会把这个已经屏蔽的 token 重新变成可选项；因此硬约束应当和软调整分开思考。

如果要在规则链里加入归一化，可以把 LogitNormalization 放在分数变换完成之后。官方说明特别提到，beam search 在应用处理器或 warper 后仍可能需要重新归一化；如果只是让生成策略继续选择 token，则不要把“看起来像概率”误认为处理器已经完成了概率归一化。

把列表传给 generate，或单独调用它观察边界

在完整生成中，把列表作为 logits_processor 传给 generate 即可。若正在编写自定义生成循环，也可以直接用 processors(input_ids, scores) 获得处理后的分数。第二种写法适合确认某个规则的输入输出形状，但不应把它当成一次完整生成。

import torch
from transformers import LogitsProcessorList

def apply_rules(processors: LogitsProcessorList, input_ids: torch.Tensor,
                scores: torch.Tensor) -> torch.Tensor:
    # 列表会按顺序把上一层的返回值传给下一层。
    processed = processors(input_ids, scores)
    # 保留统一的张量返回值，调用方再交给采样或搜索策略。
    return processed

直接调用时，input_ids 的批次维度和 scores 的批次维度必须对应，词表维度也要与模型输出一致。若某个自定义处理器声明了额外参数，列表调用支持通过 kwargs 传入与该处理器匹配的参数；不要把不属于处理器签名的字段随意塞进调用。

自定义处理器只做一个清楚的分数动作

内置规则覆盖不了业务约束时，可以继承 LogitsProcessor。建议一个自定义类只负责一件事，例如在达到某个输入长度后屏蔽一个 token。这样组合时可以清楚判断它放在硬约束前还是后，也便于在问题出现时单独移除。

import torch
from transformers import LogitsProcessor, LogitsProcessorList

class BlockTokenAfterLength(LogitsProcessor):
    def __init__(self, token_id: int, start_length: int):
        self.token_id = token_id
        self.start_length = start_length

    def __call__(self, input_ids: torch.Tensor,
                 scores: torch.Tensor) -> torch.Tensor:
        # 达到长度边界后，只屏蔽一个指定 token，其余分数保持不变。
        if input_ids.shape[1] >= self.start_length:
            scores[:, self.token_id] = -float("inf")
        return scores

processors = LogitsProcessorList([
    BlockTokenAfterLength(token_id=123, start_length=16),
])

这个示例没有运行模型，也没有声称某个 token id 在所有 tokenizer 中都代表同一文本。真实项目里应先由当前 tokenizer 得到 id，再把它注入处理器。修改 scores 时也要保持设备、批次和词表维度一致。

组合失效时从四个边界排查

最后可以按最小组合逐个加回：先只保留一个处理器，确认它的输入和目标边界，再加入第二个规则，最后才接入自定义处理器与归一化。这样排查的是分数处理链本身，不会把模型采样差异、tokenizer 分词差异和规则顺序混在一起。

常见问题

LogitsProcessorList 会不会改变模型的原始 logits？

它不会改变模型参数，也不负责生成原始 logits；它在生成过程中接收当前分数并返回处理后的分数。

两个处理器的先后顺序可以随便交换吗？

不能一概而论。列表会按顺序处理，硬屏蔽、分数调整和归一化的组合结果可能不同，应按每个处理器的职责安排。

为什么禁用词参数不是普通字符串列表？

NoBadWordsLogitsProcessor 需要 token id 序列，因为模型选择的是词表 token。应使用当前 tokenizer 编码禁用词，并注意前导空格和特殊 token 设置。

什么时候需要 LogitNormalization？

当后续策略或应用需要把处理后的分数按对数概率解释，尤其是 beam search 场景，可以在其它分数规则完成后考虑归一化。

把 LogitsProcessorList 当作“可读的分数规则链”即可：每个处理器负责一个边界，列表顺序表达组合关系，模型与 tokenizer 继续保持自己的职责。这样新增规则时，只需说明它修改什么分数、依赖哪些输入，以及应该位于哪一个处理器之前或之后。