UltraRAG 완전 튜토리얼: 로우코드 프레임워크로 고급 RAG 시스템 구축하기
⏱️ 예상 읽기 시간: 15분
UltraRAG 소개
UltraRAG 2.0은 OpenBMB에서 개발한 혁신적인 MCP(Model Context Protocol) 기반 로우코드 RAG 프레임워크입니다. “적은 코드, 낮은 진입장벽, 빠른 배포”라는 모토로, 연구자와 개발자가 최소한의 코딩 노력으로 복잡한 RAG 파이프라인을 구축할 수 있게 해줍니다.
주요 특징
- 로우코드 프레임워크: YAML 설정 파일로 정교한 RAG 시스템 구축
- MCP 통합: Model Context Protocol을 활용한 원활한 모델 통신
- 광범위한 데이터셋 지원: 17개 이상의 인기 평가 데이터셋 내장 지원
- 다양한 기준선 방법: 최신 RAG 접근법들의 사전 구현
- Docker 지원: 쉬운 배포와 컨테이너화된 환경
- 모듈러 아키텍처: 사용자 정의를 위한 유연한 파이프라인 구성요소
지원되는 기준선 방법
UltraRAG는 사전 구현된 고급 RAG 방법들을 제공합니다:
- Vanilla RAG: 기본 검색 증강 생성
- IRCoT: 검색과 사고 연쇄의 인터리빙
- IterRetGen: 반복적 검색 및 생성
- RankCoT: 순위 기반 사고 연쇄
- R1-searcher: 고급 검색 방법론
- Search-o1: 최적화된 검색 알고리즘
- Search-r1: 개선된 검색 접근법
- WebNote: 웹 기반 노트 작성 통합
사전 요구사항
시작하기 전에 시스템이 다음 요구사항을 충족하는지 확인하세요:
# 시스템 요구사항
- Python 3.9+
- CUDA 지원 (선택사항, GPU 가속용)
- Docker (선택사항, 컨테이너화 배포용)
- 저장소 복제를 위한 Git
설치 가이드
방법 1: UV 패키지 매니저 사용 (권장)
UltraRAG는 더 빠른 의존성 해결과 설치를 위해 최신 uv 패키지 매니저를 사용합니다.
1단계: UV 패키지 매니저 설치
# uv가 설치되지 않은 경우 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
# 셸을 새로고침하거나 실행:
source ~/.bashrc # zsh 사용자는 ~/.zshrc
2단계: 저장소 복제
# UltraRAG 저장소 복제
git clone https://github.com/OpenBMB/UltraRAG.git
cd UltraRAG
3단계: 의존성 설치
필요에 가장 적합한 설치 옵션을 선택하세요:
# 기본 설치 (최소 의존성)
uv pip install -e .
# LLM 호스팅 지원 (vLLM 포함)
uv pip install -e ".[vllm]"
# 문서 파싱 기능
uv pip install -e ".[corpus]"
# 완전 설치 (FAISS 제외한 모든 기능)
uv pip install -e ".[all]"
4단계: 설치 확인
# 설치 테스트
ultrarag run examples/sayhello.yaml
예상 출력:
Hello, UltraRAG 2.0!
고급 RAG 프레임워크에 오신 것을 환영합니다!
방법 2: Docker 설치
컨테이너화된 배포와 더 쉬운 환경 관리를 위해:
1단계: Docker 이미지 빌드
# UltraRAG 디렉터리 복제 및 이동
git clone https://github.com/OpenBMB/UltraRAG.git
cd UltraRAG
# Docker 이미지 빌드
docker build -t ultrarag:v2.0.0-beta .
2단계: 인터랙티브 컨테이너 실행
# GPU 지원과 함께 인터랙티브 Docker 컨테이너 시작
docker run -it --rm --gpus all ultrarag:v2.0.0-beta bash
# 컨테이너 내에서 설치 확인
ultrarag run examples/sayhello.yaml
기본 사용법: 첫 번째 RAG 파이프라인
UltraRAG 워크플로우 이해
UltraRAG는 간단한 3단계 프로세스를 따릅니다:
- 파이프라인 컴파일: YAML에서 매개변수 설정 생성
- 매개변수 수정: 필요에 따라 설정 사용자 정의
- 파이프라인 실행: 구성된 RAG 시스템 실행
예제 1: 기본 Vanilla RAG
간단한 vanilla RAG 구현으로 시작해보겠습니다:
1단계: 설정 검토
# 기본 RAG 예제 보기
cat examples/rag.yaml
2단계: 파이프라인 컴파일
# 설정 매개변수 생성
ultrarag compile examples/rag.yaml
이는 모든 구성 가능한 매개변수가 포함된 rag_params.yaml 파일을 생성합니다.
3단계: 매개변수 사용자 정의 (선택사항)
# 생성된 매개변수 파일 편집
nano rag_params.yaml
# 사용자 정의할 주요 매개변수:
# - model_name: 사용할 LLM 모델
# - retriever_name: 검색용 임베딩 모델
# - corpus_path: 문서 코퍼스 경로
# - dataset_path: 평가 데이터셋 위치
4단계: 파이프라인 실행
# RAG 파이프라인 실행
ultrarag run examples/rag.yaml
예제 2: 사고 연쇄를 사용한 고급 RAG
IRCoT(검색과 사고 연쇄의 인터리빙)를 사용하여 더 정교한 RAG 시스템을 구현해보겠습니다:
# IRCoT 파이프라인 컴파일
ultrarag compile examples/IRCoT.yaml
# IRCoT RAG 시스템 실행
ultrarag run examples/IRCoT.yaml
데이터셋과 코퍼스 작업
지원되는 평가 데이터셋
UltraRAG는 17개의 인기 데이터셋에 대한 내장 지원을 제공합니다:
| 데이터셋 유형 | 데이터셋 이름 | 원본 크기 | 평가 샘플 |
|---|---|---|---|
| QA | Natural Questions (NQ) | 3,610 | 1,000 |
| QA | TriviaQA | 11,313 | 1,000 |
| QA | PopQA | 14,267 | 1,000 |
| Multi-hop QA | HotpotQA | 7,405 | 1,000 |
| Multi-hop QA | 2WikiMultiHopQA | 12,576 | 1,000 |
| Multiple-choice | ARC | 3,548 | 1,000 |
| Multiple-choice | MMLU | 14,042 | 1,000 |
| Long-form QA | ASQA | 948 | 948 |
| Fact-verification | FEVER | 13,332 | 1,000 |
사용자 정의 데이터셋 사용
자신만의 데이터셋을 사용하려면 UltraRAG 데이터 형식을 따르세요:
{
"id": "고유_질문_아이디",
"question": "질문 텍스트",
"answers": ["답변1", "답변2"],
"context": "선택적_문맥_정보"
}
문서 코퍼스 설정
옵션 1: 사전 구축된 코퍼스 사용
# wiki-2018 코퍼스 다운로드 (2100만+ 문서)
# 문서의 데이터셋 다운로드 지침을 따르세요
옵션 2: 사용자 정의 코퍼스 생성
# 문서 코퍼스 디렉터리 생성
mkdir -p data/my_corpus
# 문서 추가 (텍스트 파일)
# UltraRAG는 다양한 형식 지원: .txt, .pdf, .docx
cp your_documents/* data/my_corpus/
검색기와 LLM 배포
검색기 서버 설정
UltraRAG는 코퍼스 인덱싱과 검색을 위한 검색 서비스를 배포할 수 있습니다:
# 검색기 서버 시작
ultrarag serve retriever \
--model_name BAAI/bge-m3 \
--corpus_path data/wiki-2018 \
--port 8001
LLM 서비스 배포
vLLM 백엔드를 사용하여 언어 모델 배포:
# OpenAI 호환 LLM 서버 배포
ultrarag serve llm \
--model_name Qwen/Qwen2.5-72B-Instruct \
--port 8000 \
--gpu_memory_utilization 0.8
외부 API 서비스 사용
외부 API를 사용하도록 UltraRAG 구성:
# 파이프라인 설정에서
llm:
provider: "openai"
api_key: "your_api_key"
model: "gpt-4"
base_url: "https://api.openai.com/v1"
retriever:
provider: "custom"
endpoint: "http://your-retriever-service:8001"
고급 설정 예제
예제 3: IterRetGen을 사용한 다단계 추론
# examples/advanced_iterretgen.yaml
pipeline:
name: "iterative_retrieval_generation"
components:
- retriever:
model: "BAAI/bge-m3"
top_k: 10
iterations: 3
- llm:
model: "Qwen/Qwen2.5-72B-Instruct"
temperature: 0.1
max_tokens: 1024
- reasoning:
strategy: "iterative"
max_iterations: 5
convergence_threshold: 0.95
evaluation:
dataset: "hotpotqa"
metrics: ["exact_match", "f1_score", "retrieval_precision"]
예제 4: 사용자 정의 검색 전략
# examples/custom_search.yaml
pipeline:
name: "custom_search_rag"
components:
- search:
strategy: "search-o1"
search_depth: 3
query_expansion: true
rerank_threshold: 0.7
- retriever:
model: "sentence-transformers/all-MiniLM-L6-v2"
chunk_size: 512
chunk_overlap: 50
- generator:
model: "microsoft/DialoGPT-large"
response_length: "medium"
성능 최적화
GPU 가속 설정
# CUDA 가용성 확인
python -c "import torch; print(f'CUDA 사용 가능: {torch.cuda.is_available()}')"
# 파이프라인에서 GPU 설정 구성
gpu_config:
enabled: true
device_map: "auto"
memory_fraction: 0.8
mixed_precision: true
메모리 최적화
# 파이프라인 설정에서
optimization:
batch_size: 8
gradient_checkpointing: true
cpu_offload: true
memory_efficient_attention: true
디버깅 및 문제 해결
일반적인 문제와 해결책
문제 1: CUDA 메모리 부족
# 해결책: 배치 크기 줄이기 또는 CPU 오프로드 사용
# 설정에서:
optimization:
batch_size: 2
cpu_offload: true
문제 2: 느린 검색 성능
# 해결책: 근사 검색 사용 또는 코퍼스 크기 줄이기
retriever:
search_type: "approximate"
index_type: "faiss"
nprobe: 10
문제 3: 모델 로딩 오류
# 해결책: 모델 가용성과 권한 확인
# 모델 다운로드 확인:
huggingface-cli download Qwen/Qwen2.5-7B-Instruct
디버그 모드
문제 해결을 위한 상세 로깅 활성화:
# 디버그 출력과 함께 실행
ultrarag run examples/rag.yaml --debug --verbose
# 로그 확인
tail -f logs/ultrarag.log
다른 도구와의 통합
Jupyter Notebook 통합
# Jupyter 노트북에서
import ultrarag
# 파이프라인 로드 및 실행
pipeline = ultrarag.load_pipeline("examples/rag.yaml")
results = pipeline.run(question="머신러닝이란 무엇인가요?")
print(results)
API 통합
# RESTful API 사용
import requests
response = requests.post(
"http://localhost:8000/v1/chat/completions",
json={
"model": "ultrarag",
"messages": [{"role": "user", "content": "양자 컴퓨팅을 설명해주세요"}],
"rag_enabled": True
}
)
모범 사례
1. 설정 관리
- 파이프라인 설정에 버전 관리 사용
- 개발과 프로덕션용 별도 설정 유지
- 사용자 정의 매개변수와 그 효과 문서화
2. 데이터 준비
- 일관된 문서 형식 보장
- 적절한 텍스트 전처리 구현
- 도메인에 적합한 청크 크기 사용
3. 평가 전략
- 최적화 전 기준선 메트릭 설정
- 다중 평가 데이터셋 사용
- 설정 변경에 대한 A/B 테스트 구현
4. 리소스 관리
- GPU 메모리 사용량 모니터링
- 적절한 캐싱 전략 구현
- 대규모 평가를 위한 배치 처리 사용
프로덕션 배포
Docker Compose 설정
# docker-compose.yml
version: '3.8'
services:
ultrarag-api:
image: ultrarag:v2.0.0-beta
ports:
- "8000:8000"
environment:
- CUDA_VISIBLE_DEVICES=0
volumes:
- ./data:/app/data
- ./configs:/app/configs
command: ultrarag serve api --config configs/production.yaml
retriever:
image: ultrarag:v2.0.0-beta
ports:
- "8001:8001"
command: ultrarag serve retriever --port 8001
Kubernetes 배포
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ultrarag-deployment
spec:
replicas: 3
selector:
matchLabels:
app: ultrarag
template:
metadata:
labels:
app: ultrarag
spec:
containers:
- name: ultrarag
image: ultrarag:v2.0.0-beta
ports:
- containerPort: 8000
resources:
requests:
nvidia.com/gpu: 1
limits:
nvidia.com/gpu: 1
결론
UltraRAG 2.0은 연구자와 개발자가 RAG 시스템에 접근하는 방식에서 중요한 발전을 나타냅니다. 로우코드 접근법, 광범위한 기준선 지원, 유연한 아키텍처를 통해 정교한 RAG 애플리케이션을 빠르게 프로토타입하고 배포할 수 있습니다.
주요 포인트
- 쉬운 설정: uv 또는 Docker로 빠른 설치
- 풍부한 생태계: 17개 이상의 데이터셋과 다양한 기준선 방법
- 유연한 설정: YAML 기반 파이프라인 정의
- 프로덕션 준비: Docker와 Kubernetes 배포 옵션
- 연구 친화적: 내장된 평가 및 디버깅 도구
다음 단계
- 다양한 기준선 방법 실험
- 도메인별 데이터셋에서 테스트
- 사용 사례에 맞는 검색기와 생성기 사용자 정의
- 모니터링과 스케일링을 통한 프로덕션 배포
고급 기능과 최신 업데이트는 공식 UltraRAG 문서와 GitHub 저장소를 참조하세요.
이 튜토리얼은 UltraRAG 2.0의 핵심 측면을 다루었습니다. 구체적인 구현 세부사항과 고급 설정은 공식 문서와 예제 저장소를 참조하세요.