エージェント的で十分か？ 独自ツールでのオープン・モデルのベンチマーク

記事一覧に戻る

Benchmarking transformers revisions across different metrics

これは人間が作成した、エージェントに焦点を当てたブログ投稿です。

Coding agentsは私たちではなく、私たちのソフトウェアでますます動作するようになっています。タスクを記述すると、エージェントがライブラリを選び、呼び出しを書き、それを実行し、自らのミスをデバッグします。ライブラリが邪魔になると、エージェントは喜んでそれを回避し、ゼロからロジックを書き直します。これにより、ライブラリ開発に新しい概念が導入されます。コードは正しく高速であるだけでなく、エージェントが効果的に操作できるように設計される必要があります。使いにくいAPIや古いドキュメントは開発者を悩ませますが、今ではエージェントをより長く高コストな道に導くことにもなります。

ほとんどのベンチマークは最終的な回答だけを見ます。私たちは代わりにプロセス全体を見たかったのです。エージェントが正解したかどうかだけでなく、そこに至るまでにどれだけの作業が必要だったか、そしてそれがモデル、ライブラリの改訂、タスクによってどのように変化するかを測定しました。私たちはtransformersをケーススタディとして、正確にそれを測定しました。

ここでは、回答がどのように見つかったかに焦点を当てたツール固有のベンチマークを紹介し、piコーディングエージェントによって駆動されるオープン・モデルを完全に使用し、モデル×改訂×タスクの全範囲をHugging Face Jobsに分散させて実行する、このようなハーネスの簡単な実装を提供します。これにより、すべての実行が同一のハードウェアで見られます。

しかし、ソフトウェアをエージェント向けに最適化するにはどうすればよいでしょうか？

私たちは次の2つのソフトウェア原則を強く信じています。

• テストされていないものは機能しない
• 文書化されていないものは存在しない

これはエージェント向けに最適化されたツールの領域でも変わりません。そして今回は、この2つが直接結びついています。

ツールをエージェントに存在させたい場合、発見可能である必要があります。APIは明確で、ドキュメントは包括的である必要があります。エージェントが有用なファイルや例に迅速にアクセスできるように構造化されている必要があります。ツールをエージェント向けに機能させたい場合、エージェントによる使用のためにテストする必要があります。

エージェントによる使用のためのソフトウェアのテスト

このブログ投稿を通じて、transformersを例として使用します。エージェントはtransformersを使用してMLタスク（テキストの分類、画像のキャプション、音声の書き起こし）を解決しますが、transformersへのコードの貢献ではありません。ただし、ハーネスはコマンドラインから操作できる任意のツールで動作するように設計されています。

transformersに関する私たちの直感は、CLI、Skill、および自己完結型のタスク固有の例をいくつか変更することで、使用を大幅に簡素化できるというものでした。これは最近hf CLIに適用されたのと同じレシピで、エージェント向けに再設計されたものです。このCLIでは、エージェントが使用するトークンが1.3〜1.8倍（最大6倍）少なく済みました。私たちは、この種の利点が一般化するかどうか、そしてtransformersにも役立つかどうかを知りたかったのです。

直感は強力なツールですが、transformersのような広く使用されているコードベースに数千行のコードを追加するPRを開く前に、より多くの証拠が欲しかったです。私たちは成功とはどのようなものかを測定することにしました。

すべての成功が等しいわけではない

2つのエージェントがどちらも感情分類タスクの正しいラベルを生成できますが、片方は次のことを行います。

• 40行のPythonスクリプトを書き、transformersをインポートし、形状エラーをデバッグし、2回再実行し、最後に回答を出力する

もう片方は次のことを行います。

• transformers classify --model ... --text "..."と入力し、1回の呼び出しで完了する

どちらもPOSITIVE (0.9999)に到達します。ここに、この正確なタスクでエージェントが実際に取った2つのパスがあります。

# 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!"

両方の方法で同じ結果に到達します。しかし、コスト、レイテンシ、トークン使用量、失敗に関して非常に異なるプロファイルを持っています。

