Vero는 실제 환경의 엄격함으로 AI 파이프라인을 평가하고 모니터링할 수 있는 오픈 플랫폼입니다.

이는 표준 벤치마킹을 넘어, 사용자의 비즈니스 사용 사례를 이해하여 **사용자 페르소나(user personas)**와 **스트레스 테스트(stress-test)**를 생성함으로써 에이전트(Agent)를 까다로운 시나리오에 걸쳐 평가하고, 위험 요소를 식별하며 고도로 신뢰할 수 있는 AI 시스템을 구축하는 데 도움을 줍니다.

대부분의 평가 도구는

• 생성 지표(Generation Metrics) — 답변의 의미적/사실적 품질을 측정합니다.

• 순위 지정 지표(Ranking Metrics) — 재순위 지정기(rerankers)의 순위 지정 품질을 측정합니다.

• 검색 지표(Retrieval Metrics) — 검색된 컨텍스트의 품질과 충분성을 측정합니다.

• Evaluator는 모델 출력 및 검색 결과를 대상으로 여러 지표를 실행하기 위한 편의 래퍼(convenience wrapper)입니다.

• 이는 생성 평가(text-generation metrics), 검색 평가(precision/recall/sufficiency), 그리고 재순위 지정기 평가(NDCG, MAP, MRR)를 오케스트레이션합니다. 기본적으로 CSV 요약본을 생성합니다.

빠른 참고 사항 (Quick notes)

• Evaluator는 프로젝트 지표 클래스(예: BartScore, BertScore, RougeScore, SemScore, PrecisionScore, RecallScore, MeanAP, MeanRR, RerankerNDCG, CumulativeNDCG 등)를 사용합니다. 이 지표들은 vero.metrics에 있으며 내부적으로 참조됩니다.
• 많은 방법들이 특정 CSV 열 이름(Expected CSV schemas 참고)을 예상합니다.
• GPU 버전의 torch 라이브러리 설치를 강력히 권장합니다.

1단계 - 생성 평가 (Generation evaluation)

• 입력: 'Context Retrieved'와 'Answer' 열이 포함된 CSV 파일입니다.
• 결과: SemScore, BertScore, RougeLScore, BARTScore, BLUERTScore, G-Eval(Faithfulness) 등의 열을 가진 Generation_Scores.csv가 생성됩니다.

예시:

from vero.evaluator import Evaluator
evaluator = Evaluator()
# data_path는 'Context Retrieved'와 'Answer' 열이 포함된 CSV를 가리켜야 합니다.
...

2단계 - 재순위 지정기 입력 준비 (ground truth + retriever 출력 파싱)

• parse_retriever_data를 사용하여 ground-truth 청크 ID와 검색기 출력을 재순위 지정기 평가에 적합한 ranked_chunks_data.csv로 변환합니다.

예시:

from vero.evaluator import Evaluator
evaluator = Evaluator()
# ground_truth_path: 'Chunk IDs'와 'Less Relevant Chunk IDs' 열이 있는 데이터셋입니다.
...

3단계 - 검색 평가 (precision, recall, sufficiency)

• 입력:

• retriever_data_path: 'Retrieved Chunk IDs'와 'True Chunk IDs' 열(리스트 또는 문자열)을 포함하는 CSV 파일입니다.

• data_path: 'Context Retrieved'와 'Question'이 있는 생성 CSV 파일입니다 (sufficiency용).

• Result: Retrieval_Scores.csv

Example:

from vero.evaluator import Evaluator
evaluator = Evaluator()
df_retrieval_scores = evaluator.evaluate_retrieval(...)

Step 4 - Reranker 평가 (MAP, MRR, NDCG)
Example:

from vero.evaluator.evaluator import Evaluator
evaluator = Evaluator()
df_reranker_scores = evaluator.evaluate_reranker(...)

단일 지표를 직접 실행하려면 해당 지표 클래스를 인스턴스화할 수 있습니다. 예를 들어, 쌍별로 BARTScore 또는 BertScore를 계산하려면:

from vero.metrics import BartScore, BertScore
with BartScore() as bs:
bart_results = [bs.evaluate(context, answer) for context, answer in zip(contexts, answers)]
...

• Test Dataset Generation 모듈은 문서 컬렉션으로부터 고품질의 질문-답변 쌍을 생성합니다. 이 모듈은 RAG 시스템에서 검색 및 추론 실패를 드러내고 엣지 케이스 사용자 페르소나까지 고려한 도전적인 질의(query)를 생성하며, 이를 통해 평가합니다.
• 내부적으로 문서를 청크(chunk)로 나누고, 관련 청크들을 클러스터링하며, LLM을 사용하여 Ground-truth 청크 ID와 메타데이터가 포함된 QA 항목을 생성합니다.

from vero.test_dataset_generator import generate_and_save
# ./data/pdfs 디렉토리에 저장된 PDF에서 100개의 질의를 생성하고 test_dataset 디렉토리에 결과를 저장합니다.
generate_and_save(...)

• Report Generation 모듈은 생성(generation), 검색(retrieval), 재순위화(reranking)로부터 얻은 평가 결과들을 종합하여 최종 보고서로 만듭니다.
• 다양한 평가기에서 나온 CSV 결과를 처리하고 포괄적인 통찰력과 권장 사항을 합성하는 상태 기반 워크플로우를 오케스트레이션합니다.

from vero.report_generation_workflow import ReportGenerator
# 보고서 생성기를 초기화합니다.
report_generator = ReportGenerator()
...

• Docker 및 Docker Compose 설치
• 디스크 공간 >= 50 GB
• CPU >= 4 코어 (더 빠른 지표 계산을 위해 GPU 권장)
• RAM >= 8 GB

Step 1 - 저장소를 클론하고 deploy 폴더로 이동합니다.

git clone https://github.com/vero-eval/vero-eval.git
cd vero-deploy

2단계 - 예시 입력값 검토

• vero-deploy 디렉터리 내의 data/inputs 폴더를 엽니다.
• 제공된 예시 CSV(data/inputs/input.csv 등)를 검토하고, 자신의 입력 CSV도 동일한 방식으로 구조화합니다. 프로젝트 전반에서 사용되는 일반적인 열 이름에는 Context Retrieved, Answer, Question, Retrieved Chunk IDs, True Chunk IDs, Chunk IDs, 그리고 Less Relevant Chunk IDs가 포함됩니다.

3단계 - 입력 파일명 설정

• vero-deploy 디렉터리에서 config.yaml을 열고, 입력 CSV 파일명을 참조하는 키를 확인합니다. 필요한 경우 이를 업데이트하여 자신의 CSV 파일을 가리키도록 합니다 (선택한 파일명이 data/inputs 내의 파일과 일치하는지 확인하십시오).

4단계 - Docker Compose에 OpenAI 키 설정

• docker-compose.yaml을 열고, 평가 서비스(evaluation service)를 위한 환경 변수 OPEN_AI_KEY를 설정합니다. 예시 코드 조각:

x-base-config: &base-config
image: crimsonceres/demo-test
environment:
...

• 또한 환경 변수 치환(예: OPEN_AI_KEY=${OPEN_AI_KEY})을 사용하고, Docker를 실행하기 전에 셸에서 해당 변수를 내보낼 수도 있습니다.

5단계 - 평가 컨테이너 실행

• GPU가 사용 가능한 경우 (권장):
  docker compose run evaluation-runner-gpu
• CPU만 사용하는 경우:
  docker compose run evaluation-runner-cpu

이것으로 컨테이너화된 평가를 실행하는 데 필요한 모든 과정이 완료되었습니다. data/inputs에 config.yaml에서 참조하는 CSV가 포함되어 있는지, 그리고 적절한 docker compose run 명령을 실행하기 전에 docker-compose.yaml에 OPEN_AI_KEY가 설정되었는지 확인하십시오.