Hugging Face Transformers generate 返回分数怎么验收：output_scores、compute_transition_scores 与长度惩罚

做文本生成评测时，光看 outputs.sequences 往往不够：你还需要知道每个新 token 当时拿了多少分，才能解释候选答案为什么被选中。Hugging Face Transformers 已经提供了现成的验收链路——让 generate 返回每步分数，再用 compute_transition_scores() 把最终序列对应的 token 分数取出来。

先把 generate 的返回值变成可验收结果

最小示例可以用任意支持文本生成的 decoder-only 模型。关键不是模型名称，而是返回值配置。output_scores=True 让结果保留每一步的词表分数，return_dict_in_generate=True 则让这些分数挂在结构化输出对象上。

import numpy as np
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "distilgpt2"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)
inputs = tokenizer("A small robot learns", return_tensors="pt")

outputs = model.generate(
    **inputs,
    max_new_tokens=8,
    return_dict_in_generate=True,
    output_scores=True,
)

print(outputs.sequences.shape)
print(len(outputs.scores))

这里的 outputs.scores 是一个按生成步数排列的 tuple，每个元素的形状通常接近 (batch_size, vocab_size)。它不是“最终答案的一个总分”，而是每一步对整个词表的候选分数。

compute_transition_scores 如何对应到已生成 token

我们真正关心的是最终序列里已经选中的那些 token，而不是每一步整个词表。compute_transition_scores 会沿着生成序列取出对应分数；设置 normalize_logits=True 后，可以把它理解成归一化后的 log probability。

transition_scores = model.compute_transition_scores(
    outputs.sequences,
    outputs.scores,
    normalize_logits=True,
)

input_length = inputs.input_ids.shape[1]
generated_tokens = outputs.sequences[:, input_length:]

for token_id, score in zip(
    generated_tokens[0].tolist(), transition_scores[0].tolist()
):
    token = tokenizer.decode([token_id])
    print(f"{token!r:16} logp={score:.3f} prob={np.exp(score):.2%}")

验收时可以检查两件事：len(outputs.scores) 是否与实际生成步数一致，以及 generated_tokens.shape[1] 是否与分数行数一致。遇到提前生成 eos_token_id 的情况，长度小于 max_new_tokens 是正常结果，不要把它当成丢分。

提示词长度为什么是最容易错的一位

对 GPT 一类 decoder-only 模型，outputs.sequences 通常包含“输入提示词 + 新生成 token”。所以切片起点应是 inputs.input_ids.shape[1]，而不是写死成 1。写死 1 的代码在英文短提示上可能看不出问题，换成长上下文后就会把提示词误当成生成结果。

beam search 下要把 beam_indices 传进去

使用 beam search 时，每一步保留下来的路径可能已经换过 beam。此时只传 sequences 和 scores 不足以恢复路径，应把生成结果里的 beam_indices 一起交给函数。

outputs = model.generate(
    **inputs,
    max_new_tokens=8,
    num_beams=4,
    num_return_sequences=4,
    return_dict_in_generate=True,
    output_scores=True,
)

transition_scores = model.compute_transition_scores(
    outputs.sequences,
    outputs.scores,
    outputs.beam_indices,
    normalize_logits=False,
)

output_length = (transition_scores 

官方示例采用 normalize_logits=False 来复算 beam search 的 sequences_scores；如果只是展示每个 token 的概率，可以用归一化后的分数，但不要把两种分数混在同一个“总分”公式里。

和旧方案相比，应该改哪一层

如果旧代码只调用 model.generate(...) 并接收一个 Tensor，最小改动是打开两个返回配置，再把后处理从“解码完整序列”拆成“切新 token、取 transition score、最后解码”。不必为了拿分数重写模型的 forward。

不过，分数只能解释模型在当前采样或搜索策略下的选择，不能直接当作事实置信度。温度、top-p、重复惩罚、停止条件都会改变生成过程；比较两个版本时，这些参数和 tokenizer 也要固定。

上线前的四项检查

• 固定模型、tokenizer、随机种子和生成参数，记录实际输入 token 数。
• 断言 transition_scores.shape[1] 等于新 token 数，而不是完整序列长度。
• beam search 用 beam_indices，并明确记录 normalize_logits 与 length_penalty。
• 对空输出、提前结束和超长输入分别测一次，避免只测正常样例。

相关问题

为什么没有设置 output_scores 就拿不到分数？

默认生成只保留完成推理所需的结果。需要逐步分数时，必须显式设置 output_scores=True，并用字典式返回值承载它。

transition_scores 是概率还是 log probability？

设置 normalize_logits=True 后，它是归一化后的对数概率；用 np.exp(score) 才能得到对应概率。

为什么我的总分和 sequences_scores 对不上？

常见原因是漏传 beam_indices、输入长度切错，或用归一化分数去复算未归一化的 beam 分数。先把生成策略和长度惩罚固定，再逐项对齐。

小结

generate 的分数验收可以保持很小：打开两个返回开关，用 compute_transition_scores 取最终 token 的分数，decoder-only 模型切掉输入部分，beam search 再补上路径索引和长度惩罚。这样得到的是可复现的生成证据，足够支撑候选比较、回归测试和异常定位。