본문 바로가기
AI 생성 글 정리/tech_github

RAGFlow — Deep document understanding + Agent 기능을 결합한 오픈소스 RAG 엔진

by Honbul 2026. 4. 8.

한 줄 요약
RAGFlow는 문서 파싱/청킹/검색/재랭킹/인용(citation) 생성뿐 아니라, 에이전트 워크플로·메모리·MCP·코드 실행까지 하나의 플랫폼 안에서 다루는 “context layer” 지향형 RAG 시스템이다.

 

Quick Links

Key Features

  1. Deep document understanding
    • deepdoc/ 파서 계층이 PDF, DOCX, PPT, Excel, HTML, Markdown, TXT, EPUB, JSON 등을 다룬다.
    • OCR, 레이아웃 인식, 표 구조 인식, figure/caption 추출 등 “문서의 모양과 의미”를 함께 처리하려는 설계가 보인다.
  2. Template-based chunking
    • 단순 길이 기반 분할이 아니라 템플릿/규칙 기반 청킹을 전면에 내세운다.
    • 실제 RAG 품질을 좌우하는 chunk granularity를 제품 레벨의 핵심 기능으로 다루는 점이 인상적이다.
  3. Grounded citations / traceable answers
    • 답변에 인용 근거를 붙이고, 가능한 경우 원문 위치와 연결한다.
    • 규제 산업이나 운영 현장에서는 “정답률”만큼이나 근거 추적성이 중요하므로 이 부분이 강점이다.
  4. 멀티포맷/이기종 데이터 소스 지원
    • Word, slides, Excel, text, scanned docs, images, structured data, web pages 등 다양한 입력을 전제로 한다.
    • 최근 업데이트 로그 기준으로 Confluence, S3, Notion, Discord, Google Drive 동기화도 강조된다.
  5. Agentic workflow
    • agent/ 디렉터리 아래에 canvas, component, plugin, tools, sandbox 등이 모여 있어 단순 챗봇이 아니라 도구 사용형 에이전트를 염두에 둔 구조다.
    • 반복(loop), invoke, categorize, list/data operations, docs generation 등 워크플로 빌딩 블록이 준비되어 있다.
  6. MCP + code execution + memory
    • mcp/, memory/, sandbox executor 관련 구성이 따로 존재한다.
    • 즉, RAG를 “문서 검색기”가 아니라 에이전트용 문맥 운영체제(context OS)처럼 확장하려는 방향성이 분명하다.
  7. 하이브리드 백엔드 구조
    • Python(Quart 기반) API 레이어와 Go(Gin 기반) 서비스 레이어가 함께 존재한다.
    • 문서 처리/오케스트레이션은 Python, 일부 서비스/인프라는 Go로 나누는 하이브리드 아키텍처로 읽힌다.
  8. 선택 가능한 검색/문서 엔진
    • Docker 및 설정 파일 기준으로 Elasticsearch, OpenSearch, Infinity, OceanBase 등 복수 엔진을 고려한다.
    • 인덱싱/검색 레이어를 교체 가능하게 두려는 실용적 설계다.
  9. SDK / API / Admin
    • sdk/python/, api/apps/sdk/, admin/, cmd/ragflow_cli.go 등이 있어 제품/플랫폼으로서의 확장성이 높다.
  10. 관측성과 평가 확장 포인트
    • evaluation_app.py, langfuse_app.py 등에서 운영형 제품으로 가기 위한 계측/평가 포인트가 확인된다.

Representative UI / Workflow Figures

 

 

Template-aware chunking / preview 데모

 

 

Agentic workflow / canvas UI 데모

Tech Stack

1) 핵심 런타임과 프레임워크

Layer Stack 확인된 버전/단서
Core project Python backend + Go service + React frontend Project version 0.24.0
Python runtime Python >=3.12, <3.15
Go runtime Go 1.25.0
Frontend runtime Node.js >=18.20.4

2) Python / API / RAG 계층

