rag-bench

name	rag-bench
description	RAG 실험 결과를 측정·비교·분석한다. 실험 결과 JSON을 입력받아 모드별 메트릭 산출, cross-mode 비교, hop_type/hit_category별 분해, 종합 보고서를 생성한다. eval-runner(실행 오케스트레이션)와 보완 관계. "성능 비교해줘", "메트릭 뽑아줘", "hop별 분석", "벤치마크 리포트" 등의 요청에 트리거된다.

rag-bench

RAG 성능 측정 + 비교 분석 전문 스킬.

When to use

• 실험 결과 JSON에서 메트릭을 산출할 때
• 모드 간 성능을 비교할 때 (baseline vs target)
• hop_type, hit_category, solvability별 분해 분석할 때
• 종합 벤치마크 보고서가 필요할 때

Subcommands

# 메트릭 산출
python3 scripts/rag_bench.py measure --result RESULT.json

# 모드 간 비교
python3 scripts/rag_bench.py compare --results R1.json R2.json --baseline MODE --targets MODE1,MODE2

# 차원별 분해
python3 scripts/rag_bench.py breakdown --result RESULT.json --by hop_type|hit_category|solvability

# 종합 보고서
python3 scripts/rag_bench.py report --results R1.json R2.json --format md

Read Order

문서를 읽는 순서. 위에서 아래로 따라가면 전체 지표 체계가 잡힌다.

1. 수식/이름 규약 (fixed point) — knowledge_bases/metric_formula_contract.md
   • naming, formula, class, strict/proxy, suffix governance
   • 수식/이름 충돌 시 이 문서가 이긴다
2. 추상화 계보 + 비교 패러다임 — references/metric_taxonomy.md
   • 4개 비교 패러다임 분류, μ/σ 일반화 축, P/R 분해 가능성, 패러다임 간 퇴화 관계
3. 지표 정의 인덱스 (허브) — references/metric_definitions.md
   • 기초 수학 도구 + 패러다임별 하위 문서 링크
4. 패러다임별 상세 정의 — 허브에서 링크를 따라 내려감:
   1. 패러다임 1 — 집합 비교: Hit Rate → Recall@k → ChunkRecall → Evidence Density
   2. 패러다임 2 — Soft 매칭: GriTS_Top → GriTS_Loc → mAP/mAR → Cosine
   3. 패러다임 3 — 구조 편집: TEDS-S → SR → CC → Contiguity
   4. 패러다임 4 — 순위 가중: MRR → Context Precision → RCP
   5. 횡단·진단 지표: 분포(IC/Entropy) + 토폴로지(GFR/PR) + LLM + 진단매핑 + P/R 총괄표
5. 해석 로직 — knowledge_bases/rag_metric_logic.md
   • 결과 해석이나 보고서를 쓸 때는 여기를 먼저 본다

태스크별 진입점

전부 읽을 필요 없다. 태스크에 따라 진입점이 다르다.

태스크	진입	경로
메트릭 이름/수식 확인	1번 (contract)	→ 끝. 필요하면 3번 허브에서 해당 패러다임 문서
새 지표 추가	1번 → 2번	→ Details의 metric_definition_examples.md → family example
결과 해석 / 보고서 작성	5번 (logic)	→ 3번 허브 → 필요한 패러다임 문서
특정 지표 상세 (GriTS, SR 등)	3번 (허브)	→ 해당 패러다임 문서 직행
모드 간 비교 분석	5번 (logic)	→ 횡단·진단 (진단매핑 표) → 패러다임 1 (Recall 계보)
파이프라인 병목 진단	횡단·진단	→ 진단매핑 표에서 단계별 지표 확인 → 해당 패러다임
추상화 관계 / 지표 간 관계 파악	2번 (taxonomy)	→ 끝. 패러다임 퇴화 관계, P/R 분해 총괄표

Details

본문에 다 넣지 못하는 세부/참고/확장 문서 포인터.

• new-metric examples index: references/metric_definition_examples.md — 새 지표 정의 시 먼저 읽는 구현 지향 보조문서
• coverage/retrieval examples: references/metric_examples_coverage_retrieval.md
• ranking/placement examples: references/metric_examples_ranking_placement.md
• context integrity examples: references/metric_examples_context_integrity.md
• 파이프라인 단계 정의: references/pipeline_stages.md
• 스키마 정의: references/schemas.md

정합성 레이어

이 skill의 공통 고정점은 knowledge_bases/metric_formula_contract.md다.

레이어	문서	역할
1. fixed point	metric_formula_contract.md	naming, formula, class, suffix governance
2. abstraction	metric_taxonomy.md	패러다임 분류, μ/σ 일반화, 추상화 계보
3. interpretation	rag_metric_logic.md + metric_definitions.md	해석·비교·보고
4. design	metric_definition_examples.md + family 3종	구현 지향 예시
5. execution	scripts/	report-facing key는 contract 이름을 따른다

정합성 규칙:

• 수식/이름 충돌 시 contract(레이어 1)가 이긴다
• family example 문서는 contract를 구현 지향으로 풀어쓴다
• 실행 script와 보고서는 contract의 report-facing profile 이름을 우선한다

파이프라인 단계별 진단:

단계	병목	진단 지표	패러다임
A-1 Parsing	파서 품질	TEDS-S, GriTS_Top, mAP	2, 3
A0 Chunks	chunk_size	ChunkRecall_count@k, Recall_length@k	1
A1 Retrieved	임베딩/HyDE	Hit Rate, Recall@k	1
A2 Re-ranked	Reranker	MRR, ContextPrecision_AP@k	4
A3 Context	절삭/노이즈	ContextDensity, CC_adj_lexical, SR_fragmentation_proxy	1, 3
LLM	생성 품질	Judge Score, Faithfulness	—

주의:

• ChunkRecall, ChunkPrecision, CC, SR, RCP는 family label로는 쓸 수 있지만, report-facing key는 suffix profile 이름을 우선한다.
• strict SR과 executable SR_fragmentation_proxy는 같은 이름으로 보고하지 않는다.

확장 지표 (진단용)

범주	지표	의미
소스-청크	Parent-to-Child Ratio	부모 메타데이터 대비 자식 청크 정보 비중
소스-청크	Contiguity Score (pair/seq)	검색된 청크 간 원문 인접성
청크 유사도	Pair-wise Cosine Similarity	검색된 청크 간 의미적 거리 (다양성 진단)
질문-청크	CCRS	답변 기여도 분산 (single-hop vs multi-hop)
청크 길이	Recall@k × ChunkRecall 교차	Large Chunk vs Boundary Cut 진단

Output

• 메트릭 JSON: stdout 또는 --out 지정
• 보고서: plans/claude/RAG_BENCH_REPORT_YYYY-MM-DD-HH-MM.md