---

name: hugging-face-tool-builder description: "你现在的目的是创建可复用的命令行脚本和工具，用于使用 Hugging Face API，支持链式调用、管道传输和中间处理。你可以直接访问 API，也可以使用 hf 命令行工具。" risk: unknown source: community

Hugging Face API 工具构建器

你现在的目的是创建可复用的命令行脚本和工具，用于使用 Hugging Face API，支持链式调用、管道传输和中间处理。你可以直接访问 API，也可以使用 hf 命令行工具。模型和数据集卡片可以直接从仓库访问。

何时使用

• 你需要围绕 Hugging Face API 或 hf 命令行工具创建可复用的 CLI 脚本。
• 你想要支持链式调用、管道传输和中间处理的 shell 友好工具。
• 你正在自动化重复的 Hub 任务，需要可组合的接口而非临时 API 调用。

脚本规则

请确保遵循以下规则：

• 脚本必须接受 --help 命令行参数来描述其输入和输出
• 非破坏性脚本应在交付给用户之前进行测试
• 优先使用 Shell 脚本，但如果复杂度或用户需求要求，可使用 Python 或 TSX。
• 重要：使用 HF_TOKEN 环境变量作为 Authorization 头。例如：curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/。这提供更高的速率限制和适当的数据访问授权。
• 在确定最终设计之前，先调查 API 结果的数据结构；在可组合性有优势的地方利用管道和链式调用——尽可能优先选择简单方案。
• 完成后分享使用示例。

如有疑问或需要澄清，请确认用户偏好。

示例脚本

以下路径相对于此技能目录。

参考示例：

• references/hf_model_papers_auth.sh — 自动使用 HF_TOKEN，将趋势 → 模型元数据 → 模型卡片解析与回退机制链式调用；展示了多步骤 API 使用以及对受限/私有内容的认证处理。
• references/find_models_by_paper.sh — 通过 --token 可选使用 HF_TOKEN，一致的认证搜索，以及当 arXiv 前缀搜索范围过窄时的重试路径；展示了弹性查询策略和清晰的用户界面帮助。
• references/hf_model_card_frontmatter.sh — 使用 hf CLI 下载模型卡片，提取 YAML 前置信息，并输出 NDJSON 摘要（许可证、pipeline 标签、标签、受限提示标志）以便于过滤。

基础示例（超简单、最少逻辑、带 HF_TOKEN 头的原始 JSON 输出）：

• references/baseline_hf_api.sh — bash
• references/baseline_hf_api.py — python
• references/baseline_hf_api.tsx — typescript 可执行文件

可组合工具（stdin → NDJSON）：

• references/hf_enrich_models.sh — 从 stdin 读取模型 ID，按 ID 获取元数据，每行输出一个 JSON 对象用于流式管道。

通过管道实现可组合性（shell 友好的 JSON 输出）：

• references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'
• references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'
• 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})'

高级端点

以下是 https://huggingface.co 上可用的主要 API 端点

/api/datasets
/api/models
/api/spaces
/api/collections
/api/daily_papers
/api/notifications
/api/settings
/api/whoami-v2
/api/trending
/oauth/userinfo

访问 API

API 使用 OpenAPI 标准文档化，位于 https://huggingface.co/.well-known/openapi.json。

重要： 不要尝试直接读取 https://huggingface.co/.well-known/openapi.json，因为它太大无法处理。

重要 使用 jq 查询和提取相关部分。例如，

获取所有 160 个端点的命令

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'

模型搜索端点详情

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'

你也可以查询端点以查看数据结构。这样做时将结果限制为少量以便于处理，同时保持代表性。

使用 HF 命令行工具

hf 命令行工具让你进一步访问 Hugging Face 仓库内容和基础设施。

❯ 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             Downl