golden-dataset

ゴールデンデータセット

AI／ML 評価用のゴールデンデータセットを構築、管理、検証するための包括的なパターンです。各カテゴリには個別のルールファイルがあり、rules/ から必要に応じて読み込まれます。

クイックリファレンス

カテゴリ	ルール	影響度	使用するタイミング
キュレーション	2	HIGH	コンテンツ収集、アノテーションパイプライン
管理	2	HIGH	バージョン管理、バックアップ／復元
検証	1	CRITICAL	回帰テスト
追加ワークフロー	1	HIGH	9 フェーズのキュレーション、品質スコアリング、バイアス検出、シルバーからゴールドへの移行

4 カテゴリにわたるルールは合計 6 件です。プロジェクト内のしきい値と知見については、references/ork-delta.md を参照してください。

キュレーション

ゴールデンデータセットのコンテンツ収集、マルチエージェントによるアノテーション、多様性分析を行います。

ルール	ファイル	主なパターン
収集	rules/curation-collection.md	コンテンツタイプの分類、品質しきい値、重複防止
アノテーション	rules/curation-annotation.md	マルチエージェントパイプライン、コンセンサスの集約、Langfuse トレーシング

難易度の段階、カバレッジの下限、重複のしきい値については、references/ork-delta.md を参照してください。

管理

ゴールデンデータセットのバージョン管理、ストレージ、CI／CD 自動化を行います。

ルール	ファイル	主なパターン
バージョン管理	rules/management-versioning.md	JSON バックアップ形式、埋め込みの再生成、災害復旧
ストレージ	rules/management-storage.md	バックアップ戦略、URL の契約、データ整合性チェック

バックアップの CI 自動化は上流側の担当です。下記の「上流の対応範囲」を参照してください。

検証

ゴールデンデータセットの品質スコアリング、ドリフト検出、回帰テストを行います。

ルール	ファイル	主なパターン
回帰	rules/validation-regression.md	難易度の分布、pre-commit フック、データセット全体の検証

スキーマ検証と重複検出は上流側の担当です（下記の「上流の対応範囲」を参照）。適用すべきプロジェクト内のしきい値は、references/ork-delta.md に記載されています。

追加ワークフロー

ゴールデンデータセットに新しいドキュメントを追加するための構造化されたワークフローです。

ルール	ファイル	主なパターン
ドキュメントの追加	rules/curation-add-workflow.md	9 フェーズのキュレーション、並列品質分析、バイアス検出

クイックスタート例

async def validate_before_add(document: dict, source_url_map: dict) -> dict:
    """Pre-addition validation for golden dataset entries."""
    errors = []

    # 1. URL contract check
    if "placeholder" in document.get("source_url", ""):
        errors.append("URL must be canonical, not a placeholder")

    # 2. Content quality
    if len(document.get("title", "")) < 10:
        errors.append("Title too short (min 10 chars)")

    # 3. Tag requirements
    if len(document.get("tags", [])) < 2:
        errors.append("At least 2 domain tags required")

    return {"valid": len(errors) == 0, "errors": errors}

主な決定事項

決定事項	推奨事項
バックアップ形式	JSON（バージョン管理可能で、移植性が高い）
埋め込みの保存	バックアップから除外する（復元時に再生成）
品質しきい値	採用するには品質スコアが 0.70 以上
信頼度しきい値	自動採用するには 0.65 以上
重複しきい値	類似度が 0.90 以上ならブロックし、0.85 以上なら警告
エントリあたりの最小タグ数	ドメインタグ 2 個
ドキュメントあたりの最小テストクエリ数	3 件
難易度のバランス	最低限、初級 3 件、簡単 3 件、中級 5 件、難しい 3 件
CI の頻度	週次の自動バックアップ（UTC 日曜日午前 2 時）

よくある間違い

