OpenRAG (문서를 업로드하고, 처리하고, 검색하고, 대화형으로 활용)

OpenRAG는 할 수 있게 만든 Retrieval-Augmented Generation(RAG) 플랫폼입니다. GitHub 저장소 설명과 공식 문서 기준으로 보면, 이 프로젝트는 Langflow 기반 워크플로우, Docling 기반 문서 처리, OpenSearch 기반 검색 인덱싱, 그리고 Next.js/Starlette 기반 애플리케이션 계층을 하나의 패키지처럼 묶어 제공하는 것이 핵심입니다. 저장소는 langflow-ai/openrag에 공개되어 있고, 현재 공개 릴리스는 2026년 2월 27일 기준 0.2.5입니다. (GitHub)

---

프로젝트 소개

OpenRAG를 한 문장으로 정리하면, **“설치 직후 바로 돌려볼 수 있는 셀프 호스팅형 문서 검색·대화 플랫폼”**입니다. 사용자는 문서를 업로드한 뒤 채팅 인터페이스에서 자연어로 질의할 수 있고, 내부적으로는 임베딩·검색·리랭킹·에이전트 호출 같은 RAG 파이프라인이 동작합니다. 공식 README는 OpenRAG를 “intelligent document search and AI-powered conversations”를 위한 종합 RAG 플랫폼이라고 설명합니다. 또 애플리케이션은 Starlette와 Next.js로 구성되고, 핵심 엔진은 OpenSearch, Langflow, Docling에 의존합니다. (GitHub)

특히 눈에 띄는 점은 OpenRAG가 단순한 “라이브러리”가 아니라는 점입니다. 일반적인 RAG 오픈소스는 보통 다음 중 하나에 집중합니다.

• 벡터 검색 엔진
• 문서 파싱
• 체인/에이전트 오케스트레이션
• 챗 UI

OpenRAG는 이 네 층을 모두 묶어 **“개발자가 직접 조립하지 않아도 되는 실행형 플랫폼”**으로 제공하려고 합니다. 공식 문서도 OpenRAG 아키텍처를 중앙 백엔드가 여러 서비스와 외부 커넥터를 오케스트레이션하는 경량 컨테이너 기반 구조라고 설명합니다. (docs.openr.ag)

---

왜 이 프로젝트가 등장했을까

RAG를 실제 제품 수준으로 만들려면 생각보다 준비물이 많습니다. 단순히 임베딩 모델 하나와 벡터 DB 하나만 연결한다고 끝나지 않습니다.

1. 문서 전처리 문제
   현실의 문서는 깔끔하지 않습니다. PDF, 스캔, 표, 복잡한 레이아웃, 폴더 단위 업로드, URL 수집 같은 문제가 생깁니다. README도 OpenRAG가 “messy, real-world data”를 다루는 문서 ingestion을 강조합니다. (GitHub)
2. 워크플로우 커스터마이징 문제
   실서비스에서는 “검색 → 리랭크 → 응답 생성” 정도로 끝나지 않습니다. 필터링, 멀티에이전트, 프롬프트 조정, 권한, 추적, 장애 대응이 필요합니다. OpenRAG는 이런 부분을 Langflow 기반 시각 편집기로 노출합니다. 공식 quickstart에서도 설정 화면에서 일부 값을 바꿀 수 있지만, 전체 커스터마이징은 Langflow 에디터에서 하라고 안내합니다. (OpenRAG)
3. 실행 환경 구성 문제
   보통은 frontend, backend, vector store, workflow engine, document parser를 각각 설치하고 붙여야 합니다. OpenRAG는 uv/uvx, Docker 또는 Podman, 그리고 초기 설정 TUI를 제공해 이 과정을 줄이려고 합니다. uvx 설치 시 의존성 설치와 서비스 기동 흐름을 최대한 감싸고, 설정은 ~/.openrag/tui의 .env와 compose 파일들로 관리됩니다. (OpenRAG)

