onerag 1.0.7

5분 안에 시작하고, 설정 1줄로 컴포넌트를 교체하는 Production-ready RAG 백엔드

한국어 | English

---

TL;DR

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

---

데모

---

왜 OneRAG인가?

하나의 코드베이스로 모든 RAG 컴포넌트를 조립합니다.

• 설정 1줄로 교체 — Vector DB, LLM, Reranker, Cache 모두 .env 또는 YAML 한 줄로 변경
• API 키 없이 시작 — Ollama 로컬 LLM으로 인터넷 없이도 완전 동작
• OpenAI SDK 호환 — 기존 OpenAI 코드 그대로 OneRAG에 연결 (/v1/chat/completions)
• 2,100+ 테스트 — 프로덕션 검증된 안정성, CI/CD 완비
• PoC에서 프로덕션까지 — 동일한 코드베이스로 확장, 재구축 불필요

아키텍처 한눈에 보기

---

시작하기

	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

방법 A: Full API 서버 (Docker)

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  # 종료

방법 B: 로컬 CLI 챗봇 (Docker 불필요)

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 호환 API

기존 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를 사용하는 모든 도구와 바로 연결됩니다.

---

컴포넌트 교체하기

Vector DB 바꾸기 (설정 1줄)

# .env 파일에서 한 줄만 변경
VECTOR_DB_PROVIDER=weaviate  # 또는 chroma, pinecone, qdrant, pgvector, mongodb

LLM 바꾸기 (설정 1줄)

# .env 파일에서 한 줄만 변경
LLM_PROVIDER=google  # 또는 openai, anthropic, openrouter, ollama

리랭커 추가하기 (YAML 2줄)

# app/config/features/reranking.yaml
reranking:
  approach: "cross-encoder"  # 또는 late-interaction, llm, local
  provider: "jina"           # 또는 cohere, google, openai, openrouter, sentence-transformers

기능 On/Off (YAML 설정)

# 캐싱 활성화
cache:
  enabled: true
  type: "redis"  # 또는 memory, semantic

# GraphRAG 활성화
graph_rag:
  enabled: true

# PII 마스킹 활성화
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 설정

---

RAG 파이프라인

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으로 시작해서, 필요할 때 블록을 추가하면 됩니다.

---

프론트엔드 UI

별도의 React 기반 웹 UI가 포함되어 있습니다. 백엔드 API 서버와 함께 실행하면 브라우저에서 전체 RAG 시스템을 체험할 수 있습니다.

주요 기능:

• 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,100+)
make lint         # 린트 검사
make type-check   # 타입 체크

---

문서

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

---

라이선스

MIT License

---

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

Report Bug · Request Feature · Discussions