評価が最終的な文字列だけをチェックする場合、これらや、ライブラリに出荷した変更（CLIの改善、より良いエラーメッセージ、Skill）が実際にエージェントを助けたかどうかも見えなくなります。

このハーネスの目標は、エージェントが特定のタスクを実行するのにどれだけの作業が必要か、そしてライブラリの変更がパフォーマンスを改善するかどうかを評価することです。

評価の実行方法

ここでエージェントを評価する方法について少し説明します。

各タスクを3つのバリアント（または「ティア」）で実行します。これはエージェントがtransformersにアプローチできる3つの異なる方法です。

bare     pip install transformersのみ
clone    作業ディレクトリにチェックアウトされた完全なtransformersソース
skill    パッケージ化されたSkill：CLIのドキュメント + タスクの例、コンテキストにロード済み

これらはネストされていません。skillはcloneを含まず（ソースツリーではなくキュレーションされたドキュメントを同梱）、どちらも厳密に他方を含みません。それぞれがエージェントに異なる種類の助けを提供します。後でわかるように、モデルがskillよりもcloneでより良い結果を出すこともあります。

さらにいくつかの選択：

• 今は、実験のための非常に良い基盤を提供する正確な一致が可能な決定論的なタスクのみに焦点を当てています。Model-as-a-judgeや他のスキームは、他のタスクのための明らかな次のステップです。
• すべての実行は独自のHugging Face Jobです。1つの（モデル×改訂×タスク）ごとに1つなので、全範囲が同一のハードウェア上で並列に実行され、大規模な場合でも比較が公平に保たれます。
• 結果とトレースはHugging Face Bucketに保存されます。高速で、バージョン管理は不要で、非常に高い書き込み同時実行性を処理できます。

ベンチマーク対象のモデル

エージェントを駆動するすべてのモデルが等しいわけではなく、それらの違いによって実行時に何を見るべきかが変わります。

大規模なオープン・モデル

一方の端には、最大で最も高性能なオープン・モデルがあります。合理的に一般的なタスクでは、これらのモデルは最終的に正しい答えを得るはずです。これらのモデルでは、タスク完了率がほぼ100%近くで飽和し、ツールについて多くのことを教えてくれなくなります。より関連性の高いベンチマークは、そこに至るまでに要した労力です。ターン数、トークン数、秒数、そしてきれいなパスを歩いたか、非推奨のAPIを使用したかです。

ローカル

ローカルモデルはサイズが大きく異なり、能力も異なります。「一致率」などのメトリクスは、大規模なモデルよりも関連性が高くなります。特定のツールでモデルサイズ/能力が結果にどのように影響するかを確認できるためです。

このハーネスは、ライブラリメンテナにエージェントとのインタラクションのためにリポジトリを改善する方法のガイダンスを提供するだけでなく、異なるエージェントとモデルがユーザーが関心を持つタスクでどのようにパフォーマンスを発揮するかを評価するのにも役立ちます。

ハーネスは各実行を複数の軸でスコアリングするため、各クラスのモデルにとって実際に何が重要かを尋ねることができます。

• 一致率：最終的な回答に期待される結果が含まれていたか（タスクごと、大文字小文字を区別しない部分文字列 / 正規表現 / 完全一致、すべてレポートに明示）
• 中央値時間と中央値トークン数（新規 vs. キャッシュ済み vs. 生成済み）
• エラー発生率：何も生成しなかった実行（出力トークン0、ツール呼び出しなし、回答なし）をフラグ付けするガードを含むため、サイレント失敗が「0」として偽装されない
• マーカー採用率：ツール定義の行動マーカー。以下で説明します。

すべては直接調べることができるレポートに保存されます。

ライブレポート：概要、カバレッジ、結果はすべてクライアントサイド。

そして、すべての実行のネイティブなエージェントトレースをキャプチャするため、数値は始まりに過ぎません。エージェントがコマンドごとに何をしたかを正確に読むことができます。トレースはHubのagent-traces viewerを通じて共有可能です。