즉, OpenRAG의 등장은 “RAG를 잘 만드는 법”보다 **“RAG를 실제로 굴러가게 만드는 복잡함”**에 대한 대응으로 보는 편이 맞습니다.

---

핵심 기능

1) 바로 실행 가능한 패키지형 RAG

README는 OpenRAG의 첫 번째 강점으로 **“Pre-packaged & ready to run”**을 내세웁니다. 즉, 핵심 도구들이 미리 연결되어 있어서 설치 후 바로 사용할 수 있다는 뜻입니다. quickstart 기준으로는 Python 3.13과 uv, 그리고 모델 API 키를 준비한 뒤 uvx --python 3.13 openrag로 시작할 수 있습니다. (GitHub)

mkdir openrag-workspace
cd openrag-workspace
uvx --python 3.13 openrag

이 접근은 “프레임워크를 가져다 쓰는” 방식보다 “완성된 플랫폼을 띄우는” 방식에 가깝습니다.

---

2) 문서 업로드와 지식 베이스 구축

OpenRAG는 업로드된 문서를 OpenSearch 인덱스에 저장하고, Chat 화면에서 이를 바탕으로 질의응답할 수 있게 설계되어 있습니다. quickstart에 따르면 기본 문서가 포함되어 있으며, 사용자는 파일 또는 폴더 단위로 문서를 추가할 수 있습니다. 기본 로컬 문서 디렉터리는 ~/.openrag/documents입니다. (OpenRAG)

또 .env.example을 보면 단순 파일 업로드 외에도 Google OAuth, Microsoft Graph OAuth, AWS 자격 증명, 웹훅 기반 연속 수집 설정 등이 들어 있어, 로컬 파일 외부의 문서 소스까지 염두에 둔 구조임을 알 수 있습니다. 이는 OpenRAG가 단순 데모를 넘어서 조직 문서 수집 파이프라인을 지향한다는 신호입니다. (GitHub)

---

3) Langflow 기반 시각 워크플로우 편집

OpenRAG의 가장 흥미로운 지점은 RAG 파이프라인을 코드만이 아니라 플로우로 다룬다는 점입니다. quickstart는 설정 화면에서 모델과 agent instructions를 변경할 수 있고, 더 깊은 수정은 내장된 Langflow visual editor에서 수행한다고 설명합니다. 또한 .env.example에는 chat flow, ingest flow, URL ingest flow, nudges flow의 ID가 노출되어 있습니다. (OpenRAG)

이 구조는 개발자 입장에서 꽤 중요합니다.

• 프롬프트와 체인 구조를 코드 배포 없이 조정하기 쉽고
• 검색/리랭크/에이전트 로직을 시각적으로 실험할 수 있으며
• 운영 중인 흐름을 다시 복원하거나 교체하기 좋습니다. (OpenRAG)

즉, OpenRAG는 “RAG 앱”이면서 동시에 “RAG 실험실” 역할도 합니다.

---

4) Agentic RAG와 리랭킹 지향

README는 OpenRAG의 highlight로 Agentic RAG workflows, re-ranking, multi-agent coordination을 직접 언급합니다. (GitHub)

이건 단순한 키워드가 아닙니다. OpenRAG는 Langflow를 내장하고 flow ID를 여러 개 관리하며, 채팅용 플로우와 ingestion 플로우를 분리합니다. 이런 설계는 다음과 같은 확장을 자연스럽게 만듭니다.

• 질의 분해
• 검색 결과 재정렬
• 여러 에이전트의 역할 분담
• 응답 전 후처리
• 문맥 기반 nudges 생성

README의 “intelligent nudges” 언급도 같은 방향입니다. (GitHub)

---

5) OpenSearch 기반 엔터프라이즈 검색

OpenRAG의 저장·검색 계층은 OpenSearch입니다. README가 이를 명시하고 있고, docker-compose.yml에서도 opensearch와 opensearch-dashboards 서비스가 포함되어 있습니다. 백엔드와 Langflow 모두 OpenSearch 관련 환경 변수를 사용하며, 인덱스 이름도 설정 가능합니다. (GitHub)

