5분 안에 시작하고, 설정 1줄로 컴포넌트를 교체하는 Production-ready RAG 백엔드
한국어 | English
라이브 데모 체험하기 · 접근코드: 1127
git clone https://github.com/youngouk/OneRAG.git && cd OneRAG && uv sync# 🐳 Docker 있으면 → Full API 서버 (Weaviate + FastAPI + Swagger UI)
cp quickstart/.env.quickstart .env # GOOGLE_API_KEY만 설정
make start # → http://localhost:8000/docs
# 💻 Docker 없으면 → 로컬 CLI 챗봇 (설치만으로 바로 실행)
make easy-start # → 터미널에서 바로 대화
# 🔒 API 키 없이 → Ollama 로컬 LLM으로 완전 오프라인 동작
ollama pull llama3.2 && make easy-start
하나의 코드베이스로 모든 RAG 컴포넌트를 조립합니다.
- 설정만 바꾸면 끝 — Vector DB(6종), LLM(5종), Reranker(6종), Cache(3종) 모두
.env또는 YAML로 교체 - API 키 없이 시작 — Ollama 로컬 LLM으로 인터넷 없이도 완전 동작
- OpenAI SDK 호환 — 기존 OpenAI 코드 그대로 OneRAG에 연결 (
/v1/chat/completions) - 2,200+ 테스트 — 프로덕션 검증된 안정성, CI/CD 완비
- PoC에서 프로덕션까지 — 동일한 코드베이스로 확장, 재구축 불필요
라이브 데모에서 바로 체험해보세요 (접근코드:
1127)
Full API 서버 (make start) |
CLI 챗봇 (make easy-start) |
|
|---|---|---|
| Docker | 필요 | 불필요 |
| Vector DB | Weaviate (하이브리드 검색) | ChromaDB (로컬 파일) |
| 인터페이스 | REST API + Swagger UI | 터미널 CLI |
| LLM | 5종 (Gemini, OpenAI, Claude, OpenRouter, Ollama) | Gemini / OpenRouter / Ollama |
| 용도 | 프로덕션, API 통합, 팀 개발 | 학습, 체험, 빠른 PoC |
git clone https://github.com/youngouk/OneRAG.git
cd OneRAG && uv sync
cp quickstart/.env.quickstart .env
# .env 파일에서 GOOGLE_API_KEY 설정
# (무료: https://aistudio.google.com/apikey)
make start끝! http://localhost:8000/docs에서 바로 테스트할 수 있습니다.
make start-down # 종료Docker 설치 없이 터미널에서 바로 RAG 검색 + AI 답변을 체험할 수 있습니다.
git clone https://github.com/youngouk/OneRAG.git
cd OneRAG && uv sync
make easy-start샘플 데이터 25개가 자동 적재되고, 하이브리드 검색(Dense + BM25)이 바로 작동합니다. AI 답변 생성을 사용하려면 API 키를 하나 설정하세요:
# 셋 중 하나만 설정하면 됩니다
export GOOGLE_API_KEY="발급받은키" # 무료: https://aistudio.google.com/apikey
export OPENROUTER_API_KEY="발급받은키" # https://openrouter.ai/keys
ollama pull llama3.2 # API 키 없이 로컬 LLM 사용OneRAG가 처음이라면?
make easy-start로 시작해서 챗봇에게 직접 물어보세요. "하이브리드 검색이 뭐야?", "RAG 파이프라인이 어떻게 돼?" — 샘플 데이터에 답이 있습니다.
기존 OpenAI SDK 코드를 수정 없이 OneRAG에 연결할 수 있습니다.
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
# RAG 검색 + AI 답변 생성
response = client.chat.completions.create(
model="gemini", # 또는 ollama/llama3.2, openrouter/google/gemini-2.0-flash
messages=[{"role": "user", "content": "RAG란 무엇인가요?"}],
)
print(response.choices[0].message.content)지원 엔드포인트:
POST /v1/chat/completions— 채팅 완료 (스트리밍 지원)GET /v1/models— 사용 가능한 모델 목록
모델 선택:
| 형식 | 예시 | 설명 |
|---|---|---|
provider |
gemini, ollama, claude |
기본 모델 사용 |
provider/model |
ollama/qwen2.5:3b |
특정 모델 지정 |
openrouter/vendor/model |
openrouter/google/gemini-2.0-flash |
OpenRouter 경유 |
LangChain, Cursor, Open WebUI 등 OpenAI SDK를 사용하는 모든 도구와 바로 연결됩니다.
.env 또는 YAML 설정만 변경하면 모든 컴포넌트를 교체할 수 있습니다.
# Vector DB 교체
VECTOR_DB_PROVIDER=weaviate # 또는 chroma, pinecone, qdrant, pgvector, mongodb
# LLM 교체
LLM_PROVIDER=google # 또는 openai, anthropic, openrouter, ollama# 리랭커 추가 (app/config/features/reranking.yaml)
reranking:
approach: "cross-encoder" # 또는 late-interaction, llm, local
provider: "jina" # 또는 cohere, google, openai, openrouter, sentence-transformers
# 기능 On/Off
cache: { enabled: true, type: "redis" } # 또는 memory, semantic
graph_rag: { enabled: true } # 지식 그래프 관계 추론
pii: { enabled: true } # 개인정보 마스킹| 카테고리 | 선택지 | 변경 방법 |
|---|---|---|
| Vector DB | Weaviate, Chroma, Pinecone, Qdrant, pgvector, MongoDB | 환경변수 1줄 |
| LLM | Google Gemini, OpenAI, Anthropic Claude, OpenRouter, Ollama | 환경변수 1줄 |
| 리랭커 | Jina, Cohere, Google, OpenAI, OpenRouter, Local | YAML 2줄 |
| 캐시 | Memory, Redis, Semantic | YAML 1줄 |
| 쿼리 라우팅 | LLM 기반, Rule 기반 | YAML 1줄 |
| 한국어 검색 | 동의어, 불용어, 사용자사전 | YAML 설정 |
| 보안 | PII 탐지, 마스킹, 감사 로깅 | YAML 설정 |
| GraphRAG | 지식 그래프 기반 관계 추론 | YAML 1줄 |
| Agent | 도구 실행, MCP 프로토콜 | YAML 설정 |
Query → Router → Expansion → Retriever → Cache → Reranker → Generator → PII Masking → Response
| 단계 | 기능 | 교체 가능 |
|---|---|---|
| 쿼리 라우팅 | 쿼리 유형 분류 | LLM/Rule 선택 |
| 쿼리 확장 | 동의어, 불용어 처리 | 사전 커스텀 |
| 검색 | 벡터/하이브리드 검색 | 6종 DB |
| 캐싱 | 응답 캐시 | 3종 캐시 |
| 재정렬 | 검색 결과 정렬 | 6종 리랭커 |
| 답변 생성 | LLM 응답 생성 | 5종 LLM |
| 후처리 | 개인정보 마스킹 | 정책 커스텀 |
| 단계 | 구성 | 용도 |
|---|---|---|
| Basic | 벡터 검색 + LLM | 간단한 문서 Q&A |
| Standard | + 하이브리드 검색 + Reranker | 검색 품질이 중요한 서비스 (권장) |
| Advanced | + GraphRAG + Agent | 복잡한 관계 추론, 도구 실행 |
Basic으로 시작해서, 필요할 때 블록을 추가하면 됩니다.
별도의 React 기반 웹 UI가 포함되어 있습니다. **라이브 데모**에서 바로 체험하거나, 로컬에서 실행할 수 있습니다.
챗봇 인터페이스 (다크 모드) · 문서 관리
주요 기능:
- WebSocket 실시간 스트리밍 채팅 (RAG 검색 결과 + AI 답변)
- 드래그앤드롭 문서 업로드 (PDF, Word, Excel, Markdown 등)
- 문서 관리 — 검색, 정렬, 일괄 삭제, 상세 정보 조회
- 다크 모드, 모바일 반응형 레이아웃
- Feature Flag 기반 모듈 활성화/비활성화
- 관리자 대시보드 — 세션, 성능, 프롬프트 통합 관제
# 백엔드 실행 중인 상태에서
make frontend-dev # → http://localhost:5173프론트엔드 + 백엔드 + Weaviate 동시 실행:
make start-full
easy-start CLI 챗봇은 4개 언어를 지원합니다.
make easy-start LANG=en # English
make easy-start LANG=ja # 日本語
make easy-start LANG=zh # 中文
make easy-start # 한국어 (기본)각 언어별로 UI 텍스트, 시스템 프롬프트, 샘플 데이터가 모두 현지화되어 있습니다.
make dev-reload # 개발 서버 (자동 리로드)
make test # 테스트 실행 (2,200+)
make lint # 린트 검사
make type-check # 타입 체크MIT License
이 프로젝트는 RAG Chat Service PM이 여러 프로젝트를 진행하며 구현해보고 싶었던 기능들을 모아 만들었습니다.
RAG를 처음 접하는 분들이 쉽게 PoC를 진행하고, 프로덕션까지 확장할 수 있도록 설계했습니다.