跳到正文
Hugging Face Blog·· 2026-06-18精選AI 評分68

Hugging Face 以 agent-eval 評測開源模型操作 transformers 的成功率與成本

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

AI 導讀

Hugging Face 測試開源模型使用 transformers,CLI 與 Skill 縮短大型模型耗時,卻可能降低小模型成功率。Qwen3-14B 在 classify-sentiment 任務中,clone 環境的匹配率為 100%,Skill 環境則降至 0%。agent-eval CLI 可套用於其他命令列工具,並記錄匹配率、tokens、耗時、錯誤、行為標記及執行軌跡。

推薦理由

評測不只看任務是否成功,也追蹤 tokens、耗時與操作路徑,呈現 CLI 與 Skill 對大小模型的影響並不一致。

正文 · 繁體中文

Benchmarking transformers revisions across different metrics

以不同指標評測 transformers 的各個版本

本文由人撰寫,聚焦 AI agent。

Coding agent 愈來愈常代替我們操作軟件:我們描述任務,agent 便會選擇程式庫、撰寫呼叫方式、執行程式,再為自己的錯誤除錯。遇到程式庫阻礙時,它甚至會繞過程式庫,從頭重寫邏輯。這為程式庫開發帶來一個新概念:程式碼不但要正確、快速,也要設計得讓 agent 能有效操作。笨拙的 API 或過時的文件會令開發者苦惱,如今亦會令 agent 採取更迂迴、成本更高的路徑。

大部分基準測試只看最終答案。我們想評估整個過程:不只看 agent 是否答對,還要看它花了多少工夫,以及不同模型、程式庫版本和任務會帶來甚麼變化。我們以 transformers 為案例,實際量度了這些項目。

本文會介紹一套專門評估工具使用方式的基準測試,並提供一個簡單測試框架的實作。它完全以開放模型運行,由 pi coding agent 驅動;不同模型 × 版本 × 任務的全面測試則分配到 Hugging Face Jobs 執行,確保每次測試都使用相同硬件。

不過,如何為 agent 優化軟件?

我們深信以下兩項軟件原則:

  • 沒有測試,就代表行不通
  • 沒有文件,就等於不存在

這兩項原則同樣適用於為 agent 優化的工具,而且兩者今次更是直接相關。

要讓 agent 找到你的工具,工具就必須容易發現。API 必須清晰,文件也要詳盡,並以便於 agent 快速找到實用檔案和範例的方式編排。要讓 agent 能使用你的工具,就應測試它在 agent 使用情境下的表現。

測試軟件是否適合 agent 使用

本文會以 transformers 為例:agent 使用它來解決機器學習任務(分類文字、為圖片撰寫説明、轉錄音訊),而非為它貢獻程式碼;不過,這套測試框架原本就是為任何可透過命令列操作的工具而設計。

我們直覺認為,只需作幾項改動,就能大幅簡化 transformers 的使用方式:加入 CLI、Skill,以及自成一體、針對特定任務的範例。近期我們也為 hf CLI 重新設計,令它更適合 agent 使用,agent 使用的 token 減少了 1.3–1.8 倍(最多減少 6 倍)。我們想知道這類成效能否普遍重現,以及是否同樣有助於 transformers。

直覺固然有用,但在向這個廣泛使用的 transformers 程式碼庫提交新增數千行程式碼的 PR 前,我們想先取得更多證據。因此,我們開始量度怎樣才算成功。

成功不只一種

兩個 agent 都能為情感分類任務輸出正確標籤,但其中一個:

  • 撰寫一個 40 行的 Python 腳本,匯入 transformers,修正形狀錯誤,再重跑兩次,最後才輸出答案;

另一個則

  • 輸入 transformers classify --model ... --text "...",一次呼叫就完成。

兩者都得到 POSITIVE (0.9999),以下是 agent 在這項完全相同的任務中實際採取的兩條路徑:

# Task: classify the sentiment of "I absolutely loved the movie, it was fantastic!"