개발자 관점에서 이 선택은 의미가 큽니다.

• 단순 벡터 검색만이 아니라 검색 운영 도구를 붙이기 쉽고
• 인덱스 관리와 대시보드 활용이 가능하며
• 중대형 배포에서 익숙한 검색 스택을 재사용할 수 있습니다. (GitHub)

즉, OpenRAG는 “벡터 DB 장난감”보다는 검색 인프라 위에 세운 RAG 앱에 가깝습니다.

---

6) SDK와 MCP 지원

README에는 공식 Python SDK, TypeScript/JavaScript SDK, 그리고 MCP(Model Context Protocol) 서버 사용 예가 포함되어 있습니다. Python과 JS에서 OpenRAGClient로 대화 API를 호출할 수 있고, MCP 서버는 Cursor나 Claude Desktop 같은 AI 도구를 OpenRAG 지식베이스에 연결하는 용도로 제시됩니다. (GitHub)

Python 예시는 이런 식입니다. README의 예제를 바탕으로 정리하면 다음과 같습니다. (GitHub)

import asyncio
from openrag_sdk import OpenRAGClient

async def main():
    async with OpenRAGClient() as client:
        response = await client.chat.create(message="What is RAG?")
        print(response.response)

if __name__ == "__main__":
    asyncio.run(main())

TypeScript도 비슷합니다. (GitHub)

import { OpenRAGClient } from "openrag-sdk";

const client = new OpenRAGClient();
const response = await client.chat.create({ message: "What is RAG?" });

console.log(response.response);

이 말은 OpenRAG가 단순히 웹 UI로 끝나는 것이 아니라, 애플리케이션 내장형 지식 서비스로도 사용할 수 있다는 뜻입니다.

---

프로젝트 구조

저장소 루트를 보면 frontend, src, flows, sdks, kubernetes/helm/openrag, tests, docs 등이 분리되어 있습니다. 이 디렉터리 구성과 compose 파일을 함께 보면, OpenRAG는 대략 아래와 같은 구조로 이해할 수 있습니다. 이 다이어그램은 공식 문서와 저장소 구성을 바탕으로 재구성한 해석입니다. (GitHub)

디렉터리별로 보면

• frontend
  Next.js 기반 UI로 보이며, 실제 사용자와 상호작용하는 웹 애플리케이션 계층입니다. README가 frontend를 Next.js 기반이라고 밝힙니다. (GitHub)
• src
  Python 백엔드의 핵심 로직이 들어가는 위치로 보입니다. pyproject.toml은 openrag 패키지와 openrag 실행 스크립트를 정의합니다. (GitHub)
• flows
  Langflow 플로우 정의를 저장하는 디렉터리입니다. compose 파일에서 이 디렉터리가 Langflow 컨테이너에 마운트됩니다. (GitHub)
• sdks
  공식 SDK 소스가 들어가는 위치로 보이며, README에서 Python/JS SDK를 제공한다고 설명합니다. (GitHub)
• kubernetes/helm/openrag
  헬름 차트가 포함되어 있어 쿠버네티스 배포도 염두에 둔 구조입니다. (GitHub)
• openrag-documents, keys, config, data
  compose 파일상에서 문서, 키, 플로우, 설정, 데이터 저장을 위한 볼륨 경로가 분리되어 있습니다. (GitHub)

---

실제 실행 구조를 더 깊게 보기

docker-compose.yml을 보면 주요 서비스는 다음 네 축으로 나뉩니다. (GitHub)

1. openrag-frontend
2. openrag-backend
3. langflow
4. opensearch 및 opensearch-dashboards

또 문서 관리 문서에 따르면 대부분 서비스는 컨테이너에서 동작하지만, Docling 같은 일부 서비스는 로컬 머신에서 native process로 실행됩니다. 공식 문서는 이를 분명히 구분합니다. (OpenRAG)

이 구성이 의미하는 바는 다음과 같습니다.

프론트엔드와 백엔드 분리

