基于 Hugging Face API Tool Builder 技能構(gòu)建可復(fù)用 CLI 工具鏈ai-engineering-hub 實戰(zhàn)指南【免費(fèi)下載鏈接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.項目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本文以 hugging-face-skills/skills/hugging-face-tool-builder/SKILL.md 為核心骨架系統(tǒng)講解如何為 AI Agent 構(gòu)建用于 Hugging Face API 的可復(fù)用命令行腳本涵蓋認(rèn)證規(guī)范、腳本規(guī)則、OpenAPI 探索、hfCLI 用法以及基于管道piping的可組合數(shù)據(jù)流水線。讀完本文你將掌握從零編寫、測試并組合 HF API 腳本的完整方法論并能直接復(fù)用 ai-engineering-hub 倉庫中隨附的 7 個參考腳本投入實戰(zhàn)。Skill 概覽為 Agent 打造可復(fù)用的 HF API 工具h(yuǎn)ugging-face-tool-builder是 hugging-face-skills 技能集中的一個專門技能其定位非常明確當(dāng)用戶需要構(gòu)建工具/腳本或需要借助 Hugging Face API 數(shù)據(jù)完成任務(wù)時使用該技能。它在以下場景尤其有價值需要鏈?zhǔn)浇M合chaining多個 API 調(diào)用任務(wù)需要重復(fù)執(zhí)行或自動化需要創(chuàng)建可復(fù)用的腳本來獲取fetch、豐富enrich或處理processHF 數(shù)據(jù)。該技能的本質(zhì)是讓 Agent 創(chuàng)建可復(fù)用的命令行腳本與工具充分發(fā)揮 API 的鏈?zhǔn)秸{(diào)用、管道傳輸piping與中間處理能力。你可以直接訪問 REST API也可以使用hf命令行工具模型卡片Model Card和數(shù)據(jù)集卡片Dataset Card則可以從倉庫中直接讀取。SKILL.md 的 YAML 前置元數(shù)據(jù)frontmatter是該技能被 Agent 自動激活的關(guān)鍵--- name: hugging-face-tool-builder description: Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. This is especially useful when chaining or combining API calls or the task will be repeated/automated. This Skill creates a reusable script to fetch, enrich or process data. ---正如 hugging-face-skills/README.md 所解釋的Skill 是自包含的文件夾將指令、腳本和資源打包在一起供 Agent 使用每個文件夾包含一個帶 YAML frontmatter 的SKILL.mdAgent 在執(zhí)行相關(guān)任務(wù)時自動加載其中的指令和輔助腳本。腳本規(guī)則Script RulesAgent 寫腳本的六條鐵律SKILL.md 明確列出了構(gòu)建腳本時必須遵守的六條規(guī)則它們是產(chǎn)出高質(zhì)量、可交付腳本的驗收標(biāo)準(zhǔn)必須支持--help參數(shù)每個腳本都必須接受--help命令行參數(shù)用于描述其輸入與輸出。這是腳本可被發(fā)現(xiàn)、可被他人或 Agent 自己正確調(diào)用的基礎(chǔ)。非破壞性腳本交付前必須測試不會修改數(shù)據(jù)、不會產(chǎn)生副作用的腳本在交給用戶之前必須先自行測試通過。優(yōu)先 Shell 腳本默認(rèn)使用 Shell 腳本只有當(dāng)復(fù)雜度或用戶需求要求時才改用 Python 或 TSX。認(rèn)證必須使用HF_TOKEN環(huán)境變量以HF_TOKEN作為 Authorization 頭。例如curl -H Authorization: Bearer ${HF_TOKEN} https://huggingface.co/api/。這樣可以獲得更高的速率限制和適當(dāng)?shù)臄?shù)據(jù)訪問授權(quán)例如訪問 gated/private 模型。先探查 API 返回結(jié)構(gòu)再定型設(shè)計在最終確定腳本設(shè)計之前先調(diào)查 API 結(jié)果的形狀在可組合性有利的地方充分利用管道piping與鏈?zhǔn)秸{(diào)用并優(yōu)先采用簡單方案。完成后分享用法示例腳本完成后要提供使用示例方便其他 Agent 或用戶快速上手。此外在存在疑問或需要澄清時應(yīng)當(dāng)先確認(rèn)用戶偏好再進(jìn)行設(shè)計。認(rèn)證規(guī)范HF_TOKEN 的正確使用姿勢認(rèn)證是本技能強(qiáng)調(diào)的核心工程規(guī)范也是訪問 gated/private 內(nèi)容與提升速率限制的前提。倉庫中的基線腳本給出了標(biāo)準(zhǔn)實現(xiàn)模式。在 references/baseline_hf_api.sh 中認(rèn)證被封裝為可選的條件頭headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer ${HF_TOKEN}) fi curl -s ${headers[]} https://huggingface.co/api/models?limit${LIMIT}在 references/baseline_hf_api.py 中同樣的邏輯用 Python 標(biāo)準(zhǔn)庫urllib實現(xiàn)token os.getenv(HF_TOKEN) headers {Authorization: fBearer {token}} if token else {} url fhttps://huggingface.co/api/models?limit{limit} req urllib.request.Request(url, headersheaders) with urllib.request.urlopen(req) as resp: sys.stdout.write(resp.read().decode(utf-8))關(guān)鍵設(shè)計要點(diǎn)令牌來自環(huán)境變量而非硬編碼絕不把 token 寫死在腳本里避免泄露風(fēng)險未設(shè)置 token 時優(yōu)雅降級HF_TOKEN為空時構(gòu)造空 headers腳本仍然可用只是速率限制較低、無法訪問受限內(nèi)容set -euo pipefail保證健壯性Shell 腳本通過該行讓任何失敗命令立即終止、未定義變量報錯、管道中任何環(huán)節(jié)失敗都被捕獲避免靜默產(chǎn)出臟數(shù)據(jù)。高層級 API 端點(diǎn)總覽SKILL.md 列出了 Hugging Face 主要的高層級 API 端點(diǎn)它們都位于https://huggingface.co/api/datasets /api/models /api/spaces /api/collections /api/daily_papers /api/notifications /api/settings /api/whoami-v2 /api/trending /oauth/userinfo這些端點(diǎn)是構(gòu)建腳本時的常用入口/api/models用于檢索模型/api/datasets檢索數(shù)據(jù)集/api/trending獲取趨勢內(nèi)容/api/whoami-v2用于驗證當(dāng)前令牌身份。探索 OpenAPI 規(guī)范用 jq 精準(zhǔn)提取端點(diǎn)信息Hugging Face API 采用 OpenAPI 標(biāo)準(zhǔn)文檔化規(guī)范文件位于https://huggingface.co/.well-known/openapi.json。?? 重要警告SKILL.md 特別強(qiáng)調(diào)不要直接讀取完整的 openapi.json因為該文件過大無法直接處理。正確的做法是使用jq查詢并提取相關(guān)部分。獲取全部 160 個端點(diǎn)的命令curl -s https://huggingface.co/.well-known/openapi.json | jq .paths | keys | sort查看模型搜索端點(diǎn)/api/models的詳細(xì)定義curl -s https://huggingface.co/.well-known/openapi.json | jq .paths[/api/models]還可以直接查詢端點(diǎn)以觀察數(shù)據(jù)形狀shape但要把結(jié)果數(shù)量限制在較小的數(shù)值既便于處理又具有代表性。這與腳本規(guī)則第 5 條先探查 API 結(jié)果形狀再定型設(shè)計一脈相承——先用jq了解字段結(jié)構(gòu)再決定腳本如何解析輸出。使用 hf 命令行工具除了直接調(diào)用 REST APIhf命令行工具提供了對 Hugging Face 倉庫內(nèi)容與基礎(chǔ)設(shè)施的進(jìn)一步訪問。SKILL.md 記錄了hf --help的完整輸出? hf --help Usage: hf [OPTIONS] COMMAND [ARGS]... Hugging Face Hub CLI Options: --help Show this message and exit. Commands: auth Manage authentication (login, logout, etc.). cache Manage local cache directory. download Download files from the Hub. endpoints Manage Hugging Face Inference Endpoints. env Print information about the environment. jobs Run and manage Jobs on the Hub. repo Manage repos on the Hub. repo-files Manage files in a repo on the Hub. upload Upload a file or a folder to the Hub. upload-large-folder Upload a large folder to the Hub. version Print information about the hf version.注意hfCLI 已取代現(xiàn)已棄用的huggingface_hubCLI 命令。如果腳本或文檔中還引用舊的huggingface_hub命令應(yīng)遷移到hf。在 references/hf_model_card_frontmatter.sh 中可以看到對hf的存在性檢查運(yùn)行前會先驗證環(huán)境if ! command -v hf /dev/null 21; then echo Error: hf CLI is required but not installed 2 exit 1 fi基線腳本三種語言的最小可運(yùn)行實現(xiàn)SKILL.md 提供了一組ultra-simple基線示例它們邏輯極簡、輸出原始 JSON并且都帶HF_TOKEN認(rèn)證頭。這三個腳本是理解整個工具鏈的起點(diǎn)。Shell 版本baseline_hf_api.sh完整源碼見 references/baseline_hf_api.sh。其核心特性包括$0 [limit]用法limit默認(rèn)值為 3--help展示使用說明參數(shù)校驗LIMIT必須是純數(shù)字否則報錯退出Error: limit must be a number可選認(rèn)證頭 curl拉取/api/models?limitN輸出原始 JSON。LIMIT${1:-3} if ! [[ $LIMIT ~ ^[0-9]$ ]]; then echo Error: limit must be a number 2 exit 1 fiPython 版本baseline_hf_api.py完整源碼見 references/baseline_hf_api.py。它僅使用 Python 標(biāo)準(zhǔn)庫urllib.request無第三方依賴直接可運(yùn)行def main() - int: if len(sys.argv) 1 and sys.argv[1] --help: show_help() return 0 limit sys.argv[1] if len(sys.argv) 1 else 3 if not limit.isdigit(): print(Error: limit must be a number, filesys.stderr) return 1 ...該腳本以raise SystemExit(main())結(jié)尾保證非零退出碼能被管道下游正確感知——這是可組合腳本的關(guān)鍵設(shè)計。TypeScript 版本baseline_hf_api.tsx完整源碼見 references/baseline_hf_api.tsx。它以#!/usr/bin/env tsxshebang 開頭可用tsx直接執(zhí)行使用原生fetchAPIconst limit arg ?? 3; if (!/^\d$/.test(limit)) { console.error(Error: limit must be a number); process.exit(1); } const token process.env.HF_TOKEN; const headers: Recordstring, string token ? { Authorization: Bearer ${token} } : {}; const url https://huggingface.co/api/models?limit${limit};三個基線腳本遵循完全一致的約定默認(rèn) limit3、支持 --help、數(shù)字參數(shù)校驗、HF_TOKEN 可選認(rèn)證、原始 JSON 輸出。這種一致性使得它們可以無差別地作為管道入口被替換?？山M合工具stdin → NDJSON 流式管道可組合性的關(guān)鍵模式是stdin → NDJSON腳本從標(biāo)準(zhǔn)輸入讀取模型 ID 列表逐條獲取元數(shù)據(jù)每行輸出一個 JSON 對象NDJSONNewline-Delimited JSON方便流式處理。references/hf_enrich_models.sh 正是這樣一個工具。它同時支持位置參數(shù)和stdin 輸入兩種模式# 直接傳參 hf_enrich_models.sh gpt2 distilbert-base-uncased # 管道輸入 baseline_hf_api.sh 50 | jq -r .[].id | hf_enrich_models.sh # 帶認(rèn)證 HF_TOKENyour_token hf_enrich_models.sh microsoft/DialoGPT-medium其無參數(shù)且 stdin 是終端TTY時展示幫助并退出的設(shè)計保證了交互式誤調(diào)用不會掛起if [[ -t 0 ]]; then show_help exit 1 fi while IFS read -r model_id; do process_id $model_id done每個模型 ID 的處理邏輯包含了完整的錯誤分級設(shè)計這是生產(chǎn)級腳本的重要細(xì)節(jié)請求失敗request_failed返回非法 JSONinvalid_json返回.error字段not_found如 404 模型不存在解析失敗parse_failed。錯誤以{id: ..., error: ...}的 NDJSON 行輸出而不是讓整個管道崩潰——錯誤行與正常行格式一致下游jq過濾時可以選擇丟棄error字段或單獨(dú)處理。正常行的輸出字段為id, downloads, likes, pipeline_tag, tagsjq -c --arg id $model_id { id: (.id // $id), downloads: (.downloads // 0), likes: (.likes // 0), pipeline_tag: (.pipeline_tag // unknown), tags: (.tags // []) } $response使用//提供默認(rèn)值保證字段缺失時輸出依然結(jié)構(gòu)完整。實戰(zhàn)管道把命令串成數(shù)據(jù)流水線SKILL.md 給出了三條可直接運(yùn)行的管道示例充分展示了以簡單工具組合出強(qiáng)大能力的設(shè)計哲學(xué)。示例 1Top 10 高下載模型baseline_hf_api.sh 25 | jq -r .[].id | hf_enrich_models.sh | jq -s sort_by(.downloads) | reverse | .[:10]鏈路解析拉取 25 個模型 → 提取 ID 列表 → 逐條豐富元數(shù)據(jù)NDJSON→ 按 downloads 降序排序取前 10。示例 2純 jq 一步到位baseline_hf_api.sh 50 | jq [.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]當(dāng)數(shù)據(jù)已經(jīng)在響應(yīng)中時無需額外的豐富步驟單個jq即可完成投影、排序、截取。示例 3模型卡片 frontmatter 摘要printf %s\n openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s map({id, license, has_extra_gated_prompt})這條管道混合了 printf 構(gòu)造輸入、frontmatter 提取、批量聚合三種能力輸出每個模型的 license 與是否含額外 gated 提示標(biāo)志。進(jìn)階參考腳本三段源碼級剖析SKILL.md 引用了三個reference examples它們展示了比基線更完整的工程模式。1. hf_model_papers_auth.sh多步 API 認(rèn)證衛(wèi)生完整源碼見 references/hf_model_papers_auth.sh。它演示了多步 API 調(diào)用trending → 模型元數(shù)據(jù) → 模型卡片解析并帶降級策略。核心能力兩種模式$0 MODEL_ID分析單個模型$0 --trending [N]分析前 N 個趨勢模型默認(rèn) 5認(rèn)證封裝hf_api_call()函數(shù)統(tǒng)一處理HF_TOKEN認(rèn)證頭并返回錯誤 JSON 兜底網(wǎng)絡(luò)異常hf_api_call() { local url$1 local headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer $HF_TOKEN) fi curl -s ${headers[]} $url 2/dev/null || echo {error: Network error} }卡片論文提取extract_papers()從模型卡片 README 中用正則抽取 arXiv URL、DOI URL、arXiv ID格式Y(jié)YYY.NNNNN以及 paper/publication 提及私有模型友好提示當(dāng) API 返回錯誤且未設(shè)置 token 時提示用戶這可能是私有模型請嘗試設(shè)置 HF_TOKEN 環(huán)境變量。從源碼結(jié)構(gòu)看該腳本將認(rèn)證-請求-解析-展示分離為獨(dú)立函數(shù)為后續(xù)擴(kuò)展其他端點(diǎn)提供了清晰模板。2. find_models_by_paper.sh彈性檢索策略完整源碼見 references/find_models_by_paper.sh。它展示了搜索策略的彈性和用戶友好的幫助輸出arXiv ID 識別輸入匹配^[0-9]{4}\.[0-9]{4,7}$時自動構(gòu)造arxiv:ID搜索查詢否則按普通關(guān)鍵詞搜索檢索降級路徑當(dāng) arXiv 前綴搜索無結(jié)果時自動回退為去掉arxiv:前綴的寬泛搜索并再次嘗試——這正是 SKILL.md 描述的resilient query strategyif [[ $IS_ARXIV_SEARCH true ]]; then echo -e ${YELLOW}Trying broader search without arxiv: prefix...${NC} SEARCH_QUERY$SEARCH_TERM ... fi可選認(rèn)證--token標(biāo)志控制是否使用HF_TOKEN設(shè)置了 token 但未加--token時輸出黃色警告提示結(jié)構(gòu)化輸出用jq從響應(yīng)中提取id, arxiv_tags, downloads, likes, task(pipeline_tag), library(library_name)base64 編碼后逐條解碼輸出避免 JSON 中特殊字符破壞行結(jié)構(gòu)。3. hf_model_card_frontmatter.shhf CLI YAML 解析完整源碼見 references/hf_model_card_frontmatter.sh。它演示了hfCLI 與 Python 內(nèi)聯(lián)解析的結(jié)合用hf download $MODEL_ID README.md --repo-type model --local-dir ...下載模型卡片HF_TOKEN通過--token參數(shù)傳遞給hfCLI用內(nèi)聯(lián) Pythonheredoc解析 README 的 YAML frontmatter輸出字段為id, license, pipeline_tag, library_name, tags, language, new_version, has_extra_gated_prompt關(guān)鍵設(shè)計has_extra_gated_prompt是通過檢測 frontmatter 中是否出現(xiàn)extra_gated_prompt鍵得出的布爾標(biāo)志可用來快速篩選需要額外申請訪問的模型使用mktemp -d創(chuàng)建臨時目錄并在退出時用trap cleanup EXIT清理避免殘留臨時文件對每個模型 ID 都保證輸出一行 JSON——成功時輸出解析結(jié)果失敗時輸出{id: ..., error: ...}管道下游永遠(yuǎn)可以按行消費(fèi)。最佳實踐總結(jié)綜合 SKILL.md 的規(guī)則與倉庫參考腳本的實現(xiàn)可以提煉出構(gòu)建 HF API 工具的核心實踐統(tǒng)一的--help約定每個腳本自描述輸入輸出是腳本可組合與可發(fā)現(xiàn)的前提HF_TOKEN環(huán)境變量認(rèn)證不硬編碼令牌認(rèn)證頭可選構(gòu)造未設(shè)置時優(yōu)雅降級先探查數(shù)據(jù)結(jié)構(gòu)再定型設(shè)計用curl jq觀察響應(yīng) shape避免憑猜測寫解析邏輯NDJSON 作為中間格式每行一個 JSON 對象天然適配流式管道錯誤也按相同格式輸出函數(shù)化組織將認(rèn)證、請求、解析、展示拆分為獨(dú)立函數(shù)如 references/hf_model_papers_auth.sh 所示便于復(fù)用與擴(kuò)展交付前測試非破壞性腳本在交給用戶前必須運(yùn)行驗證提供使用示例完成腳本后附上可復(fù)制的調(diào)用示例包括直接調(diào)用與管道組合兩種形態(tài)。快速上手本技能的參考腳本位于 hugging-face-skills/skills/hugging-face-tool-builder/references/包含 7 個可直接運(yùn)行的示例。按 hugging-face-skills/README.md 的說明克隆倉庫后可運(yùn)行bash scripts/link-skills.sh安裝全部技能然后在支持 Agent Skill 的編碼 Agent如 Claude Code中通過/skills命令驗證技能是否就緒之后便可在對話中直接要求 Agent使用 hugging-face-tool-builder 技能構(gòu)建腳本來完成任務(wù)。環(huán)境前提運(yùn)行hfCLI 相關(guān)腳本如hf_model_card_frontmatter.sh需要預(yù)先安裝hf工具管道示例依賴jqTSX 腳本需要tsx運(yùn)行時訪問 gated/private 模型或追求更高速率限制時請設(shè)置HF_TOKEN環(huán)境變量?！久赓M(fèi)下載鏈接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.項目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考