DocAILab/XRAG

📣 업데이트 (Updates)
📖 서론 (Introduction)
✨ 특징 (Features)
🌐 WebUI 데모 (WebUI Demo)
🛠️ 설치 (Installation)
🚀 빠른 시작 (Quick Start)
⚙️ 설정 (Configuration)
⚠️ 문제 해결 (Troubleshooting)
📋 변경 이력 (Changelog)
💬 피드백 및 지원 (Feedback and Support)
📍 감사 (Acknowledgement)
📚 인용 (Citation)

2026-02.24: 논문이 ICDE 2026에 채택되었습니다.🎉🎉🎉🎉🎉
2025-11.18: 오케스트레이터 (orchestrators) 추가: SIM-rag.
2025-11.05: 오케스트레이터 (orchestrators) 추가: self-rag, adaptive-rag.
2025-07.18: SemanticSplitterNodeParser, SentenceSplitterNodeParser, SentenceWindowNodeParser를 포함한 텍스트 분할기 (Text Splitters) 추가.
2025-06.23: 설정 파일 (configuration file) 업데이트, 파라미터 (parameters)가 더 명확하게 표시됩니다.
2025-01.09: API 지원 추가. 이제 XRAG를 백엔드 서비스 (backend service)로 사용할 수 있습니다.
2025-01.06: ollama LLM 지원 추가.
2025-01.05: 생성 (generate) 명령 추가. 이제 문서를 포함하는 폴더로부터 직접 QA 쌍을 생성할 수 있습니다.
2024-12.23: XRAG 문서 (Documentation)가 출시되었습니다🌈.
2024-12.20: XRAG가 출시되었습니다🎉.

개발자, 연구자, 그리고 열정적인 분들이 XRAG 오픈 소스 프로젝트에 참여하는 것을 환영합니다!

의미론적 당혹도 (Semantic Perplexity (SePer)) -
엔트로피 (Entropy) & 의미론적 엔트로피 (Semantic Entropy) -
Auto-J -
Prometheus

PGE/GTE/M3E 임베딩 (embeddings) -
OpenAI API 또는 Ollama를 통한 30B 이상의 파라미터 모델 (30B/more-parameter models)

적응형 검색 (Adaptive Retrieval) -
다단계 접근 방식 (Multi-step Approach) -
Self-RAG -
FLARE -
Adaptive-RAG

후기 청킹 (Late Chunking)

🙌 여러분의 기여—코드, 데이터, 아이디어 또는 피드백—는 XRAG의 심장박동입니다!

저장소 (Repository): https://github.com/DocAILab/XRAG

XRAG는 고급 검색 증강 생성 (Retrieval-Augmented Generation (RAG)) 시스템의 기초 구성 요소를 평가하기 위해 설계된 벤치마킹 프레임워크 (benchmarking framework)입니다. 각 핵심 모듈을 해부하고 분석함으로써, XRAG는 서로 다른 구성 및 구성 요소가 RAG 시스템의 전반적인 성능에 어떻게 영향을 미치는지에 대한 통찰력을 제공합니다.

🔍 종합적인 평가 프레임워크 (Comprehensive Evaluation Framework):

다각적인 평가 차원: LLM 기반 평가 (LLM-based evaluation), 심층 평가 (Deep evaluation), 그리고 전통적인 지표 (traditional metrics)
검색 품질 (retrieval quality), 응답 충실도 (response faithfulness), 정답 정확도 (answer correctness) 평가 지원
LlamaIndex, DeepEval 및 사용자 정의 지표 (custom metrics)를 포함한 내장 평가 모델

⚙️ 유연한 아키텍처 (Flexible Architecture):

리트리버 (retrievers), 임베딩 (embeddings), LLM을 위한 플러그형 컴포넌트를 갖춘 모듈형 설계
다양한 검색 방법 지원: 벡터 (Vector), BM25, 하이브리드 (Hybrid), 트리 기반 (Tree-based)
사용자 정의 검색 및 평가 전략과의 용이한 통합

🤖 다양한 LLM 지원 (Multiple LLM Support):

OpenAI 모델과의 원활한 통합
로컬 모델 (Qwen, LLaMA 등) 지원
구성 가능한 모델 파라미터 및 API 설정

📊 풍부한 평가 지표 (Rich Evaluation Metrics):

전통적인 지표: F1, EM, MRR, Hit@K, MAP, NDCG
LLM 기반 지표: 충실도 (Faithfulness), 관련성 (Relevancy), 정확도 (Correctness)
심층 평가 지표: 문맥적 정밀도/재현율 (Contextual Precision/Recall), 환각 (Hallucination), 편향 (Bias)