웹 UI는 독립 서비스이고, backend가 orchestration 역할을 맡습니다. 프론트가 직접 Langflow나 OpenSearch와 통신하는 게 아니라, backend를 중심으로 묶는 구조입니다. (GitHub)

Langflow는 “내장형 플로우 엔진”

Langflow는 별도 서비스로 돌지만 OpenRAG의 일부처럼 묶입니다. flow 파일이 볼륨으로 주입되고, backend는 flow ID와 Langflow URL을 사용해 이를 호출합니다. (GitHub)

OpenSearch는 저장소이자 검색 엔진

문서 청크 저장, 검색, 운영 대시보드까지 담당합니다. opensearch-dashboards가 함께 뜨는 것도 이를 보여 줍니다. (GitHub)

Docling은 “문서 파서 계층”

공식 문서는 Docling을 native service로 설명하고, compose 환경 변수에는 DOCLING_SERVE_URL이 있습니다. 즉, OpenRAG는 문서 파싱을 별도 프로세스로 취급하고 Langflow/Backend가 이를 호출하는 방식으로 보입니다. (OpenRAG)

이 구조는 잘 나눈 편입니다. 문서 파싱, 검색, 워크플로우, 앱 UI를 각각 독립 계층으로 두었기 때문에 바꾸기 쉽고 장애 지점도 분리됩니다.

---

설치와 운영 방식이 독특한 이유

OpenRAG는 보통의 Python 패키지처럼 pip install만 하고 끝나는 프로젝트가 아닙니다. 설치 후 터미널 세션이 설정 마법사처럼 동작합니다. 공식 문서에 따르면 uv 또는 uvx로 OpenRAG를 실행하면, OpenSearch 비밀번호, Langflow 관리자 비밀번호, 모델 공급자 키, Langfuse 추적, 문서 경로, 클라우드 커넥터 등을 순서대로 구성하게 됩니다. (OpenRAG)

이 방식의 장점은 분명합니다.

• 환경 변수의 진입 장벽을 낮춤
• Compose/컨테이너 런타임 관리 보조
• 앱 초기 온보딩과 운영 설정을 연결

반면 단점도 있습니다.

• Python 3.13 요구사항이 다소 공격적입니다. pyproject.toml과 quickstart 모두 3.13을 요구합니다. (GitHub)
• Windows는 WSL을 요구합니다. (OpenRAG)
• 최소 8GB RAM, 50GB 디스크 권장을 문서가 명시합니다. 즉, 가벼운 툴이라기보다는 제법 묵직한 로컬 플랫폼입니다. (OpenRAG)

---

개발자 관점에서 좋은 점

1) “완성도 있는 기본형”이 있다

많은 오픈소스 RAG 프로젝트는 시작점만 제공합니다. 반면 OpenRAG는 기본 문서, 기본 플로우, 온보딩, 웹 UI, 설정 화면, Langflow 편집기, SDK, MCP까지 갖추고 있습니다. RAG 데모를 빨리 만들고 싶거나 내부 지식검색 PoC를 띄우고 싶은 팀에게 유리합니다. (OpenRAG)

2) 커스터마이징 포인트가 명확하다

설정 UI에서 바꿀 수 있는 것과 Langflow에서 바꿔야 하는 것이 분리되어 있습니다. 이건 운영자/개발자 역할을 나누기 좋습니다. 간단한 모델 교체는 UI에서, 파이프라인 개조는 Langflow에서 처리할 수 있습니다. (OpenRAG)

3) 외부 앱 통합 경로가 있다

SDK와 MCP가 있다는 것은 OpenRAG를 독립 앱으로만 쓰지 않고, 다른 제품의 지식 백엔드로 재사용할 수 있다는 뜻입니다. (GitHub)

4) 운영 고려가 비교적 진지하다

OpenSearch dashboards, GPU compose, Helm chart, 서비스 상태 확인, 로그 조회, factory reset, Langfuse tracing 문서가 있다는 점에서 실험용을 넘어 운영 시나리오를 의식한 프로젝트입니다. (GitHub)

---

아쉬운 점과 주의할 점