A run rendered in the Hub's agent-traces viewer: MiniMax-M2.7 on the answer-question task.
Open this trace on the Hub ↗

結果の前に、セットアップの簡単な要約です。各実行は4つのものを変化させます。モデル（エージェントを駆動）、transformers改訂（実行対象）、タスク、ティア（bare / clone / skill）。前述のように、2つの異なるモデルカテゴリに対して異なるメトリクスを見ます。

大規模なオープン・モデル：モデルを固定し、改訂を変化させる

大規模なオープン・モデルは通常、正しい結果に到達するため、実際に測定しているのはそれまでに要した労力です。10ターンかかったか、1ターンで済んだか？ 古いドキュメントを信頼して非推奨にしたAPIパスに従ったか？ 予期していなかったエラーに遭遇したか？

自然な実験は、1つの強力なモデルを固定し、ツールの改訂を変化させることです。v5.8.0やv5.9.0のようなリリースタグから、CLIとSkillを導入した特定のコミットまで、テスト対象のtransformersの連続したgitバージョンです。エージェントにかかる負荷が増加するか減少するかを観察したいのです。ハーネスをtransformersで使用して、専用のCLIとSkillの追加が実際にエージェントの作業を軽減したかどうかを確認しました。

テストで使用した3つの大規模モデルについて、すべてのタスクに費やした平均時間は、Skillコミットがタスクでの作業時間を短縮することを示しています。

Median time per revision, by tier: the skill commit (green dot) is the fastest.

一方、リポジトリをクローンした実験では、CLIと例を導入したコミットにより、トークン消費が大幅に増加することがわかります。後で確認します。

Median new tokens per revision, by tier: the clone variant jumps once the CLI lands in the repo.

