eval-runner

name	eval-runner
description	RAG 실험을 실행하고 결과를 수집한다. preflight 검증 → 실험 실행(checkpoint resume) → metrics 추출 → 결과 저장 → MASTER 갱신까지 하나의 워크플로우로 처리. YAML config 기반.

Eval Runner

RAG 실험의 전체 생명주기를 관리하는 스킬.

Workflow

1. preflight  → config 검증, 파일 존재 확인, 의존성 체크
2. run        → 실험 실행 (checkpoint resume 자동)
3. metrics    → 결과 JSON → 지표 추출
4. report     → MD 보고서 생성
5. update     → CURRENT_STATE_MASTER 갱신

Commands

# 1) Preflight: config 검증만 (실행 안 함)
python3 scripts/eval_runner.py preflight --config CONFIG_PATH

# 2) Run: 실험 실행 (checkpoint 자동 resume)
python3 scripts/eval_runner.py run --config CONFIG_PATH

# 3) Metrics: 결과 JSON에서 지표 추출
python3 scripts/eval_runner.py metrics --result RESULT_JSON

# 4) Report: MD 보고서 생성
python3 scripts/eval_runner.py report --result RESULT_JSON --out REPORT_PATH

# 5) Full: preflight → run → metrics → report 전체 실행
python3 scripts/eval_runner.py full --config CONFIG_PATH

# 6) Chain: 여러 실험을 순차 실행 (chain config)
python3 scripts/eval_runner.py chain --config CHAIN_CONFIG_PATH

Config 구조

실험 config YAML은 기존 plans/codex/algorithms/configs/ 형식을 그대로 사용한다.

# 필수
paths:
  eval_jsonl: datasets/eval_v1.jsonl
  eval_classified_json: datasets/eval_v1_classified.json

models:
  llm_model: gpt-4.1-mini

base:
  eval_limit: 70
  chunk_size_chars: 1200
  chunk_overlap_chars: 150
  parent_group_size: 3

# 실험 유형별 선택
modes: [hyde_rerank, A3_section_hybrid_evidence_dynamic_k_rerank]

grid:
  k_values: [160]

retrieval:
  scorer: embedding
  embedding_model: text-embedding-3-large
  final_top_n: 10

# rerank 사용 시
rerank:
  strategy: pinecone
  pinecone_model: bge-reranker-v2-m3
  top_m: 80

결과 저장 규칙

• 결과 JSON: plans/codex/test_result/<experiment_name>_YYYY-MM-DD-HH-MM.json
• Checkpoint: plans/codex/test_result/<experiment_name>_checkpoint.json
• 로그: plans/codex/test_result/<experiment_name>_run_YYYY-MM-DD-HH-MM.log
• 보고서: plans/claude/<REPORT_TYPE>_YYYY-MM-DD-HH-MM.md

실험 유형 → 스크립트 매핑

실험 유형	스크립트	설명
rerank5	eval_rerank5_artifacts.py	Reranker 적용 실험
nonrerank5	eval_nonrerank5_artifacts.py	Reranker 미적용 실험
judge	eval_ragas_llmjudge_10modes_kgrid.py	LLM-as-Judge 평가
chain	run_experiment_chain.py	다단계 순차 실행

Preflight 체크 항목

1. eval_jsonl 파일 존재
2. eval_classified_json 파일 존재
3. embedding_store_path 파일 존재 (embedding scorer 사용 시)
4. query_embedding_cache_path 존재 (offline 모드 시)
5. Pinecone API key 확인 (rerank strategy=pinecone 시)
6. Python 의존성 (yaml, rapidfuzz, pinecone 등)
7. .venv 활성화 상태

Checkpoint Resume

• 모든 실험은 checkpoint.json을 주기적으로 저장
• 재실행 시 자동으로 checkpoint에서 이어서 실행
• checkpoint meta 불일치 시 초기화 (config 변경 감지)

환경변수

변수	용도	기본값
EVAL_RUNNER_CONFIG	config YAML 경로	(필수)
EVAL_RUNNER_OUT	결과 JSON 경로	auto-generated
EVAL_RUNNER_CKPT	checkpoint 경로	auto-generated
EVAL_RUNNER_LOG	로그 경로	auto-generated
PINECONE_API_KEY	Pinecone reranker API	.env에서 로드

지표 해석 가이드

metrics/report 결과를 해석할 때 참조하는 지표 체계. 상세 정의는 rag-bench 스킬의 references/ 참조.

핵심 지표 요약

지표	수식 요약	진단 대상
Hit Rate@K	top-K에 정답 하나라도 있으면 1	검색 자체의 성공 여부
ChunkRecall@K	정답 정보량 중 검색된 비율	정보 포괄성
ChunkPrecision@K	top-K 중 정답 비율	노이즈 수준
MRR	첫 정답의 순위 역수 평균	Reranker 품질
Faithfulness	답변 주장 중 컨텍스트 근거 비율	환각 수준

교차 진단 패턴

Recall@k	ChunkRecall	진단
낮	높	Large Chunk (양호)
높	낮	Boundary Cut (위험 - chunk_size 조정 필요)
높	높	최적
낮	낮	검색 실패 (임베딩/HyDE 개선 필요)

파이프라인 병목 진단

DocHit@10 < 0.7   → A1 병목 (임베딩/HyDE)
MRR < 0.5         → A2 병목 (Reranker)
ChunkRecall < 0.3 → A0/A3 병목 (chunk_size 또는 절삭)
Judge < 8/15      → LLM 병목 (프롬프트/컨텍스트 구조)