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

Hugging Face 如何將 hf CLI 設計成適合 AI 智能體操作 Hugging Face Hub 的入口

Designing the hf CLI as an agent-optimized way to work with the Hub

AI 導讀

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,遠超其他工具;本文稍後會對這兩者進行基準測試。

Distinct users of the Hugging Face Hub by coding agent since April 2026. Claude Code leads with 39.5k users and 48.6M requests, then Codex with 34.8k users and 36.4M requests, followed by antigravity, cursor-cli, openclaw, cursor, gemini and pi. Distinct users of the Hugging Face Hub by coding agent since April 2026. Claude Code leads with 39.5k users and 48.6M requests, then Codex with 34.8k users and 36.4M requests, followed by antigravity, cursor-cli, openclaw, cursor, gemini and pi.

圖表中的柱代表每個代理程式的獨立用戶數;副標籤則顯示請求量。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 的方法:

  • hf CLI;或
  • curl/Python SDK:完全不提供 hf CLI,因此代理程式只能透過 curl 呼叫 REST API,或使用 huggingface_hub Python 程式庫。

我們以兩種設定執行 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 表現最差:

Task success on Claude Code with Sonnet 4.6: hf CLI 94%, curl / Python SDK 84%. Task success on Claude Code with Sonnet 4.6: hf CLI 94%, curl / Python SDK 84%.

不使用 CLI 時,curl 和 SDK 的成功率低十個百分點,因為 Sonnet 無法完成部分工作(主要是寫入操作),而 hf CLI 則能完成。

第二張圖按任務拆解 GPT-5.5 的 token 影響。每條柱代表同一任務中 curl/SDK 的 token 用量除以 CLI 的用量,因此 2.4× 表示非 hf 方案完成相同工作所耗用的 token 是 2.4 倍:

Per-task token ratio of curl/Python SDK divided by the hf CLI on GPT-5.5, sorted high to low. Multi-step tasks cost curl/Python SDK far more: bucket create+sync+prune 6.0x, rank orgs by trending models 4.1x, repo create+branch+tag / delete files / copy files across repos 2.4x each. Simple one-shot reads sit near parity or cheaper: batch model metadata 0.5x, count dataset rows 0.3x. Per-task token ratio of curl/Python SDK divided by the hf CLI on GPT-5.5, sorted high to low. Multi-step tasks cost curl/Python SDK far more: bucket create+sync+prune 6.0x, rank orgs by trending models 4.1x, repo create+branch+tag / delete files / copy files across repos 2.4x each. Simple one-shot reads sit near parity or cheaper: batch model metadata 0.5x, count dataset rows 0.3x.

對於一次性讀取任務(例如計算數據集列數、批次讀取中繼資料),curl 和 SDK 都足以勝任,有時甚至更精簡。但任務一旦變得更複雜、涉及多個互相依賴的步驟,代理程式就要手動編寫整串 REST 呼叫(或翻查 SDK),成本隨即大幅增加:建立含分支和標籤的儲存庫、刪除檔案、跨儲存庫複製檔案或同步 bucket 等任務,會耗用 CLI 的2.4 至 6 倍 token。hf CLI 讓代理程式用幾個較高層次的命令表達任務,無須手動設計複雜工作流程。

主要發現

  • hf CLI 比 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 的情況:

Mean commands (tool calls) per run, with and without the hf-cli skill, on both agents. Claude Code (Sonnet 4.6): 10.4 without the skill, 6.9 with it. Codex (GPT-5.5): 10.1 without, 7.3 with. Fewer is better. Mean commands (tool calls) per run, with and without the hf-cli skill, on both agents. Claude Code (Sonnet 4.6): 10.4 without the skill, 6.9 with it. Codex (GPT-5.5): 10.1 without, 7.3 with. Fewer is better.

兩種代理程式使用 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