AgentSkillsCN

sdv-synthetic-data

使用SDV（合成数据仓库）生成人工数据（合成数据）。通过机器学习对真实数据的模式进行学习，生成在保护隐私的前提下生成的合成数据。应用场景：(1) 单一表的合成数据生成；(2) 多个表（关系型数据库）的合成数据生成；(3) 时序数据的合成数据生成；(4) 合成数据的质量评估；(5) 元数据及约束条件的设定。

SKILL.md
--- frontmatter
name: sdv-synthetic-data
description: "SDV (Synthetic Data Vault) を使用した人工データ（合成データ）の生成。機械学習で実データのパターンを学習し、プライバシーを保護した合成データを生成する。使用シーン: (1) 単一テーブルの合成データ生成、(2) 複数テーブル（リレーショナルDB）の合成データ生成、(3) 時系列データの合成データ生成、(4) 合成データの品質評価、(5) メタデータや制約の設定"

SDV 人工データ生成

SDV (Synthetic Data Vault) を使用して、実データのパターンを学習した高品質な合成データを生成する。

最重要: データプライバシー制限

このセクションを必ず最初に確認し、以下のルールを厳守すること。

禁止事項（絶対に行わないこと）

  1. •

    Readツールでデータファイルを読み取らない

    • •対象拡張子: .csv, .xlsx, .xls, .json, .pkl, .html, .txt
    • •ユーザーのデータ内容を確認・表示しない
    • •生成された合成データも閲覧禁止
  2. •

    データプレビューコードを生成しない

    • •print(data), print(df), data.head(), data.tail(), data.sample() 等を含めない
  3. •

    実際のデータ値をログ出力しない

事前のデータ確認は不要

スクリプトがデータ構造を自動検出するため、事前にデータファイルの内容や構造を確認しないこと。 ワークフローに従い、ユーザーへの確認（生成行数、シード値等）のみを行い、直接スクリプトを実行すること。

対応ファイル形式

データ入力（対応形式）

形式拡張子読み込み方法
CSV.csvpd.read_csv()
Excel.xlsx, .xlspd.read_excel()
JSON.jsonpd.read_json()

SDV生成ファイル

ファイル種別拡張子説明
合成データ.csv, .xlsx, .json生成された合成データ
シンセサイザー.pkl学習済みモデル
メタデータ.jsonデータ構造定義
品質レポート.html, .txt評価レポート

実行環境の確認と実行方法

このスキルは、スキルを実行するプロジェクトの Python 環境を確認し、その環境でスクリプトを実行する。

確認の目安（上から優先）:

  • •uv.lock や pyproject.toml がある → uv 環境を優先し、uv run python scripts/... で実行
  • •.venv/ がある → その仮想環境の Python を使用（例: .venv/bin/python scripts/...）
  • •上記がない場合 → どの環境で実行するかユーザーに確認する

※ 実行コマンドは、必ず対象プロジェクトの環境（uv/venv/poetry/pipenv 等）に合わせて選ぶ。

ワークフロー

