Hugging Face 如何將 hf CLI 設計成適合 AI 智能體操作 Hugging Face Hub 的入口
Designing the hf CLI as an agent-optimized way to work with the Hub
Hugging Face 重建 hf CLI,讓它按使用情境為人類與 AI 智能體提供不同格式的輸出,並以可直接執行的提示引導後續操作。
Claude Code 與 Codex 參與 18 項 Hub 任務的多輪測試,文章並列成功率與 token 用量,呈現 hf CLI 相較 curl/Python SDK 在多步操作上的差異。
hf 是 Hugging Face Hub 官方命令列入口。透過 Python SDK 在 Hub 上可執行的操作,都可以在終端機完成:下載和上載模型、數據集及 Spaces;建立和管理儲存庫、分支、標籤及 pull request;在 HF 基礎設施上執行 Jobs;管理 Buckets、Collections、webhook 和 Inference Endpoints。
多年來,hf CLI 主要為用戶而建。如今它愈來愈常由編程代理程式使用,包括 Claude Code、Codex、Cursor 等。因此,我們重新打造 CLI,讓兩類用戶都能使用。本文總結我們做了甚麼,以及如何進行基準測試。結果顯示,在複雜的多步驟任務中,沒有 CLI 的基準做法(代理程式自行編寫 curl 或使用 Python SDK)最多會用上 6 倍 token,相較於 hf CLI。
Hub 上的 AI 代理程式流量
我們從 2026 年四月開始追蹤代理程式對 Hub 的使用情況。hf CLI(以及它所基於的 huggingface_hub Python SDK)會讀取代理程式設定的環境變數,以偵測是否由編程代理程式操作:Claude Code 使用 CLAUDECODE/CLAUDE_CODE,Codex 使用 CODEX_SANDBOX,此外還包括 Cursor、Gemini、Pi,以及通用變數 AI_AGENT。這個單一訊號有兩個用途:調整 CLI 輸出(下文詳述),並在每個 Hub 請求中加入 agent/<name> user-agent,讓我們能把流量歸因至操作它的代理程式。按獨立用戶數計,最大的兩個代理程式是Claude Code 和 Codex,遠超其他工具;本文稍後會對這兩者進行基準測試。
圖表中的柱代表每個代理程式的獨立用戶數;副標籤則顯示請求量。Claude Code 單獨已有約 40k 名用戶和近 49M 個請求,Codex 緊隨其後。這些仍是早期數據(我們只從 2026 年四月開始歸因代理程式流量),但規模已相當顯著;隨着編程代理程式逐漸成為使用 Hub 的標準方式,我們預期數字會繼續上升。
同時為人類和代理程式而設
對相同的 hf 命令,人類和編程代理程式期望不同的輸出。人類需要豐富的終端機輸出:ANSI 顏色、為配合螢幕而截短的表格、成功時的綠色 ✅、布林值顯示為 ✔、進度列和文字提示。代理程式則需要相反的呈現方式:不用 ANSI、不截短任何內容、完整呈現所有值(因為代理程式可以處理比人類密集得多的輸出),並保持精簡和結構化,以減少 token 開銷。代理程式亦無法回應 CLI 提示,逾時後還會直接重試命令。本節其餘內容會介紹 hf 如何滿足兩方需要。我們在 hf v1.9.0 引入代理模式輸出,並在之後的版本逐步將 CLI 其他部分遷移至此模式。
一個命令,多種呈現方式
hf 自動偵測代理程式使用方式(透過上文提到的環境變數)後,會以不同方式呈現相同命令。無須傳入旗標,就會按人類或代理程式的需要優化輸出格式:
# human (default in a terminal): aligned table, truncated to fit, with a hint
> hf models ls --author Qwen --sort downloads --limit 3
ID CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG PRIVATE TAGS
------------------------ ---------- --------- ------------ ----- --------------- ------- -------------------------
Qwen/Qwen3-0.6B 2025-04-27 21156913 transformers 1285 text-generation transformers, safetens...
Qwen/Qwen2.5-1.5B-Ins... 2024-09-17 15143953 transformers 725 text-generation transformers, safetens...
Qwen/Qwen3-4B 2025-04-27 14808352 transformers 625 text-generation transformers, safetens...
Hint: Use `--no-truncate` or `--format json` to display full values.
# agent (auto-detected): TSV, full ids + ISO timestamps + every tag, nothing truncated
$ hf models ls --author Qwen --sort downloads --limit 3
id created_at downloads library_name likes pipeline_tag private tags
Qwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00 21156913 transformers 1285 text-generation False ['transformers', 'safetensors', 'qwen3', 'text-generation', 'conversational', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-0.6B-Base', 'base_model:finetune:Qwen/Qwen3-0.6B-Base', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen2.5-1.5B-Instruct 2024-09-17T14:10:29+00:00 15143953 transformers 725 text-generation False['transformers', 'safetensors', 'qwen2', 'text-generation', 'chat', 'conversational', 'en', 'arxiv:2407.10671', 'base_model:Qwen/Qwen2.5-1.5B', 'base_model:finetune:Qwen/Qwen2.5-1.5B', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen3-4B 2025-04-27T03:41:29+00:00 14808352 transformers 625 text-generation False ['transformers', 'safetensors', 'text-generation', 'arxiv:2309.00071', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-4B-Base', 'base_model:finetune:Qwen/Qwen3-4B-Base', 'license:apache-2.0', 'endpoints_compatible', 'deploy:azure', 'region:us']
人類會看到對齊的表格,內容截短以配合終端機大小,並附有查看更多資料的提示;狀態亦會以顏色標示(成功為綠色 ✓,錯誤為紅色)。代理程式會取得完整的 TSV 記錄:完整儲存庫 ID、完整 ISO 時間戳記、所有標籤;沒有 ANSI 代碼,不截短內容,方便解析且 token 開銷低。
實際上,我們實作了 .table(...)、.result(...)、.json() 等記錄方法,直接接收原始數據並負責格式化。除了人類和代理模式外,我們亦加入 --json 和 --quiet 選項,方便串接多個命令。系統會按情境自動選擇預設模式,但用戶隨時可用 --format human | agent | json | quiet 強制指定格式。
下一個命令提示
CLI 命令很少獨立執行:完成一步通常就要接着做下一步(例如先執行 git add,再執行 git commit)。現在許多 hf 命令結尾都會附上提示:列出下一個要執行的確切命令,並預先填入你剛使用的 ID,讓用戶或代理程式可以直接接續操作,無須從頭推敲。例如在背景啟動 Job 後,提示會提供日誌位置;建立 Space 後,則會提供其啟動狀態:
$ hf jobs run --detach python:3.12 python train.py
✓ Job started
id: 6f3a1c2e9b
url: https://huggingface.co/jobs/celinah/6f3a1c2e9b
Hint: Use `hf jobs logs 6f3a1c2e9b` to fetch the logs.
對人類而言,這很方便;對代理程式而言,這就像一條操作軌道:下一步操作已列明,並填入正確 ID,可直接執行,減少摸索下一步所需的操作。錯誤訊息亦同樣處理,會指出修正方法,而非只告知失敗:
Error: Not logged in. Run `hf auth login` first.
提示、警告和錯誤都會輸出至 stderr,數據則輸出至 stdout,因此不會讓代理程式正在解析的輸出混入指引文字。
非阻塞,而且可安全重試
hf 不會停在互動式提示中,等候代理程式無法按下的按鍵。破壞性命令仍會要求人類確認,但在代理模式下會以快速失敗方式結束,並在訊息中提供修正方法(Use --yes to skip confirmation.);使用 -y/--yes 則可略過確認。代理程式可能因逾時或上下文遺失而重試,因此所有操作都設計成可安全重複:如果儲存庫已存在,hf repos create --exist-ok 會變成無操作;再次執行上載亦會乾淨地重新提交。此外,會搬移實際數據的命令都支援 --dry-run,可在執行前準確顯示將要傳輸的內容。這對人類和代理程式都很有用,因為雙方都無須承諾進行長時間下載或盲目同步:
# agent mode: a destructive command without --yes refuses, with the fix in the message
$ hf repos delete my-org/old-model
Error: You are about to permanently delete model 'my-org/old-model'. Proceed? Use --yes to skip confirmation.
# commands that move data take --dry-run to preview the transfer first
$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run
[dry-run] Will download 1 files (out of 1) totalling 1.8K.
file size
config.json 1.8K
命令易於探索且行為可預測
hf 的設計方便探索:執行 hf 查看資源羣組,對所需羣組執行 --help;每份 --help 文件結尾都附有可直接複製貼上的實例(代理程式比起解析説明文字,能快得多地比對範例):
$ hf models ls --help
...
Examples
$ hf models ls --sort downloads --limit 10
$ hf models ls --search "qwen" --author Qwen
$ hf models ls Qwen/Qwen3-4B --tree
命令樹結構一致,採用資源 + 動作模式,並提供直觀別名(hf models ls、hf repos create、hf jobs ps、hf collections delete;list/ls、remove/rm),因此代理程式學會一個命令後,便可推測其他用法。輸出亦可串接:-q 每行輸出一個 ID,供下一個命令使用;--json 則會輸出可交給 jq 處理的內容。
$ hf models ls --author Qwen -q | head -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
Qwen/Qwen3-4B
為編程代理程式評測 hf CLI
為了確認 hf CLI 對代理程式是否真的更有效率,我們進行了量測。我們建立小型評估 harness,讓同一組 Hub 任務透過不同方式操作 Hub,反覆執行多次,並根據即時 Hub 狀態為每次執行評分。先看主要結果,再談方法:兩種代理程式使用 hf CLI 都取得較佳表現,尤其在複雜多步驟任務中,所用 token 少得多。
| 代理程式 | 工具 | 成功分數 | token 用量 | 自我回報錯誤 |
|---|---|---|---|---|
| Claude Code(Sonnet 4.6) | hf CLI |
0.94 | 基準方案 | 2 / 163 |
| curl/Python SDK | 0.84 | 1.3–1.6× token | 11 / 163 | |
| Codex(GPT-5.5) | hf CLI |
0.93 | 基準方案 | 3 / 163 |
| curl/Python SDK | 0.92 | 1.6–1.8× token | 10 / 163 |
(自我回報錯誤 = 代理程式在 17 項可解任務中報告成功,但 Hub 顯示實際並非如此。hf CLI 列代表安裝了其 skill 的 CLI;skill 在純 CLI 之上帶來的效益(主要是減少工具呼叫),會在下方的skill 章節獨立分析。具代表性的執行紀錄已發布於此 bucket。)
測試設定
我們定義了 18 項不簡單的 Hub 任務。不是「下載一個檔案」之類的任務,而是人們實際會提出的要求:彙整熱門機構的模型、檢查儲存庫檔案及其大小、按照納入/排除規則上載資料夾、刪除檔案、跨儲存庫複製檔案、建立加入授權的 PR、建立包含分支和標籤的儲存庫、同步並清理 bucket,以及建立 collection。每項任務都交給全新的編程代理程式,而且只提供一種操作 Hub 的方法:
hfCLI;或- curl/Python SDK:完全不提供
hfCLI,因此代理程式只能透過curl呼叫 REST API,或使用huggingface_hubPython 程式庫。
我們以兩種設定執行 hf CLI:安裝和不安裝 skill(即自動生成的命令參考;詳情會在專屬章節介紹)。不過,以下主要比較的只是hf CLI 與 curl/SDK;skill 帶來的增量效果較小,因此我們另外分析,而不把它擠進主要結果。
測試設定刻意保持乾淨:每次執行都使用全新實例,沒有自訂 MCP 伺服器,不提供 CLAUDE.md 或 AGENTS.md,上下文中亦沒有任何誘導行為的內容。任務和工具一併放入單一提示,代理程式結束時會輸出 TASK_COMPLETE 或 TASK_FAILED 標記,但我們不會信任該標記(代理程式可能會對尚未真正完成的工作報告成功),而是透過重新查詢即時 Hub,獨立為每次執行評分:分支真的建立了嗎?檔案真的刪除了嗎?bucket 存在嗎?每種任務/工具組合都執行 10 次,因為編程代理程式具有非確定性;每個代理程式約有 520 次執行(18 項任務 × 3 種工具 × 10 次重複,另有一項收費 Jobs 任務受次數上限影響),總計評分約 1,000 次執行。整套測試執行了兩次,分別使用最受歡迎的兩種編程代理程式(使用 Sonnet 4.6 的 Claude Code,以及使用 GPT-5.5 的 OpenAI Codex)。
測試結果
以下兩張圖會進一步拆解上表數據。首先是 Sonnet 的任務成功率;在這個代理程式上,curl 和 SDK 表現最差:
不使用 CLI 時,curl 和 SDK 的成功率低十個百分點,因為 Sonnet 無法完成部分工作(主要是寫入操作),而 hf CLI 則能完成。
第二張圖按任務拆解 GPT-5.5 的 token 影響。每條柱代表同一任務中 curl/SDK 的 token 用量除以 CLI 的用量,因此 2.4× 表示非 hf 方案完成相同工作所耗用的 token 是 2.4 倍:
對於一次性讀取任務(例如計算數據集列數、批次讀取中繼資料),curl 和 SDK 都足以勝任,有時甚至更精簡。但任務一旦變得更複雜、涉及多個互相依賴的步驟,代理程式就要手動編寫整串 REST 呼叫(或翻查 SDK),成本隨即大幅增加:建立含分支和標籤的儲存庫、刪除檔案、跨儲存庫複製檔案或同步 bucket 等任務,會耗用 CLI 的2.4 至 6 倍 token。hf CLI 讓代理程式用幾個較高層次的命令表達任務,無須手動設計複雜工作流程。
主要發現
hfCLI 比 curl 或 SDK 精簡得多。在完成相同任務且成功率相同或更高的情況下,curl 和 SDK 會耗用約 1.3 至 1.8 倍 token。簡單讀取任務還可以,但真正的多步驟工作會耗用2 至 6 倍:CLI 會把一連串 REST 呼叫整合成幾個高層次命令,而 curl 或 SDK 則要在每次執行時重新手動組合流程。- 使用能力較強的模型時,curl 和 SDK 也能運作,但仍然浪費資源。Sonnet 無法完成部分工作(主要是寫入操作);GPT-5.5 大多能成功,也能正確手動編寫 REST 呼叫(或使用 SDK),但 token 開銷仍遠高於 CLI。
hf-cli skill
hf 隨附一項skill:代理程式會載入上下文中的精簡命令參考,涵蓋完整命令介面。它是自動生成的,根據即時 hf 命令樹逐個資源整理;每個命令佔一行(包括語法、一句説明和重要旗標),並附有常用選項簡明詞彙表。為保持精簡並減少上下文佔用,它會刻意略去不言自明的旗標,並在每次發布時重新生成。執行 hf skills preview 即可查看,亦可透過以下命令安裝:
# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude
它有甚麼作用?主要是令代理程式不用再猜測。最清楚的指標是每次執行所需的命令數目;下圖比較安裝和不安裝 skill 的情況:
兩種代理程式使用 skill 後,每項任務大約由十個命令減至七個,工具呼叫約少 30%。這是因為代理程式無須透過 --help 試探合適命令和參數。skill 不會減少 token 開銷,因為它會在上下文前置一段固定資訊;因此,相同任務的 token 用量大致不變,甚至略為增加。skill 亦不會令 CLI 更可靠,但可讓代理程式把時間用於執行你的任務,而非研究工具用法。使用本機模型配合 hf 時,這點尤其有幫助。
我們每次都在全新工作階段中執行任務,因此每項任務都要付出載入 skill 的上下文成本。在真實的多任務工作階段中,這項成本會由多個任務分攤(代理程式只需學一次命令介面),所以 token 用量可能會更理想;但我們沒有測試這種情況。
親自試用
我們進行這些基準測試,是因為認為它們很重要。代理程式正成為 Hub 的真正用戶:它們會訓練模型、建立和整理數據集,以及以 Spaces 發布示範,幾乎總是代表人類用戶操作。讓代理程式易於使用的 Hub,也會令使用它們的人受惠。代理程式的工具越好,能為你完成的工作就越多。
如果你的代理程式會與 Hugging Face Hub 互動,我們建議讓它使用 hf CLI:
# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
然後把 skill 提供給它,讓它從第一輪開始就熟悉整個命令介面:
hf skills add # Codex, Cursor, OpenCode, Pi and other agents that load skills from .agents/skills
hf skills add --claude # the above + Claude Code
之後讓代理程式連接 Hub 並開始工作。請先確認已登入(hf auth login),再提供類似以下的提示:
Use `hf` to list my Hugging Face Hub models, datasets, and Spaces.
Take a look at how I am currently using the Hub and suggest a few ways you could help me.
它會自行找出所需命令,並回覆有用的結果。
完整命令參考載於 hf CLI 指南。
註冊代理程式 harness
正在建構代理程式 harness?請註冊!這樣 hf 才能識別它,Hub 亦才能把流量歸因至你的 harness。只需提交一個小型 PR,在 agent-harnesses.ts 新增一項即可。詳情請參閲註冊代理程式 harness指南。
來源:Hugging Face Blog · huggingface.co