クローン・バリアントのトレースを読むと理由がわかります。このコミットはコマンドを追加しますが、CLIの実装と一連のcli/agentic/*.py使用例もリポジトリに直接同梱します。

cloneバリアントでは、エージェントの前に完全なtransformersチェックアウトがあり、実行の約3分の1がCLIを呼び出す前に新しいサーフェス（/cli/ツリーと例のスクリプト）を読んでインターフェースを学習します。これにより、中央値入力が約4kから約6.4kトークンに増加します。

2つのグラフはトレードオフの両面です。このコミットは大規模モデルに時間短縮をもたらします（Pythonをデバッグする代わりにCLIに手を伸ばす）が、トークン増加という代償を伴います（CLIを教えたコードを読む）。マージ前に知っておく価値のあるトレードオフです。

CLIに有利に働く注意点がありますが、まだベンチマークされていません。CLIを読むコストは連続した実行で償却されます。私たちのセットアップは1回限りの実験用に構築されています。各実行はCLIをゼロから再発見する新しいエージェントなので、発見コストを毎回支払います。実際の使用では、エージェントはインターフェースを一度学習し、同じセッション内でタスクを次々と解決し、多くのリクエストにわたってそのコストを償却します。ここで測定するトークンの増加は、日常的なユーザーが見るものよりも最悪のケースに近いものです。

小規模モデル：改訂を固定し、モデルを変化させる

オープン・モデルは、ここで最も重要な変数（サイズ、設定、量子化、プロバイダ、トレーニング、次に異なる可能性のあるもの）に対するきめ細かい制御を提供してくれます。また、良いツールサーフェスが最も重要となる場所でもあります。bare環境で小規模モデルに「transformersを使ってXを実行せよ」と依頼すると、何リリースか前に変更されたAPIを推測し、不必要なツール呼び出しを行い、誤った回答を得る可能性があります。

したがって、ここでの実験は上記とは逆です。改訂を固定し、モデルをスイープします。これにより、トークン数や時間だけでなく、ツール呼び出しを確実に処理できないモデルまで含めて、実際にタスクを処理するモデルを確認できます。私たちの直感では、モデルが小さいほどツールの使用とタスクの両方が難しくなります。ハーネスをさまざまなモデルサイズで実行して、まさにそれをテストしました。

Match % across models, by tier: the skill tier lifts the larger models but drops the smaller ones.

これは摂取されたトークン数とも相関しているようです。

Median new tokens across models, by tier.

公平な比較に関する注意：カバレッジが不均一な場合、タスク全体を単純に平均化すると誤解を招きます（高速なタスクだけを完了したモデルは高速に見えます）。レポートには「共有タスクのみ」トグル（モデル間および/または改訂間）があり、同等なものを比較でき、Coverageヒートマップで実際に実行されたタスク×改訂×モデルセルを正確に確認できます。

ツールの調整：マーカーと結果

ここで2つのことが結びつきます。エージェントが成功したかどうかだけでなく、何をし、どのようにしたかを見ること。そして、ハーネスから得られた最初の結果です。

マーカーとは

一致率、トークン数、時間は実行のコストを教えてくれますが、内部で何が起こったかについてはあまり教えてくれません。

これがマーカーの概念を導入した理由です。マーカーは、プロファイル（特定のライブラリを構築・駆動する方法をハーネスに教える小さなツールごとのプラグイン）が実行に対して照合する名前付きパターンです。

これは、シェルコマンド、エージェントが書いたコード、読んだファイル、または最終的な回答に対してチェックされる、気になる動作の1行ラベルです。実行は複数のマーカーを発火させるか、どのマーカーも発火させない可能性があります。レポートはモデルごと、改訂ごとに各マーカーが発火した頻度を表示します。

transformersではいくつか宣言しますが、ここでは最も関連性の高い2つだけを見ます。

• cli：エージェントがPythonを書く代わりにtransformersコマンドラインツールを呼び出した（例：transformers classify …）
• pipeline：高レベルのpipeline(...) Python APIに手を伸ばした

これらは、変更が実際にエージェントの行動をシフトさせたかどうかを確認するために監視するものです。ここで興味深いのは、モデルが大きいほど、新しいコンテキストを活用してメモリを使用する代わりに、新しく導入されたCLIを活用するということです。

CLI adoption by tier across models: only the skill tier reaches for it, and more so as models grow.

CLIの採用は新しいものです。CLIは単一のコミットで登場し、どのモデルのトレーニングデータにも含まれておらず、軽くしか文書化されていません。効果は明確です。CLIのドキュメントを同梱するSkillバリアントが実際にCLIに手を伸ばし、55.3%に達します。

CLI + Skillコミットは役立っているか

モデルサイズ間でコミットを比較すると、CLI + Skillはより大きなモデルを助けます。skillティアでは、Kimiや他の大規模エージェントがCLIに手を伸ばし、ターン数を減らして完了します。（cloneでは、新しいCLIコードを読むために最初により多くの入力トークンを使います。前述のように、勝ちは時間とターン数に現れ、生のトークン数には現れません。）

Kimi-K2.6, GLM-5.1, and MiniMax-M2.7 across revisions

しかし、一部の小規模モデル設定では、パフォーマンスを損なうようです。1つの妥当な説明は、小規模モデルが記憶されたAPIパターンに依存し、トレーニングデータで見たpipeline(...)スニペットを再現することです。新しい概念はそれらにとってより大きな誤りの表面になります。これはハーネスで直接確認できます。低い一致率、より多くの再試行、cliマーカーがほとんど発火しないことです。これは特にQwen3-4Bモデルで顕著です。Skillは一致率をほとんど変えませんが、コスト分布は大幅に影響を受けます。

そのほとんどはすべてcloneティアから来ています。チェックアウトにはCLIの実装とcli/agentic/*.pyの例が含まれるようになり、4Bエージェントはそれらを一括で読みます。中央値の新規トークンが約2.4kから約23kに跳ね上がり、時間と出力も急上昇しますが、精度は向上しません。

Qwen3-4B across revisions. The CLI + Skill commit fans the cost distribution wide open, on the clone tier the agent reads the newly-shipped CLI source in bulk (~10× the new tokens), for no gain in match %. (repeat tokens stays flat: this setup uses no prompt caching.)

しかし、Skillが正しさを完全に破壊することもあります。トレースを見ると、例えばQwen3-14Bの場合、Skillの追加により全体の一致率が67%（bare）から43%に低下し、最も単純なタスクでは崩壊が非常に顕著です。classify-sentimentはcloneバリアントで100%だったのが、Skillでは0%に崩れます。

Qwen3-14B on classify-sentiment, by tier: clone (blue) holds at 100% across revisions, but the Skill variant (green) collapses to 0% at the CLI + Skill revision.

トレースを見ると、モデルはCLIを直接呼び出せるツール（web-searchのようなエージェントハーネスのツールのように）と誤解しています。Skillは実行可能なツールではありません。エージェントのコンテキストにロードされるドキュメントであり、transformers CLIはシェルから（bash経由で）実行されることを意図したものです。したがって、これは動作しません。

Qwen3-14BはSkillを読み、56回のSkill実行のうち39回で、transformers(command="classify", ...)ツール呼び出し（登録されたことのないツール）を出力するか、read/bash/edit/writeツールの中にそれに似たものがないことを発見し、モデルを実行できないと結論づけて諦めます。どちらにしても、cloneチェックアウトで100%だった1行のpipeline(...)にフォールバックする代わりに、タスクは不可能であると宣言します。

Qwen3-14B on classify-sentiment (Skill variant): it reasons that read/bash/edit/write can't run a model, and gives up.

これがまさにハーネスがキャッチするために構築したものです。大規模モデルを高速化する同じ変更が小規模モデルを破壊することになります。これは最初は少し直感に反するように思われ、そのまま出荷していた可能性が高いものです。メンテナへの教訓：エージェント向けAPIはモデルサイズ全体で評価されるべきです。なぜなら、新しい利便性が強力なモデルでは作業を減らす一方で、小規模なモデルでは曖昧さを増す可能性があるからです。また、修正のヒントも示しています。Skillを手書きして後でチェックするのではなく、弱いモデルに対して事前に生成して検証することができます。

これがまさにUpskillが行っていることです。強力なモデルのソリューションを、小規模なモデルに測定可能な助けになる場合にのみSkillに変換します。

自分で試す

ハーネスは1つのCLI、agent-evalです。インストールし、スイートを実行し、HF Jobs上でモデル×改訂に分散させ、レポートをHugging Face Spaceとして公開します。

信頼できるローカル使用のみ。ハーネスはバイパスされた権限でコーディングエージェントを実行し、指定した任意の改訂からコードを実行します。トレースにはプロンプト、出力、ローカルパスが含まれる可能性があります。自分が書いていないコードを指定したり、結果を共有したりする前に、SECURITY.mdを参照してください。

完全で最新のセットアップと使用方法はREADMEにあります。

まとめ

最終的な回答をチェックすると、エージェントがライブラリを使用できるかどうかがわかります。そこに至るまでに要したコスト（ターン数、トークン数、エラー、取ったパス）はわかりません。このハーネスは、選択した改訂とモデル全体でそれを測定します。

transformersでは、CLI + Skillが最大のオープン・モデルを助け、最小のモデルを害するという、信じて出荷していたであろうことをキャッチしました。マージ前に知っておく価値があります！

これはプロファイルベースで、適応可能に設計されています。独自のライブラリを指定し、いくつかのタスクとその期待される回答を定義し、同じレポートを取得します。コードとタスクはリポジトリにあり、トレースはHubにあります。プロジェクトで使用した場合はお知らせください！

謝辞

このハーネスは完全にpi、Mario ZechnerのコーディングエージェントCLIの上に成り立っています。あらゆるオープン・モデルの実行を駆動し、モデルを提供するためにHF_TOKENのみを必要とします。これがオープン・モデルのスイープを実際に実現可能にしたものです。

スイープしたモデルの背後にあるモデルビルダーと推論プロバイダーに感謝します。全体として、bareベースラインが示唆するものを大幅に上回るパフォーマンスを発揮しました。