Quando Usar

• Use quando o fluxo de trabalho upstream corresponder ao objetivo declarado do usuário.
• Use quando a tarefa exigir os procedimentos documentados nesta habilidade.

Visualizador de Datasets Hugging Face

Use esta habilidade para executar chamadas de API do Visualizador de Datasets somente leitura para exploração e extração de datasets.

Fluxo de trabalho principal

1. Opcionalmente, valide a disponibilidade do dataset com /is-valid.
2. Resolva config + split com /splits.
3. Pré-visualize com /first-rows.
4. Paginação de conteúdo com /rows usando offset e length (máximo de 100).
5. Use /search para correspondência de texto e /filter para predicados de linha.
6. Recupere links de parquet via /parquet e totais/metadados via /size e /statistics.

Padrões

• URL base: https://datasets-server.huggingface.co
• Método de API padrão: GET
• Os parâmetros de consulta devem ser codificados em URL.
• offset é baseado em 0.
• O máximo de length é geralmente 100 para endpoints semelhantes a linhas.
• Datasets protegidos/privados exigem Authorization: Bearer <HF_TOKEN>.

Visualizador de Datasets

• Validate dataset: /is-valid?dataset=<namespace/repo>
• List subsets and splits: /splits?dataset=<namespace/repo>
• Preview first rows: /first-rows?dataset=<namespace/repo>&config=<config>&split=<split>
• Paginate rows: /rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int>
• Search text: /search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int>
• Filter with predicates: /filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int>
• List parquet shards: /parquet?dataset=<namespace/repo>
• Get size totals: /size?dataset=<namespace/repo>
• Get column statistics: /statistics?dataset=<namespace/repo>&config=<config>&split=<split>
• Get Croissant metadata (if available): /croissant?dataset=<namespace/repo>

Padrão de paginação:

curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=0&length=100"
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=100&length=100"

Quando a paginação for parcial, use campos de resposta como num_rows_total, num_rows_per_page e partial para direcionar a lógica de continuação.

Notas de pesquisa/filtro:

• /search corresponde a colunas de string (o comportamento de estilo de texto completo é interno à API).
• /filter requer sintaxe de predicado em where e ordenação opcional em orderby.
• Mantenha a filtragem e as pesquisas somente leitura e sem efeitos colaterais.

Para descoberta de URL de parquet baseada em CLI ou SQL, use a habilidade hf-cli com hf datasets parquet e hf datasets sql.

Criação e Upload de Datasets

Use um destes fluxos dependendo das restrições de dependência.

Zero dependências locais (Interface do Hub):

• Crie o repositório de dataset no navegador: https://huggingface.co/new-dataset
• Faça upload de arquivos parquet na página "Arquivos e versões" do repositório.
• Verifique se os shards aparecem no Visualizador de Datasets:

curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"

Fluxo CLI de baixa dependência (npx @huggingface/hub / hfjs):

• Defina o token de autenticação:

export HF_TOKEN=<your_hf_token>

• Faça upload da pasta parquet para um repositório de dataset (cria o repositório automaticamente se estiver faltando):

npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data

• Faça upload como repositório privado na criação:

npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data --private

Após o upload, chame /parquet para descobrir os valores de <config>/<split>/<shard> para consulta com @~parquet.

Rastreamentos de Agente

O Hub suporta rastreamentos brutos de sessão de agente do Claude Code, Codex e Pi Agent. Faça o upload deles para Hugging Face Datasets como arquivos JSONL originais e o Hub poderá detectar automaticamente o formato do rastreamento, marcar o dataset como Traces e habilitar o visualizador de rastreamento para navegar por sessões, turnos, chamadas de ferramentas e respostas de modelos. Diretórios comuns de sessão local:

• Claude Code: ~/.claude/projects
• Codex: ~/.codex/sessions
• Pi: ~/.pi/agent/sessions

Use repositórios de dataset privados por padrão, pois os rastreamentos podem conter prompts, caminhos de arquivo, saídas de ferramentas, segredos ou PII. Preserve os arquivos .jsonl brutos e aninhe-os por projeto/cwd em vez de fazer upload de cada sessão na raiz do dataset.

hf repos create <namespace>/<repo> --type dataset --private --exist-ok
hf upload <namespace>/<repo> ~/.codex/sessions codex/<project-or-cwd> --type dataset

Exemplos

…