grahama1970/batch-quality

Batch Quality Skill (배치 품질 스킬)

전체 배치 작업을 실행하기 전에 품질을 검증하여 LLM 호출 낭비를 방지합니다.

이 스킬이 실제로 하는 일

단순한 파일 존재 여부 확인과 달리, 이 스킬은 다음을 수행합니다:

1. 실제로 LLM에서 N개 샘플을 실행 (scillm 사용)
2. JSON 응답 구조 검증 (excerpts, source_quality 등)
3. SPARTA 계약 사용 DuckDB 검증 쿼리용
4. 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>

실제 수행 작업:

1. 해당 단계의 SPARTA 계약 로드 (있는 경우)
2. 환경 변수 확인 (CHUTES_API_KEY, CHUTES_TEXT_MODEL)
3. 실행 ID에 해당하는 DuckDB 연결
4. 입력 큐에서 N개 항목 샘플링
5. 각 샘플을 scillm으로 실행 (실제 LLM 호출)
6. JSON 응답 구조 검증
7. 샘플의 50% 이상 통과 필요

종료 코드:

• 0: 통과 - 안전하게 진행 가능
• 1: 실패 - 먼저 문제 해결 필요

validate (검증)

SPARTA 계약을 사용하여 배치 출력을 검증합니다.

uv run python cli.py validate \
    --stage <stage-name> \
    --run-id <sparta-run-id> \
    --task-name <task-monitor-name>

실제 수행 작업:

1. SPARTA 계약 로드 (예: 05_extract_knowledge.json)
2. 계약의 모든 validation_queries를 DuckDB에 대해 실행
3. 각 쿼리 결과를 expected_min과 비교
4. 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마다):

1. 중단 — 생성 프로세스에 SIGSTOP 전송
2. 스냅샷 — 오프라인 분석을 위해 DuckDB 복사, 즉시 SIGCONT
3. 샘플링 — 층화 무작위 샘플 (높음/중간/낮음 접지 계층)
4. 평가 — 각 샘플 확인: 엔터티 접지, 답변 품질, 추론
5. 진단 — 추세 분석: 접지 감소 중? 엔터티 실패 증가 중?
6. 조정 — 품질 저하 시: 프롬프트, 필터 임계값, 관계 점수 조정
7. 재개 — 품질이 임계값을 충족하는 경우에만
8. 중단 + 알림 — 품질이 최저 기준 미만이면 중단 및 사람에게 알림

이것은 선택 사항이 아닙니다. 품질 게이트 없이 100k 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

품질 임계값

지표	경고	중단
평균 접지율	< 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초 동안 중단하여 품질을 확인하는 것은 비용이 거의 들지 않습니다. 100k QRA를 맹목적으로 실행하고 절반이 사용 불가능하다는 것을 발견하는 것은 모든 것을 잃는 것입니다.