バッチ品質スキル
フルバッチ操作を実行する前に品質を検証することで、無駄なLLM呼び出しを防止します。
このスキルが実際に行うこと
単純なファイル存在チェックとは異なり、このスキルは以下のことを行います。
- scillmを使用してN個のサンプルで実際にLLMを実行
- JSONレスポンス構造を検証（抜粋、source_qualityなど）
- SPARTA契約を使用したDuckDB検証クエリ
- task-monitorと統統合して品質ゲートを強制
クイックスタート
cd .pi/skills/batch-quality
# プリフライト: 3サンプルを実際のLLMでテスト
uv run python cli.py preflight \
--stage 05 \
--run-id run-recovery-verify \
--samples 3
# プリフライトが成功したら、バッチを実行
# ...バッチ操作...
# 検証: DuckDBの内容を契約に対してチェック
uv run python cli.py validate \
--stage 05 \
--run-id run-recovery-verify \
--task-name "sparta-stage-05"
コマンド
preflight
フルバッチを実行する前に、実際のLLMでNサンプルをテストします。
uv run python cli.py preflight \
--stage <stage-name> \
--run-id <sparta-run-id> \
--samples 3 \
--prompt <optional-prompt-file>
実際に行うこと:
- ステージのSPARTA契約を読み込む（存在する場合）
- 環境変数をチェック（CHUTES_API_KEY、CHUTES_TEXT_MODEL）
- 実行のDuckDBに接続
- 入力キューからNアイテムをサンプリング
- 各サンプルをscillmで実行（実際のLLM呼び出し）
- JSONレスポンス構造を検証
- 50%以上のサンプルが合格する必要がある
終了コード:
- 0: 合格 - 続行しても安全
- 1: 不合格 - 先に問題を修正
validate
SPARTA契約を使用してバッチ出力を検証します。
uv run python cli.py validate \
--stage <stage-name> \
--run-id <sparta-run-id> \
--task-name <task-monitor-name>
実際に行うこと:
- SPARTA契約を読み込む（例:
05_extract_knowledge.json） - 契約のすべての
validation_queriesをDuckDBに対して実行 - 各クエリ結果を
expected_minと比較 - 合格/不合格をtask-monitorに通知
契約の例（05_extract_knowledge.json）:
{
"validation_queries": [
{"name": "url_knowledge_count", "query": "SELECT COUNT(*) FROM url_knowledge", "expected_min": 10},
{"name": "urls_processed", "query": "SELECT COUNT(*) FROM url_extraction_log WHERE ok = true", "expected_min": 5}
]
}
status
現在のプリフライトステータスを確認します（JSON出力）。
uv run python cli.py status
clear
プリフライト状態をクリアします（新しいプリフライトが必要）。
uv run python cli.py clear
SPARTAパイプライン統合
# 1. 検証要件でタスクを登録
uv run python .pi/skills/task-monitor/monitor.py register \
--name "sparta-stage-05" \
--require-validation
# 2. プリフライトを実行（実際にLLMをテスト）
uv run python .pi/skills/batch-quality/cli.py preflight \
--stage 05 \
--run-id run-recovery-verify \
--samples 3
# 3. バッチを実行（プリフライトが成功した場合のみ）
uv run python -m sparta.pipeline_duckdb.05_extract_knowledge \
--run-id run-recovery-verify
# 4. 契約クエリを使用して検証
uv run python .pi/skills/batch-quality/cli.py validate \
--stage 05 \
--run-id run-recovery-verify \
--task-name "sparta-stage-05"
設定
環境変数:
SPARTA_ROOT: SPARTAプロジェクトへのパス（デフォルト:~/workspace/experiments/sparta）CHUTES_API_KEY: LLM呼び出し用のAPIキーCHUTES_API_BASE: APIベースURL（デフォルト:https://llm.chutes.ai/v1）CHUTES_TEXT_MODEL: テキスト抽出用のモデルID
契約の場所:
$SPARTA_ROOT/tools/pipeline_gates/fixtures/D3-FEV/contracts/
依存関係
typer- CLIフレームワークduckdb- データベースクエリscillm- LLMバッチ処理（実際のサンプルテスト用）
必須の飛行中品質ゲート（譲歩不可）
長時間実行されるバッチ操作（特にQRA生成、抽出など）では、プリフライトだけでは不十分です。実行中に品質ゲートを実行する必要があります。
一時停止-評価-診断-調整-再開ループ
Nバッチチェックポイントごとに（例: KNNバッチ5回ごと / 約1000 QRAごと）:
- 一時停止 — 生成プロセスをSIGSTOP
- スナップショット — DuckDBをコピーしてオフライン分析、すぐにSIGCONT
- サンプリング — 層化ランダムサンプル（高/中/低グラウンディング層）
- 評価 — 各サンプルをチェック: エンティティグラウンディング、回答品質、推論
- 診断 — トレンド分析: グラウンディングは低下しているか？エンティティ障害が増加しているか？
- 調整 — 劣化している場合: プロンプト、フィルターしきい値、関係スコアを調整
- 再開 — 品質がしきい値を満たしている場合のみ
- 停止 + 通知 — 品質が下限を下回っている場合、停止して人間に通知
これはオプションではありません。 品質ゲートなしで10万QRAまで実行すると、ゴミが生成され、それを修正するよりも正しく再生成する方が時間がかかります。
QRA品質ゲートスクリプト
# 連続ウォッチドッグ（QRA生成と並行して実行）
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
--run-id run-recovery-verify \
--batch-interval 5 \
--samples 10
# 1回限りの評価
python $SPARTA_ROOT/scripts/qra_quality_gate.py assess \
--run-id run-recovery-verify \
--samples 20
# チェックポイント間のトレンドを表示
python $SPARTA_ROOT/scripts/qra_quality_gate.py trend \
--run-id run-recovery-verify
品質しきい値
| 指標 | 警告 | 停止 |
|---|---|---|
| 平均グラウンディング | < 0.65 | < 0.55 |
| エンティティ障害率 | > 5% | > 10% |
| サンプル不合格率 | > 15% | > 30% |
| チェックポイントあたりのグラウンディング低下 | > 0.05 | > 0.10 |
これが重要な理由
ウォッチドッグが受動的だったため、QRAグラウンディングスコアは数時間かけて0.74から0.62に低下しました。適切な品質ゲートがあれば、0.70→0.65の低下を検出し、診断（KNNが簡単な関係を使い果たした、プロンプトドリフトなど）を行い、0.62まで低下させる代わりに対処できたはずです。
主要原則
プリフライトは安価です。バッチの失敗は高コストです。
3サンプルのテストには約$0.01と30秒かかります。 壊れたプロンプトで1000アイテムを実行するには約$3と数時間かかります。
飛行中ゲートは再生成よりも安価です。 1000 QRAごとに10秒間一時停止して品質を確認するコストはほとんどありません。10万QRAを盲目的に実行し、半分が使用不可能であることを後で知るコストは莫大です。