Batch Quality 技能
通过在运行完整批量操作之前验证质量，避免浪费 LLM 调用。
此技能实际执行的操作
与简单的文件存在性检查不同，此技能：
- 实际使用 scillm 对 N 个样本运行 LLM
- 验证 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
# 如果预检通过，运行您的批量操作
# ...batch operation...
# 验证：根据合约检查 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 个批量检查点之后（例如，每 5 个 KNN 批次 / 约 1000 个 QRA）：
- 暂停 — SIGSTOP 生成进程
- 快照 — 复制 DuckDB 用于离线分析，然后立即 SIGCONT
- 采样 — 分层随机抽样（高/中/低 grounding 层）
- 评估 — 检查每个样本：实体 grounding、答案质量、推理
- 诊断 — 趋势分析：grounding 是否下降？实体失败是否增加？
- 调整 — 如果持续恶化：调整提示、过滤阈值、关系分数
- 恢复 — 仅当质量满足阈值时
- 停止 + 通知 — 如果质量低于下限，停止并通知人工
这不是可选的。 在没有质量门控的情况下运行到 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 然后发现一半不可用，代价则是巨大的。