Is it agentic enough? Benchmarking open models on your own tooling

背景

随着 Coding agents（代码智能体）的兴起，软件交互模式正在发生根本性转变。智能体不再仅仅是辅助人类编写代码的工具，而是越来越多地直接操作我们的软件：描述任务，智能体自行选择库、编写调用、执行代码，甚至调试自身的错误。当现有库的逻辑阻碍了任务完成时，智能体会毫不犹豫地绕过它，从头重写逻辑。

这种变化为库开发引入了一个新概念：代码不仅要正确且高效，还必须设计成能让智能体有效驱动的形式。笨拙的 API 或过时的文档不仅会让开发者感到厌烦，现在还会导致智能体走上更长、更昂贵的路径。

然而，现有的基准测试大多只关注最终答案。Hugging Face 团队认为，我们需要关注整个过程：不仅要看智能体是否答对，还要看为此付出了多少工作，以及这种工作负载如何随模型、库版本和任务的变化而改变。本文以 transformers 库为例，介绍了一种专注于“答案是如何被找到的”特定基准测试工具，并提供了一个简单的实现方案。该方案完全基于由 pi coding agent 驱动的开箱即用模型，并通过 Hugging Face Jobs 将模型 × 版本 × 任务的组合并行分发到相同的硬件上运行，确保对比的公平性。

核心内容

为智能体优化软件的两大原则

Hugging Face 团队坚信以下两个软件原则，这在面向智能体的工具优化中同样适用，且两者紧密相关：

1. 如果没有经过测试，它就不起作用。
2. 如果没有文档，它就不存在。

对于智能体而言，工具必须具有“可发现性”。API 需要清晰，文档需要详尽，并且结构上要方便智能体快速访问有用的文件和示例。如果要让工具服务于智能体，就必须针对智能体使用场景进行测试。

以 transformers 为例的直觉与验证

本文以 transformers 库为例，探讨智能体如何利用它解决机器学习任务（如文本分类、图像描述、音频转录），而非向该库贡献代码。

团队最初的直觉是，通过以下三项改变可以大幅简化 transformers 的使用：

• 提供一个 CLI（命令行界面）。
• 提供 Skill（技能包）。
• 提供自包含的、针对特定任务的示例。

这一策略近期也应用于 hf CLI 的重设计中，使其成为面向智能体优化的版本。结果显示，使用优化后的 CLI，智能体的 token 消耗减少了 1.3–1.8 倍（最高达 6 倍）。团队希望验证这种收益是否具有普遍性，以及是否同样适用于 transformers 库。

在提交包含数千行代码的 PR 之前，团队决定先通过基准测试来衡量成功的定义。

并非所有成功都平等

两个智能体可能都对情感分类任务给出了正确的标签（例如 "POSITIVE"），但实现路径截然不同：

• 路径 A（低效）：编写一个 40 行的 Python 脚本，导入 transformers，调试形状错误，重新运行两次，最后打印答案。
• 路径 B（高效）：直接输入一条命令 transformers classify --model ... --text "..."，一次调用完成。

尽管两者都达到了相同的结果（例如置信度 0.9999 的 POSITIVE），但它们在成本、延迟、token 使用量和失败率方面有着巨大的差异。如果评估仅检查最终字符串，就会对这些差异视而不见，也无法判断库的改进（如 CLI 优化、更好的错误消息、Skill 引入）是否真正帮助了智能体。

评估方法论：三个层级与指标

为了评估智能体执行给定任务所需的工作量，以及库的更改是否提升了性能，团队设计了包含三个变体（或“层级”）的评估框架：

1. Bare（裸用）：仅 pip install transformers，无其他辅助。
2. Clone（克隆）：克隆完整的 transformers 源代码到工作目录。
3. Skill（技能）：打包的 Skill，包含 CLI 文档和任务示例，直接加载到上下文中。

这三个层级不是嵌套关系。Skill 不包含源代码树，而是提供策展过的文档；Clone 也不包含 Skill。它们为智能体提供了不同类型的帮助。值得注意的是，模型在某些情况下在 Clone 层级上的表现可能优于 Skill 层级。

评估选择与基础设施：

• 任务类型：目前仅关注确定性任务，以便提供精确匹配的实验基础。模型作为裁判（Model-as-a-judge）等方案将是后续步骤。
• 并行执行：每次运行都是一个独立的 Hugging Face Job（每个模型 × 版本 × 任务组合一个 Job），在相同的硬件上并行运行整个扫描过程。
• 数据存储：结果和追踪数据存储在 Hugging Face Bucket 中，支持高并发写入，无需版本控制。

评分维度： 基准测试从多个轴对每次运行进行评分：

• Match %（匹配率）：最终答案是否包含预期结果（按任务区分，支持不区分大小写的子串/正则/精确匹配）。
• 中位时间与中位 Token 数：区分新请求、缓存命中和生成阶段。
• 带错误运行率：包含一个守卫机制，标记那些产生零输出（0 token、无工具调用、无答案）的运行，防止静默失败被误报为“0”。
• Marker Adoption（标记采用率）：工具定义的行为标记。

所有数据汇总成一份报告，不仅包含数字，还保留了每次运行的原生智能体追踪记录（Agent Trace）。通过 Hub 的 agent-traces 查看器，可以逐命令查看智能体的具体操作。

关键要点

• 智能体驱动的开发范式：代码设计需考虑智能体的驱动效率，API 清晰度和文档完整性直接决定智能体的工作路径长度和成本。
• 过程优于结果：传统的基准测试仅关注最终答案的正确性，忽略了智能体达成目标所需的步骤、Token 消耗和调试成本。新的基准测试旨在量化这一“工作负载”。
• Skill 与 CLI 的价值：提供结构化的 Skill（文档+示例）和优化的 CLI 能显著降低智能体的 Token 消耗（最高达 6 倍），并简化任务执行流程。
• 分层评估体系：通过 Bare、Clone、Skill 三个非嵌套层级，全面评估不同辅助手段对智能体表现的影响。
• 多维度的成功指标：除了准确率（Match %），还需关注中位时间、Token 使用量、错误率以及静默失败的检测。
• 可追溯性：利用 Hugging Face Jobs 和 Bucket 实现大规模并行测试，并通过 Agent Trace 提供从数字到具体操作命令的全链路可解释性。

意义与影响

这项基准测试框架不仅为库维护者提供了改进仓库以优化智能体交互的具体指导，还帮助评估不同智能体和模型在用户关心的任务上的实际表现。

1. 对大型开源模型：在常见任务上，大模型往往能最终得出正确答案，任务完成率接近饱和。此时，相关的基准指标不再是“是否成功”，而是“成功所需的努力”（轮数、Token、秒数）以及路径的清洁度（是否使用了已弃用的 API）。
2. 对本地/小模型：本地模型能力差异巨大。对于这类模型，“匹配率”等指标比大模型更具参考价值，因为它们能直观展示模型规模和能力如何影响在特定工具上的结果。

通过这种细粒度的评估，开发者可以明确知道哪些改进真正提升了智能体的效率，从而推动软件生态向更智能、更自动化的方向演进。