Token 准确率（Mean Token Accuracy）是 TRL SFTTrainer 在训练日志中默认记录的指标之一，表示在参与 loss 的非掩码 token 上，模型 top-1 预测是否与标准答案 token 完全一致 的比例。
段末注释：top-1 指模型 softmax 后概率最高的 token；与「整句语义正确」或「分类标签正确」不是同一概念。
系列索引：微调评估指标导读
一、直观含义
在每个被监督的 token 位置，问一个 Yes/No 问题：
模型概率最高的那个 token，是不是标注里的 token？
对所有这样的位置取平均，得到 mean_token_accuracy。
- 0.94：约 94% 的被监督 token 上，模型「猜对」了下一个 token。
- 对「只生成一个标签词」的 SFT 任务，该指标与「学没学会输出标签」高度相关。
- 对长回答生成，高 token accuracy 仍可能出现「前面都对、最后一句跑偏」的情况。
二、使用场景与所需数据
| 场景 | 适用性 |
|---|---|
| SFT 训练过程监控 | 高 — Trainer 自动输出 |
| 短 completion / 单标签生成 | 高 — 与任务成功率强相关 |
| 长文本开放生成 | 中 — 必要但不充分 |
| 最终上线验收 | 低 — 需换任务级指标 |
数据要求：与 eval_loss 相同；仅统计 label ≠ -100 的位置。completion_only_loss=True 时，不含 prompt 段 token。
三、计算方式
3.1 定义
设参与监督的位置集合为 (\mathcal{T})，(\hat{y}t = \arg\max p\theta(\cdot \mid y_{<t}))：
$$
\text{mean_token_accuracy} = \frac{1}{|\mathcal{T}|} \sum_{t \in \mathcal{T}} \mathbb{1}[\hat{y}_t = y_t]
$$
3.2 与 loss 的区别
| mean_token_accuracy | eval_loss | |
|---|---|---|
| 粒度 | 硬分类对错 | 软概率质量 |
| 错但接近 | 算错 | 给次高概率时 loss 可能不大 |
| 对 | 算对 | 概率 0.6 和 0.99 的 loss 不同 |
示例：正确 token 概率 0.51、错误 token 0.49 → accuracy 计为对（top-1 命中），loss 仍偏高。
3.3 日志中的字段
SFTTrainer.train() 返回的 metrics 及 TensorBoard 中常见：
mean_token_accuracy（train）eval_mean_token_accuracy（eval）
四、如何解读
| 任务类型 | 参考解读 |
|---|---|
单 token 标签（如 emotion → fear） |
>0.9 通常表示格式与标签已基本学会；仍须跑 test F1 |
| 短句回答（<32 token） | 0.85～0.95 常见；结合 eval_loss 看是否过拟合 |
| 长 CoT / 推理链 | token accuracy 高不保证推理正确；需 EM 或人工判读 |
六类情绪标签生成任务中，mean_token_accuracy 升至 ~0.94 时，往往与 loss 下降、test 集 macro F1 提升一致——三者构成训练侧的健康信号。
五、局限性与常见误用
- Teacher forcing 偏差：计算时使用 ground-truth 前缀，不反映 autoregressive 生成时的误差累积。
- 不等于样本级 accuracy：一条样本 10 个 token 对 9 个，token accuracy 90%，但任务可能算完全错误。
- 分词边界效应：同一词的不同切分方式会影响 token 计数；跨 tokenizer 不可比。
- 高 accuracy + 低 F1：可能学会输出训练集高频标签词，但在 generate 时格式违规（需看 invalid 比例）。
- 仅监控训练分布：对 OOD 输入无约束力。
六、与其他指标的关系
| 指标 | 关系 |
|---|---|
| eval_loss | 互补；loss 看置信度，accuracy 看硬命中 |
| Accuracy（样本级） | 分类任务需把生成结果解析为标签后再算 |
| Exact Match | 整段 completion 字符串完全匹配，比 token 级更严 |
七、实践建议
- 训练时与 eval_loss 并列观察：accuracy 升、loss 降 → 正常；accuracy 升、loss 不降 → 模型变「自信但偏错方向」需排查。
- 短标签 SFT 可将 mean_token_accuracy 作早停辅助，但 test 集 macro F1 仍为最终依据。
- 若 accuracy 已 >0.95 但业务指标停滞，转向检查 prompt 一致性 与 generate 解码策略，而非继续加长训练。