1. 正規のソース URL ではなく、プレースホルダーの URL を使用する
2. 復元後に埋め込みの再生成を省略する
3. ドキュメントとクエリ間の参照整合性を検証しない
4. 記事に偏りすぎる（チュートリアルや研究論文を軽視する）
5. テストクエリの難易度分布のバランスを欠く
6. バックアップ／復元操作後に検証を実行しない
7. ステージング環境ではなく本番環境で復元手順をテストする
8. JSON ではなく SQL ダンプをコミットする（バージョン管理に適していない）

データセットを実験として実行する

データセットのキュレーションは作業の半分にすぎません。残りの半分は、データセットに対して何かを実行し、その結果をスコアリングすることです。Langfuse SDK にはどちらもランナーが含まれていますが、その形式は異なります。

Python（SDK 4.x）： monitoring-observability/references/experiments-api.md を参照してください。

JS/TS（SDK 5.x）： @langfuse/client は、取得したデータセットからランナーを直接利用できます。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const dataset = await langfuse.dataset.get("my-evaluation-dataset");

const result = await dataset.runExperiment({
  name: "Retrieval quality",
  task: myTask,               // (params) => Promise<any>
  evaluators: [myEvaluator],  // per-item: (params) => Promise<Evaluation | Evaluation[]>
});

種類	スコア	用途
Evaluator	1 項目	例ごとの品質（忠実性、関連性）
RunEvaluator	実行全体	集約的なアサーション — 合格率、平均スコア、回帰チェック
Evaluation	—	{ name, value, comment?, metadata?, dataType?, configId? }

項目ごとの Evaluator からは他の項目を参照できないため、比較を伴うものはすべて RunEvaluator に含めます。createEvaluatorFromAutoevals は、手書きのスコアラーの代わりに autoevals のスコアラーをラップします。また、設定済みのベースラインに対して実行結果が回帰した場合は RegressionError がスローされます。これをキャッチして、例外が発生した場合だけでなく品質が低下した場合にも CI を失敗させます。

JS の全 API：monitoring-observability/references/langfuse-js-v5.md。

評価

すべてのカテゴリを網羅する 9 件のテストケースについては、test-cases.json を参照してください。

上流のカバレッジ（内容を再掲しないでください）

トピック	公式ソース
データセットスキーマの検証（JSON Schema、フィールド制約）	https://json-schema.org と https://zod.dev
埋め込みとコサイン類似度による重複検出	https://github.com/pgvector/pgvector
スケジュールされたバックアップの自動化（cron ワークフロー、コミットボット）	https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#schedule
データセットの実行、実験のスコアリング、アノテーションキュー	https://langfuse.com/docs/datasets
Postgres データセットのバックアップと復元の仕組み	https://www.postgresql.org/docs/current/backup.html

これらで適用すべき社内のしきい値：references/ork-delta.md。

関連スキル

• ork:rag-retrieval - ゴールデンデータセットを使用した検索評価
• ork:monitoring-observability - キュレーションワークフロー向けの Langfuse トレースパターン
• ork:testing-llm - ゴールデンデータセットを利用する評価ハーネス
• ork:testing-unit - ユニットテストのパターンと戦略

機能の詳細

curation

キーワード： ゴールデンデータセット、キュレーション、コンテンツ収集、アノテーション、品質基準

解決する課題：

• ゴールデンデータセット用にドキュメントのコンテンツタイプを分類する
• マルチエージェントによる品質分析パイプラインを実行する
• 新しいドキュメント向けのテストクエリを生成する

management

キーワード： ゴールデンデータセット、バックアップ、復元、バージョン管理、災害復旧

解決する課題：

• JSON を使用してゴールデンデータセットをバックアップおよび復元する
• 復元後に埋め込みを再生成する
• CI/CD でバックアップを自動化する

validation

キーワード： ゴールデンデータセット、検証、スキーマ、重複検出、品質指標

解決する課題：

• ドキュメントスキーマに照らしてエントリーを検証する
• 重複または類似したエントリーを検出する
• データセットのカバレッジと分布の不足を分析する