Visualizador de Datasets Hugging Face

Quando Usar

Use esta habilidade quando precisar do 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. 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 do 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 do tipo linha.
• Datasets com portão/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 busca/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 buscas como 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 de uma pasta de 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 originais 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

Limitações

…