1) 스택이 무겁다

Next.js, backend, Langflow, OpenSearch, Docling, 컨테이너 런타임까지 필요합니다. “가벼운 라이브러리 하나 붙여서 끝”을 기대하면 과합니다. 공식 문서가 최소 리소스를 명시하는 이유도 여기에 있습니다. (OpenRAG)

2) Python 3.13 전제

의존성 최신화를 적극적으로 따라가고 있지만, 조직 환경에 따라 3.13은 아직 빠를 수 있습니다. 개발용 랩탑이나 CI 환경에서 제약이 생길 수 있습니다. (GitHub)

3) “올인원”은 곧 “교체 비용”이기도 하다

OpenRAG의 장점은 미리 잘 붙어 있다는 것이지만, 반대로 특정 계층만 떼어내고 바꾸려면 이해해야 할 범위가 넓습니다. 특히 Langflow 플로우 중심 설계는 강력하지만, 팀이 그 모델에 익숙하지 않으면 운영 복잡도가 생길 수 있습니다. 이 평가는 저장소 구조와 문서 흐름을 바탕으로 한 해석입니다. (GitHub)

---

어떤 팀에 잘 맞을까

OpenRAG는 특히 이런 경우에 잘 맞습니다.

사내 문서 검색 챗봇을 빨리 만들어야 하는 팀

문서 업로드, 검색, 챗 UI, 기본 워크플로우가 이미 연결되어 있기 때문입니다. (GitHub)

Langflow로 실험하면서 점점 제품화하고 싶은 팀

초기에는 플로우 편집기로 빠르게 실험하고, 나중에는 SDK/MCP로 통합 범위를 넓힐 수 있습니다. (OpenRAG)

OpenSearch 기반 검색 운영 경험이 있는 팀

기존 검색 운영 노하우를 살릴 수 있습니다. (GitHub)

반대로, 아주 얇은 임베딩 검색 API만 필요하거나 완전히 코드 중심의 미세 제어를 선호하는 팀이라면 OpenRAG보다 더 작은 조합형 스택이 나을 수 있습니다. 이 부분은 아키텍처 성향에 대한 판단입니다. (OpenRAG)

---

시작해 볼 때 추천하는 접근

공식 quickstart를 기준으로 가장 현실적인 입문 루트는 다음입니다. (OpenRAG)

# 1) 작업 디렉터리 생성
mkdir openrag-workspace
cd openrag-workspace

# 2) 실행
uvx --python 3.13 openrag

그다음 흐름은 이렇습니다. (OpenRAG)

1. OpenSearch / Langflow 관리자 비밀번호 설정
2. 모델 공급자 키 입력
3. 서비스 시작
4. 브라우저에서 OpenRAG 온보딩 완료
5. 문서 업로드
6. Chat에서 질의
7. 필요하면 Langflow에서 플로우 수정

개발 블로그 관점에서 추천하는 학습 순서는 더 단순합니다.

1. 먼저 기본 플로우 그대로 써 본다
2. 문서 업로드 후 응답 품질을 확인한다
3. 설정 화면에서 모델과 지시문만 바꿔 본다
4. 그다음 Langflow에서 ingestion/chat flow를 수정한다
5. 마지막에 SDK/MCP 통합을 시도한다

이 순서가 좋은 이유는 OpenRAG의 강점이 “기본값이 이미 살아 있다”는 데 있기 때문입니다.

---

한 줄 총평

OpenRAG는 RAG를 직접 조립하는 수고를 줄이고, 문서 수집부터 검색·대화·플로우 편집·앱 통합까지 한 번에 제공하려는 실전형 플랫폼입니다. Langflow를 중심에 둔 덕분에 커스터마이징이 쉽고, OpenSearch를 택한 덕분에 검색 운영 감각도 살렸습니다. 대신 무게감 있는 스택이므로, 가벼운 라이브러리를 찾는 사람보다는 **“내부 지식 검색 서비스를 빠르게 띄우고 점차 확장하려는 팀”**에 더 잘 맞습니다. (GitHub)