범주 기술 확인된 버전
Web/API Quart 기반 앱 + Quart-Auth + Quart-CORS + Quart-Schema quart-auth==0.11.0, quart-cors==0.8.0
보조 웹 스택 Flask Session / Login / CORS / Flasgger flask-session==0.8.0, flask-login==0.6.3, flask-cors==6.0.2, flasgger>=0.9.7.1,<0.10.0
ORM/DB Peewee >=3.17.1,<4.0.0
Object store MinIO client 7.2.4
Search clients Elasticsearch DSL / OpenSearch elasticsearch-dsl==8.12.0, opensearch-py==2.7.1
Infinity stack Infinity SDK / Embedding infinity-sdk==0.7.0-dev5, infinity-emb>=0.0.66,<0.0.67
Agent / protocol MCP >=1.19.0
Observability Langfuse >=2.60.0
LLM routing LiteLLM ~=1.82.0 (1.82.7/1.82.8 제외)

3) 문서 처리 / 멀티모달 / OCR

범주 기술 확인된 버전
PDF parsing pypdf >=6.8.0
DOCX parsing python-docx >=1.1.2,<2.0.0
PPT parsing python-pptx >=1.0.2,<2.0.0
Spreadsheet parsing python-calamine >=0.4.0
Vision / OCR runtime ONNX Runtime 1.23.2
CV OpenCV 4.10.0.84
Parser modules Docling / MinerU / PaddleOCR / figure parser 등 deepdoc/parser/에 구현 흔적 존재

4) Go 서비스 계층

범주 기술 확인된 버전
HTTP framework Gin v1.9.1
ORM GORM v1.25.5
MySQL driver GORM MySQL driver v1.5.2
Elasticsearch client go-elasticsearch/v8 v8.19.1
Object store client MinIO Go client v7.0.99
Redis client go-redis/v9 v9.18.0

5) Frontend

범주 기술 확인된 버전
UI framework React 18.2.0
Bundler Vite 7.2.7
Language TypeScript 5.9.3
Design system Ant Design ecosystem package.json 기준 포함
Styling Tailwind CSS ^3
State / data Zustand, TanStack React Query package.json 기준 포함
Routing React Router 7.10.1
Flow / graph UI XYFlow React 12.3.6
Storybook Storybook 9.1.4

6) 인프라 / 배포

범주 기술 비고
Container runtime Docker >=24.0.0 권장
Compose Docker Compose >=2.26.1 권장
Search / doc engines Elasticsearch / OpenSearch / Infinity / OceanBase docker 및 설정 템플릿에 반영
Cache / queue Redis / Valkey 계열 설정 파일 및 런타임에서 사용
Object storage MinIO 기본 스택
Embedding inference TEI 이미지 기본 이미지 태그 1.8 계열
Sandbox isolation gVisor (옵션) code executor 사용 시 언급됨

기술적으로 중요한 관찰

  • 이 프로젝트는 “파이썬 단일 앱”이 아니라 Python + Go + React + 검색엔진 + 오브젝트 스토어 + 캐시 레이어가 결합된 분산형 앱에 가깝다.
  • 따라서 실제 도입 난이도는 단순 라이브러리보다 높지만, 반대로 플랫폼형 참조 구현(reference implementation)으로서의 가치가 크다.

Architecture

대표 figure

아키텍처를 한 문장으로 요약하면

웹 UI / API / 문서 처리 / 검색 인덱싱 / 에이전트 런타임 / 메모리 / 외부 툴 호출을 분리한 다층형 RAG 플랫폼이다.

코드 구조 관점에서 본 핵심 레이어

ragflow/
├─ api/                  # Python API 앱(Quart), auth/rest/sdk/system endpoints
│  ├─ apps/              # document, chunk, kb, llm, connector, evaluation, langfuse, mcp ...
│  ├─ db/                # 모델/서비스/runtime config
│  └─ ragflow_server.py  # Python server entrypoint
├─ cmd/                  # Go entrypoints (server_main.go, admin_server.go, cli)
├─ deepdoc/              # 문서 파싱, OCR, layout, figure/table extraction
│  ├─ parser/
│  └─ vision/
├─ rag/                  # advanced_rag, graphrag, flow, llm, prompts, utils
├─ agent/                # workflow canvas, components, plugins, tools, sandbox
├─ memory/               # agent memory services / utils
├─ mcp/                  # MCP client/server
├─ sdk/python/           # Python SDK
├─ web/                  # React + Vite frontend
├─ docker/               # compose, .env, service_conf templates
├─ helm/                 # Kubernetes 배포용 매니페스트
└─ admin/                # admin client/server 및 release scripts

