huggingface-datasets

Hugging Face 数据集查看器

使用此技能执行只读的 Dataset Viewer API 调用，以探索和提取数据集。

核心工作流

1. 可选：通过 /is-valid 验证数据集是否可用。
2. 通过 /splits 确定 config 和 split。
3. 使用 /first-rows 预览。
4. 使用 /rows 分页获取内容，通过 offset 和 length 指定（最多为 100）。
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>。

Dataset Viewer

• 验证数据集：/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
• 在仓库的“Files and versions”页面上传 parquet 文件。
• 确认分片显示在 Dataset Viewer 中：

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 轨迹

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

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

默认使用私有数据集仓库，因为轨迹可能包含提示词、文件路径、工具输出、机密信息或个人身份信息。保留原始 .jsonl 文件，并按项目／cwd 嵌套存放，而不是将所有会话都上传到数据集根目录。

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