evalvault 1.67.0__tar.gz → 1.68.0__tar.gz

{evalvault-1.67.0 → evalvault-1.68.0}/.dockerignore

@@ -34,7 +34,8 @@ htmlcov
 docs/_build
 
 # Local data (mounted as volume)
-data/
+# Note: data/ is included for offline packaging when needed.
+!data/**
 reports/
 
 # Environment files (use docker env instead)

evalvault-1.68.0/.env.offline.example

@@ -0,0 +1,58 @@
+# EvalVault Offline Environment Template
+# Copy to .env.offline and fill required values.
+#
+# Usage:
+#   cp .env.offline.example .env.offline
+#   # Edit .env.offline with your air-gapped network settings
+#   docker compose -f docker-compose.offline.yml --env-file .env.offline up -d
+
+# ================================================
+# Profile
+# ================================================
+EVALVAULT_PROFILE=dev
+
+# ================================================
+# PostgreSQL (core stack)
+# ================================================
+POSTGRES_USER=evalvault
+POSTGRES_PASSWORD=evalvault
+POSTGRES_DB=evalvault
+
+# ================================================
+# Storage (SQLite paths for local file-based storage)
+# ================================================
+EVALVAULT_DB_PATH=data/db/evalvault.db
+EVALVAULT_MEMORY_DB_PATH=data/db/evalvault_memory.db
+
+# ================================================
+# API / CORS
+# ================================================
+CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# API_AUTH_TOKENS=
+# KNOWLEDGE_READ_TOKENS=
+# KNOWLEDGE_WRITE_TOKENS=
+
+# ================================================
+# External LLM servers (air-gapped network)
+# ================================================
+# IMPORTANT: Model weights are NOT shipped with EvalVault.
+# You must provide the URL to your air-gapped LLM server.
+
+# Ollama (if using dev/prod profile)
+# OLLAMA_BASE_URL=
+OLLAMA_TIMEOUT=120
+# OLLAMA_TOOL_MODELS=
+
+# vLLM (if using vllm profile)
+# VLLM_BASE_URL=
+# VLLM_API_KEY=
+# VLLM_MODEL=
+# VLLM_EMBEDDING_MODEL=
+# VLLM_EMBEDDING_BASE_URL=
+
+# ================================================
+# Faithfulness fallback (optional)
+# ================================================
+# FAITHFULNESS_FALLBACK_PROVIDER=
+# FAITHFULNESS_FALLBACK_MODEL=

{evalvault-1.67.0 → evalvault-1.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evalvault
-Version: 1.67.0
+Version: 1.68.0
 Summary: RAG evaluation system using Ragas with Phoenix/Langfuse tracing
 Project-URL: Homepage, https://github.com/ntts9990/EvalVault
 Project-URL: Documentation, https://github.com/ntts9990/EvalVault#readme

{evalvault-1.67.0 → evalvault-1.68.0}/data/rag/user_guide_bm25.json

@@ -1,15 +1,15 @@
 {
   "version": 1,
   "source": "docs/guides/USER_GUIDE.md",
-  "source_hash": "3371b632290e3f17d7b0b9642586e037269de9f4583e50a165c67b894699e34c",
+  "source_hash": "1e7bc84b5056c973203130e11423e01feeb9bb779a32d4a4df8c024df7075015",
   "chunk_limit": 80,
-  "created_at": "2026-01-20T08:02:45.258030+00:00",
+  "created_at": "2026-01-26T21:32:23.599657+00:00",
   "documents": [
     "# EvalVault 사용자 가이드\n\n> RAG 시스템 품질 평가 · 분석 · 추적을 위한 종합 워크플로 가이드\n\n이 문서는 README에서 다룬 간단한 소개를 넘어, 설치부터 Phoenix 연동·Domain Memory·자동화까지 모든 기능을 심층적으로 설명합니다.\n\n---\n\n## 목차\n\n1. [핵심 워크플로](#핵심-워크플로) - 평가 → 자동 분석 → 보고서/아티팩트 저장 → 비교 2. [시작하기](#시작하기) 3. [환경 구성](#환경-구성) 4. [CLI 명령어 참조](#cli-명령어-참조) 5. [Web UI](#web-ui) 6. [분석 워크플로](#분석-워크플로) 7. [Domain Memory 활용](#domain-memory-활용) 8. [관측성 & Phoenix](#관측성--phoenix) - [Open RAG Trace 표준 연동](#open-rag-trace-표준-연동) 9. [프롬프트 관리](#프롬프트-관리) 10. [성능 튜닝](#성능-튜닝) 11. [메서드 플러그인](#메서드-플러그인) 12. [문제 해결](#문제-해결) 13. [참고 자료](#참고-자료)\n\n---\n\n## 핵심 워크플로\n\nEvalVault의 가장 큰 장점은 **평가 → 자동 분석 → 보고서/아티팩트 저장 → 비교**가 하나의 `run_id`로 끊김 없이 이어져서, 재현성과 개선 루프가 매우 빠르다는 점입니다. 점수만 보는 게 아니라 통계·NLP·원인 분석까지 묶어서 바로 \"왜 좋아졌는지/나빠졌는지\"로 이어지는 게 핵심입니다.\n\n### 초간단 실행 (CLI)\n\n```bash uv run evalvault run --mode simple tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness,answer_relevancy \\ --profile dev \\ --db data/db/evalvault.db \\ --auto-analyze ```\n\n### 결과 확인 경로\n\n평가 실행 후 자동 분석이 완료되면 다음 파일들이 생성됩니다:\n\n- **요약 JSON**: `reports/analysis/analysis_<RUN_ID>.json` - **Markdown 보고서**: `reports/analysis/analysis_<RUN_ID>.md` - **아티팩트 인덱스**: `reports/analysis/artifacts/analysis_<RUN_ID>/index.json` - **노드별 결과**: `reports/analysis/artifacts/analysis_<RUN_ID>/<node_id>.json`\n\n요약 JSON에는 `artifacts.dir`와 `artifacts.index`가 포함되어 있어 경로 조회가 쉽습니다.\n\n### A/B 비교\n\n두 실행 결과를 비교하려면:\n\n```bash uv run evalvault analyze-compare <RUN_A> <RUN_B> --db data/db/evalvault.db ```\n\n결과는 `reports/comparison/comparison_<RUN_A>_<RUN_B>.md`에 저장됩니다.\n\n### Web UI 연동\n\nCLI와 Web UI가 동일한 DB를 사용하면 Web UI에서 바로 결과를 확인할 수 있습니다:\n\n```bash # Terminal 1: API 서버 uv run evalvault serve-api --reload\n\n# Terminal 2: React 프론트엔드 cd frontend npm install npm run dev ```\n\n동일한 DB(`data/db/evalvault.db`)를 사용하면 Web UI에서 바로 이어서 볼 수 있습니다.\n\n---\n\n## 시작하기\n\n### 시스템 요구 사항\n\n| 항목 | 권장 버전 | 비고 | |------|-----------|------| | Python | 3.12.x | `uv`가 자동 설치 (macOS/Linux/Windows 지원) | | uv | 최신 | [설치 가이드](https://docs.astral.sh/uv/getting-started/installation/) | | Docker (선택) | 최신 | Langfuse/Phoenix 로컬 배포 시 | | Ollama (선택) | 최신 | 폐쇄망/로컬 모델 사용 시 |\n\n### 설치 옵션\n\n#### PyPI ```bash uv pip install evalvault ```\n\n#### 소스 (권장) ```bash git clone https://github.com/ntts9990/EvalVault.git cd EvalVault uv sync --extra dev        # 전체 기능 포함 (dev 도구 + 모든 extras) # 경량 설치 예시: uv sync --extra analysis ```\n\nPhoenix 트레이싱은 `dev`에 포함되어 있습니다. 경량 설치라면 `--extra phoenix`를 추가하세요.\n\n**Extras 설명**:\n\n| Extra | 패키지 | 목적 | |-------|--------|------| | `analysis` | scikit-learn | 통계/NLP 분석 모듈 | | `korean` | kiwipiepy, rank-bm25, sentence-transformers | 한국어 토크나이저 및 검색 | | `postgres` | psycopg | PostgreSQL 저장소 지원 | | `mlflow` | mlflow | MLflow 트래커 통합 | | `phoenix` | arize-phoenix + OpenTelemetry exporters | Phoenix 트레이싱, 데이터셋/실험 동기화 | | `anthropic` | anthropic | Anthropic LLM 어댑터 | | `perf` | faiss-cpu, ijson | 대용량 데이터셋 성능 도우미 | | `docs` | mkdocs, mkdocs-material, mkdocstrings | 문서 빌드 |\n\n`.python-version`이 Python 3.12를 고정하므로 추가 설치가 필요 없습니다.\n\n---\n\n## 환경 구성\n\n### 프로젝트 초기화 (init)\n\n빠르게 시작하려면 초기화 명령으로 기본 파일을 생성합니다.\n\n```bash uv run evalvault init ```\n\n- `.env` 템플릿과 `sample_dataset.json`을 생성합니다. - `dataset_templates/`에 JSON/CSV/XLSX 빈 템플릿을 생성합니다. - `--output-dir`로 생성 위치를 바꿀 수 있습니다. - `--skip-env`/`--skip-sample`/`--skip-templates`로 단계별 생성을 끌 수 있습니다.\n\n### .env 작성\n\n`cp .env.example .env` 후 아래 값을 채웁니다.\n\n```bash # 공통 EVALVAULT_PROFILE=dev              # config/models.yaml에 정의된 프로필 EVALVAULT_DB_PATH=data/db/evalvault.db     # SQLite 저장 경로 (API/CLI 공통) EVALVAULT_MEMORY_DB_PATH=data/db/evalvault_memory.db  # 도메인 메모리 DB 경로 OPENAI_API_KEY=sk-...\n\n# Langfuse (선택) LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-... LANGFUSE_HOST=http://localhost:3000\n\n# Phoenix/OpenTelemetry (선택) PHOENIX_ENABLED=true PHOENIX_ENDPOINT=http://localhost:6006/v1/traces PHOENIX_SAMPLE_RATE=1.0\n\n# React 프론트엔드에서 API 호출 시 (선택) CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173\n\n# vLLM(OpenAI-compatible) 사용 예 EVALVAULT_PROFILE=vllm VLLM_BASE_URL=http://localhost:8001/v1 VLLM_MODEL=gpt-oss-120b VLLM_EMBEDDING_MODEL=qwen3-embedding:0.6b # 선택: VLLM_EMBEDDING_BASE_URL=http://localhost:8002/v1 ```\n\nOpenAI를 쓰지 않는다면 `OPENAI_API_KEY`는 비워둬도 됩니다.\n\n### 초간단 시작 (Ollama 3줄)\n\n```bash cp .env.example .env ollama pull gemma3:1b uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness \\ --db data/db/evalvault.db \\ --profile dev ```\n\nTip: `answer_relevancy` 등 임베딩 메트릭을 쓰려면 `qwen3-embedding:0.6b`도 내려받으세요.\n\n### 초간단 시작 (vLLM 3줄)\n\n```bash cp .env.example .env printf \"\\nEVALVAULT_PROFILE=vllm\\nVLLM_BASE_URL=http://localhost:8001/v1\\nVLLM_MODEL=gpt-oss-120b\\n\" >> .env uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness \\ --db data/db/evalvault.db ```\n\nTip: 임베딩 메트릭은 `VLLM_EMBEDDING_MODEL`과 `/v1/embeddings` 엔드포인트가 필요합니다.\n\nOllama를 사용할 경우 `OLLAMA_BASE_URL`, `OLLAMA_TIMEOUT`을 추가하고, 평가 전에 `ollama pull`로 모델을 내려받습니다. Tool/function calling 지원 모델을 쓰려면 `.env`에 `OLLAMA_TOOL_MODELS`를 콤마로 지정합니다. 지원 여부는 `ollama show <model>` 출력의 `Capabilities`에 `tools`가 있는지 확인합니다.\n\n> 참고: vLLM이 임베딩 엔드포인트(`/v1/embeddings`)를 제공하지 않으면 임베딩 기반 메트릭은 실패할 수 있습니다. > 이 경우 `faithfulness`, `answer_relevancy` 등 LLM 기반 메트릭만 선택하거나 별도의 임베딩 서버를 지정하세요.\n\n### 임베딩 엔드포인트 체크리스트\n\n- 임베딩이 필요한 메트릭: `answer_relevancy`, `semantic_similarity` - Ollama: `ollama pull qwen3-embedding:0.6b` 후 `ollama list`로 확인 - vLLM: `/v1/embeddings` 응답 확인 - 임베딩 서버가 분리돼 있으면 `VLLM_EMBEDDING_BASE_URL`을 설정\n\n예시: ```bash curl -s http://localhost:8001/v1/embeddings \\ -H \"Authorization: Bearer local\" \\ -H \"Content-Type: application/json\" \\ -d '{\"model\":\"qwen3-embedding:0.6b\",\"input\":\"ping\"}' ```\n\n### Ollama 모델 추가\n\nOllama는 **로컬에 내려받은 모델만** 목록에 노출됩니다. 다음 순서로 추가하세요.",
     "1. **모델 내려받기** ```bash ollama pull gpt-oss:120b ollama pull gpt-oss-safeguard:120b ``` 2. **목록 확인** ```bash ollama list ``` 3. **EvalVault에서 선택** - Web UI: `Provider = ollama` 선택 후 모델 카드에서 선택 - CLI: `config/models.yaml`의 프로필 모델을 변경하거나 `--profile`로 지정 4. **Tool 지원 모델 등록** - `ollama show <model>`로 `Capabilities: tools` 확인 - 지원 모델은 `.env`의 `OLLAMA_TOOL_MODELS`에 콤마로 추가\n\n미리 받아두면 좋은 모델: `gpt-oss:120b`, `gpt-oss-safeguard:120b`, `gpt-oss-safeguard:20b`.\n\n### 모델 프로필 관리\n\n`config/models.yaml`은 프로필별 LLM/임베딩 구성을 정의합니다.\n\n```yaml profiles: dev: llm: provider: ollama model: gemma3:1b embedding: provider: ollama model: qwen3-embedding:0.6b openai: llm: provider: openai model: gpt-5-mini embedding: provider: openai model: text-embedding-3-small vllm: llm: provider: vllm model: gpt-oss-120b embedding: provider: vllm model: qwen3-embedding:0.6b ```\n\n사용법: - 환경 변수 `EVALVAULT_PROFILE` 설정 - 또는 CLI `--profile <name>` / `-p <name>` (예: dev, openai, vllm)\n\n### 데이터셋 준비\n\n### 요약 메트릭 실무 매뉴얼 (개발 현황 + 평가 방법 + 해석)\n\n이 섹션은 **요약 메트릭 개발 현황**과 **실무 평가 매뉴얼**을 함께 제공합니다.\n\n#### 1) 개발 현황 요약 (현재 코드 기준) - **RAGAS 요약 메트릭** - `summary_score` (RAGAS SummaryScore) - `summary_faithfulness` (RAGAS Faithfulness alias) - **커스텀 요약 메트릭(보험 도메인 확장)** - `entity_preservation` (규칙 기반) - `summary_accuracy` (규칙 기반) - `summary_risk_coverage` (규칙 + metadata.summary_tags) - `summary_non_definitive` (규칙 기반) - `summary_needs_followup` (규칙 + metadata.summary_tags) - **스냅샷/추적** - 커스텀 메트릭은 `custom_metric_snapshot`에 규칙/입력/출력/해시가 저장됩니다. - Excel `CustomMetrics` 시트와 Langfuse/Phoenix/MLflow artifact에도 기록됩니다. - **확장 계획** - 보험 요약 메트릭 확장 설계: `docs/guides/INSURANCE_SUMMARY_METRICS_PLAN.md` - 규칙 + LLM 보정 하이브리드 설계 포함 (경계 사례 보정)\n\n#### 2) 평가 준비(데이터셋) - 필수 컬럼 - `contexts`: 상담 대화 원문/스크립트 - `answer`: 모델 요약 - `ground_truth`: 현업 요약(선택이지만 있으면 해석이 훨씬 명확) - 선택 컬럼 - `metadata.summary_tags`: 리스크 태그 목록 (`exclusion`, `deductible`, `limit`, `needs_followup` 등) - `metadata.summary_intent`: `agent_notes` (내부용 요약 표시) - 권장 포맷 - JSON 데이터셋을 우선 권장 (metadata 지원)\n\n#### 3) 실행 방법 (CLI) ```bash # 기본 요약 메트릭 uv run evalvault run data.json \\ --metrics summary_score,summary_faithfulness,entity_preservation \\ --profile <profile> \\ --db data/db/evalvault.db\n\n# 보험 요약 커스텀 메트릭 포함 uv run evalvault run data.json \\ --metrics summary_accuracy,summary_risk_coverage,summary_non_definitive,summary_needs_followup \\ --threshold-profile summary \\ --profile <profile> \\ --db data/db/evalvault.db ```\n\n#### 3-1) 실행 방법 (Web UI) - Evaluation Studio에서 데이터셋 업로드 후, 요약 메트릭을 선택해 실행합니다. - 결과는 Runs/Reports 화면에서 요약 카드와 메트릭 상세로 확인할 수 있습니다.\n\n#### 3-2) 결과/아티팩트 위치 - DB 저장: `data/db/evalvault.db` (또는 `EVALVAULT_DB_PATH`) - Excel: `data/db/evalvault_run_<RUN_ID>.xlsx` - 시트 구성: `Summary`, `MetricScores`, `MetricsSummary`, `CustomMetrics` - 자동 분석 결과(옵션): - JSON: `reports/analysis/analysis_<RUN_ID>.json` - Markdown: `reports/analysis/analysis_<RUN_ID>.md` - 아티팩트: `reports/analysis/artifacts/analysis_<RUN_ID>/` - 비교 분석 결과: - JSON: `reports/comparison/comparison_<RUN_A>_<RUN_B>.json` - Markdown: `reports/comparison/comparison_<RUN_A>_<RUN_B>.md`\n\n#### 4) 점수 해석 방법 (실무 기준) - `summary_faithfulness`: **근거성** - 낮으면 우선 `contexts` 품질(누락/불일치)을 점검합니다. - `summary_score`: **핵심 보존/간결성** - 동의어/재서술이 많은 요약은 낮게 나올 수 있습니다. - `entity_preservation`: **핵심 엔티티 보존** - 숫자/금액/기간/조건이 누락되면 급격히 낮아집니다. - `summary_accuracy`: **요약의 엔티티 정확성** - 컨텍스트 밖 수치/조건 추가에 민감합니다. - `summary_risk_coverage`: **리스크 항목 누락** - `metadata.summary_tags`가 없으면 1.0으로 처리되므로 태깅 정책이 필수입니다. - `summary_non_definitive`: **단정 표현 억제** - 단 1회 매칭에도 0점이므로 문장 스타일 변화에 민감합니다. - `summary_needs_followup`: **추가 확인 문구** - `needs_followup` 태그가 있는 경우에만 요구됩니다.\n\n#### 5) 운영 해석 팁 - 단일 지표보다 **조합 해석**을 권장합니다. - 예: `summary_faithfulness` + `entity_preservation` + `summary_risk_coverage` - `contexts` 품질이 낮으면 대부분의 요약 지표가 왜곡됩니다. - 태그 기반 지표는 **태그 누락률**을 함께 모니터링해야 합니다.\n\n#### 6) 더 풍부한 해석을 위한 기능 활용 - **자동 분석/리포트**: `--auto-analyze`로 요약 보고서 + 아티팩트 생성 - **A/B 비교 분석**: `evalvault analyze-compare`로 요약 메트릭 개선 여부 통계 비교 - **LLM 인사이트**: `evalvault analyze --enable-llm`로 실패 원인/개선 제안 생성 - **프롬프트 변경 추적**: `prompts diff` + `prompt manifest`로 변경 영향 분석 - **Phoenix/Langfuse**: trace 기반으로 요약 실패 케이스를 세부 분석 - **repeat_query 적용**: 비추론 요약 프롬프트에 반복을 적용해 정확도 개선 가능 - 계획 문서: `docs/guides/repeat_query.md`\n\n### 요약 메트릭 해석 가이드 (summary_score, summary_faithfulness, entity_preservation)\n\n### 커스텀 메트릭 스냅샷 (평가 방식/과정/결과 기록)\n\nEvalVault는 커스텀 메트릭의 평가 방식/과정을 실행 메타데이터에 기록합니다. - 저장 위치: `run.tracker_metadata.custom_metric_snapshot` - Excel: `CustomMetrics` 시트 - 추적 도구: Langfuse/Phoenix/MLflow artifact에 `custom_metric_snapshot` 포함\n\n**기록 항목(요약)** - `evaluation_method`: 규칙 기반/문자열 매칭/랭킹 기반 등 - `inputs`: `answer`, `contexts`, `ground_truth`, `question` 등 - `output`: 점수 범위 또는 판정 규칙 - `evaluation_process`: 핵심 평가 절차 요약 - `rules`: 키워드/정규식/가중치 등 - `implementation_path` / `implementation_hash`: 구현 파일 경로/해시",
     "**메트릭 목적** - `summary_faithfulness`: 요약의 주장들이 컨텍스트에 근거하는지 평가합니다. 환각/왜곡 리스크를 직접 측정합니다. - `summary_score`: 컨텍스트 대비 요약의 핵심 정보 보존/간결성 균형을 평가합니다. 정답 요약 단일 기준의 편향을 줄입니다. - `entity_preservation`: 보험 요약에서 금액·기간·조건·면책 등 핵심 엔티티가 요약에 유지되는지 평가합니다.\n\n**보험 도메인 특화 근거** - 보험 약관에서 치명적인 요소(면책, 자기부담, 한도, 조건 등)를 키워드로 직접 반영하고, 금액/기간/비율 같은 핵심 엔티티를 보존하도록 설계했습니다. - 범용 규칙(숫자/기간/금액)과 보험 특화 키워드를 함께 사용하므로, 현재 상태는 “보험 리스크 중심의 약한 도메인 특화”로 보는 것이 정확합니다.\n\n**해석 주의사항** - 세 메트릭 모두 `contexts` 품질에 크게 의존합니다. 컨텍스트가 부정확/과도하면 점수가 낮아질 수 있습니다. - `summary_score`는 키프레이즈 기반이므로, 표현이 달라지면 점수가 낮게 나올 수 있습니다. - `entity_preservation`은 보험 도메인에 맞춘 엔티티 위주라, 다른 도메인에서는 해석에 주의가 필요합니다.\n\n**메트릭별 예시(간단)** - `summary_score` (RAGAS, 키프레이즈 기반) - 컨텍스트: “3월 청구서 7만2천원, 데이터 10GB 추가(2만2천원), 4월 5GB 옵션(1만1천원)” - 요약 A: “3월 청구서 7만2천원은 10GB 추가 사용 때문이며 4월부터 5GB 옵션(1만1천원)으로 변경됨” → 금액/수치 키프레이즈 유지 → 점수 ↑ - 요약 B: “지난달 청구액이 늘었고 다음 달부터 요금 옵션을 낮춤” → 수치/금액 누락 → 점수 ↓ - `summary_faithfulness` (RAGAS, 근거성) - 컨텍스트: “5GB 옵션이면 1만1천원 추가” - 요약 A: “5GB 옵션은 1만1천원 추가” → 근거 일치 → 점수 ↑ - 요약 B: “5GB 옵션은 2만2천원 추가” → 근거 불일치 → 점수 ↓ - `entity_preservation` (커스텀, 규칙 기반) - 컨텍스트 엔티티: {10GB, 7만2천원, 2만2천원, 1만1천원} - 요약 A: “10GB, 7만2천원, 1만1천원” 포함 → 보존률 3/4 - 요약 B: 수치 미포함 → 보존률 0/4\n\n### 메트릭 신뢰도/타당도 및 리스크/완화 가이드\n\n이 절은 **메트릭 점수의 신뢰도(재현성/안정성)와 타당도(무엇을 실제로 측정하는지)** 관점에서, 실무에서 자주 발생하는 오해/리스크와 완화책을 정리합니다.\n\n#### RAGAS 메트릭(LLM/임베딩 기반): 신뢰도/타당도\n\n- 공통 특징: LLM/임베딩 호출을 포함하므로 **동일 입력이라도 점수 변동(분산)**이 발생할 수 있습니다. 또한 대부분이 **\"사용자 만족\"이 아니라 \"근거/관련성/정답과의 유사\"라는 대리 신호**를 측정합니다. - `faithfulness`, `summary_faithfulness`: 컨텍스트 근거(groundedness)에 초점을 둔 지표입니다. 컨텍스트가 부족/불일치하면 모델이 사실을 알고 있어도 낮게 나올 수 있고, 반대로 컨텍스트가 장황하거나 유사 문장이 섞이면 과대평가될 수 있습니다. - `answer_relevancy`: 질문-답변 관련성(대체로 임베딩 유사도 + LLM 보조)에 초점을 둡니다. 질문이 모호하거나 답변이 장황하면 관련성 점수 해석이 왜곡될 수 있습니다. - `context_precision`, `context_recall`: `ground_truth`(레퍼런스)가 있을 때만 의미가 커집니다. 레퍼런스 품질이 낮거나 누락되면 지표 자체가 retrieval 성능이 아니라 **레퍼런스 품질/정의의 노이즈**를 반영할 수 있습니다. - `factual_correctness`: `ground_truth` 대비 사실 일치성을 보려는 지표지만, claim 분해/검증 단계가 포함되어 비용이 크고(LLM 다중 호출), 데이터/언어/프롬프트에 따라 분산이 커질 수 있습니다. - `semantic_similarity`: 임베딩 유사도 기반으로, 문장 표현이 바뀌어도 높은 점수가 나올 수 있습니다. 따라서 \"정답과 의미가 비슷\"은 반영하지만, **누락/추가/조건(면책/한도) 같은 위험 요소의 부재**를 직접 보장하지는 않습니다.\n\n#### 요약 메트릭(요약 품질 신호): 신뢰도/타당도",
     "- `summary_score`(RAGAS): 컨텍스트 대비 핵심 정보 보존/간결성 균형의 **대리 신호**입니다. 요약이 동의어/재서술을 많이 쓰면 키프레이즈 기반 구성상 낮아질 수 있으며, \"좋은 요약\"의 도메인별 정의(보험/콜센터/정책)가 다르면 동일 점수라도 의미가 달라집니다. - `summary_faithfulness`(RAGAS): 요약의 주장들이 컨텍스트에 근거하는지(환각/왜곡 리스크)를 평가합니다. 그러나 LLM 기반 판정이므로, **경계 사례(암시/추론/조건부 문장)**에서 변동이 생길 수 있습니다. - `entity_preservation`(커스텀, 규칙 기반): 컨텍스트에 등장하는 숫자/기간/금액/키워드가 요약에 유지되는지를 봅니다. 규칙 기반이어서 안정적이지만, 엔티티 정의(정규식/키워드 목록)에 없는 표현은 놓칠 수 있고, \"엔티티는 유지됐지만 조건이 바뀐\" 왜곡을 완전히 잡아내지는 못합니다.\n\n#### 요약 커스텀 메트릭(규칙/메타데이터 기반): 신뢰도/타당도\n\n- `summary_accuracy`(규칙 기반): 요약(answer)에서 추출한 엔티티(숫자/기간/금액/키워드)가 컨텍스트에 존재하는지 비율로 계산합니다. 따라서 \"요약이 컨텍스트 밖의 수치/조건을 추가했는가\"에 민감하지만, **동일 의미의 다른 표현/표기**(예: 단위, 띄어쓰기, 약어)는 놓칠 수 있습니다. - `summary_risk_coverage`(규칙+메타데이터): `metadata.summary_tags`에 정의된 기대 리스크 태그(exclusion/limit/...)가 요약에 반영되는지 확인합니다. - `metadata.summary_tags`가 비어 있으면 점수가 `1.0`으로 처리되므로, 태그가 없는 데이터셋에서는 \"리스크 커버\"를 검증했다고 보기 어렵습니다. - `summary_non_definitive`(규칙 기반): \"무조건/반드시/100%\" 같은 단정 표현이 있으면 `0.0`, 없으면 `1.0`입니다. 간단하고 안정적이지만 **단 1회 매칭으로 0점**이므로, 문장 스타일/표현 습관에 매우 민감합니다. - `summary_needs_followup`(규칙+메타데이터): `metadata.summary_tags`에 `needs_followup`가 있는 경우에만 follow-up 문구를 요구합니다. - 태그가 없는데 follow-up 문구가 들어가면 `0.0`이 될 수 있어, 데이터셋 태깅 정책과 함께 해석해야 합니다.\n\n#### QA 커스텀 메트릭(규칙/사전/문자열 기반): 신뢰도/타당도\n\n- `insurance_term_accuracy`(사전 기반): 보험 용어 사전(정규형/변형)을 기준으로 답변 용어가 컨텍스트에 근거하는지 확인합니다. 사전에 없는 신조어/상품명은 놓칠 수 있어, 도메인 확장 시 사전 갱신이 필요합니다. - `contextual_relevancy`(규칙 기반): 질문-컨텍스트 토큰 겹침으로 \"컨텍스트가 질문과 맞는가\"를 빠르게 점검합니다. 의미적 유사(동의어/패러프레이즈)에는 약해, **retriever 디버깅용 보조 신호**로 보는 것이 안전합니다. - `no_answer_accuracy`, `exact_match`, `f1_score`(규칙/문자열 기반): 재현성이 높아 회귀 테스트에는 유리하지만, 문제 정의가 조금만 바뀌면(표현 다양성/서술형 답변) 타당도가 급격히 떨어질 수 있습니다. - `mrr`, `ndcg`, `hit_rate`(규칙 기반): retrieval 순위 품질을 보기 위한 지표이지만, 관련성 판정이 토큰 겹침 기반이므로 **ground_truth 표현과의 어휘 불일치**가 크면 과소평가될 수 있습니다. - `confidence_score`(휴리스틱 결합): 여러 신호를 가중 결합한 참고 지표로, \"품질 확정\"보다는 **리뷰 우선순위/에스컬레이션 신호**로 사용하는 편이 안전합니다.",
-    "**실사용 주의사항** - LLM 기반 지표(RAGAS 계열)는 단일 run의 점수만으로 결론을 내리지 말고, 최소 샘플 수/분산(재실행) 관점에서 함께 보세요. - `contexts`가 부정확/누락/중복되면 대부분의 지표가 왜곡됩니다. 특히 `faithfulness`/`summary_faithfulness` 저하는 \"모델 문제\"가 아니라 \"근거 입력 문제\"일 수 있습니다. - `ground_truth`가 필요한 지표(`context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`, 일부 커스텀)는 레퍼런스 품질이 곧 지표 품질입니다. 레퍼런스 정의가 불안정하면 지표가 흔들립니다. - 일부 전처리 경로는 레퍼런스(`reference`) 누락을 질문/답변/컨텍스트 기반으로 보완할 수 있습니다. 이 경우 지표가 \"정답 대비\"가 아니라 \"입력으로 만든 준-정답 대비\"가 되어 타당도가 달라질 수 있으므로, 가능하면 데이터셋에 명시적 `ground_truth`/`reference`를 제공하세요. - `metadata.summary_tags`에 의존하는 지표(`summary_risk_coverage`, `summary_needs_followup`)는 태그가 없으면 점수가 과대평가되거나(항상 1.0), 반대로 불필요한 패널티가 생길 수 있습니다. - 규칙 기반 지표(문자열/정규식/사전)는 안정적이지만, 도메인이 바뀌면 키워드/패턴/사전 갱신이 필요합니다(미갱신 상태에서의 점수는 \"측정 실패\"일 수 있음).\n\n**개선 제안(옵션)** - LLM 기반 지표의 변동을 줄이려면: 동일 모델/프롬프트/프로필을 고정하고, 프롬프트 스냅샷(`--db`, `--ragas-prompts`, `--system-prompt*`)을 함께 저장해 비교 조건을 고정하세요. - 요약 품질을 더 안전하게 보려면: `summary_faithfulness`(근거) + `entity_preservation`/`summary_accuracy`(핵심 엔티티) + `summary_risk_coverage`(리스크 태그)처럼 **서로 다른 실패 모드를 커버하는 조합**으로 해석하세요. - `summary_risk_coverage`/`summary_needs_followup`를 쓰려면: 데이터셋 생성 단계에서 `metadata.summary_tags` 정책을 정의하고(누가/어떻게 태깅), 누락률을 모니터링하세요. - 규칙 기반 지표를 도메인에 맞추려면: 사전(`terms_dictionary.json`)·키워드·정규식을 도메인/제품 정책에 맞춰 확장하고, 변경 시 `custom_metric_snapshot`을 통해 구현 해시가 기록되는지 확인하세요. - RAGAS 점수와 실사용 만족도의 정합성을 높이려면: 대표 샘플링 + 인간 평가로 보정하는 절차를 병행하세요(참고: `docs/guides/RAGAS_HUMAN_FEEDBACK_CALIBRATION_GUIDE.md`).\n\nEvalVault는 JSON/CSV/Excel을 지원합니다. **threshold는 데이터셋에 포함**되며, 값이 없으면 기본값 `0.7`을 사용합니다. Domain Memory를 켜면 신뢰도에 따라 자동 조정될 수 있습니다.\n\nJSON 예시는 아래와 같습니다.\n\n```json { \"name\": \"insurance_qa_korean\", \"version\": \"1.0.0\", \"thresholds\": {\"faithfulness\": 0.8}, \"test_cases\": [ { \"id\": \"tc-001\", \"question\": \"보험 해지 환급금은 어떻게 계산하나요?\", \"answer\": \"...\", \"contexts\": [\"...\"], \"ground_truth\": \"...\" } ] } ```\n\n- `thresholds`: 메트릭별 pass 기준 (0.0~1.0) - `ground_truth`: `context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`에 필요\n\nCSV/Excel의 경우 `id,question,answer,contexts,ground_truth` 컬럼을 포함하고, 선택적으로 `threshold_*` 컬럼을 넣을 수 있습니다. `threshold_*` 값은 **첫 번째로 채워진 행 기준**으로 데이터셋 전체 임계값으로 사용됩니다. `contexts`는 JSON 배열 문자열 또는 `|` 로 구분합니다. 대용량 파일은 `--stream` 옵션으로 스트리밍 평가를 활성화하세요.\n\n#### 데이터셋 템플릿\n\n빈 템플릿은 아래 위치에서 사용할 수 있습니다. 필요한 값만 채워 바로 사용할 수 있습니다.\n\n- 프로젝트 초기화 시: `dataset_templates/` 폴더에 JSON/CSV/XLSX 템플릿 생성 - 문서 저장소: `docs/templates/dataset_template.json` - 문서 저장소: `docs/templates/dataset_template.csv` - 문서 저장소: `docs/templates/dataset_template.xlsx`\n\nJSON 템플릿의 `thresholds` 값은 `null`로 비워져 있으므로 사용 전 숫자로 채우거나 삭제하세요. CSV/Excel은 `threshold_*` 컬럼에 값을 채우면 동일하게 적용됩니다.\n\n#### 실행 결과 엑셀(컬럼 설명) - 시트/컬럼 상세: `docs/guides/EVALVAULT_RUN_EXCEL_SHEETS.md`\n\n---\n\n## CLI 명령어 참조\n\n### 루트 명령어\n\n#### `init` - 프로젝트 초기화\n\n```bash uv run evalvault init uv run evalvault init --output-dir ./my-project uv run evalvault init --skip-env --skip-sample ```\n\n- `.env` 템플릿과 `sample_dataset.json`을 생성합니다. - `dataset_templates/`에 JSON/CSV/XLSX 템플릿을 생성합니다. - `--output-dir`로 생성 위치를 지정할 수 있습니다. - `--skip-env`/`--skip-sample`/`--skip-templates`로 단계별 생성을 끌 수 있습니다.\n\n#### `run` - 평가 실행\n\n```bash uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness,answer_relevancy \\ --tracker phoenix \\ --profile dev \\ --db data/db/evalvault.db \\ --auto-analyze ```\n\n**주요 옵션**:",
+    "**실사용 주의사항** - LLM 기반 지표(RAGAS 계열)는 단일 run의 점수만으로 결론을 내리지 말고, 최소 샘플 수/분산(재실행) 관점에서 함께 보세요. - `contexts`가 부정확/누락/중복되면 대부분의 지표가 왜곡됩니다. 특히 `faithfulness`/`summary_faithfulness` 저하는 \"모델 문제\"가 아니라 \"근거 입력 문제\"일 수 있습니다. - `ground_truth`가 필요한 지표(`context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`, 일부 커스텀)는 레퍼런스 품질이 곧 지표 품질입니다. 레퍼런스 정의가 불안정하면 지표가 흔들립니다. - 일부 전처리 경로는 레퍼런스(`reference`) 누락을 질문/답변/컨텍스트 기반으로 보완할 수 있습니다. 이 경우 지표가 \"정답 대비\"가 아니라 \"입력으로 만든 준-정답 대비\"가 되어 타당도가 달라질 수 있으므로, 가능하면 데이터셋에 명시적 `ground_truth`/`reference`를 제공하세요. - `metadata.summary_tags`에 의존하는 지표(`summary_risk_coverage`, `summary_needs_followup`)는 태그가 없으면 점수가 과대평가되거나(항상 1.0), 반대로 불필요한 패널티가 생길 수 있습니다. - 규칙 기반 지표(문자열/정규식/사전)는 안정적이지만, 도메인이 바뀌면 키워드/패턴/사전 갱신이 필요합니다(미갱신 상태에서의 점수는 \"측정 실패\"일 수 있음).\n\n**개선 제안(옵션)** - LLM 기반 지표의 변동을 줄이려면: 동일 모델/프롬프트/프로필을 고정하고, 프롬프트 스냅샷(`--db`, `--ragas-prompts`, `--system-prompt*`)을 함께 저장해 비교 조건을 고정하세요. - 요약 품질을 더 안전하게 보려면: `summary_faithfulness`(근거) + `entity_preservation`/`summary_accuracy`(핵심 엔티티) + `summary_risk_coverage`(리스크 태그)처럼 **서로 다른 실패 모드를 커버하는 조합**으로 해석하세요. - `summary_risk_coverage`/`summary_needs_followup`를 쓰려면: 데이터셋 생성 단계에서 `metadata.summary_tags` 정책을 정의하고(누가/어떻게 태깅), 누락률을 모니터링하세요. - 규칙 기반 지표를 도메인에 맞추려면: 사전(`terms_dictionary.json`)·키워드·정규식을 도메인/제품 정책에 맞춰 확장하고, 변경 시 `custom_metric_snapshot`을 통해 구현 해시가 기록되는지 확인하세요. - RAGAS 점수와 실사용 만족도의 정합성을 높이려면: 대표 샘플링 + 인간 평가로 보정하는 절차를 병행하세요(참고: `docs/guides/RAGAS_HUMAN_FEEDBACK_CALIBRATION_GUIDE.md`).\n\nEvalVault는 JSON/CSV/Excel을 지원합니다. **threshold는 데이터셋에 포함**되며, 값이 없으면 기본값 `0.7`을 사용합니다. Domain Memory를 켜면 신뢰도에 따라 자동 조정될 수 있습니다.\n\nJSON 예시는 아래와 같습니다.\n\n```json { \"name\": \"insurance_qa_korean\", \"version\": \"1.0.0\", \"thresholds\": {\"faithfulness\": 0.8}, \"test_cases\": [ { \"id\": \"tc-001\", \"question\": \"보험 해지 환급금은 어떻게 계산하나요?\", \"answer\": \"...\", \"contexts\": [\"...\"], \"ground_truth\": \"...\" } ] } ```\n\n- `thresholds`: 메트릭별 pass 기준 (0.0~1.0) - `ground_truth`: `context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`에 필요\n\nCSV/Excel의 경우 `id,question,answer,contexts,ground_truth` 컬럼을 포함하고, 선택적으로 `threshold_*` 컬럼을 넣을 수 있습니다. `threshold_*` 값은 **첫 번째로 채워진 행 기준**으로 데이터셋 전체 임계값으로 사용됩니다. `contexts`는 JSON 배열 문자열 또는 `|` 로 구분합니다.\n\n요약 메트릭용 선택 컬럼: - `summary_tags`: 콤마/파이프 구분 또는 JSON 배열 문자열 - `summary_intent`: 예) `agent_notes` - `metadata`: JSON 객체 문자열 (예: `{ \"priority\": \"high\" }`)\n\n대용량 파일은 `--stream` 옵션으로 스트리밍 평가를 활성화하세요.\n\n#### 데이터셋 템플릿\n\n빈 템플릿은 아래 위치에서 사용할 수 있습니다. 필요한 값만 채워 바로 사용할 수 있습니다.\n\n- 프로젝트 초기화 시: `dataset_templates/` 폴더에 JSON/CSV/XLSX 템플릿 생성 - 문서 저장소: `docs/templates/dataset_template.json` - 문서 저장소: `docs/templates/dataset_template.csv` - 문서 저장소: `docs/templates/dataset_template.xlsx`\n\nJSON 템플릿의 `thresholds` 값은 `null`로 비워져 있으므로 사용 전 숫자로 채우거나 삭제하세요. CSV/Excel은 `threshold_*` 컬럼에 값을 채우면 동일하게 적용됩니다.\n\n#### 실행 결과 엑셀(컬럼 설명) - 시트/컬럼 상세: `docs/guides/EVALVAULT_RUN_EXCEL_SHEETS.md`\n\n---\n\n## CLI 명령어 참조\n\n### 루트 명령어\n\n#### `init` - 프로젝트 초기화\n\n```bash uv run evalvault init uv run evalvault init --output-dir ./my-project uv run evalvault init --skip-env --skip-sample ```\n\n- `.env` 템플릿과 `sample_dataset.json`을 생성합니다. - `dataset_templates/`에 JSON/CSV/XLSX 템플릿을 생성합니다. - `--output-dir`로 생성 위치를 지정할 수 있습니다. - `--skip-env`/`--skip-sample`/`--skip-templates`로 단계별 생성을 끌 수 있습니다.\n\n#### `run` - 평가 실행\n\n```bash uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness,answer_relevancy \\ --tracker phoenix \\ --profile dev \\ --db data/db/evalvault.db \\ --auto-analyze ```\n\n**주요 옵션**:",
     "- `--metrics, -m`: 쉼표로 구분된 메트릭 목록 - `--preset`: `quick`/`production`/`comprehensive` 프리셋 적용 - `--mode`: `simple`/`full` 실행 모드 - `--auto-analyze`: 평가 완료 후 통합 분석을 자동 실행하고 보고서를 저장 - `--analysis-json`: 자동 분석 JSON 결과 파일 경로 (기본값: `reports/analysis`) - `--analysis-report`: 자동 분석 Markdown 보고서 경로 (기본값: `reports/analysis`) - `--analysis-dir`: 자동 분석 결과 저장 디렉터리 (기본: `reports/analysis`) - `--parallel, -P`: 병렬 평가 활성화 - `--batch-size, -b`: 배치 크기 (기본: 5) - `--stream, -s`: 대용량 데이터셋 스트리밍 평가 - `--stream-chunk-size`: 스트리밍 청크 크기 (기본: 200) - `--tracker, -t`: 추적기 선택 (`none`, `langfuse`, `mlflow`, `phoenix`) - `--db, -D`: SQLite 저장소 지정 - `--use-domain-memory`: Domain Memory 기반 threshold/컨텍스트 보강 활성화 - `--memory-domain`: Domain Memory 도메인 이름 - `--memory-language`: Domain Memory 언어 코드 (기본: ko) - `--augment-context`: Domain Memory 사실을 컨텍스트에 추가 - `--memory-db, -M`: Domain Memory DB 경로 - `--retriever, -r`: 리트리버 선택 (`bm25`, `dense`, `hybrid`, `graphrag`) - `--retriever-docs`: 리트리버 문서 파일 (.json/.jsonl/.txt) - `--kg, -k`: GraphRAG용 Knowledge Graph JSON 파일 - `--retriever-top-k`: 리트리버 Top-K (기본: 5) - `--phoenix-dataset`: Phoenix Dataset 이름 - `--phoenix-experiment`: Phoenix Experiment 이름 - `--prompt-manifest`: Phoenix prompt manifest JSON 경로 - `--prompt-files`: 프롬프트 파일 목록 (쉼표로 구분) - `--system-prompt`: 시스템 프롬프트 텍스트 - `--system-prompt-file`: 시스템 프롬프트 파일 경로 - `--ragas-prompts`: Ragas 프롬프트 오버라이드 YAML 파일\n\n**Run Modes**:\n\n| 모드 | 명령 | 동작 | |------|------|------| | Simple | `uv run evalvault run --mode simple DATASET.json`<br>`uv run evalvault run-simple DATASET.json` | `faithfulness,answer_relevancy` 메트릭 + Phoenix tracker 고정, Domain Memory/Prompt manifest 비활성 | | Full | `uv run evalvault run --mode full DATASET.json`<br>`uv run evalvault run-full DATASET.json` | 모든 Typer 옵션(프로파일, Prompt manifest, Phoenix dataset/experiment, Domain Memory, streaming)을 노출 |\n\n**Evaluation Presets**:\n\n| 프리셋 | 설명 | 기본 메트릭 | |--------|------|-------------| | `quick` | 빠른 반복 평가 (parallel, batch_size=10) | `faithfulness` | | `production` | 프로덕션 밸런스 (parallel, batch_size=5) | `faithfulness`, `answer_relevancy`, `context_precision`, `context_recall` | | `comprehensive` | 전체 메트릭 평가 (parallel, batch_size=3) | `faithfulness`, `answer_relevancy`, `context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity` |\n\n#### `pipeline` - 분석 파이프라인 실행\n\n```bash uv run evalvault pipeline analyze \"요약해줘\" --run <RUN_ID> --db data/db/evalvault.db ```\n\n의도 분류 후 DAG 모듈을 실행하여 통계/NLP/인과 분석을 수행합니다.\n\n#### `history` - 평가 이력 조회\n\n```bash uv run evalvault history --limit 20 --db data/db/evalvault.db uv run evalvault history --mode simple --db data/db/evalvault.db ```\n\n#### `analyze` - 단일 실행 분석\n\n```bash uv run evalvault analyze <RUN_ID> \\ --db data/db/evalvault.db \\ --nlp --causal \\ --output analysis.json \\ --report analysis.md ```\n\n**옵션**: - `--nlp, -N`: NLP 분석 포함 - `--causal, -c`: 인과 분석 포함 - `--playbook, -B`: 플레이북 기반 개선 분석 포함 - `--enable-llm, -L`: LLM 기반 인사이트 생성 활성화 - `--output, -o`: 출력 JSON 파일 - `--report, -r`: 출력 보고서 파일 (*.md or *.html) - `--save, -S`: 분석 결과를 데이터베이스에 저장\n\n#### `analyze-compare` - A/B 비교 분석\n\n```bash uv run evalvault analyze-compare <RUN_A> <RUN_B> \\ --db data/db/evalvault.db \\ --metrics faithfulness,answer_relevancy \\ --test t-test ```\n\n기본 저장 위치: - JSON 결과: `reports/comparison/comparison_<RUN_A>_<RUN_B>.json` - Markdown 보고서: `reports/comparison/comparison_<RUN_A>_<RUN_B>.md`\n\n비교 보고서는 **프롬프트 변경 요약 + 통계 비교 + 개선 제안**을 자동으로 포함합니다.\n\n#### `generate` - 테스트셋 생성\n\n```bash uv run evalvault generate --from-docs documents.txt --output dataset.json ```\n\n#### `gate` - 품질 게이트 검사\n\n```bash uv run evalvault gate <RUN_ID> --db data/db/evalvault.db --format github-actions ```\n\n#### `agent` - 에이전트 관리\n\n```bash uv run evalvault agent list uv run evalvault agent info <agent_type> uv run evalvault agent run <agent_type> --project-dir . ```\n\n#### `experiment` - 실험 관리\n\n```bash uv run evalvault experiment-create --name \"A/B Test\" --db data/db/evalvault.db uv run evalvault experiment-add-group <EXPERIMENT_ID> --name \"baseline\" uv run evalvault experiment-add-run <EXPERIMENT_ID> <GROUP_NAME> <RUN_ID> --db data/db/evalvault.db uv run evalvault experiment-compare <EXPERIMENT_ID> --db data/db/evalvault.db ```\n\n#### `config` - 설정 확인\n\n```bash uv run evalvault config ```\n\n현재 설정 상태를 확인합니다.\n\n#### `langfuse` - Langfuse 설정 확인\n\n```bash uv run evalvault langfuse-dashboard ```\n\n#### `serve-api` - FastAPI 서버 실행\n\n```bash uv run evalvault serve-api --reload ```\n\n### 서브앱 명령어\n\n#### `kg` - Knowledge Graph\n\n```bash uv run evalvault kg build ./docs --output data/kg/knowledge_graph.json uv run evalvault kg stats ./docs --use-llm --profile dev ```\n\n#### `domain` - Domain Memory\n\n```bash uv run evalvault domain memory stats --db data/db/evalvault_memory.db uv run evalvault domain memory ingest-embeddings phoenix.csv --domain insurance --language ko ```\n\n#### `benchmark` - KMMLU 벤치마크 실행\n\nlm-evaluation-harness를 사용하여 KMMLU(Korean MMLU) 벤치마크를 실행합니다.\n\n```bash # Ollama 백엔드로 실행 uv run evalvault benchmark kmmlu -s Insurance --backend ollama -m gemma3:1b\n\n# Thinking 모델로 실행 (gpt-oss-safeguard, deepseek-r1 등) uv run evalvault benchmark kmmlu -s Accounting --backend ollama -m gpt-oss-safeguard:20b --limit 10\n\n# Phoenix 트레이싱 활성화 uv run evalvault benchmark kmmlu -s Insurance --backend ollama -m gemma3:1b --phoenix\n\n# vLLM 백엔드로 실행 uv run evalvault benchmark kmmlu -s Insurance --backend vllm\n\n# 여러 도메인 동시 실행 uv run evalvault benchmark kmmlu -s \"Insurance,Finance\" -m llama2\n\n# 테스트용 샘플 제한 uv run evalvault benchmark kmmlu -s Insurance --limit 10 -o results.json ```\n\n**주요 옵션**: - `-s, --subjects`: 평가할 KMMLU 도메인 (Insurance, Finance, Accounting 등) - `--backend`: 백엔드 선택 (`ollama`, `vllm`, `hf`, `openai`) - `-m, --model`: 모델 이름 - `--limit`: 테스트 샘플 수 제한 - `--phoenix`: Phoenix 트레이싱 활성화 - `-o, --output`: 결과 JSON 파일 경로\n\n**Thinking Model 지원**: Ollama의 thinking 모델(예: `gpt-oss-safeguard:20b`, `deepseek-r1:*`)은 자동으로 감지됩니다. - `max_gen_toks`가 8192로 증가 (thinking 토큰 포함) - Stop sequence가 `[\"Q:\", \"\\n\\n\\n\"]`로 수정 - MCQ 응답에서 첫 번째 A/B/C/D를 자동 추출\n\n#### `method` - 메서드 플러그인\n\n```bash uv run evalvault method list uv run evalvault method run data.json --method my_team_method --metrics faithfulness ```\n\n#### `phoenix` - Phoenix 연동\n\n```bash uv run evalvault phoenix export-embeddings --dataset ds_123 --output embeddings.csv uv run evalvault phoenix prompt-link agent/prompts/baseline.txt --prompt-id pr-428 uv run evalvault phoenix prompt-diff baseline.txt system.txt --manifest manifest.json ```\n\n#### `prompts` - 프롬프트 관리\n\n```bash uv run evalvault prompts show <RUN_ID> --db data/db/evalvault.db uv run evalvault prompts diff <RUN_A> <RUN_B> --db data/db/evalvault.db ```\n\n프롬프트 언어 기본값은 `ko`이며, 필요 시 API/SDK에서 다음 옵션으로 영어를 지정할 수 있습니다. - 평가/요약 판정: `language=\"en\"` - 프롬프트 후보 평가: `prompt_language=\"en\"`\n\n#### `stage` - 단계별 성능 평가\n\n```bash uv run evalvault stage ingest examples/stage_events.jsonl --db data/db/evalvault.db uv run evalvault stage summary <RUN_ID> --db data/db/evalvault.db uv run evalvault stage compute-metrics <RUN_ID> --db data/db/evalvault.db uv run evalvault stage report <RUN_ID> --db data/db/evalvault.db ```\n\n#### `debug` - 디버그 리포트\n\n```bash uv run evalvault debug report <RUN_ID> --db data/db/evalvault.db ```\n\n### 공통 옵션\n\n| 옵션 | 설명 | 사용 예 | |------|------|---------| | `--profile, -p` | `config/models.yaml`에 정의된 프로필을 적용합니다. | `uv run evalvault run dataset.json -p dev` | | `--db, -D` | 평가 결과를 저장할 SQLite 경로입니다. 기본값은 `EVALVAULT_DB_PATH` 또는 `data/db/evalvault.db`. | `uv run evalvault history -D reports/evalvault.db` | | `--memory-db, -M` | 도메인 메모리 SQLite 경로입니다. 기본값은 `EVALVAULT_MEMORY_DB_PATH` 또는 `data/db/evalvault_memory.db`. | `uv run evalvault domain memory stats -M data/memory.db` |\n\n---\n\n## Web UI\n\n### 실행 방법\n\n```bash # Terminal 1: API 서버 uv run evalvault serve-api --reload\n\n# Terminal 2: React 프론트엔드 cd frontend npm install npm run dev ```\n\n- 기본 접속: http://localhost:5173 - API 기본: http://127.0.0.1:8000 - Vite dev 서버는 `/api`를 API로 프록시합니다.\n\n### 주요 기능\n\n- **Evaluation Studio**: 데이터셋 업로드, 평가 실행, 결과 확인 - **Analysis Lab**: 분석 파이프라인 실행, 결과 저장/불러오기 - **Reports**: 평가 결과 보고서, 히스토리, 비교 뷰\n\n### Web UI와 CLI 연동\n\nCLI와 Web UI가 동일한 DB(`--db` 또는 `EVALVAULT_DB_PATH`)를 사용하면: - CLI에서 실행한 평가 결과를 Web UI에서 바로 확인 가능 - Web UI에서 실행한 평가 결과를 CLI `history` 명령으로 확인 가능 - 분석 결과도 양쪽에서 공유\n\n### 보고서 언어 옵션\n\nLLM 보고서는 기본 한국어이며, 필요 시 영어로 요청할 수 있습니다.\n\n- `GET /api/v1/runs/{run_id}/report?language=en` (기본값: `ko`)\n\n### 피드백 집계 규칙\n\nWeb UI의 별점/Thumb 피드백 집계는 다음 규칙을 따릅니다.\n\n- 집계 기준: 동일 `rater_id` + `test_case_id`의 **최신 피드백만** 반영 - 취소(`thumb_feedback=none` 또는 빈 값)는 집계에서 제외\n\n---\n\n## 분석 워크플로\n\n### 자동 분석 (옵션 방식)\n\n평가 완료 후 자동으로 분석을 실행하려면 `--auto-analyze` 옵션을 사용합니다:\n\n```bash uv run evalvault run data.json \\ --metrics faithfulness,answer_relevancy \\ --db data/db/evalvault.db \\ --auto-analyze ```\n\n### 기본 저장 위치",
     "- JSON 결과: `reports/analysis/analysis_<run_id>.json` - Markdown 보고서: `reports/analysis/analysis_<run_id>.md` - 아티팩트 인덱스: `reports/analysis/artifacts/analysis_<run_id>/index.json` - 노드별 결과: `reports/analysis/artifacts/analysis_<run_id>/<node_id>.json`\n\n### 저장 위치 커스터마이즈\n\n```bash uv run evalvault run data.json \\ --db data/db/evalvault.db \\ --auto-analyze \\ --analysis-dir reports/custom \\ --analysis-json reports/custom/run_001.json \\ --analysis-report reports/custom/run_001.md ```\n\n### 단일 실행 분석 (수동)\n\n```bash uv run evalvault analyze RUN_ID \\ --db data/db/evalvault.db \\ --nlp --causal ```\n\n필요 시 `--output`, `--report`로 파일 저장 가능합니다.\n\n### A/B 직접 비교 분석\n\n```bash uv run evalvault analyze-compare RUN_A RUN_B \\ --db data/db/evalvault.db \\ --metrics faithfulness,answer_relevancy \\ --test t-test ```\n\n기본 저장 위치: - JSON 결과: `reports/comparison/comparison_<run_a>_<run_b>.json` - Markdown 보고서: `reports/comparison/comparison_<run_a>_<run_b>.md`\n\n비교 보고서는 **프롬프트 변경 요약 + 통계 비교 + 개선 제안**을 자동으로 포함합니다.\n\n### 분석 결과에 포함되는 내용\n\n- **통계 요약**: 평균/분산/상관관계/통과율 - **Ragas 요약**: 메트릭별 평균, 케이스별 점수 - **저성과 케이스**: 낮은 점수 샘플, 우선순위 케이스 - **진단/원인 분석**: 문제 원인 가설 + 개선 힌트 - **패턴/트렌드**: 키워드/질문 유형 패턴, 실행 이력 추세 - **A/B 변경 사항**: 시스템 프롬프트, Ragas 프롬프트, 모델/옵션 차이 - **LLM 종합 보고서**: 원인 분석 + 개선 방향 + 다음 실험 제안\n\n### 평가 → 분석 전체 흐름\n\n1. **평가 실행** - `evalvault run data.json --db ...` 2. **자동 분석 (옵션)** - `--auto-analyze`로 즉시 보고서 생성 3. **추가 분석** - 필요 시 `evalvault analyze`로 상세 분석 4. **A/B 비교** - `evalvault analyze-compare`로 비교 보고서 생성 5. **프롬프트/메트릭 개선** - 보고서의 개선 제안을 반영해 다음 실행\n\n### 품질 확보 팁\n\n- A/B 비교는 **데이터셋 동일** 조건에서 수행하세요. - 프롬프트 변경은 프롬프트 관리 섹션의 흐름대로 스냅샷 저장하세요. - 비교 결과가 애매하면 샘플 수를 늘리고 재실행하세요.\n\n---\n\n## Domain Memory 활용\n\nDomain Memory는 과거 평가 결과에서 도메인 지식/패턴을 축적하여 다음 평가에 활용하는 시스템입니다.\n\n### 기본 사용법\n\n```bash uv run evalvault run data.json \\ --metrics faithfulness,answer_relevancy \\ --use-domain-memory \\ --memory-domain insurance \\ --memory-language ko \\ --augment-context \\ --db data/db/evalvault.db ```\n\n**옵션 설명**: - `--use-domain-memory`: Domain Memory 활성화 - `--memory-domain`: 도메인 이름 (기본값: 데이터셋 메타데이터에서 추출) - `--memory-language`: 언어 코드 (기본: ko) - `--augment-context`: 관련 사실을 컨텍스트에 추가 - `--memory-db, -M`: Domain Memory DB 경로\n\n### 동작 원리\n\n1. **Threshold 자동 조정**: Domain Memory의 신뢰도 점수에 따라 메트릭 임계값을 자동 조정 2. **컨텍스트 보강**: 각 테스트 케이스의 질문으로 관련 사실을 검색하여 컨텍스트에 추가 3. **학습**: 평가 완료 후 Domain Learning Hook이 결과에서 사실/패턴/행동을 추출하여 저장\n\n### MemoryBasedAnalysis\n\n과거 학습 메모리와 현재 결과를 비교하여 추세와 추천을 생성합니다:\n\n```bash uv run evalvault analyze <RUN_ID> \\ --db data/db/evalvault.db \\ --use-domain-memory ```\n\n**제한 사항**: - Streaming 모드(`--stream`)에서는 Domain Memory를 사용할 수 없습니다. - Web UI 인사이트: Domain Memory/MemoryBasedAnalysis 인사이트는 CLI 출력 기준으로만 제공됩니다.\n\n---\n\n## 관측성 & Phoenix\n\n### 트레이싱 활성화\n\n1. `uv sync --extra phoenix` 2. `.env` 에 `PHOENIX_ENABLED=true`, `PHOENIX_ENDPOINT`, `PHOENIX_SAMPLE_RATE`, `PHOENIX_API_TOKEN(선택)` 설정 3. CLI 실행 시 `--tracker phoenix` 또는 `--phoenix-max-traces` 사용\n\nPhoenix 트레이스는 OpenTelemetry 스팬으로 생성되며 `tracker_metadata[\"phoenix\"][\"trace_url\"]` 에 링크가 저장됩니다.\n\n### Dataset/Experiment 동기화\n\n```bash uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json \\ --metrics faithfulness,answer_relevancy \\ --tracker phoenix \\ --phoenix-dataset insurance-qa-ko \\ --phoenix-dataset-description \"보험 QA v2025.01\" \\ --phoenix-experiment gemma3-ko-baseline \\ --phoenix-experiment-description \"Gemma3 vs OpenAI 비교\" ```\n\n- `--phoenix-dataset`: EvalVault Dataset을 Phoenix Dataset으로 업로드 - `--phoenix-experiment`: Phoenix Experiment 생성 및 메트릭/Pass Rate/Domain Memory 메타데이터 포함 - 생성된 URL은 JSON 출력과 Web UI 히스토리에서 확인할 수 있습니다.\n\n### Open RAG Trace 표준 연동\n\n외부/내부 RAG 시스템을 EvalVault·Phoenix와 동일한 스키마로 연결하려면 OpenTelemetry + OpenInference 기반의 **Open RAG Trace 표준**을 따르세요.\n\n**핵심 규칙** - `rag.module`로 모듈 단위를 식별 (retrieve/llm/eval 등) - 로그는 span event로 흡수 - 표준 필드 외 데이터는 `custom.*`로 보존 - 객체 배열은 `*_json`으로 직렬화 (`retrieval.documents_json` 등)\n\n**연동 순서** 1. Collector 실행 ```bash docker run --rm \\ -p 4317:4317 -p 4318:4318 \\ -e PHOENIX_OTLP_ENDPOINT=http://host.docker.internal:6006 \\ -v \"$(pwd)/scripts/dev/otel-collector-config.yaml:/etc/otelcol/config.yaml\" \\ otel/opentelemetry-collector:latest \\ --config=/etc/otelcol/config.yaml ``` 2. 계측 래퍼 적용 - `OpenRagTraceAdapter`, `trace_module`, `install_open_rag_log_handler` - `build_retrieval_attributes`, `build_llm_attributes` 등 헬퍼 사용 3. OTLP 전송 - Collector: `http://localhost:4318/v1/traces` - Phoenix 직접: `http://localhost:6006/v1/traces` 4. 검증 스크립트 실행 ```bash python3 scripts/dev/validate_open_rag_trace.py --input traces.json ```\n\n**관련 문서** - `docs/architecture/open-rag-trace-spec.md` - `docs/architecture/open-rag-trace-collector.md` - `docs/guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md` - `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`\n\n### 임베딩 분석 & 내보내기\n\nPhoenix 12.27.0의 Embeddings Analysis 뷰는 드리프트/클러스터/3D 시각화를 제공합니다. 업로드된 Dataset/Experiment 화면에서 \"Embeddings\" 탭을 열면 EvalVault 질문/답변 벡터 및 Domain Memory 태그를 확인할 수 있습니다.\n\n오프라인 분석이 필요하면 CLI로 내보내세요: ```bash uv run evalvault phoenix export-embeddings \\ --dataset phoenix-dataset-id \\ --endpoint http://localhost:6006 \\ --output tmp/phoenix_embeddings.csv ```\n\nUMAP/HDBSCAN 라이브러리가 없는 경우 자동으로 PCA/DBSCAN으로 대체합니다.\n\n### Prompt Manifest 루프\n\nPrompt Playground와 EvalVault 실행을 동기화하려면 `agent/prompts/prompt_manifest.json`과 전용 명령을 사용합니다.\n\n1. **프롬프트 ↔ Phoenix ID 연결** ```bash uv run evalvault phoenix prompt-link agent/prompts/baseline.txt \\ --prompt-id pr-428 \\ --experiment-id exp-20250115 \\ --notes \"Gemma3 베이스라인\" ``` 2. **Diff 확인** ```bash uv run evalvault phoenix prompt-diff \\ agent/prompts/baseline.txt agent/prompts/system.txt \\ --manifest agent/prompts/prompt_manifest.json --format table ``` 3. **평가 실행에 Prompt 정보 주입** ```bash DATASET=\"tests/fixtures/e2e/insurance_qa_korean.json\" uv run evalvault run \"$DATASET\" --metrics faithfulness \\ --profile prod \\ --tracker phoenix \\ --prompt-files agent/prompts/baseline.txt,agent/prompts/system.txt \\ --prompt-manifest agent/prompts/prompt_manifest.json ```\n\n`tracker_metadata[\"phoenix\"][\"prompts\"]` 에 파일 상태/체크섬/diff가 기록되어 Slack 릴리즈 노트, 히스토리, Web UI에 그대로 노출됩니다.\n\n> **Tip**: Prompt Playground 연동 시에는 Phoenix tool-calling을 지원하는 `prod` 프로필(`gpt-oss-safeguard:20b`)을 사용하면 \"does not support tools\" 오류 없이 메타데이터가 기록됩니다.\n\n### 드리프트 감시 & 릴리스 노트\n\n- `scripts/ops/phoenix_watch.py`: Phoenix Dataset을 주기적으로 조회하여 `embedding_drift_score` 초과 시 Slack 알림 또는 `uv run evalvault gate <run_id>`/회귀 테스트 실행 ```bash uv run python scripts/ops/phoenix_watch.py \\ --endpoint http://localhost:6006 \\ --dataset-id ds_123 \\ --drift-key embedding_drift_score \\ --drift-threshold 0.18 \\ --slack-webhook https://hooks.slack.com/services/... \\ --gate-command \"uv run evalvault gate RUN_ID --format github-actions --db data/db/evalvault.db\" \\ --run-regressions threshold \\ --regression-config config/regressions/default.json ``` - `scripts/reports/generate_release_notes.py`: `uv run evalvault run --output run.json` 결과를 Markdown/Slack 형식 릴리스 노트로 변환하고 Phoenix 링크를 삽입합니다.\n\n---\n\n## 프롬프트 관리",
     "EvalVault는 **시스템 프롬프트**와 **Ragas 메트릭 프롬프트**를 실행 단위로 스냅샷 저장하고, 실행 간 변경점을 비교할 수 있도록 설계되어 있습니다.\n\n### 저장되는 프롬프트 범위\n\n- **시스템 프롬프트**: 대상 LLM에 실제로 주입한 시스템 메시지 - **Ragas 메트릭 프롬프트**: faithfulness 등 평가 메트릭용 프롬프트 오버라이드 - **Prompt Set 스냅샷**: 위 프롬프트들을 `run_id`와 함께 DB에 저장 (비교/회귀 추적용)\n\n> **중요**: Prompt Set 저장은 `--db` 옵션이 있어야 동작합니다.\n\n### 시스템 프롬프트 등록\n\n#### 텍스트 직접 입력\n\n```bash uv run evalvault run data.json \\ --system-prompt \"당신은 보험 약관 전문가입니다...\" \\ --prompt-set-name \"sys-v2\" \\ --db data/db/evalvault.db ```\n\n#### 파일로 입력\n\n```bash uv run evalvault run data.json \\ --system-prompt-file agent/prompts/system.txt \\ --system-prompt-name sys-v2 \\ --prompt-set-name \"sys-v2\" \\ --db data/db/evalvault.db ```\n\n### Ragas 프롬프트 YAML 오버라이드\n\n#### YAML 예시\n\n```yaml faithfulness: | 너는 답변의 근거가 컨텍스트에 있는지 평가한다...\n\nanswer_relevancy: | 질문 의도와 답변의 연관성을 평가한다... ```\n\n#### 실행 예시\n\n```bash uv run evalvault run data.json \\ --ragas-prompts config/ragas_prompts.yaml \\ --prompt-set-name \"ragas-v3\" \\ --db data/db/evalvault.db ```\n\n> YAML에 있는 메트릭이 `--metrics`에 없으면 경고가 출력됩니다.\n\n### 저장된 프롬프트 확인/비교\n\n#### 스냅샷 보기\n\n```bash uv run evalvault prompts show RUN_ID --db data/db/evalvault.db ```\n\n#### 두 실행 간 비교\n\n```bash uv run evalvault prompts diff RUN_A RUN_B --db data/db/evalvault.db ```\n\n#### 비교 분석 보고서에서 자동 반영\n\n```bash uv run evalvault analyze-compare RUN_A RUN_B --db data/db/evalvault.db ```\n\n`analyze-compare` 결과에는 **프롬프트 변경 요약 + 메트릭 변화**가 함께 포함됩니다.\n\n### 운영 팁\n\n- **Prompt Set 이름 규칙화**: `sys-v3`, `ragas-v2`, `release-2025-02` 등으로 관리 - **A/B 비교 시 데이터셋 고정**: 데이터셋이 바뀌면 비교 해석이 왜곡됩니다 - **Prompt Manifest 활용**: Phoenix Prompt Playground와 연결하려면 관측성 & Phoenix 섹션의 Prompt Manifest 절을 참고하세요.\n\n---\n\n## 성능 튜닝\n\n### TL;DR (우선순위 요약)\n\n1. **병렬 평가 + 배치 크기 조절**로 처리량 확보 2. **느린 메트릭 제외** (특히 `factual_correctness`, `semantic_similarity`) 3. **빠른 LLM/임베딩 모델**로 교체 (프로필/옵션 조정) 4. **컨텍스트 길이/개수 줄이기** (retriever/top_k, 데이터 전처리) 5. **부가 기능 끄기** (Domain Memory, Tracker)\n\n### 병렬 평가와 배치 크기\n\nEvalVault는 배치 단위 `asyncio.gather`로 병렬 평가를 수행합니다. 동시성은 `batch_size`가 결정하며, `parallel`은 병렬 활성화 스위치입니다.\n\n**CLI 예시** ```bash uv run evalvault run data.json --metrics faithfulness --parallel --batch-size 10 ```\n\n> 권장: 로컬 Ollama는 5~10, 외부 API는 레이트리밋에 맞춰 단계적으로 증가\n\n### 메트릭 최소화 (속도 영향 큼)\n\n현재 EvalVault는 메트릭을 **순차적으로 평가**합니다. 필요한 메트릭만 선택해 호출 수를 줄이는 것이 가장 큰 효과를 냅니다.\n\n| 메트릭 | 호출 성격 | 속도 영향 | |--------|-----------|-----------| | `faithfulness` | LLM 호출 | 중 | | `answer_relevancy` | LLM + 임베딩 | 중~높음 | | `context_precision` | LLM | 중 | | `context_recall` | LLM | 중 | | `semantic_similarity` | 임베딩 | 높음 (임베딩 모델 속도 영향) | | `factual_correctness` | LLM 다중 호출 (claim 분해/검증) | 매우 높음 | | 커스텀 메트릭 | 규칙 기반/비LLM | 낮음 |\n\n> 빠른 반복 평가 단계에서는 `faithfulness` 단일 메트릭만으로 시작하세요.\n\n### LLM/임베딩 모델 선택\n\n평가 속도는 모델이 좌우합니다. 빠른 모델을 별도 프로필로 두고 사용하세요.\n\n```bash # 빠른 모델 프로필로 전환 EVALVAULT_PROFILE=dev uv run evalvault run data.json --metrics faithfulness ```\n\n**Ollama**: - `config/models.yaml`에서 `think_level`을 낮추거나 제거하면 속도 개선 - 임베딩 모델은 소형 모델(`qwen3-embedding:0.6b` 등) 권장\n\n### 컨텍스트 길이/개수 줄이기\n\n프롬프트 토큰이 늘어날수록 평가 속도는 급격히 느려집니다.\n\n- 데이터셋의 `contexts`를 **짧게 유지** - `retriever`를 사용할 경우 `top_k`를 낮춤 - 중복/불필요한 컨텍스트 제거\n\n**CLI 예시** ```bash uv run evalvault run data.json \\ --metrics faithfulness \\ --retriever bm25 \\ --retriever-docs docs.jsonl \\ --retriever-top-k 3 ```\n\n> Web UI는 현재 `top_k=5` 고정이므로, 더 낮추려면 CLI 또는 API 사용이 필요합니다.\n\n### 부가 기능 비활성화\n\n아래 기능은 평가 속도에 직접적인 부하를 더합니다.\n\n- Domain Memory (`--use-domain-memory` OFF) - Tracker (`--tracker none`) - Phoenix 자동 트레이싱 (`PHOENIX_ENABLED=false`) - Retriever (컨텍스트가 이미 있으면 비활성화)\n\n---\n\n## 메서드 플러그인\n\nEvalVault는 메서드 플러그인 인터페이스를 지원하여 팀별 RAG 파이프라인을 공유 기본 데이터셋에 대해 실행하고, 표준 메트릭 및 분석 도구로 출력을 평가할 수 있습니다.\n\n### 소스\n\n- **내부 레지스트리**: `config/methods.yaml` - **외부 패키지**: `evalvault.methods` entry points\n\n### 기본 데이터셋 템플릿\n\n`dataset_templates/method_input_template.json`의 질문 우선 템플릿을 사용하세요. `question/ground_truth/contexts/metadata`만 필요하며 팀 간 안정적으로 유지됩니다.\n\n### 내부 레지스트리 예시\n\n```yaml methods: baseline_oracle: class_path: \"evalvault.adapters.outbound.methods.baseline_oracle:BaselineOracleMethod\" description: \"Use ground truth as the answer when available.\" tags: [\"baseline\", \"oracle\"] ```\n\n### Entry Point 예시 (외부 패키지)\n\n```toml [project.entry-points.\"evalvault.methods\"] my_team_method = \"my_team_pkg.methods:MyTeamMethod\" ```\n\n`examples/method_plugin_template`에서 작동하는 스캐폴드를 참고하세요.\n\n### 외부 명령 (의존성 격리)\n\n메서드 의존성이 충돌할 때 별도 venv/컨테이너에서 실행합니다. `config/methods.yaml`에 명령 기반 메서드를 구성하세요:\n\n```yaml methods: team_method_external: runner: external command: \"bash -lc 'cd ../team_method && uv run python -m team_method.run --input \\\"$EVALVAULT_METHOD_INPUT\\\" --output \\\"$EVALVAULT_METHOD_OUTPUT\\\"'\" shell: true timeout_seconds: 3600 description: \"Team method executed in its own env\" ```",
@@ -1939,6 +1939,21 @@
       "문자열",
       "구분",
       "하",
+      "요약",
+      "메",
+      "트릭",
+      "용",
+      "선택",
+      "컬럼",
+      "콤마",
+      "파이프",
+      "구분",
+      "배열",
+      "문자열",
+      "예",
+      "객체",
+      "문자열",
+      "예",
       "대",
       "용량",
       "파일",

evalvault-1.68.0/docker-compose.offline.yml

@@ -0,0 +1,118 @@
+# EvalVault Offline Deployment - Docker Compose Configuration
+# Air-gapped environment: PostgreSQL + EvalVault API + Web UI
+#
+# Usage:
+#   docker compose -f docker-compose.offline.yml --env-file .env.offline.example config
+#   docker compose -f docker-compose.offline.yml --env-file .env.offline up -d
+#
+# Prerequisites:
+#   - External LLM server (Ollama/vLLM) must be accessible within the air-gapped network
+#   - Model weights are NOT shipped; configure OLLAMA_BASE_URL or VLLM_BASE_URL in .env.offline
+#
+# Architecture (linux/amd64 assumed for most air-gapped deployments):
+#   - postgres: Evaluation data storage
+#   - evalvault-api: FastAPI backend (port 8000 internal)
+#   - evalvault-web: Nginx reverse proxy + React frontend (port 5173 exposed on 127.0.0.1)
+
+services:
+  # PostgreSQL database for evaluation storage
+  postgres:
+    image: postgres:16-alpine
+    container_name: evalvault-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-evalvault}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-evalvault}
+      POSTGRES_DB: ${POSTGRES_DB:-evalvault}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-evalvault}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - evalvault-net
+
+  # EvalVault API service (FastAPI backend)
+  evalvault-api:
+    image: evalvault-api:offline
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: evalvault-api
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      # Profile selection (dev/prod/vllm - see config/models.yaml)
+      EVALVAULT_PROFILE: ${EVALVAULT_PROFILE:-dev}
+      # SQLite paths (for local file-based storage if needed)
+      EVALVAULT_DB_PATH: ${EVALVAULT_DB_PATH:-data/db/evalvault.db}
+      EVALVAULT_MEMORY_DB_PATH: ${EVALVAULT_MEMORY_DB_PATH:-data/db/evalvault_memory.db}
+      # PostgreSQL connection
+      EVALVAULT_DB_HOST: postgres
+      EVALVAULT_DB_PORT: 5432
+      EVALVAULT_DB_NAME: ${POSTGRES_DB:-evalvault}
+      EVALVAULT_DB_USER: ${POSTGRES_USER:-evalvault}
+      EVALVAULT_DB_PASSWORD: ${POSTGRES_PASSWORD:-evalvault}
+      # Ollama configuration (air-gapped LLM server - user must provide URL)
+      OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-}
+      OLLAMA_TIMEOUT: ${OLLAMA_TIMEOUT:-120}
+      OLLAMA_TOOL_MODELS: ${OLLAMA_TOOL_MODELS:-}
+      # vLLM configuration (alternative air-gapped LLM server - user must provide URL)
+      VLLM_BASE_URL: ${VLLM_BASE_URL:-}
+      VLLM_API_KEY: ${VLLM_API_KEY:-}
+      VLLM_MODEL: ${VLLM_MODEL:-}
+      VLLM_EMBEDDING_MODEL: ${VLLM_EMBEDDING_MODEL:-}
+      VLLM_EMBEDDING_BASE_URL: ${VLLM_EMBEDDING_BASE_URL:-}
+      # Faithfulness fallback (optional)
+      FAITHFULNESS_FALLBACK_PROVIDER: ${FAITHFULNESS_FALLBACK_PROVIDER:-}
+      FAITHFULNESS_FALLBACK_MODEL: ${FAITHFULNESS_FALLBACK_MODEL:-}
+      # API authentication (optional)
+      API_AUTH_TOKENS: ${API_AUTH_TOKENS:-}
+      KNOWLEDGE_READ_TOKENS: ${KNOWLEDGE_READ_TOKENS:-}
+      KNOWLEDGE_WRITE_TOKENS: ${KNOWLEDGE_WRITE_TOKENS:-}
+      CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:5173,http://127.0.0.1:5173}
+    volumes:
+      - ./data:/app/data
+      - ./config:/app/config:ro
+    # Override entrypoint to run API server
+    command: ["serve-api", "--host", "0.0.0.0", "--port", "8000"]
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      start_period: 10s
+      retries: 3
+    networks:
+      - evalvault-net
+
+  # EvalVault Web UI (Nginx reverse proxy + React frontend)
+  # Nginx proxies /api/ to evalvault-api:8000
+  evalvault-web:
+    image: evalvault-web:offline
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    container_name: evalvault-web
+    restart: unless-stopped
+    depends_on:
+      evalvault-api:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:5173:80"
+    environment:
+      # API backend URL for nginx proxy_pass (used by nginx config)
+      API_BACKEND_URL: http://evalvault-api:8000
+    networks:
+      - evalvault-net
+
+volumes:
+  postgres_data:
+    driver: local
+
+networks:
+  evalvault-net:
+    driver: bridge

{evalvault-1.67.0 → evalvault-1.68.0}/docs/INDEX.md

@@ -16,6 +16,7 @@
 - CLI 실행 시나리오 가이드: `guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
 - 사용자 가이드(운영 포함): `guides/USER_GUIDE.md`
 - 개발/기여: `guides/DEV_GUIDE.md`
+- 폐쇄망 Docker: `guides/OFFLINE_DOCKER.md`
 - 진단 플레이북: `guides/EVALVAULT_DIAGNOSTIC_PLAYBOOK.md` (문제→분석→해석→액션 흐름)
 - RAG 성능 개선 제안서: `guides/RAG_PERFORMANCE_IMPROVEMENT_PROPOSAL.md` (목적/미션·KPI·로드맵)
 - RAGAS 인간 피드백 보정: `guides/RAGAS_HUMAN_FEEDBACK_CALIBRATION_GUIDE.md`

evalvault-1.68.0/docs/guides/OFFLINE_DOCKER.md

@@ -0,0 +1,158 @@
+# 폐쇄망(에어갭) Docker 배포 가이드
+
+EvalVault를 외부망 없이 운영하기 위한 **오프라인 Docker 패키지** 구성 가이드입니다.
+모델 가중치는 폐쇄망 내부에 이미 존재한다는 전제로, EvalVault는 **외부 모델 서버**를 호출합니다.
+
+## 목표 구성
+
+- EvalVault API + Web UI를 docker-compose로 실행
+- 모델 서버(vLLM/Ollama)는 **외부 엔드포인트**로 연결
+- 필요 시 Postgres는 compose 프로필로 선택
+
+## 핵심 파일
+
+- `docker-compose.offline.yml`: 오프라인용 compose
+- `.env.offline.example`: 환경 변수 템플릿
+- `frontend/Dockerfile`: Web UI 정적 서빙 이미지
+- `frontend/nginx.conf`: `/api/*` 프록시 + SPA 라우팅
+- `scripts/offline/*.sh`: 이미지 export/import/smoke-test
+
+## 1) 환경 파일 준비
+
+```bash
+cp .env.offline.example .env.offline
+```
+
+`.env.offline`에 아래 항목을 **직접 입력**하세요.
+
+- `EVALVAULT_PROFILE` (dev/prod/vllm)
+- `OLLAMA_BASE_URL` 또는 `VLLM_BASE_URL`
+- `CORS_ORIGINS` (기본: http://localhost:8080)
+
+### 폐쇄망 사용자에게 전달할 필수 정보
+
+아래 내용을 그대로 전달하면 됩니다.
+
+**필수 입력값**
+- `EVALVAULT_PROFILE`: `dev`(Ollama) / `openai` / `vllm` 중 선택
+- `OLLAMA_BASE_URL` 또는 `OPENAI_API_KEY` 또는 `VLLM_BASE_URL` 중 하나 이상
+- `CORS_ORIGINS`: 기본 `http://localhost:8080`
+
+**포트 안내**
+- API: `http://<HOST>:8000`
+- Web UI: `http://<HOST>:8080`
+
+**실행 명령**
+```bash
+cp .env.offline.example .env.offline
+# .env.offline 편집 후
+docker compose --env-file .env.offline -f docker-compose.offline.yml up -d
+```
+
+**검증 명령**
+```bash
+curl -f http://<HOST>:8000/health
+curl -f http://<HOST>:8000/api/v1/config/profiles
+curl -f http://<HOST>:8000/api/v1/runs/options/datasets
+curl -I http://<HOST>:8080/
+```
+
+**참고**
+- 모델 서버는 폐쇄망 내부에 이미 존재한다고 가정합니다.
+- vLLM은 폐쇄망에서 사용할 수 있으며, 로컬(macOS)에서는 테스트하지 않았습니다.
+
+### vLLM 사용자 안내
+
+폐쇄망에서 vLLM을 사용할 경우 다음을 설정합니다.
+
+**필수 설정**
+- `EVALVAULT_PROFILE=vllm`
+- `VLLM_BASE_URL=http://<VLLM_HOST>:8000/v1`
+
+**선택 설정**
+- `VLLM_API_KEY`: vLLM 서버가 인증을 요구할 때만 사용
+- `VLLM_MODEL`: 서버 기본 모델과 다를 때 지정
+- `VLLM_EMBEDDING_MODEL`, `VLLM_EMBEDDING_BASE_URL`: 임베딩 서버를 분리 운용할 때 지정
+
+**검증 명령**
+```bash
+curl -f http://<HOST>:8000/api/v1/config/profiles
+```
+
+`vllm` 프로필이 보이고, `VLLM_BASE_URL`이 실제 vLLM 서버를 가리키면 정상입니다.
+
+## 2) 온라인 빌드/패키징
+
+스크립트를 실행하기 전 권한을 부여하세요.
+
+```bash
+chmod +x scripts/offline/*.sh
+```
+
+```bash
+./scripts/offline/export_images.sh
+```
+
+- 산출물: `dist/evalvault_offline.tar`
+- 체크섬: `dist/evalvault_offline.tar.sha256`
+
+Postgres 이미지를 함께 포함하려면:
+
+```bash
+INCLUDE_POSTGRES=1 ./scripts/offline/export_images.sh
+```
+
+## 3) 폐쇄망 반입 및 로드
+
+```bash
+./scripts/offline/import_images.sh dist/evalvault_offline.tar
+```
+
+## 4) 오프라인 실행
+
+```bash
+docker compose --env-file .env.offline -f docker-compose.offline.yml up -d
+```
+
+- API: `http://localhost:8000`
+- Web UI: `http://localhost:8080`
+
+Postgres를 함께 띄우려면:
+
+```bash
+docker compose --env-file .env.offline -f docker-compose.offline.yml --profile postgres up -d
+```
+
+## 5) 간단 스모크 테스트
+
+```bash
+./scripts/offline/smoke_test.sh
+```
+
+스모크 테스트가 실패하면 다음을 확인하세요.
+- Docker Desktop 실행 상태
+- `.env.offline`의 모델 서버 주소
+- 포트 충돌 여부 (8000/8080)
+
+## 데이터 포함 정책
+
+`data/`는 이미지에 포함됩니다.
+단, `/app/data`를 볼륨으로 마운트하면 **이미지에 포함된 데이터가 가려집니다**.
+필요 시 아래처럼 선택적으로 마운트하세요.
+
+```yaml
+# docker-compose.override.yml 예시
+services:
+  evalvault-api:
+    volumes:
+      - evalvault_data:/app/data
+
+volumes:
+  evalvault_data:
+```
+
+## 참고 문서 (공식 Docker)
+
+- Docker image save: https://docs.docker.com/reference/cli/docker/image/save/
+- Docker image load: https://docs.docker.com/reference/cli/docker/image/load/
+- Docker compose pull: https://docs.docker.com/reference/cli/docker/compose/pull/

{evalvault-1.67.0 → evalvault-1.68.0}/docs/guides/USER_GUIDE.md

@@ -497,6 +497,12 @@ JSON 예시는 아래와 같습니다.
 CSV/Excel의 경우 `id,question,answer,contexts,ground_truth` 컬럼을 포함하고,
 선택적으로 `threshold_*` 컬럼을 넣을 수 있습니다. `threshold_*` 값은 **첫 번째로 채워진 행 기준**으로
 데이터셋 전체 임계값으로 사용됩니다. `contexts`는 JSON 배열 문자열 또는 `|` 로 구분합니다.
+
+요약 메트릭용 선택 컬럼:
+- `summary_tags`: 콤마/파이프 구분 또는 JSON 배열 문자열
+- `summary_intent`: 예) `agent_notes`
+- `metadata`: JSON 객체 문자열 (예: `{ "priority": "high" }`)
+
 대용량 파일은 `--stream` 옵션으로 스트리밍 평가를 활성화하세요.
 
 #### 데이터셋 템플릿

{evalvault-1.67.0 → evalvault-1.68.0}/docs/new_whitepaper/03_data_flow.md

@@ -92,6 +92,20 @@ uv run evalvault analyze-compare <RUN_A> <RUN_B> --db data/db/evalvault.db
 
 > Stage 이벤트는 `--stage-events`(JSONL로 내보내기), `--stage-store`(DB 저장) 같은 옵션과 연결된다.
 
+최소 스키마(필수):
+- `run_id` (string)
+- `stage_type` (string, 소문자 정규화)
+
+권장 필드:
+- `stage_id`, `parent_stage_id`
+- `status` (예: success/failed)
+- `started_at`, `finished_at`, `duration_ms`
+- `attributes`, `metadata`
+- `trace_id`, `span_id`
+
+표준 stage_type 최소 집합:
+- `system_prompt`, `input`, `retrieval`, `output`
+
 ### 3.4 자동 분석(`--auto-analyze`)
 
 CLI 구현 흐름(요약):

{evalvault-1.67.0 → evalvault-1.68.0}/docs/new_whitepaper/12_operations.md

@@ -94,6 +94,15 @@ docker compose -f docker-compose.phoenix.yaml up
   - 옵션: `--stage-events <path>`
   - 근거: `src/evalvault/adapters/inbound/cli/commands/run.py`
 
+최소 스키마(필수):
+- `run_id` (string)
+- `stage_type` (string, 소문자 정규화)
+
+표준 stage_type 최소 집합:
+- `system_prompt`, `input`, `retrieval`, `output`
+
+필드가 누락되면 `stage summary`에서 `missing_required_stage_types`로 표시된다.
+
 ### 3.2 Stage Metrics(단계 지표)
 
 - `StageMetricService.build_metrics(...)`가 stage 이벤트에서

evalvault-1.68.0/frontend/Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-alpine AS build
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . ./
+RUN npm run build
+
+FROM nginx:1.27-alpine
+
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]

evalvault-1.68.0/frontend/nginx.conf

@@ -0,0 +1,20 @@
+server {
+  listen 80;
+  server_name _;
+
+  root /usr/share/nginx/html;
+  index index.html;
+
+  location /api/ {
+    proxy_pass http://evalvault-api:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

{evalvault-1.67.0 → evalvault-1.68.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "evalvault"
-version = "1.67.0"
+version = "1.68.0"
 description = "RAG evaluation system using Ragas with Phoenix/Langfuse tracing"
 readme = "README.md"
 requires-python = ">=3.12"