엔트리포인트 관점

  • Python 진입점: api/ragflow_server.py
    • DB 초기화
    • 설정 로드
    • 앱 실행
    • 백그라운드 진행률 업데이트 thread
    • MCP session 정리 훅 등
  • Go 진입점: cmd/server_main.go
    • logger/config/DB/doc engine/cache/storage/tokenizer 초기화
    • handler/router 조립
    • auth/user/tenant/document/dataset/chunk/search/chat/session/file 계층 서비스
    • admin server heartbeat/reporting

추정 가능한 데이터 흐름

  1. 수집(Ingestion)
    • 파일 업로드 또는 connector를 통해 문서 유입
    • MinIO/object store 및 DB 메타데이터에 저장
  2. 문서 이해(Parsing)
    • deepdoc/parser/가 파일 유형에 맞는 parser 선택
    • OCR, layout recognition, table structure recognition, figure parser 수행 가능
  3. 구조화/청킹
    • 템플릿 기반 chunking
    • section-aware / layout-aware 분할
    • citation을 위한 위치(positional metadata) 보존
  4. 임베딩/인덱싱
    • 선택된 embedding 모델과 문서 엔진(Elastic/OpenSearch/Infinity 등)에 인덱싱
    • metadata condition, cross-language retrieval 등의 옵션이 SDK/API에 반영됨
  5. 검색/재랭킹
    • multi-recall + fused reranking + advanced/graph RAG 경로 활용
    • rag/advanced_rag, rag/graphrag, rag/flow가 이 레이어의 확장점
  6. 응답 생성
    • LLM이 검색 결과를 바탕으로 답변 생성
    • citation / source grounding 부착
  7. 에이전트 확장
    • 필요 시 agent/ 컴포넌트, memory/, mcp/, code executor를 사용해 툴 호출형 워크플로 실행

왜 이 구조가 중요한가

RAGFlow는 “임베딩해서 검색한다” 수준을 넘어서, 다음 세 가지를 동시에 해결하려고 한다.

  • 문서 이해 문제: PDF/스캔/표/도형/캡션을 어떻게 읽을 것인가
  • 검색 품질 문제: 어떤 단위로 chunking하고 어떤 metadata로 retrieval 할 것인가
  • 실행 문제: 검색 결과를 agent/workflow/tool/memory와 어떻게 연결할 것인가

즉, RAG의 품질은 모델보다도 파서·청킹·메타데이터·실행 오케스트레이션에서 결정된다는 철학이 코드 구조에 반영되어 있다.

Implementation-Relevant Caveats (Discussions에서 읽히는 포인트)

1) Citation highlight는 positional metadata 의존적이다

  • 커뮤니티 논의에 따르면, 수동으로 추가한 chunk는 원문 하이라이트가 되지 않을 수 있다.
  • 이유는 원문 위치를 가리키는 positions 메타데이터가 없기 때문이다.
  • 의미: 문서를 후처리로 수정하거나 커스텀 파이프라인을 붙일 때도, 원문 span 좌표를 잃지 않도록 설계해야 한다.

2) Langfuse trace는 기본적으로 조각날 수 있다

  • Discussion 상에서 chat / encode / stream 단계가 별도 trace로 보이는 사례가 보고되었다.
  • 기본적으로 하나의 계층형 trace로 자동 결합되지 않으므로, 공유 trace ID propagation이 필요한 운영 환경이 있다.
  • 의미: 관측성을 중요하게 보는 팀이라면 tracing context를 애플리케이션 레벨에서 강제해야 한다.

3) Chunking은 “튜닝 포인트”가 아니라 사실상 핵심 모델링 변수다

  • 커뮤니티에서 chunking parameter optimizer를 따로 만든 사례가 있다.
  • 이는 RAGFlow가 실제로 chunking을 retrieval 품질의 1급 변수로 취급하고 있음을 보여준다.
  • 의미: 도메인 적용 시 가장 먼저 손댈 것은 LLM 교체보다 chunk schema / section policy / metadata 설계다.

Usage & Setup

A. 가장 빠른 시작: Docker Compose

요구사항

  • CPU: 4 cores 이상
  • RAM: 16GB 이상
  • Disk: 50GB 이상
  • Docker: 24.0.0 이상
  • Docker Compose: 2.26.1 이상
  • 시스템 설정: vm.max_map_count >= 262144

핵심 명령

# Linux 예시
sudo sysctl -w vm.max_map_count=262144

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