🎯 고급 검색 방법 (Advanced Retrieval Methods):

BM25 기반 검색
벡터 기반 의미론적 검색 (semantic search)
트리 구조 검색 (Tree-structured retrieval)
키워드 기반 검색
문서 요약 검색 (Document summary retrieval)
사용자 정의 검색 전략

💻 사용자 친화적 인터페이스 (User-Friendly Interface):

풍부한 옵션을 제공하는 명령줄 인터페이스 (CLI)
대화형 평가를 위한 웹 UI (Web UI)
상세한 평가 보고서 및 시각화

오케스트레이터 (Orchestrators)는 RAG 구성 요소의 실행 로직과 워크플로우를 조직하고 관리하는 데 사용되며, 이를 통해 XRAG에서 에이전틱 RAG (agentic RAG) 방식을 구현합니다. 그림에서 설명된 바와 같이, XRAG 프레임워크는 순차적 (sequential), 조건부 (conditional), 반복적 (iterative), 병렬적 (parallel), 그리고 하이브리드 (hybrid)의 다섯 가지 유형의 오케스트레이터를 포함합니다.

XRAG는 대화형 평가 및 시각화를 위한 직관적인 웹 인터페이스를 제공합니다. 다음 명령어로 실행하세요:

xrag-cli webui

WebUI는 다음과 같은 워크플로우를 안내합니다:

데이터셋 업로드 및 구성:

벤치마크 데이터셋 (HotpotQA, DropQA, NaturalQA) 지원
사용자 정의 데이터셋 통합
자동 형식 변환 및 전처리

시스템 파라미터 (system parameters) 설정 및 인덱스 (indices) 구축:

API 키 설정
파라미터 (Parameter) 설정
벡터 데이터베이스 (Vector database) 인덱스 구축
청크 크기 (Chunk size) 최적화

RAG 파이프라인 (pipeline) 구성 요소 정의:

검색 전 (Pre-retrieval) 방법
리트리버 (Retriever) 선택
후처리 (Post-processor) 설정
사용자 정의 프롬프트 템플릿 (prompt template) 생성

RAG 시스템 대화형 테스트:

실시간 쿼리 (query) 테스트
검색 결과 (retrieval result) 검사
응답 생성 (response generation) 검토
성능 분석 (performance analysis)

XRAG를 설치하기 전에 Python 3.11 이상이 설치되어 있는지 확인하십시오.

# 새로운 conda 환경 생성
conda create -n xrag python=3.11
# 환경 활성화
...

pip를 사용하여 XRAG를 직접 설치할 수 있습니다:

# XRAG 설치
pip install examinationrag
# 충돌을 방지하기 위해 의존성 없이 'jury' 설치
...

XRAG를 시작하는 방법은 다음과 같습니다:

config.toml 파일을 수정하여 원하는 설정을 구성하십시오.

XRAG를 설치한 후에는 환경에서 xrag-cli 명령어를 사용할 수 있습니다. 이 명령어는 Python 스크립트를 직접 호출할 필요 없이 XRAG와 상호작용할 수 있는 편리한 방법을 제공합니다.

xrag-cli [command] [options]

run: 벤치마킹 (benchmarking) 프로세스를 실행합니다. xrag-cli run [--override key=value ...]

webui: 웹 기반 사용자 인터페이스 (user interface)를 실행합니다. xrag-cli webui

ver: XRAG의 현재 버전을 표시합니다. xrag-cli version

help: 도움말 정보를 표시합니다. xrag-cli help

generate: 폴더에서 QA 쌍을 생성합니다. xrag-cli generate -i <input_file> -o <output_file> -n <num_questions> -s <sentence_length>

api: XRAG 서비스를 위한 API 서버를 실행합니다. xrag-cli api [--host <host>] [--port <port>] [--json_path <json_path>] [--dataset_folder <dataset_folder>]

옵션 (Options):

--host: API 서버 호스트 주소 (기본값: 0.0.0.0)
--port: API 서버 포트 번호 (기본값: 8000)
--json_path: JSON 설정 파일 경로
--dataset_folder: 데이터셋 폴더 경로

API 서버가 실행되면 HTTP 요청을 사용하여 상호작용할 수 있습니다. 사용 가능한 엔드포인트(Endpoints)는 다음과 같습니다:

/query로 POST 요청을 보내어 문서를 기반으로 답변을 얻습니다:

curl -X POST "http://localhost:8000/query" \
-H "Content-Type: application/json" \
-d '{
...

