hugging-face-datasets

概述

此技能提供用于管理 Hugging Face Hub 上数据集的工具，重点关注数据集的创建、配置、内容管理和基于 SQL 的数据操作。它旨在补充现有的 Hugging Face MCP 服务，提供数据集编辑和查询功能。

与 HF MCP 服务集成

• 使用 HF MCP 服务进行：数据集发现、搜索和元数据检索
• 使用此技能进行：数据集创建、内容编辑、SQL 查询、数据转换和结构化数据格式化

版本

2.1.0

依赖项

此技能使用 PEP 723 脚本进行内联依赖管理

运行脚本时会自动安装所需依赖项：uv run scripts/script_name.py

• uv（Python 包管理器）
• 入门指南：请参阅下方“使用说明”，了解 PEP 723 的用法

核心功能

1. 数据集生命周期管理

• 初始化：创建结构规范的新数据集仓库
• 配置：存储详细配置，包括系统提示词和元数据
• 流式更新：无需下载整个数据集即可高效添加行

2. 基于 SQL 的数据集查询（新增）

通过 scripts/sql_manager.py 使用 DuckDB SQL 查询任意 Hugging Face 数据集：

• 直接查询：使用 hf:// 协议对数据集运行 SQL
• 架构发现：描述数据集结构和列类型
• 数据采样：获取随机样本以便探索
• 聚合：分析计数、直方图和唯一值
• 转换：使用 SQL 筛选、联接和重塑数据
• 导出与推送：在本地保存结果，或推送到新的 Hub 仓库

3. 多格式数据集支持

通过模板系统支持多种数据集类型：

• 聊天/对话：聊天模板、多轮对话、工具使用示例
• 文本分类：情感分析、意图检测、主题分类
• 问答：阅读理解、事实问答、知识库
• 文本补全：语言建模、代码补全、创意写作
• 表格数据：用于回归/分类任务的结构化数据
• 自定义格式：为专门需求灵活定义架构

4. 质量保证功能

• JSON 验证：确保上传期间的数据完整性
• 批处理：高效处理大型数据集
• 错误恢复：妥善处理上传失败和冲突

使用说明

此技能包含两个使用 PEP 723 内联依赖管理的 Python 脚本：

所有路径均相对于包含此 SKILL.md 文件的目录。 脚本运行方式：uv run scripts/script_name.py [arguments]

• scripts/dataset_manager.py - 数据集创建和管理
• scripts/sql_manager.py - 基于 SQL 的数据集查询和转换

先决条件

• 已安装 uv 包管理器
• 必须设置 HF_TOKEN 环境变量，并使用具有写入权限的令牌

---

SQL 数据集查询（sql_manager.py）

使用 DuckDB SQL 查询、转换并推送 Hugging Face 数据集。hf:// 协议可直接访问任何公开数据集（使用令牌也可访问私有数据集）。

快速入门

# Query a dataset
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --sql "SELECT * FROM data WHERE subject='nutrition' LIMIT 10"

# Get dataset schema
uv run scripts/sql_manager.py describe --dataset "cais/mmlu"

# Sample random rows
uv run scripts/sql_manager.py sample --dataset "cais/mmlu" --n 5

# Count rows with filter
uv run scripts/sql_manager.py count --dataset "cais/mmlu" --where "subject='nutrition'"

SQL 查询语法

在 SQL 中使用 data 作为表名——它会被替换为实际的 hf:// 路径：

-- Basic select
SELECT * FROM data LIMIT 10

-- Filtering
SELECT * FROM data WHERE subject='nutrition'

-- Aggregations
SELECT subject, COUNT(*) as cnt FROM data GROUP BY subject ORDER BY cnt DESC

-- Column selection and transformation
SELECT question, choices[answer] AS correct_answer FROM data

-- Regex matching
SELECT * FROM data WHERE regexp_matches(question, 'nutrition|diet')

-- String functions
SELECT regexp_replace(question, '\n', '') AS cleaned FROM data