- # one agent: pipe a script into python and parse the output
- python - <<'PY'
- from transformers import AutoTokenizer, AutoModelForSequenceClassification
- import torch
- import torch.nn.functional as F
-
- model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
- tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
- inputs = tokenizer("I absolutely loved the movie, it was fantastic!", return_tensors="pt")
- with torch.no_grad():
-     logits = model(**inputs).logits
- probs = F.softmax(logits, dim=1)
- idx = torch.argmax(probs, dim=1).item()
- print(model.config.id2label[idx], probs[0][idx].item())
- PY

+ # the other agent: one command
+ transformers classify \
+   --model distilbert/distilbert-base-uncased-finetuned-sst-2-english \
+   --text "I absolutely loved the movie, it was fantastic!"

兩種方法都得到相同結果,但在成本、延遲、token 用量和失敗情況方面,兩者的表現截然不同。

如果評估只檢查最後輸出的字串,你就會看不到這些差異,也無從知道你發布的程式庫改動(例如改良 CLI、更好的錯誤訊息或 Skill)是否真的幫到 agent。

這套測試框架的目標,是評估 agent 執行指定任務要花多少工夫,以及程式庫改動能否提升表現。

如何執行評測?

先簡單介紹我們在此如何評估 agent。

每項任務都會採用三種變體(或稱「級別」)執行,也就是 agent 操作 transformers 的三種不同方式:

bare     pip install transformers, and nothing else
clone    the full transformers source, checked out in the working directory
skill    a packaged Skill: the CLI's docs + task examples, loaded in context

這些變體並非層層包含:skill 並不包含 clone(它提供經整理的文件,而非原始碼樹),而且兩者都不會嚴格包含對方;它們各自提供不同類型的協助。正如我們稍後會看到,某個模型有時在 clone 變體的表現會比 skill 更好。

另外還有幾項設定:

  • 目前我們只聚焦於可以精確比對結果的確定性任務,因為這類任務非常適合用作實驗基礎。對其他任務而言,採用模型評判或其他評估方式,顯然是下一步。
  • 每次執行都會建立一個 Hugging Face Job:每組(模型 × 版本 × 任務)各一個 Job,讓整個測試套件在相同硬件上平行執行,確保大規模比較仍然公平。
  • 結果和執行軌跡會儲存在 Hugging Face Bucket:速度快、無須版本管理,而且能應付極高的並行寫入量。

應選哪些模型作比較?

驅動 agent 的模型各有不同,而模型之間的差異會影響你執行評測時應該觀察甚麼。

大型開放模型

一端是規模最大、能力最強的開放模型。面對相當常見的任務時,這些模型最終理應能答對。對它們而言,任務完成率會接近 100% 並趨於飽和,因而不再能提供太多關於工具本身的資訊;更值得評估的是 agent 為此付出的代價:用了多少輪、token 和秒數,以及它採取的路徑是否直接,還是使用了已棄用的 API。

本機模型

本機模型的規模差異很大,能力亦然。對這類模型而言,「匹配率」等指標比起大型模型更重要,因為你可以看到模型規模和能力如何影響它在指定工具上的結果。

這套測試框架不但可指引程式庫維護者如何改善儲存庫與 agent 的互動方式,也有助評估不同 agent 和模型在使用者關心的任務上的表現。

測試框架會從多個面向為每次執行評分,讓你按模型類別檢視真正重要的指標:

  • 匹配率:最終答案是否包含預期結果(每項任務會明確指定不區分大小寫的子字串、正規表示式或完全相符比對方式,並列於報告中);
  • 中位時間和中位 token 數(新生成、快取和生成的 token);
  • 出錯執行比例:包括一項防護檢查,會標記完全沒有產出的執行(0 個輸出 token、沒有工具呼叫、沒有答案),避免無聲失敗被誤當成「0」;
  • 標記採用率:由工具定義、用來辨識行為的標記;下文會説明其意義。

所有資料都會整合到一份可直接檢視的報告:


即時報告:Overview、Coverage 和 Results,全由用戶端顯示。