응답 형식 (Response format):

{
"answer": "질문에 대해 생성된 답변",
"sources": [
...

/health로 GET 요청을 보내 API 서버 상태를 확인합니다:

curl "http://localhost:8000/health"

응답 형식 (Response format):

{
"status": "healthy",
"engine_status": "initialized"
...

API 서비스는 사용자 정의 JSON 데이터셋과 폴더 기반 문서 모두를 지원합니다:

JSON 형식의 QA 데이터셋에는 --json_path를 사용하세요.
문서 폴더에는 --dataset_folder를 사용하세요.
--json_path와 --dataset_folder를 동시에 설정하지 마세요.

--override 플래그 뒤에 키-값(key-value) 쌍을 사용하여 설정 값을 재정의(override)할 수 있습니다:

xrag-cli run --override embeddings="new-embedding-model"

xrag-cli generate -i <input_file> -o <output_file> -n <num_questions> -s <sentence_length>

폴더로부터 QA 쌍을 자동으로 생성합니다.

XRAG는 구성 관리(configuration management)를 위해 config.toml 파일을 사용합니다. 다음은 설정 옵션에 대한 자세한 설명입니다:

[api_keys]
api_key = "sk-xxxx" # LLM 서비스를 위한 API 키
api_base = "https://xxx" # API 기본 URL (base URL)
...

의존성 충돌 (Dependency Conflicts): 의존성 문제가 발생하는 경우, requirements.txt에 지정된 올바른 버전을 사용 중인지 확인하고 가상 환경(virtual environment) 사용을 고려하세요.
유효하지 않은 설정 키 (Invalid Configuration Keys): 재정의하는 키가 config.toml 파일의 키와 정확히 일치하는지 확인하세요.
데이터 타입 불일치 (Data Type Mismatches): 설정을 재정의할 때 값이 올바른 데이터 타입(예: 정수, 불리언)인지 확인하세요.
API 지원 추가. 이제 XRAG를 백엔드 서비스로 사용할 수 있습니다.
ollama LLM 지원 추가.
generate 명령 추가. 이제 문서를 포함하는 폴더로부터 직접 QA 쌍을 생성할 수 있습니다.
핵심 벤치마킹 (benchmarking) 기능이 포함된 초기 릴리스.
HotpotQA 데이터셋 지원.
명령줄 구성 (command-line configuration) 오버라이드.
xrag-cli 명령줄 도구 도입.

저희는 사용자들의 피드백을 소중히 여깁니다. 제안 사항, 기능 요청이 있거나 문제를 발견하신 경우:

이슈 생성 (Open an Issue): 저희 GitHub 저장소에 이슈를 제출해 주세요.
이메일 문의 (Email Us): luoyangyifei@buaa.edu.cn으로 연락해 주세요.
토론 참여 (Join the Discussion): 토론에 참여하여 귀하의 통찰을 공유해 주세요.

조직자: Qianren Mao, Yangyifei Luo (罗杨一飞), Qili Zhang (张启立), Yashuo Luo (罗亚硕), Zhilong Cao(曹之龙), Jinlong Zhang (张金龙), Hanwen Hao (郝瀚文), Zhenting Huang (黄振庭), Feng Yan(闫丰), Weifeng Jiang (蒋为峰).

이 프로젝트는 RAGLAB, FlashRAG, FastRAG, AutoRAG, LocalRAG에서 영감을 받았습니다.

저희 프로젝트의 개발과 기능 구현에 중추적인 역할을 한 다음의 외부 라이브러리들에 깊은 감사를 표합니다: LlamaIndex, Hugging Face Transformers.

이 작업이 도움이 되었다면, 저희 논문을 인용해 주세요:

@article{mao2025xragexaminingcore,
title={XRAG: eXamining the Core -- Benchmarking Foundational Components in Advanced Retrieval-Augmented Generation},
author={Qianren Mao and Yangyifei Luo and Qili Zhang and Yashuo Luo and Zhilong Cao and Jinlong Zhang and HanWen Hao and Zhijun Chen and Weifeng Jiang and Junnan Liu and Xiaolong Wang and Zhenting Huang and Zhixing Tan and Sun Jie and Bo Li and Xudong Liu and Richong Zhang and Jianxin Li},
...

XRAG를 사용해 주셔서 감사합니다! 이 도구가 검색 증강 생성 (Retrieval-Augmented Generation) 분야의 귀하의 연구 및 개발 노력에 가치 있는 도구가 되기를 바랍니다.

DocAILab/XRAG

요약

핵심 포인트

댓글