OneRAG

Production-ready RAG Framework (Python/FastAPI). 1-line config swaps: 6 Vector DBs (Weaviate, Pinecone, Qdrant, ChromaDB, pgvector, MongoDB), 5 LLMs (Gemini, OpenAI, Claude, Ollama, OpenRouter). OpenAI-compatible API. 2100+ tests.

Generate Convert Improve

Install / Use

/learn @notadev-iamaura/OneRAG

About this skill

Quality Score

0/100

README

<img src="assets/logo.svg" alt="OneRAG Logo" width="400"/> 5분 안에 시작하고, 설정 1줄로 컴포넌트를 교체하는 Production-ready RAG 백엔드 <a href="https://github.com/youngouk/OneRAG/actions/workflows/ci.yml"><img src="https://github.com/youngouk/OneRAG/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.11+-blue.svg" alt="Python 3.11+"></a> <a href="https://demo-frontend-production-3c93.up.railway.app"><img src="https://img.shields.io/badge/Live_Demo-Railway-blueviolet.svg" alt="Live Demo"></a> <a href="https://github.com/youngouk/OneRAG/stargazers"><img src="https://img.shields.io/github/stars/youngouk/OneRAG?style=social" alt="GitHub Stars"></a> 한국어 | <a href="README_EN.md">English</a> <a href="https://demo-frontend-production-3c93.up.railway.app">라이브 데모 체험하기</a> · 접근코드: <code>1127</code>

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 컴포넌트를 조립합니다.

설정만 바꾸면 끝 — 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 |

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

컴포넌트 교체하기

.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 설정 |

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가 포함되어 있습니다. **라이브 데모**에서 바로 체험하거나, 로컬에서 실행할 수 있습니다.

<img src="assets/screenshot-chat-dark.png" alt="OneRAG Chat - Dark Mode" width="49%"/> <img src="assets/screenshot-docs.png" alt="OneRAG Document Management" width="49%"/> 챗봇 인터페이스 (다크 모드) · 문서 관리

주요 기능:

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를 진행하고, 프로덕션까지 확장할 수 있도록 설계했습니다. <a href="https://github.com/youngouk/OneRAG/issues">Report Bug</a> · <a href="https://github.com/youngouk/OneRAG/issues">Request Feature</a> · <a href="https://github.com/youngouk/OneRAG/discussions">Discussions</a>

Related Skills

claude-opus-4-5-migration

83.3k

Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5

model-usage

337.7k

Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.

feishu-drive

337.7k

things-mac

337.7k

Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database)