Hugging Face Evaluate 统一指标输入格式

我第一次把几个 Hugging Face Evaluate 指标接进同一条评测流水线时，最容易产生的误解是：既然接口都叫 predictions 和 references，输入格式应该已经完全统一。真正稳定的做法只统一“批次外壳”，而把元素类型、嵌套层级和额外计算参数继续交给每个指标的 metric.features 与文档约束。

这样处理后，分类准确率、文本指标和序列标注可以共用一套适配入口，但不会被强行压成同一种值。Evaluate 官方快速入门说明，features 描述单个输入元素的类型，实际调用通常传入一批元素；Python 列表、NumPy 数组和 PyTorch 张量等容器会被转换为适合存储和计算的格式。

官方资料：https://huggingface.co/docs/evaluate/main/a_quick_tour、https://huggingface.co/docs/evaluate/main/package_reference/main_classes

先从 metric.features 读取真实输入契约

Evaluate 的公共 API 给了我们稳定入口，但指标输入的“单元素”仍可能不同。accuracy 常见的是整数标签；文本指标可能要求字符串；序列标注可能要求字符串列表的列表。metric.features 正是输入适配层应该读取或至少记录的契约。

我现在会把输入关系拆成六个明确节点：原始批次 先进入 输入适配器，适配器参照 metric.features 整理 predictions 与 references，再交给 Evaluate 模块。公共键名解决调用一致性，features 解决类型边界，两者不能互相替代。

固定批次字典的公共外壳

上游模型可能返回张量、NumPy 数组或普通列表，我会在评测边界把它们收敛成一个字典。外壳只保留两个必需键，其他参数如 average、pos_label 或指标配置不要混进样本数据，而应在调用指标时显式传入。

def normalize_batch(predictions, references):
    # 把常见张量或数组转换为普通列表，便于统一交给 Evaluate。
    if hasattr(predictions, "detach"):
        predictions = predictions.detach().cpu().tolist()
    elif hasattr(predictions, "tolist"):
        predictions = predictions.tolist()

    # 参考值采用相同的容器收敛规则，但不擅自修改标签语义。
    if hasattr(references, "detach"):
        references = references.detach().cpu().tolist()
    elif hasattr(references, "tolist"):
        references = references.tolist()

    # 裸字符串是一个样本，不应被误拆成字符批次。
    if isinstance(predictions, str) or isinstance(references, str):
        raise TypeError("批次输入必须是序列，单条文本请先放入列表")

    # 预测值和参考值需要一一对应，长度不一致时立即停止累计。
    if len(predictions) != len(references):
        raise ValueError("predictions 与 references 的批次长度不一致")

    return {"predictions": predictions, "references": references}

这段代码只解决公共容器问题。整数标签是否该转成字符串、logits 是否需要先取 argmax、BIO 标签是否要恢复成 token 序列，都属于任务适配规则，必须由模型输出定义和 metric.features 共同决定。

在适配器里守住长度与嵌套边界

统一层最有价值的地方不是少写两行代码，而是把错误拦在指标累计之前。至少应检查三件事：预测与参考数量一致；批次不是裸字符串；嵌套层级与指标要求一致。若 features 提供多个可选输入格式，也不要只拿第一个格式硬套，应根据当前样本选择匹配的结构，匹配失败就保留原始批次标识并报错。

我不建议在这里做“尽力猜测”。例如看到二维数值就自动 argmax，可能把多标签预测误当成多分类 logits；看到字符串列表就自动切词，也可能破坏已经对齐的 token 标签。显式的任务适配器虽然多一层配置，却能让错误更早、更可解释。

让 compute 与 add_batch 共用同一份输入

Evaluate 官方提供两种主要计算方式：数据量小时可直接把完整输入交给 compute()；逐批推理时可多次调用 add_batch()，最后再调用不带输入的 compute()。两种方式应共用同一个 normalize_batch 输出。

import evaluate

# 加载指标后先查看 features，确认单元素类型与字段名称。
metric = evaluate.load("accuracy")
print(metric.features)

# 小数据可以直接计算，字典键与 Evaluate 公共接口保持一致。
batch = normalize_batch([1, 0, 1], [1, 1, 1])
direct_result = metric.compute(**batch)

# 增量计算复用同一个适配器，最终 compute 不再重复传入样本。
stream_metric = evaluate.load("accuracy")
for predictions, references in [([1, 0], [1, 1]), ([1], [1])]:
    stream_metric.add_batch(**normalize_batch(predictions, references))
stream_result = stream_metric.compute()

上面的结果只是调用示例，不代表在本文环境中真实运行。官方文档还说明，评测模块返回字典；分布式场景下最终结果由主进程计算，非主进程可能返回 None，因此统一层也要允许“本进程无结果”而不是强制把它改成空字典。

组合指标前比较 features 而不是只看键名

evaluate.combine() 可以把多个指标放在一次调用里，但“都有 predictions/references”不代表语义兼容。accuracy、precision、recall 在同一个整数分类任务上通常容易组合；文本生成指标与整数分类指标则不应仅因为键名相同就放进同一组。

我会在组合前比较各模块的 metric.features，再确认任务适配器输出的元素类型一致。对 precision 或 f1 这类还需要 average 等计算参数的指标，参数应留在调用层，不要写进每一行样本。统一的是数据接口，不是所有指标的数学定义。

从静态依赖看，dataset batch 与 normalize_batch 属于数据边界，add_batch、compute 与 combine 属于评测接口，最后由 result dict 承接结果。它们共享输入契约，但承担的职责不同。

哪些团队会从统一输入层受益

如果一个项目只有一个指标和一段离线脚本，直接按 metric card 调用通常更清楚。统一层更适合同时评测多个模型、多个数据切片或多个任务的团队：训练循环只负责产出任务结果，适配器负责转换到指标契约，指标配置负责数学参数。

代价也很明确。适配器会成为新的维护点；隐式转换太多时，它可能让数据错误更难发现。因此我会限制自动转换的范围，并记录转换前类型、目标指标、批次大小和失败原因，但不记录包含敏感文本的完整样本。

用输入失败率观察统一层是否值得保留

这类改造不需要用“代码更整洁”作为唯一结论。可以持续观察四个指标：输入适配失败率、长度不一致次数、features 不兼容次数、每增加一个指标所需的分支数量。如果前三项下降、扩展指标时新增分支也减少，统一层确实在发挥作用；反之就应该拆回更明确的任务适配器。

对我来说，Hugging Face Evaluate 最值得统一的是 predictions/references 的调用外壳和批次生命周期，最不该统一的是每个任务的标签语义。先读 features，再转换容器，最后选择 compute 或 add_batch，这条边界既能减少重复代码，也保留了指标真正需要的差异。

常见问题

可以把 NumPy 数组和 PyTorch 张量直接传给 Evaluate 吗？

官方快速入门说明 Evaluate 接受多种输入容器并进行转换。工程上仍建议在统一层明确处理设备张量与容器类型，便于记录错误并避免后续代码依赖某个框架。

predictions 和 references 的键名固定后，就能任意 combine 吗？

不能。还要比较各指标的 features、任务语义和额外计算参数；键名相同只是公共 API，不代表元素类型与数学定义相同。

add_batch 之后还要把完整数据传给 compute 吗？

不需要。逐批 add_batch 后调用无输入的 compute 即可完成累计数据的计算；不要把同一批数据再传一次。