Construtor de Ferramentas da API Hugging Face

Quando Usar

Use esta habilidade quando o usuário quiser construir ferramentas/scripts ou realizar uma tarefa onde o uso de dados da API Hugging Face seria útil. Isso é especialmente útil ao encadear ou combinar chamadas de API ou quando a tarefa será repetida/automatizada. Esta Habilidade cria um script reutilizável para buscar, enriquecer...

Seu propósito agora é criar scripts e utilitários de linha de comando reutilizáveis para usar a API Hugging Face, permitindo encadeamento, piping e processamento intermediário onde for útil. Você pode acessar a API diretamente, bem como usar a ferramenta de linha de comando hf. Cartões de modelos e conjuntos de dados podem ser acessados diretamente de repositórios.

Regras de Script

Certifique-se de seguir estas regras:

• Scripts devem aceitar um argumento de linha de comando --help para descrever suas entradas e saídas
• Scripts não destrutivos devem ser testados antes de serem entregues ao Usuário
• Scripts shell são preferidos, mas use Python ou TSX se a complexidade ou a necessidade do usuário exigir.
• IMPORTANTE: Use a variável de ambiente HF_TOKEN como um cabeçalho de Autorização. Por exemplo: curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/. Isso fornece limites de taxa mais altos e autorização apropriada para acesso a dados.
• Investigue a forma dos resultados da API antes de se comprometer com um design final; faça uso de piping e encadeamento onde a composibilidade seria uma vantagem - prefira soluções simples sempre que possível.
• Compartilhe exemplos de uso assim que concluído.

Certifique-se de confirmar as preferências do usuário quando houver perguntas ou esclarecimentos necessários.

Exemplos de Scripts

Os caminhos abaixo são relativos a este diretório de habilidade.

Exemplos de referência:

• references/hf_model_papers_auth.sh — usa HF_TOKEN automaticamente e encadeia trending → metadados do modelo → análise do cartão do modelo com fallbacks; demonstra uso de API em várias etapas mais higiene de autenticação para conteúdo restrito/privado.
• references/find_models_by_paper.sh — uso opcional de HF_TOKEN via --token, busca autenticada consistente e um caminho de retentativa quando buscas com prefixo arXiv são muito restritas; mostra estratégia de consulta resiliente e ajuda clara para o usuário.
• references/hf_model_card_frontmatter.sh — usa a CLI hf para baixar cartões de modelos, extrai frontmatter YAML e emite resumos NDJSON (licença, tag de pipeline, tags, flag de prompt restrito) para filtragem fácil.

Exemplos de linha de base (ultra-simples, lógica mínima, saída JSON bruta com cabeçalho HF_TOKEN):

• references/baseline_hf_api.sh — bash
• references/baseline_hf_api.py — python
• references/baseline_hf_api.tsx — executável typescript

Utilitário Componível (stdin → NDJSON):

• references/hf_enrich_models.sh — lê IDs de modelo do stdin, busca metadados por ID, emite um objeto JSON por linha para pipelines de streaming.

Composibilidade através de piping (saída JSON amigável para shell):

• 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})'

Endpoints de Alto Nível

Os seguintes são os principais endpoints da API disponíveis em 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

Acessando a API

A API é documentada com o padrão OpenAPI em https://huggingface.co/.well-known/openapi.json.

IMPORTANTE: NÃO TENTE ler https://huggingface.co/.well-known/openapi.json diretamente, pois é muito grande para processar.

IMPORTANTE Use jq para consultar e extrair partes relevantes. Por exemplo,

Comando para Obter Todos os 160 Endpoints

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

Detalhes do Endpoint de Busca de Modelos

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

Você também pode consultar endpoints para ver a forma dos dados. Ao fazer isso, restrinja os resultados a números baixos para torná-los fáceis de processar, mas representativos.

Usando a ferramenta de linha de comando HF

A ferramenta de linha de comando hf oferece acesso adicional ao conteúdo e infraestrutura do repositório Hugging Face.

❯ hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:

…