# 주요 설정 파일:
# - .env
# - service_conf.yaml.template
# - docker-compose.yml
#
# 모델/임베딩/API key 등은 service_conf.yaml.template 기준으로 먼저 점검

docker compose -f docker-compose.yml up -d

첫 부팅 전에 꼭 볼 파일

  • docker/.env
  • docker/service_conf.yaml.template
  • docker/docker-compose.yml

운영 시 알아두면 좋은 설정 포인트

  • 문서 엔진 전환: DOC_ENGINE=infinity
  • 기본 이미지 태그: infiniflow/ragflow:v0.24.0
  • 기본 TEI embedding model: Qwen/Qwen3-Embedding-0.6B
  • 기본 포트 예시
    • Web HTTP: 80
    • Web HTTPS: 443
    • Python API: 9380
    • Admin HTTP: 9381
    • MCP: 9382
    • Go HTTP: 9384
    • Go Admin: 9383

접근

  • 배포 후 브라우저에서 http://<YOUR_MACHINE_IP> 형태로 접속

B. 소스 기반 개발 모드

pipx install uv pre-commit

git clone https://github.com/infiniflow/ragflow.git
cd ragflow

uv sync --python 3.12
uv run download_deps.py
pre-commit install

docker compose -f docker/docker-compose-base.yml up -d

# /etc/hosts 예시
# 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager

source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

cd web
npm install
npm run dev

개발 모드 팁

  • Hugging Face 접근이 느리거나 막힌 환경에서는 HF_ENDPOINT=https://hf-mirror.com 같은 우회 설정이 문서에 언급된다.
  • sandbox code executor를 쓸 계획이면 격리 런타임(gVisor 등)과 권한 모델을 함께 검토하는 편이 좋다.
  • 이 프로젝트는 서비스 수가 많기 때문에, 로컬 개발이라도 “단일 프로세스 앱”처럼 생각하면 오히려 디버깅이 어려워진다.

실무 적용 시 추천 체크리스트

  1. 문서군별 parser/청킹 정책 분리
    • 연구 논문 / 기술문서 / SOP / 매뉴얼 / FAQ를 같은 chunk rule로 처리하지 말 것
  2. metadata schema 먼저 설계
    • source, section, page, figure_id, table_id, positions, language, tenant 등
  3. 평가셋부터 만들기
    • retrieval hit-rate, citation accuracy, answer faithfulness를 문서군별로 측정
  4. observability 통일
    • trace ID / request ID / document ID를 ingestion~generation까지 이어줄 것
  5. 엔진 선택 기준 명확화
    • small-scale 실험, multi-tenant 운영, 고빈도 업데이트, 대용량 batch ingestion의 요구가 각각 다르다

Personal Insights

1) 의료 AI 관점에서 주는 영감

RAGFlow는 의료 문서 QA/clinical copilot을 만드는 팀에게 꽤 좋은 참조 구조다.

  • 병원/제약/의료기기 문서는 PDF 스캔본, 프로토콜, 라벨, SOP, 표, 그림, 첨부문서가 섞여 있다.
  • 따라서 “텍스트만 잘 읽는 LLM”보다 문서를 어떻게 구조적으로 읽고 citation을 보존하느냐가 더 중요하다.
  • RAGFlow의 deepdoc/ + citation 지향 구조는 다음 과제에 직접 연결된다.
    • 임상시험 프로토콜 QA
    • IFU/라벨/규제 문서 검색
    • 약물 용량표 / 이상반응표 / inclusion-exclusion criteria 추출
    • 위원회/감사 대응용 근거 추적형 답변

내가 의료 AI에 적용한다면

  • chunk 기준을 일반 문단이 아니라 section semantics(Indications, Contraindications, Methods, Safety, Dosage 등)로 재설계한다.
  • citation metadata에 page, paragraph, table cell, figure caption을 강제한다.
  • PHI/PII 처리 때문에 memory는 원문 저장이 아니라 비식별 요약 memory 위주로 제한한다.
  • 정답률보다도 근거 정확성 / 인용 위치 정확성 / human review friendliness를 우선 지표로 둔다.

2) Bioinformatics 관점에서 주는 영감

