hugging-face-datasets

概要

このスキルは、作成、設定、コンテンツ管理、SQL ベースのデータ操作に重点を置き、Hugging Face Hub 上のデータセットを管理するためのツールを提供します。データセットの編集およびクエリ機能を提供することで、既存の 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. 複数形式のデータセットに対応

テンプレートシステムにより、さまざまな種類のデータセットに対応しています。

• チャット／会話：チャットのテンプレート化、複数ターンの対話、ツールの使用例
• テキスト分類：感情分析、インテント検出、トピック分類
• 質問応答：読解力、事実に基づく QA、ナレッジベース
• テキスト補完：言語モデリング、コード補完、クリエイティブライティング
• 表形式データ：回帰／分類タスク用の構造化データ
• カスタム形式：特定のニーズに合わせて柔軟にスキーマを定義できます

4. 品質保証機能

• JSON 検証：アップロード中にデータの整合性を確認します
• バッチ処理：大規模なデータセットを効率的に処理します
• エラーからの復旧：アップロードの失敗や競合を適切に処理します

使用方法

このスキルには、PEP 723 のインライン依存関係管理を使用する Python スクリプトが 2 つ含まれています。

すべてのパスは、この 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. QA テンプレート（--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)"