由於它會擷取每次執行的原生 agent 軌跡,數字只是起點:你可以逐條指令查看 agent 實際做過甚麼。執行軌跡可透過 Hub 的 agent-traces 檢視器分享:

A run rendered in the Hub's agent-traces viewer: MiniMax-M2.7 on the answer-question task
在 Hub 的 agent-traces 檢視器中呈現的一次執行:MiniMax-M2.7 執行 answer-question 任務。
在 Hub 開啟此執行軌跡 ↗

先快速回顧結果前的設定。每次執行會改變四個項目:驅動 agent 的模型、執行時使用的 transformers 版本、任務,以及級別(bare/clone/skill)。如上文所述,兩類模型會採用不同指標評估。

大型開放模型:固定模型,改變版本

大型開放模型通常都能得出正確結果,所以你真正衡量的是達成目標所花的工夫:用了十輪還是一輪?它有否因相信過時文件而遵循已棄用的 API 路徑?有否遇到你意料之外的錯誤?

自然的實驗方式是固定一個能力強的模型,再改變工具的版本:也就是我們測試的 transformers 各個 git 版本,從 v5.8.0 和 v5.9.0 等已發布標籤,到加入 CLI 和 Skill 的特定提交。我們想觀察這些改動令 agent 的工作量增加還是減少。我們以 transformers 執行測試框架,檢查加入專用 CLI 和 Skill 是否真的減輕 agent 的工作。

在測試中使用的 3 個大型模型上,所有任務的平均耗時顯示,加入 Skill 的提交可縮短任務處理時間:

Median time per revision, by tier
按級別劃分的各版本中位耗時:Skill 提交(綠點)最快。

另一方面,在複製整個儲存庫的實驗中,我們會看到加入 CLI 和範例的提交令 token 用量顯著增加,稍後再説明原因。

Median new tokens per revision, by tier
按級別劃分的各版本中位新增 token 數:CLI 加入儲存庫後,clone 變體的數字隨即上升。