常见操作

1. 探索数据集结构

# Get schema
uv run scripts/sql_manager.py describe --dataset "cais/mmlu"

# Get unique values in column
uv run scripts/sql_manager.py unique --dataset "cais/mmlu" --column "subject"

# Get value distribution
uv run scripts/sql_manager.py histogram --dataset "cais/mmlu" --column "subject" --bins 20

2. 筛选和转换

# Complex filtering with SQL
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --sql "SELECT subject, COUNT(*) as cnt FROM data GROUP BY subject HAVING cnt > 100"

# Using transform command
uv run scripts/sql_manager.py transform \
  --dataset "cais/mmlu" \
  --select "subject, COUNT(*) as cnt" \
  --group-by "subject" \
  --order-by "cnt DESC" \
  --limit 10

3. 创建子集并推送到 Hub

# Query and push to new dataset
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --sql "SELECT * FROM data WHERE subject='nutrition'" \
  --push-to "username/mmlu-nutrition-subset" \
  --private

# Transform and push
uv run scripts/sql_manager.py transform \
  --dataset "ibm/duorc" \
  --config "ParaphraseRC" \
  --select "question, answers" \
  --where "LENGTH(question) > 50" \
  --push-to "username/duorc-long-questions"

4. 导出到本地文件

# Export to Parquet
uv run scripts/sql_manager.py export \
  --dataset "cais/mmlu" \
  --sql "SELECT * FROM data WHERE subject='nutrition'" \
  --output "nutrition.parquet" \
  --format parquet

# Export to JSONL
uv run scripts/sql_manager.py export \
  --dataset "cais/mmlu" \
  --sql "SELECT * FROM data LIMIT 100" \
  --output "sample.jsonl" \
  --format jsonl

5. 使用数据集配置/拆分

# Specify config (subset)
uv run scripts/sql_manager.py query \
  --dataset "ibm/duorc" \
  --config "ParaphraseRC" \
  --sql "SELECT * FROM data LIMIT 5"

# Specify split
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --split "test" \
  --sql "SELECT COUNT(*) FROM data"

# Query all splits
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --split "*" \
  --sql "SELECT * FROM data LIMIT 10"

6. 使用完整路径运行原始 SQL

用于复杂查询或联接数据集：

uv run scripts/sql_manager.py raw --sql "
  SELECT a.*, b.* 
  FROM 'hf://datasets/dataset1@~parquet/default/train/*.parquet' a
  JOIN 'hf://datasets/dataset2@~parquet/default/train/*.parquet' b
  ON a.id = b.id
  LIMIT 100
"

Python API 用法

from sql_manager import HFDatasetSQL

sql = HFDatasetSQL()

# Query
results = sql.query("cais/mmlu", "SELECT * FROM data WHERE subject='nutrition' LIMIT 10")

# Get schema
schema = sql.describe("cais/mmlu")

# Sample
samples = sql.sample("cais/mmlu", n=5, seed=42)

# Count
count = sql.count("cais/mmlu", where="subject='nutrition'")

# Histogram
dist = sql.histogram("cais/mmlu", "subject")

# Filter and transform
results = sql.filter_and_transform(
    "cais/mmlu",
    select="subject, COUNT(*) as cnt",
    group_by="subject",
    order_by="cnt DESC",
    limit=10
)

# Push to Hub
url = sql.push_to_hub(
    "cais/mmlu",
    "username/nutrition-subset",
    sql="SELECT * FROM data WHERE subject='nutrition'",
    private=True
)

# Export locally
sql.export_to_parquet("cais/mmlu", "output.parquet", sql="SELECT * FROM data LIMIT 100")

sql.close()

HF 路径格式

DuckDB 使用 hf:// 协议访问数据集：

hf://datasets/{dataset_id}@{revision}/{config}/{split}/*.parquet

示例：

