Batch Quality Skill
透過在執行完整批次操作前驗證品質，避免浪費 LLM 呼叫。
這個技能實際做什麼
不同於單純的檔案存在檢查，此技能：
- 實際對 N 個樣本執行 LLM（使用 scillm）
- 驗證 JSON 回應結構（excerpts、source_quality 等）
- 使用 SPARTA 合約進行 DuckDB 驗證查詢
- 與 task-monitor 整合以強制執行品質關卡
快速開始
cd .pi/skills/batch-quality
# 前置檢查：實際透過 LLM 測試 3 個樣本
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 呼叫（實際 LLM 呼叫）
- 驗證 JSON 回應結構
- 要求至少 50% 以上的樣本通過
結束碼：
- 0：PASSED - 可以安全繼續
- 1：FAILED - 請先修正問題
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） - 針對 DuckDB 執行合約中的所有
validation_queries - 檢查每個查詢結果是否符合
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 個批次檢查點後（例如每 5 個 KNN 批次 / 約 1000 個 QRA）：
- PAUSE — 使用 SIGSTOP 暫停生成過程
- SNAPSHOT — 複製 DuckDB 進行離線分析，然後立即發送 SIGCONT
- SAMPLE — 分層隨機抽樣（高/中/低 grounding 分層）
- ASSESS — 檢查每個樣本：實體 grounding、回答品質、推理
- DIAGNOSE — 趨勢分析：grounding 是否下降？實體失敗是否增加？
- TWEAK — 如果品質惡化：調整提示詞、過濾閾值、關係分數
- RESUME — 僅當品質符合門檻時恢復
- STOP + NOTIFY — 如果品質低於底線，停止並通知人工
這不是可選項目。 一個批次如果未經品質關卡就跑到 10 萬個 QRA，所產生的垃圾資料將花費比重新生成更長的時間來清理。
QRA 品質關卡腳本
# 持續監控（與 QRA 生成同時執行）
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
--run-id run-recovery-verify \
--batch-interval 5 \
--samples 10
# 一次性評估
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
品質門檻
| 指標 | 警告 | 停止 |
|---|---|---|
| 平均 Grounding | < 0.65 | < 0.55 |
| 實體失敗百分比 | > 5% | > 10% |
| 樣本失敗率 | > 15% | > 30% |
| Grounding 下降（每個檢查點） | > 0.05 | > 0.10 |
為什麼這很重要
QRA grounding 分數在數小時內從 0.74 漂移到 0.62，而沒有任何人介入，因為監控程序是被動的。一個適當的品質關卡本該在分數從 0.70 下降到 0.65 時就發現問題並進行診斷（KNN 耗盡簡單關係、提示詞漂移等），而不是讓它一路下滑到 0.62。
關鍵原則
前置檢查很便宜。失敗的批次很昂貴。
測試 3 個樣本花費約 $0.01 美元，耗時 30 秒。 使用有問題的提示詞執行 1000 個項目花費約 $3 美元，耗時數小時。
執行中品質關卡比重做更便宜。 每 1000 個 QRA 暫停 10 秒來驗證品質幾乎沒有成本。盲目執行 10 萬個 QRA 卻發現一半無法使用，則成本極高。