合成データを生成する際は、以下の手順に従う。 スクリプトはすべてのオプションを実行時引数として受け取るため、ステップ1〜4の確認をすべて完了してからステップ5でスクリプトを実行すること。

  1. •

    生成行数の確認: ユーザーに生成したい行数（num_rows）を確認する。AskUserQuestionツールを使用して以下のように尋ねる:

    • •質問: "合成データを何行生成しますか？"
    • •ヘッダー: "生成行数"
    • •選択肢:
      • •"元データと同じ行数（推奨）" - 元データと同じ行数を生成
      • •"1,000行" - 1,000行を生成
      • •"10,000行" - 10,000行を生成
      • •"100,000行" - 100,000行を生成
    • •ユーザーが「Other」を選択した場合は、入力された数値を使用する
  2. •

    シード値の確認: 再現性を確保するため、シード値（seed）を確認する。AskUserQuestionツールを使用して以下のように尋ねる:

    • •質問: "再現性のためシード値を指定しますか？"
    • •ヘッダー: "シード値"
    • •選択肢:
      • •"指定しない（ランダム）（推奨）" - シード値を指定せずランダムに生成
      • •"42" - シード値42を使用（一般的なデフォルト値）
      • •"123" - シード値123を使用
      • •"0" - シード値0を使用
    • •ユーザーが「Other」を選択した場合は、入力された数値を使用する
    • •シード値を指定する場合は、乱数シードを設定し、sample が seed 引数に対応している場合のみ渡す（実装はスクリプト内を参照）
  3. •

    シンセサイザーの選択: 必要に応じてシンセサイザーの種類を確認する

  4. •

    モデルとメタデータの保存確認: 学習済みモデルを再利用できるよう、保存するか確認する。AskUserQuestionツールを使用して以下のように尋ねる:

    • •質問: "学習済みシンセサイザーとメタデータを保存しますか？"
    • •ヘッダー: "モデル保存"
    • •選択肢:
      • •"両方保存（推奨）" - シンセサイザーとメタデータの両方を保存
      • •"シンセサイザーのみ" - 学習済みシンセサイザーのみ保存
      • •"保存しない" - 保存せずに終了
    • •保存手順・読み込み手順は各スクリプトのオプション（--save-model, --save-metadata）を参照
  5. •

    データ生成: ステップ1〜4で確認したすべてのオプション（行数、シード値、シンセサイザー、保存設定）をスクリプトの引数として渡して実行する

クイックスタート

scripts/generate_single_table.py を使って単一テーブルの合成データを生成する。 注意: スクリプトはこのスキル配下の .codex/skills/sdv-synthetic-data/scripts/ に存在する。新規スクリプトは作成せず、既存スクリプトを直接実行する（例: uv run python .codex/skills/sdv-synthetic-data/scripts/generate_single_table.py ...）。

シンセサイザー選択

シンセサイザー特徴推奨用途
GaussianCopulaSynthesizer高速・透明性・カスタマイズ可能デフォルト選択
CTGANSynthesizerGAN使用・高忠実度より複雑なパターン
TVAESynthesizerVAE使用・高忠実度複雑なパターン
CopulaGANSynthesizerGaussianCopula + CTGANハイブリッド

具体的な選択は generate_single_table.py の --synthesizer オプションを参照。

メタデータ設定

自動検出

generate_single_table.py / generate_multi_table.py が Metadata.detect_from_dataframe(...) を使用。

手動設定

手動設定が必要な場合は --save-metadata で保存し、編集後に読み込む運用を推奨。

sdtype一覧

  • •numerical: 数値
  • •datetime: 日時（datetime_format必須）
  • •categorical: カテゴリ
  • •boolean: 真偽値
  • •id: 識別子（regex_formatでパターン指定可）
  • •email, phone_number, ssn 等: PII自動匿名化

制約設定

ビジネスルールを100%保証する制約を追加。

制約設定はメタデータの編集や追加実装が必要。必要に応じてスクリプトを拡張する。

複数テーブル（リレーショナル）

generate_multi_table.py を使用。設定ファイルで tables と relationships を指定し、--scale で生成量を調整。

generate_multi_table.py は各テーブルを metadata.detect_from_dataframe(..., table_name=...) で自動検出し、設定ファイルの primary_key と relationships を適用します。必要なら --save-metadata で保存して後から調整できます。

時系列データ

時系列は現状スクリプト未対応。必要なら新規スクリプトを追加する。

品質評価

品質評価は evaluate_quality.py を使用。診断レポートは実行時に確認され、--diagnostic または --diagnostic-output で明示的に出力可能。

モデル保存・読み込み

保存・読み込みは各スクリプトの --save-model / --save-metadata オプションを使用。

スクリプト

再利用可能なスクリプトは scripts/ を参照:

  • •generate_single_table.py: 単一テーブル合成データ生成（--rows, --seed, --synthesizer, --epochs, --save-model, --save-metadata）
  • •generate_multi_table.py: 複数テーブル合成データ生成（--config, --output-dir, --output-format, --scale, --seed, --save-model, --save-metadata）
  • •evaluate_quality.py: 品質評価レポート生成（--output, --diagnostic, --diagnostic-output）