Transformers generate 怎样区分 output_scores 与 output_logits

在 Transformers 的 generate() 里，output_scores 和 output_logits 都可以保存每个生成步的词表分数，但它们不是同一份数据：output_logits 更接近模型前向计算得到的原始 logits，output_scores 则是经过生成阶段处理后的 prediction scores。要读取这两个字段，还必须打开 return_dict_in_generate=True，否则通常只会得到序列张量。

官方地址：https://huggingface.co/docs/transformers/main_classes/text_generation

如果目标是分析模型原始偏好，优先看 output_logits；如果目标是解释实际生成过程、计算生成序列分数或观察采样处理后的结果，优先看 output_scores。两者都要保存时可以同时打开，但会增加显存和内存占用。

先让 generate 返回结构化对象

默认调用更关注最终文本，返回值可能只是序列张量。需要读取中间字段时，先把 return_dict_in_generate 设为 True。这个开关让返回值变成 Transformers 的生成输出对象，后续可以用属性名访问 sequences、scores 或 logits。

from transformers import AutoModelForCausalLM, AutoTokenizer

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

inputs = tokenizer("A small example", return_tensors="pt")
generation = model.generate(
    **inputs,
    max_new_tokens=8,
    return_dict_in_generate=True,  # 返回带字段的生成输出对象
    output_scores=True,             # 保存每一步经过生成处理的分数
    output_logits=True,             # 保存每一步未处理的原始 logits
)

print(generation.sequences.shape)  # 生成后的 token 序列
print(len(generation.scores))      # 最多对应 max_new_tokens 个生成步
print(len(generation.logits))      # 与 logits 保存开关对应的生成步

上面的代码只展示返回结构。scores 和 logits 是否存在，取决于对应开关；return_dict_in_generate 没有打开时，即使设置了输出开关，也不能按字段方式读取它们。

output_scores 与 output_logits 到底差在哪里

官方生成输出文档把 scores 描述为经过处理的 prediction scores，把 logits 描述为未处理的 prediction logits。这里的“处理”可以理解为生成阶段为了实现贪心、采样、温度、top-k 或 top-p 等策略而作用在候选分数上的那一层；它不是模型训练过程中的梯度，也不是已经归一化后的概率。

两个字段都不是概率。如果要把分数转成概率，必须明确自己要解释的是原始 logits 还是处理后的 scores，再决定是否在对应维度上做 softmax；不要把字段名里的 score 直接理解成百分比。

怎样理解每一步的返回形状

对于 decoder-only 模型，generation.logits 和 generation.scores 通常都是 tuple。tuple 的每个元素对应一个生成步，每个元素再按批次和词表保存一张分数表，常见形状可以理解为 (batch_size, vocab_size)。输入提示词的 token 不会按同样方式重复出现在每一个生成步的 tuple 中。

step_scores = generation.scores
step_logits = generation.logits

if step_scores:
    first_step_scores = step_scores[0]
    print(first_step_scores.shape)  # 第一生成步的 batch 与词表维度

if step_logits:
    first_step_logits = step_logits[0]
    print(first_step_logits.shape)  # 原始 logits 使用相同的步级索引方式

如果使用 encoder-decoder 模型，返回类型和部分字段会随模型结构变化；写通用工具时应先判断字段是否为 None，不要把 decoder-only 的形状假设硬编码到所有模型。

按任务选择 scores 还是 logits

想解释实际生成路径：选 scores

当你要解释为什么某个 token 在当前生成策略下被选中，或者要配合 Transformers 提供的序列分数计算辅助方法时，scores 更贴近生成过程。它反映的是生成处理之后参与决策的分数，但仍然要结合具体的解码器和参数解读。

想比较模型原始偏好：选 logits

当你在比较不同提示词、不同输入或不同模型的原始候选分布时，logits 更合适。它没有承载后续生成策略对候选集合的改变，因此更适合做模型前向输出层面的分析。

两者都需要：同时开启并控制保存范围

排查生成策略影响时可以同时设置两个开关，再对同一个生成步、同一个 batch 项和同一个 token 做对照。文章示例使用了很短的 max_new_tokens，实际长文本任务应评估显存、CPU 内存和序列长度，避免为了调试字段让生产请求承担不必要的保存成本。

常见误区

• 只设置 output_scores=True，却没有设置 return_dict_in_generate=True，最后按字段读取时发现返回对象不符合预期。
• 把 scores 当成概率，直接拿来当百分比展示；它仍然是分数，需要明确归一化方法和解释口径。
• 把 output_scores 与 output_logits 当成“一个旧字段、一个新字段”；它们的核心区别是生成处理边界，而不是命名版本。
• 只看 tuple 长度就断言一定等于 max_new_tokens；序列可能提前遇到结束条件，实际步数也会受生成配置影响。

小结

记住三点即可：第一，读取中间生成信息要打开 return_dict_in_generate=True；第二，output_logits 保留未处理的模型预测分数，output_scores 保存生成阶段处理后的分数；第三，做实际生成路径或序列分数分析时看 scores，做原始模型偏好对比时看 logits。两者同时打开适合诊断，但不应成为所有线上请求的默认配置。

相关问题

output_scores 返回的是概率吗？

不是。它是生成阶段处理后的分数，是否归一化、怎样归一化要结合具体分析目标决定。

为什么 generation.logits 为空？

通常是因为没有设置 output_logits=True，或者返回对象没有按结构化生成输出方式使用；先检查两个开关和返回类型。

output_scores 和 output_logits 可以同时打开吗？

可以。两者是独立的输出开关，但会保存更多中间张量，应限制生成长度并关注内存成本。