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)

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 — 사용 가능한 모델 목록

모델 선택:

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 }                    # 개인정보 마스킹

Query → Router → Expansion → Retriever → Cache → Reranker → Generator → PII Masking → Response

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   # 타입 체크

• 상세 설정 가이드
• 아키텍처 설명
• Streaming API 가이드
• WebSocket API 가이드

MIT License

_{이 프로젝트는 RAG Chat Service PM이 여러 프로젝트를 진행하며 구현해보고 싶었던 기능들을 모아 만들었습니다.
RAG를 처음 접하는 분들이 쉽게 PoC를 진행하고, 프로덕션까지 확장할 수 있도록 설계했습니다.}

Report Bug · Request Feature · Discussions