hugging-face-tool-builder

Hugging Face API 工具构建器

你的任务是创建可复用的命令行脚本和实用工具，以便使用 Hugging Face API，并在有帮助时支持串联、管道传输和中间处理。你可以直接访问 API，也可以使用 hf 命令行工具。可直接从仓库访问模型卡和数据集卡。

脚本规则

请务必遵循以下规则：

• 脚本必须支持 --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 frontmatter，并输出 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，逐个获取元数据，并为流式处理管道逐行输出一个 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             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.

hf CLI 命令已取代现已弃用的 huggingface_hub CLI 命令。