Bioinformatics는 논문, supplementary tables, assay SOP, pipeline notes, wet-lab protocol, notebook export, 엑셀 시트가 뒤섞인다는 점에서 RAGFlow의 강점과 잘 맞는다.

  • 표와 figure를 텍스트로만 취급하지 않는 parser 철학은 supplementary material-heavy한 바이오 문서 환경에서 유용하다.
  • cross-language retrieval, metadata filtering, GraphRAG/advanced RAG 경로는 다음 같은 문제에 영감을 준다.
    • gene/protein/disease 관계 질의
    • 실험 프로토콜 검색
    • cohort criteria 문서 탐색
    • multi-omics 분석 파이프라인 문서화/회수

내가 바이오인포에 적용한다면

  • 엔티티 정규화 레이어(HGNC, UniProt, MeSH, DOID 등)를 retrieval 이전 단계에 붙인다.
  • chunk를 길이 기준이 아니라 biological unit 기준(gene set, pathway block, methods step, sample processing stage)으로 자른다.
  • 표/보충자료 parser 품질을 별도 벤치마크하고, citations는 문장보다 table/figure anchor 중심으로 설계한다.

3) Autonomous Agent 관점에서 주는 영감

이 저장소가 가장 강하게 던지는 메시지는 다음이다.

“좋은 에이전트는 도구 호출을 잘하는 모델이 아니라, 신뢰할 수 있는 context layer 위에서 작동하는 시스템이다.”

이 관점에서 RAGFlow는 좋은 참조 구현이다.

  • agent/의 컴포넌트화
  • memory/의 분리
  • mcp/ 통합
  • sandboxed code execution
  • UI canvas 기반 workflow 조립
  • retrieval과 generation 사이에 여러 제어 지점을 두는 설계

내가 에이전트 제품을 만든다면 여기서 가져갈 것

  • retrieval, tool use, memory, observability를 각각 독립 모듈로 유지한다.
  • “채팅창”보다 “workflow graph”를 먼저 설계한다.
  • trace stitching, provenance, sandbox isolation을 MVP 단계부터 넣는다.
  • agent memory는 “아무거나 저장”이 아니라, 검증된 요약/의도/상태 전이만 저장한다.

4) 개인적 결론

RAGFlow의 진짜 가치는 UI가 아니라 다음에 있다.

  • 문서 이해를 1급 문제로 본다
  • chunking/metadata를 제품 중심부에 둔다
  • RAG를 agent runtime과 결합한다
  • 플랫폼형 구조로 확장성을 확보한다

따라서 이 저장소를 참고할 때는 “그대로 복제”보다 아래를 가져가는 것이 더 유익하다.

  1. 파서-청킹-인덱싱-추론-에이전트의 경계 정의
  2. 근거 추적성과 metadata discipline
  3. 도메인별 chunk template 설계
  4. 운영형 observability / evaluation 설계

Figures Included in This Archive

  • figures/ragflow-octoverse.png — 프로젝트 배너/컨셉 이미지
  • figures/architecture.png — 공식 README 아키텍처 다이어그램
  • figures/chunking.gif — chunking/UI 데모
  • figures/agentic-dark.gif — agentic workflow/UI 데모

Source Map (분석 근거로 삼은 주요 링크)

프로젝트/문서

핵심 파일

Discussions (구현 관점에서 중요했던 것)

Final Takeaway

RAGFlow를 한 문장으로 정리하면, “문서 이해와 에이전트 실행을 함께 다루는 RAG 플랫폼 레퍼런스”다.

  • 단순 챗봇 예제를 찾는 사람에게는 다소 무겁다.
  • 하지만 의료 AI, 바이오인포매틱스, 규제 대응형 엔터프라이즈 QA, 에이전트 제품을 만들려는 팀에게는 매우 좋은 설계 참고서가 될 수 있다.
  • 특히 배울 포인트는 모델 선택보다도 parser 설계, chunking 정책, metadata 보존, traceable citation, workflow orchestration이다.

'AI 생성 글 정리 > tech_github' 카테고리의 다른 글

Unsloth — unified local interface for running and training AI models  (0) 2026.04.08
Understudy — GUI·브라우저·셸·메시징을 한 세션에서 묶는 로컬 퍼스트 컴퓨터 에이전트  (0) 2026.04.08
Dify — 프로덕션 지향 Agentic Workflow / LLM App 플랫폼  (0) 2026.04.08
Paperclip — “자율 AI 회사”를 운영하기 위한 오픈소스 control plane  (0) 2026.04.08
Oh My OpenAgent — OpenCode용 멀티모델 에이전트 오케스트레이션 하네스  (0) 2026.04.07

관련글

티스토리툴바