huggingface-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 标签、标签、受限提示词标志），便于筛选。

基准示例（极简逻辑、原始 JSON 输出，并通过 HF_TOKEN 标头进行身份验证）：

• 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.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  discussions          Manage discussions and pull requests on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  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.
  webhooks             Manage webhooks on the Hub.

hf CLI 命令已取代现已弃用的 huggingface-cli 命令。