
关于
通过 Dataset Viewer API 查询 Hugging Face 数据集,支持分片、行数据、搜索、过滤和 Parquet 链接。
source: "https://github.com/huggingface/skills/tree/main/skills/huggingface-datasets" name: hugging-face-dataset-viewer description: 通过 Dataset Viewer API 查询 Hugging Face 数据集,获取分片、行、搜索、过滤和 Parquet 链接。 risk: unknown
Hugging Face 数据集查看器
何时使用
当需要通过 Dataset Viewer API 对 Hugging Face 数据集进行只读探索时使用此技能。
使用此技能执行只读的 Dataset Viewer API 调用,用于数据集探索和数据提取。
核心工作流
- 可选:使用
/is-valid验证数据集可用性。 - 使用
/splits解析config+split。 - 使用
/first-rows预览数据。 - 使用
/rows配合offset和length(最大 100)进行分页。 - 使用
/search进行文本匹配,使用/filter进行行谓词过滤。 - 通过
/parquet获取 Parquet 链接,通过/size和/statistics获取总量及元数据。
默认配置
- 基础 URL:
https://datasets-server.huggingface.co - 默认 API 方法:
GET - 查询参数应进行 URL 编码。
offset从 0 开始。- 行类端点的
length最大值通常为100。 - 受限/私有数据集需要
Authorization: Bearer <HF_TOKEN>。
数据集查看器 API
验证数据集:/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中排序。- 保持过滤和搜索为只读操作,无副作用。
查询数据集
使用 npx parquetlens 配合 Hub Parquet 别名路径进行 SQL 查询。
Parquet 别名格式:
hf://datasets/<namespace>/<repo>@~parquet/<config>/<split>/<shard>.parquet
从 Dataset Viewer /parquet 获取 <config>、<split> 和 <shard>:
curl -s "https://datasets-server.huggingface.co/parquet?dataset=cfahlgren1/hub-stats" \
| jq -r '.parquet_files[] | "hf://datasets/\(.dataset)@~parquet/\(.config)/\(.split)/\(.filename)"'
运行 SQL 查询:
npx -y -p parquetlens -p @parquetlens/sql parquetlens \
"hf://datasets/<namespace>/<repo>@~parquet/<config>/<split>/<shard>.parquet" \
--sql "SELECT * FROM data LIMIT 20"
SQL 导出
- CSV:
--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.csv' (FORMAT CSV, HEADER, DELIMITER ',')" - JSON:
--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.json' (FORMAT JSON)" - Parquet:
--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.parquet' (FORMAT PARQUET)"
创建和上传数据集
根据依赖约束选择以下流程之一。
零本地依赖(Hub UI):
- 在浏览器中创建数据集仓库:
https://huggingface.co/new-dataset - 在仓库文件和版本页面上传 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 获取 <config>/<split>/<shard> 值,用于 @~parquet 查询。
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果所需输入、权限或上下文不明确,请停下来寻求澄清。
兼容工具
Claude CodeCursor
标签
后端开发
