Hugging Face 数据集查看器

Hugging Face 数据集查看器

使用此技能执行只读的数据集查看器 API 调用来进行数据集探索和提取。

核心工作流程

1. 可选地使用 /is-valid 验证数据集可用性。
2. 使用 /splits 解析 config + split。
3. 使用 /first-rows 预览。
4. 使用 offset 和 length（最大 100）通过 /rows 分页内容。
5. 使用 /search 进行文本匹配，使用 /filter 进行行谓词过滤。
6. 通过 /parquet 检索 parquet 链接，通过 /size 和 /statistics 检索总数/元数据。

默认值

• 基本 URL：https://datasets-server.huggingface.co
• 默认 API 方法：GET
• 查询参数应进行 URL 编码。
• offset 是基于 0 的。
• 对于类似行的端点，length 最大值通常为 100。
• 受限/私有数据集需要 Authorization: Bearer <HF_TOKEN>。

数据集查看器

• 验证数据集：/is-valid?dataset=<namespace/repo>
• 列出子集和分割：/splits?dataset=<namespace/repo>
• 预览前几行：/first-rows?dataset=<namespace/repo>&config=<config>&split=<split>
• 分页行：/rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int>
• 搜索文本：/search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int>
• 使用谓词过滤：/filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int>
• 列出 parquet 分片：/parquet?dataset=<namespace/repo>
• 获取大小总计：/size?dataset=<namespace/repo>
• 获取列统计信息：/statistics?dataset=<namespace/repo>&config=<config>&split=<split>
• 获取 Croissant 元数据（如果可用）：/croissant?dataset=<namespace/repo>

分页模式：

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"

当分页不完整时，使用响应字段如 num_rows_total、num_rows_per_page 和 partial 来驱动继续逻辑。

搜索/过滤注意事项：

• /search 匹配字符串列（全文样式行为在 API 内部）。
• /filter 需要 where 中的谓词语法和 orderby 中的可选排序。
• 保持过滤和搜索为只读且无副作用。

对于基于 CLI 的 parquet URL 发现或 SQL，请使用 hf-cli 技能配合 hf datasets parquet 和 hf datasets sql。

创建和上传数据集

根据依赖约束使用以下流程之一。

零本地依赖（Hub UI）：

• 在浏览器中创建数据集仓库：https://huggingface.co/new-dataset
• 在仓库的"文件和版本"页面上传 parquet 文件。
• 验证分片是否出现在数据集查看器中：

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

低依赖 CLI 流程（npx @huggingface/hub / hfjs）：

• 设置认证令牌：

export HF_TOKEN=<your_hf_token>

• 将 parquet 文件夹上传到数据集仓库（如果仓库不存在则自动创建）：

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

• 在创建时上传为私有仓库：

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

上传后，调用 /parquet 发现用于使用 @~parquet 查询的 <config>/<split>/<shard> 值。

Agent Traces

Hub 支持来自 Claude Code、Codex 和 Pi Agent 的原始代理会话跟踪。将它们作为原始 JSONL 文件上传到 Hugging Face Datasets，Hub 可以自动检测跟踪格式，将数据集标记为 Traces，并启用跟踪查看器以浏览会话、轮次、工具调用和模型响应。常见的本地会话目录：

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

默认使用私有数据集仓库，因为跟踪可能包含提示、文件路径、工具输出、密钥或 PII。保留原始 .jsonl 文件，并按项目/工作目录嵌套，而不是将每个会话上传到数据集根目录。

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