• hf://datasets/cais/mmlu@~parquet/default/train/*.parquet
• hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/*.parquet

@~parquet 修订版本会为任何格式的数据集提供自动转换的 Parquet 文件。

实用的 DuckDB SQL 函数

-- String functions
LENGTH(column)                    -- String length
regexp_replace(col, '\n', '')     -- Regex replace
regexp_matches(col, 'pattern')    -- Regex match
LOWER(col), UPPER(col)           -- Case conversion

-- Array functions  
choices[0]                        -- Array indexing (0-based)
array_length(choices)             -- Array length
unnest(choices)                   -- Expand array to rows

-- Aggregations
COUNT(*), SUM(col), AVG(col)
GROUP BY col HAVING condition

-- Sampling
USING SAMPLE 10                   -- Random sample
USING SAMPLE 10 (RESERVOIR, 42)   -- Reproducible sample

-- Window functions
ROW_NUMBER() OVER (PARTITION BY col ORDER BY col2)

---

数据集创建（dataset_manager.py）

推荐工作流

1. 发现（使用 HF MCP Server）：

# Use HF MCP tools to find existing datasets
search_datasets("conversational AI training")
get_dataset_details("username/dataset-name")

2. 创建（使用此技能）：

# Initialize new dataset
uv run scripts/dataset_manager.py init --repo_id "your-username/dataset-name" [--private]

# Configure with detailed system prompt
uv run scripts/dataset_manager.py config --repo_id "your-username/dataset-name" --system_prompt "$(cat system_prompt.txt)"

3. 内容管理（使用此技能）：

# Quick setup with any template
uv run scripts/dataset_manager.py quick_setup \
  --repo_id "your-username/dataset-name" \
  --template classification

# Add data with template validation
uv run scripts/dataset_manager.py add_rows \
  --repo_id "your-username/dataset-name" \
  --template qa \
  --rows_json "$(cat your_qa_data.json)"

基于模板的数据结构

1. 对话模板（--template chat）

{
  "messages": [
    {"role": "user", "content": "Natural user request"},
    {"role": "assistant", "content": "Response with tool usage"},
    {"role": "tool", "content": "Tool response", "tool_call_id": "call_123"}
  ],
  "scenario": "Description of use case",
  "complexity": "simple|intermediate|advanced"
}

2. 分类模板（--template classification）

{
  "text": "Input text to be classified",
  "label": "classification_label",
  "confidence": 0.95,
  "metadata": {"domain": "technology", "language": "en"}
}

3. 问答模板（--template qa）

{
  "question": "What is the question being asked?",
  "answer": "The complete answer",
  "context": "Additional context if needed",
  "answer_type": "factual|explanatory|opinion",
  "difficulty": "easy|medium|hard"
}

4. 补全模板（--template completion）

{
  "prompt": "The beginning text or context",
  "completion": "The expected continuation",
  "domain": "code|creative|technical|conversational",
  "style": "description of writing style"
}

5. 表格模板（--template tabular）

{
  "columns": [
    {"name": "feature1", "type": "numeric", "description": "First feature"},
    {"name": "target", "type": "categorical", "description": "Target variable"}
  ],
  "data": [
    {"feature1": 123, "target": "class_a"},
    {"feature1": 456, "target": "class_b"}
  ]
}

高级系统提示词模板

用于生成高质量训练数据：

You are an AI assistant expert at using MCP tools effectively.

## MCP SERVER DEFINITIONS
[Define available servers and tools]

## TRAINING EXAMPLE STRUCTURE
[Specify exact JSON schema for chat templating]

## QUALITY GUIDELINES
[Detail requirements for realistic scenarios, progressive complexity, proper tool usage]

## EXAMPLE CATEGORIES
[List development workflows, debugging scenarios, data management tasks]

示例类别与模板

此技能包含多种训练示例，不仅限于 MCP 用法：

可用示例集：

• training_examples.json - MCP 工具使用示例（调试、项目设置、数据库分析）
• diverse_training_examples.json - 更广泛的场景，包括：
  • 教育对话 - 解释编程概念、教程
  • Git 工作流 - 功能分支、版本控制指导
  • 代码分析 - 性能优化、架构审查
  • 内容生成 - 专业写作、创意构思
  • 代码库导航 - 探索遗留代码、系统化分析
  • 对话支持 - 问题解决、技术讨论

使用不同的示例集：

# Add MCP-focused examples
uv run scripts/dataset_manager.py add_rows --repo_id "your-username/dataset-name" \
  --rows_json "$(cat examples/training_examples.json)"

# Add diverse conversational examples
uv run scripts/dataset_manager.py add_rows --repo_id "your-username/dataset-name" \
  --rows_json "$(cat examples/diverse_training_examples.json)"

# Mix both for comprehensive training data
uv run scripts/dataset_manager.py add_rows --repo_id "your-username/dataset-name" \
  --rows_json "$(jq -s '.[0] + .[1]' examples/training_examples.json examples/diverse_training_examples.json)"

命令参考

列出可用模板：

uv run scripts/dataset_manager.py list_templates

快速设置（推荐）：

uv run scripts/dataset_manager.py quick_setup --repo_id "your-username/dataset-name" --template classification

手动设置：

# Initialize repository
uv run scripts/dataset_manager.py init --repo_id "your-username/dataset-name" [--private]

# Configure with system prompt
uv run scripts/dataset_manager.py config --repo_id "your-username/dataset-name" --system_prompt "Your prompt here"

# Add data with validation
uv run scripts/dataset_manager.py add_rows \
  --repo_id "your-username/dataset-name" \
  --template qa \
  --rows_json '[{"question": "What is AI?", "answer": "Artificial Intelligence..."}]'

查看数据集统计信息：

uv run scripts/dataset_manager.py stats --repo_id "your-username/dataset-name"

错误处理

• 仓库已存在：脚本会发出通知并继续配置
• JSON 无效：提供清晰的错误消息和解析详情
• 网络问题：自动重试暂时性故障
• 令牌权限：在操作开始前进行验证

---

组合工作流示例

示例 1：从现有数据集创建训练子集

# 1. Explore the source dataset
uv run scripts/sql_manager.py describe --dataset "cais/mmlu"
uv run scripts/sql_manager.py histogram --dataset "cais/mmlu" --column "subject"

# 2. Query and create subset
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --sql "SELECT * FROM data WHERE subject IN ('nutrition', 'anatomy', 'clinical_knowledge')" \
  --push-to "username/mmlu-medical-subset" \
  --private

示例 2：转换和重塑数据

# Transform MMLU to QA format with correct answers extracted
uv run scripts/sql_manager.py query \
  --dataset "cais/mmlu" \
  --sql "SELECT question, choices[answer] as correct_answer, subject FROM data" \
  --push-to "username/mmlu-qa-format"

示例 3：合并多个数据集拆分

# Export multiple splits and combine
uv run scripts/sql_manager.py export \
  --dataset "cais/mmlu" \
  --split "*" \
  --output "mmlu_all.parquet"

示例 4：质量筛选

# Filter for high-quality examples
uv run scripts/sql_manager.py query \
  --dataset "squad" \
  --sql "SELECT * FROM data WHERE LENGTH(context) > 500 AND LENGTH(question) > 20" \
  --push-to "username/squad-filtered"

示例 5：创建自定义训练数据集

# 1. Query source data
uv run scripts/sql_manager.py export \
  --dataset "cais/mmlu" \
  --sql "SELECT question, subject FROM data WHERE subject='nutrition'" \
  --output "nutrition_source.jsonl" \
  --format jsonl

# 2. Process with your pipeline (add answers, format, etc.)

# 3. Push processed data
uv run scripts/dataset_manager.py init --repo_id "username/nutrition-training"
uv run scripts/dataset_manager.py add_rows \
  --repo_id "username/nutrition-training" \
  --template qa \
  --rows_json "$(cat processed_data.json)"