syy12335/rag-eval-scaffold

English | 中文说明

단 한 번의 명령으로 "데이터셋(dataset) → 벡터 저장소(vector store) → RAG 워크플로우(RAG workflow) → 평가(evaluation)"로 이어지는 전체 파이프라인을 실행하는 경량 RAG 평가 스캐폴드(scaffold)입니다. Streamlit 기반의 경량 시각화 콘솔을 제공하며, 통합된 invoke 인터페이스를 통해 분리된 벡터 저장소 관리 레이어(VectorManager), RAG 러너(Runner) 레이어, 그리고 평가(evaluation) 레이어를 노출합니다.

기본 예제에는 중국어 QA 데이터셋과 기본적인 RAG 워크플로우, 그리고 모델 서비스(기본값은 Qwen)를 위한 설정 예시가 포함되어 있습니다. 전체적인 설계는 특정 벤더에 종속되지 않으며, 설정을 통해 호환 가능한 모든 채팅 및 임베딩(embedding) 서비스를 플러그인 방식으로 연결할 수 있습니다.

RAG / LLM 엔지니어링 스캐폴드로서

실험이나 엔지니어링 요구사항이 있는 사용자들을 위해, 이 프로젝트는 통일된 프로토콜 하에 다음을 지원합니다:

벡터 저장소(vector stores) 구축 및 관리
통일된 구조를 출력하는 하나 이상의 RAG 워크플로우 오케스트레이션(orchestrate)
평가 엔진(evaluation engine)을 호출하여 서로 다른 워크플로우, 데이터셋 및 지표(metrics) 비교

RAG를 위한 0부터 1까지의 학습 프로젝트로서

엔드 투 엔드(end-to-end) 엔지니어링 경험이 부족한 사용자들을 위해, 이 프로젝트는 "데이터셋(dataset) → 벡터 저장소(vector store) → 검색(retrieval) → 생성(generation) → 평가(evaluation)"로 이어지는 전체 파이프라인을 이미 하나로 엮어 놓았습니다.

사용자는 서로 다른 컴포넌트의 문서를 끊임없이 오갈 필요 없이, 기본 구현에서 시작하여 점진적으로 모듈을 교체하거나 확장할 수 있습니다.

한 줄로 끝내는 벡터 저장소 구축 및 VectorManager 검색

통합된 진입점을 통해 단 한 줄로 다음을 수행할 수 있습니다:

설정에 따른 벤치마크(benchmark) 데이터셋 로드
벡터 저장소(vector store) 구축 또는 업데이트
검색, 문서 CRUD 및 리트리버(retriever) 구축을 위한 VectorManager 인스턴스 획득

설정은 데이터 경로, 청킹(chunking) 전략, 벡터 저장소 영속화(persistence) 경로 등을 포함하여 config/application.yaml에 중앙 집중식으로 관리됩니다.

데이터셋/벡터 레이어, RAG 레이어 및 평가 레이어의 완전한 디커플링(decoupling)

데이터셋/벡터 레이어는 오직 “samples → chunks → vector store” 과정만을 처리하며, 상위 계층에 VectorManager를 노출합니다.
RAG 레이어는 오직 “검색을 위해 VectorManager를 사용하는 방법과 워크플로우 형성을 위해 LLM을 호출하는 방법”에만 집중하며, Runner의 invoke를 통해 결과를 노출합니다.
평가 레이어는 Runner 프로토콜과 샘플 형식에만 의존하며, 하위의 벡터 스토어(vector store) 및 워크플로우 구현에는 무관(agnostic)하므로 데이터셋, 모델 및 파이프라인을 쉽게 교체할 수 있습니다.
통합된 invoke 프로토콜
- 벡터 스토어 관리 도구는 통합된 인터페이스를 통해 검색을 제공하며(예: VectorManager().invoke(query: str, k: int = 5) -> List[Document]), 오직 “주어진 쿼리에 대해 어떤 문서가 반환되는가”에만 집중합니다.
- 모든 Runner는 통합된 Runner().invoke(question: str) -> dict 인터페이스를 구현하며 합의된 구조(question, generation, contexts 등)를 반환합니다.
- 평가 엔진은 항상 EvalEngine().invoke(runner)를 통해 평가를 시작하며, 이는 내부적으로 배치 실행(batch execution) 및 구체적인 평가 방법을 처리합니다.
낮은 진입 장벽과 높은 확장성
기본 청킹(chunking) 로직과 워크플로우 구조가 가능한 한 단순하게 유지되므로, 초보자도 코드를 직접 읽고 수정할 수 있습니다:
- 초보자는 기본 청킹과 워크플로우에서 시작하여 프롬프트(prompt), 검색 전략을 미세 조정하거나 간단한 노드를 추가/제거할 수 있습니다.
- 숙련된 사용자는 기본 구현을 완전히 무시하고, VectorManager에서 리트리버(retriever)를 가져와 프로토콜을 준수하는 Runner를 구현한 뒤(invoke 시그니처와 출력 구조 유지), 이를 평가 레이어에 직접 연결하여 서로 다른 RAG 스킴(scheme)을 비교할 수 있습니다.
Python 버전
Python 3.10 이상을 권장합니다.
의존성 설치
프로젝트 루트에서:

pip install -r requirements.txt

모델 및 API 키 설정
설정 파일에서 모델 제공자(model provider)와 모델 이름(채팅 모델, 임베딩 모델 등)을 선택하거나 선언합니다.
시스템 환경 변수에 해당하는 API 키를 설정합니다. 예시는 다음과 같습니다:

Windows (현재 세션):

set API_KEY_XXX=your-api-key python quickstart.py

Linux 또는 macOS:

export API_KEY_XXX="your-api-key" python quickstart.py

정확한 환경 변수 이름과 설정 예시는 config/application.yaml 및 관련 문서에 정의되어 있습니다.

프로젝트 루트에서:

python quickstart.py

웹 프론트엔드(web frontend)를 사용하는 경우:

streamlit run streamlit_app.py

기본 흐름(default flow)은 다음을 포함합니다:

벤치마크 데이터셋 및 벡터 스토어(vector store) 구축
- 원시 데이터(raw data)로부터 평가 샘플(evaluation samples) 구축
- 설정에 따라 컨텍스트(context) 필드를 청크(chunk)로 분할하여 청크 생성
- 로컬 벡터 스토어를 구축 또는 업데이트하고 설정된 디렉토리에 영구 저장
평가 샘플 로드
- dataset.samples_path에서 정규화된 샘플을 로드
배치 RAG 모드에서 기본 러너(Runner) 실행
- 기본 러너는 내부적으로 컨텍스트 검색을 위해 VectorManager를 사용하고, 답변 생성을 위해 설정된 모델을 사용하며, 약속된 스키마(schema)에 따라 question, generation, contexts와 같은 필드를 출력합니다.
평가 엔진 실행
- 러너의 출력을 표준 레코드 구조로 정규화
- RAGAS 및 기타 평가 방법을 사용하여 전체 및 샘플별 지표(metrics) 계산
- 결과를 콘솔에 출력하고, 설정에 따라 선택적으로 CSV 파일로 내보내기

의존성, 설정 및 API 키가 올바르게 설정되면, 이 단일 명령으로 데이터부터 평가 보고서까지의 전체 루프를 실행할 수 있습니다.

이 섹션은 개념과 인터페이스 계약(interface contracts)에 초점을 맞춥니다. 구체적인 사용법은 저장소의 예제 스크립트를 참조하세요.

전형적인 흐름:

통합 엔트리(unified entry)인 VectorDatabaseBuilder().invoke()를 사용하여 벡터 스토어를 구축하고 VectorManager를 획득합니다 (관례에 따라 내부적으로 config/application.yaml에서 설정을 로드함).
VectorManager의 메서드를 사용하여:
특정 조건 하에 새로운 문서 추가 (add_documents(...)); - 컬렉션 삭제 또는 재구축 (delete_collection(...)); - 리트리버 (Retriever) 획득 또는 문서 리스트 직접 검색 (get_retriever(...) 또는 invoke(...)); - QA 또는 기타 분석을 수행하기 위해 사용자의 모델과 결합.
특정 조건 하에 새로운 문서 추가.

VectorManager는 하위 벡터 스토어 (Vector-store)의 구현 세부 사항을 숨기므로, RAG 워크플로우는 통합된 검색 인터페이스에만 의존합니다.

예시:

from rag_eval import VectorDatabaseBuilder
# 설정에 따라 벡터 스토어를 구축하고 매니저(VectorManager)를 가져옴
vector_manager = VectorDatabaseBuilder().invoke()
...

사용자 정의 데이터셋을 사용하려면 rag_eval/dataset_tools/__init__.py를 참조하십시오.

Runner 프로토콜 (단순화됨):

class MyRunner:
def __init__(self, vector_manager, ...):
self.vector_manager = vector_manager
...

평가 레이어 (Evaluation layer)는 invoke의 입출력 프로토콜에만 의존하므로 다음과 같습니다:

반환된 구조가 계약 (Contract)과 일치하는 한 평가가 가능합니다.
모델 선택, 프롬프트 구성, 다단계 워크플로우 (Multi-step workflows) 사용 여부는 모두 평가 레이어에 투명하게 처리됩니다 (Opaque).

전형적인 진입점 (단순화됨):

from rag_eval import EvalEngine
runner = MyRunner(...)
eval_result = EvalEngine().invoke(runner)
...

내부적으로 EvalEngine은 다음을 수행합니다:

평가 샘플 로드 (설정에 따라 샘플 제한 등을 선택적으로 제어 가능);
Runner의 invoke를 배치 (Batch)로 호출;
RAGAS 및 기타 메트릭 (Metrics) 호출;
전역 및 샘플별 메트릭을 집계하고 콘솔 및 프론트엔드 디스플레이 헬퍼를 제공.

디버깅 또는 데모를 위해 그래픽 인터페이스를 사용하려면:

프로젝트 루트에서:

streamlit run streamlit_app.py

프론트엔드는 일반적으로 두 가지 모드를 제공합니다:
평가 모드 (Evaluation mode)
현재 설정 하에서 평가 흐름을 실행하고 전역 지표 (global metrics) 및 샘플별 점수 (per-sample scores)를 보여줍니다.
샘플 수를 선택하고 평가를 트리거할 수 있으며, 페이지에 진행 상황과 예상 시간이 표시됩니다.
단일 샘플의 질문 (question), 정답 (ground_truth), 생성 결과 (generation), 그리고 컨텍스트 (contexts)를 검사하는 기능을 지원합니다.
채팅 모드 (Chat mode)
대화형 RAG QA를 위해 현재의 Runner 설정을 재사용합니다.
정량적 평가 결과와 함께 검색 (retrieval) 및 답변 품질을 정성적으로 검사하는 데 도움을 줍니다.
평가 모드 (Evaluation mode)

프론트엔드는 기저의 인터페이스 계약 (interface contracts)을 변경하지 않습니다. 단순히 기존의 Runner, 평가 엔진 (evaluation engine), 그리고 결과들을 사용하기 쉬운 제어 패널로 감싸는 역할을 합니다.

실제 레이아웃은 버전에 따라 진화할 수 있으므로, 항상 최신 구조는 리포지토리를 참조하십시오. 전형적인 레이아웃은 다음과 같습니다:

config/
application.yaml # 전역 설정: 데이터셋 (datasets), 벡터 스토어 (vector store), 모델 (models), 평가 (evaluation) 등.
agents.yaml # 모델 역할 (model roles), 프롬프트 (prompts), 에이전트 설정 (agent configs) 등.
...

주요 설정은 config/application.yaml에 위치하며, 일반적으로 다음을 포함합니다:

데이터셋 경로 및 샘플 크기 제한;
벡터 스토어 (Vector-store) 백엔드 설정 (지속성 디렉토리, 컬렉션 이름, 임베딩 모델 등);
검색 파라미터 (예: top_k);
모델 및 API 설정;
평가 출력 경로 및 평가 파라미터.

현재 버전에서 이미 제공하는 기능:

데이터셋/벡터 레이어, RAG 레이어, 그리고 평가 레이어의 완전한 디커플링 (decoupling);
한 줄 명령어로 가능한 벡터 스토어 구축 및 VectorManager 기반의 관리;
Runner와 평가 엔진이 공유하는 통합된 invoke 프로토콜;
한 번의 명령으로 실행 가능한 엔드 투 엔드 (end-to-end) 실행, 고급 커스터마이징 진입점, 그리고 개선된 프론트엔드 진행 상황 피드백;
디버깅 및 데모를 위한 Streamlit 콘솔.

계획된 확장 기능:

추가적인 벤치마크 데이터셋 및 예시 Runner;
더 많은 평가 지표 (evaluation metrics) 및 평가를 위한 더 풍부한 설정;
다양한 모델 서비스를 위한 더 완전한 설정 템플릿 및 예시.

만약 end-to-end RAG-plus-evaluation (RAG 및 평가 통합) 파이프라인을 빠르게 실행하기만을 원한다면, quickstart.py부터 시작하세요.

만약 엔지니어링 (engineering) 및 확장성 (extensibility)에 더 관심이 있다면, VectorManager, Runner 프로토콜 (Runner protocol), 그리고 Streamlit 프론트엔드 (frontend)부터 시작하여 점진적으로 모듈을 교체하거나 확장해 나가세요.

syy12335/rag-eval-scaffold

요약

핵심 포인트

댓글