查看 clone 變體的執行軌跡,就能明白原因。該提交加入一項命令,但也把 CLI 的實作和一組 cli/agentic/*.py 使用範例直接放進儲存庫。

在 clone 變體中,agent 可直接查看完整的 transformers 儲存庫;約三分之一的執行會先閲讀新加入的內容(/cli/ 目錄樹和範例腳本),瞭解介面後才呼叫 CLI。這令輸入 token 中位數由約 4k 升至約 6.4k。

兩張圖呈現同一取捨的兩面:加入該提交後,大型模型花的時間較少(它們會改用 CLI,而非除錯 Python),代價是使用更多 token(它們會閲讀令自己學懂 CLI 的程式碼)。合併 PR 前,瞭解這項取捨很有價值。

不過,有一項尚未納入基準測試、但對 CLI 有利的因素:多次執行會攤分閲讀成本。我們的設定針對一次性實驗;每次執行都是全新的 agent,必須從頭重新發現 CLI,因此每次都要付出探索成本。實際使用時,agent 只需學懂介面一次,之後便能在同一個工作階段連續解決任務,將成本攤分到許多請求之中。因此,我們量度到的 token 增幅更接近最壞情況,未必反映使用者日常會看到的情況。

小型模型:固定版本,改變模型

開放模型讓我們能細緻控制這裏最重要的變數:模型大小、設定、量化方式、供應商、訓練方式,以及不同模型之間的其他差異。工具介面對這類模型也最重要:要求小型模型使用 transformers 完成某事,並在 bare 環境中操作時,它可能會猜測某個版本已改動的 API,作出不必要的工具呼叫,甚至得出錯誤答案。

因此,這裏的實驗方式與上文相反:固定版本,再測試一系列模型。這有助觀察哪些模型真正能完成任務,不只看 token 數和時間,也看哪些模型無法可靠地處理工具呼叫。我們直覺認為,模型愈小,工具使用和任務本身就愈困難;於是我們以不同規模的模型執行測試框架,驗證這個推測:

Match % across models, by tier
按級別劃分的各模型匹配率:Skill 級別提升大型模型的匹配率,卻令小型模型的匹配率下降。

這似乎也與輸入的 token 數量相關

Median new tokens across models, by tier
按級別劃分的各模型新增 token 中位數。

公平比較須注意:當覆蓋任務不均時,直接計算所有任務的平均值會產生誤導(只完成簡單任務的模型看起來會比較快)。報告提供「只看共同任務」切換選項(可按模型及/或版本篩選),確保比較條件一致;另有覆蓋熱圖,清楚顯示實際執行過哪些任務 × 版本 × 模型組合。

調整工具:行為標記與結果

這裏會結合兩個面向:除了判斷 agent 有否成功,也要查看它做了甚麼以及如何完成;同時介紹我們從測試框架取得的首批結果。

甚麼是行為標記?

匹配率、token 數和時間可告訴你一次執行的成本,卻無法讓你瞭解背後發生了甚麼。

因此,我們引入了「行為標記」這個概念。標記是具名模式,設定檔會用它比對執行記錄;設定檔是一個小型、按工具而設的外掛,負責教導測試框架如何建構及操作指定程式庫。

它以一行標籤表示你關心的行為,並檢查 agent 執行過的 shell 命令、撰寫的程式碼、讀取的檔案或最終答案。一次執行可以觸發多個標記,也可以一個都沒有;報告會按模型和版本,顯示每個標記的觸發頻率。

我們為 transformers 定義了幾個標記,但只會查看其中兩個最相關的項目:

  • cli:agent 使用了 transformers 命令列工具(例如 transformers classify …),而非撰寫 Python。
  • pipeline:agent 使用了高階的 pipeline(...) Python API。

我們會觀察這些標記,瞭解改動是否真正改變 agent 的行為。有趣的是,模型愈大,就愈會利用新加入的上下文,而非依賴記憶;換言之,它們更善用新推出的 CLI。

CLI adoption by tier across models
不同模型在各級別使用 CLI 的比例:只有 Skill 級別會使用 CLI,而且模型愈大,使用得愈多。

CLI 是新功能:它只在一個提交中加入,不在任何模型的訓練資料內,而且文件也不多。效果十分明顯:只有提供 CLI 文件的 Skill 變體會真正使用它,使用率為 55.3%。

CLI + Skill 提交有幫助嗎?

比較不同模型規模的測試結果後可見,CLI + Skill 對較大型模型有幫助:在 skill 級別中,Kimi 等大型 agent 會使用 CLI,並以較少輪次完成任務。(在 clone 級別中,正如上文所述,它們會先花更多輸入 token 閲讀新加入的 CLI 程式碼,因此成效反映在時間和輪次,而非 token 總數。)

Kimi-K2.6, GLM-5.1, and MiniMax-M2.7 across revisions
Kimi-K2.6、GLM-5.1 和 MiniMax-M2.7 在不同版本上的結果

但在某些小型模型的設定中,這似乎會損害表現。一個可能的解釋是,小型模型依賴記住的 API 用法,重現訓練資料中看過的 pipeline(...) 範例。新概念反而擴大了它們可能出錯的範圍。你可以直接從測試框架觀察到:匹配率下降、重試增加,cli 標記幾乎沒有觸發。Qwen3-4B 尤其明顯:Skill 對它的匹配率影響不大,卻顯著改變了成本分佈。

幾乎所有影響都來自 clone 級別。複製下來的儲存庫現在包含 CLI 實作和 cli/agentic/*.py 範例;4B agent 會一次大量閲讀這些內容:其中位新增 token 數由約 2.4k 升至約 23k,耗時和輸出量也急升,準確度卻沒有提升。

Qwen3-4B cost distributions across revisions: elapsed, new tokens, repeat tokens, out tokens
Qwen3-4B 在不同版本上的結果。CLI + Skill 提交令成本分佈大幅擴闊:在 clone 級別中,agent 大量閲讀新加入的 CLI 原始碼(新增 token 數約為原來的 10 倍),匹配率卻沒有提升。(repeat tokens 維持不變:此設定沒有使用提示快取。)

不過,有時 Skill 會直接破壞正確性。查看執行軌跡,就能看到例如 Qwen3-14B 的情況:加入 Skill 後,整體匹配率由 67%(bare)降至 43%;在最簡單的任務中,跌幅尤其明顯:classify-sentiment 在 clone 變體的匹配率為 100%,使用 Skill 後卻降至0%。

Qwen3-14B classify-sentiment match % by tier across revisions
Qwen3-14B 執行 classify-sentiment 任務的各級別匹配率:clone(藍色)在各版本均維持 100%,但 Skill 變體在 CLI + Skill 版本跌至 0%。

查看執行軌跡後可見,模型把 CLI 誤認為是可直接呼叫的工具(例如 agent 框架中的 web-search 工具)。Skill 並非可執行工具,而是載入 agent 上下文的文件;transformers CLI 只應透過 bash 從 shell 執行,因此這種呼叫方式並不可行。

Qwen3-14B 讀取 Skill 後,在 56 次 Skill 執行中有 39 次會輸出 transformers(command="classify", ...) 工具呼叫(這個工具根本沒有註冊);又或者,在它的 read/bash/edit/write 工具中找不到類似功能,便認定自己無法執行模型而放棄。無論哪種情況,它都沒有改用單行 pipeline(...) 寫法(該寫法在 clone checkout 中取得 100% 匹配率),反而宣稱任務無法完成。

Qwen3-14B gives up on classify-sentiment under the Skill variant
Qwen3-14B 使用 Skill 變體執行 classify-sentiment:它推斷 read/bash/edit/write 無法執行模型,於是放棄。

這正是我們建立測試框架要找出的問題:同一項改動可以加快大型模型,卻令小型模型出錯;這一點起初也有點違反我們的直覺,而且我們很可能會照原樣發布。給維護者的啟示是:評估面向 agent 的 API 時,應涵蓋不同規模的模型,因為新功能可能減輕大型模型的工作,卻令小型模型更容易混淆。這也提示了其中一種修正方法:與其手寫 Skill 後才檢查,不如事先生成 Skill,並用較弱的模型驗證。

這正是 Upskill 的做法:只有在實際測試證明能幫助較小型模型時,才把大型模型的解決方案轉成 Skill。

親自試用

整套測試框架只有一個 CLI:agent-eval。安裝後執行測試套件,將多個模型 × 版本的工作分發到 HF Jobs,並把報告發布為 Hugging Face Space。

只限可信任的本機使用。此測試框架會以略過權限檢查的方式執行 coding agent,並執行你指定版本中的程式碼;執行軌跡可能包含提示、輸出和本機路徑。若要用於並非由你撰寫的程式碼,或分享結果,請先閲讀 SECURITY.md。

完整且持續更新的設定和使用指示載於 README。

結語

檢查最終答案,只能知道 agent能否使用你的程式庫,卻看不到代價:完成任務用了多少輪、token 和錯誤,以及它採取的路徑。這套測試框架會按你選擇的版本和模型量度這些項目。

在 transformers 上,測試框架發現了一項我們原本會憑直覺直接發布的改動:CLI + Skill 有助於最大型的開放模型,卻損害最小型模型的表現。合併前值得先知道!

測試框架採用設定檔設計,亦方便調整:只要指定自己的程式庫,定義幾項任務及其預期答案,就能產生相同格式的報告。程式碼和任務均位於儲存庫,執行軌跡則放在 Hub。歡迎告訴我們你有否在自己的專案中使用!

鳴謝

整套測試框架完全建基於 pi(Mario Zechner 的 coding-agent CLI):它負責驅動每次開放模型執行,只需 HF_TOKEN 即可提供模型服務,令大規模測試開放模型切實可行。

感謝我們測試的模型背後的模型建構者和推理服務供應商。整體而言,這些模型的表現都遠勝 bare 基線所顯示的水平。

來源:Hugging Face Blog · huggingface.co