RAG on ApexCaptain의 기술 블로그

오프라인 환경에서 RAG 앱 동작시키기

Thu, 09 Oct 2025 12:00:00 +0900

연관 포스트

Docling이란?

문제의 시작

회사에서 간단한 RAG 애플리케이션 을 하나 만들라는 지시를 받았다.

여기엔 몇 가지 단서조항이 포함되어 있었는데, 문제가 되는 부분은 다음과 같다.

운영 환경은 Windows 11 노트북
네트워크에 연결되지 않은 상태 에서 동작해야 함
Docker Desktop 설치하면 안 됨
중국 기업에서 나온 모델은 사용하면 안 됨
- 예를들어
  1. DeepSeek
  2. QWEN

추석 연휴동안 작업 하려고 허락 받고 아예 집에 가져왔다.

노트북 사양

CPU/메모리는 괜찮다. 특히 메모리는 무려 64GB나 된다!
문제는 그래픽 카드인데, VRAM이 8GB 밖에 되지 않는다.

폐쇄망

이번 프로젝트에서 가장 큰 걸림돌이 바로 이것이다.

네트워크가 안 되는 환경에서 구동 되어야 할 것

Ollama처럼 단순히 LLM을 설치하고 명령 받아서 처리만 해주는 컨테이너의 경우, 외부에서 제어만 잘 해주면 별다른 문제가 없겠으나 Docling처럼 AI가 애플리케이션 내부로 들어가서 겉에서 한 번 Wrapping된 형태라면 Offline 기능을 제공해주지 않는 이상 구현이 요원해진다.

해결방안

컨테이너 구성

우선 전체적으로 컨테이너가 어떻게 구성되어 있는지 정리해두었다.

Host OS가 Windows인 관계로, WSL 및 Docker와 Docker-Compose를 사용해서 컨테이너 환경을 마련했다.

단서조항에 Docker Desktop은 설치하면 안 됨이 있어서 Ubuntu 위에 직접 설치했다.

Application
- Web: React 기반의 웹 애플리케이션
- Backend: NestJs 기반의 API 서버
Infrastructure
- Ollama
  - Image: ollama/ollama
  - 용도: 텍스트 생성 / Embedding
  - 사용된 모델
    - 텍스트 생성: joonoh/HyperCLOVAX-SEED-Text-Instruct-1.5B:latest
    - 임베딩: bona/bge-m3-korean:latest
  - GPU 가속 : O
- Docling
  - Image: quay.io/docling-project/docling-serve
    
    이 이미지는 CPU Only 모드로만 동작하는 Docling 컨테이너 이미지이다.
    GPU 가속이 가능한 이미지로도 써봤는데, VRAM 제한 때문에 CUDA Out of Memory 이슈와 함께 먹통이 되어버렸다.
    
    결국 이 프로젝트에서 GPU는 Ollama 컨테이너만 쓰는 것으로 타협을 봤다.
    VRAM에 여유가 있다면 다음의 Docker Image 중 하나를 골라 쓰면 된다.
    - quay.io/docling-project/docling-serve-cu126: CUDA 12.6
    - quay.io/docling-project/docling-serve-cu128: CUDA 12.8
  - 용도: Embedding 전처리
  - 사용된 모델
    - ds4sd/CodeFormulaV2: 수학 공식 분석
    - HuggingFaceTB/SmolVLM-256M-Instruct: 이미지 분석
    - sentence-transformers/all-MiniLM-L6-v2: 문서 Chunking
  - GPU 가속 : X
- Chroma
  - Image: chromadb/chroma
  - 용도: VectorStore
Management
- Watchtower: 컨테이너 자동 업데이트
- AutoHeal: HealthCheck Fail시 컨테이너 자동 리스타트

이미지에 AI Model을 내장하기

이번 문제의 핵심을 다시 한 번 요약하면 다음과 같다.

RAG 애플리케이션을 Offline 상태의 노트북 1개에서 동작시켜야 한다.
여기서 핵심이 되는 컨테이너는 Ollama와 Docling이다.
두 컨테이너는 모두 AI 모델을 동적으로 다운받아 동작하는 것을 기본으로 한다.

그럼, Ollama와 Docling에서 사용할 모델을 Docker Image에 내장하면 그만인 것 아닐까?

방법 1) Docker Image에 모델 내장해서 올리기

우선 아예 모델 다운로드가 포함된 Image를 만들어서 Registry에 올려보았다.

10GB가 넘는다. 심지어 필요한 모든 모델을 다 담은 것도 아니다.

당연한 얘기지만, 모델이 포함된 만큼 정직하게 크기가 늘어나버렸다.
이게 비단 Docker 이미지가 좀 무거워졌다 수준의 문제가 아니다.

CI/CD 파이프라인이 전반적으로 다 느려진다.
이렇게 생성된 Image는 클라우드에서 제공하는 Container Registry에 올라가는데, 용량 때문에 비용 걱정도 해야 한다.

방법 2) 빌드 타임에 AI 모델을 다운받도록 변경

생각해보니, 굳이 Image Registry에 올릴 필요는 없었다.

Offline 환경에서 동작해야 한다이지,
Offline 환경에서 설치해야 한다의 개념은 아니지 않은가.

Docker Compose에 image 대신 build를 넣고 아예 Dockerfile 자체를 정의해주면 그만이다.

그렇게 해서 나온 결과는 다음과 같다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


# docker-compose.yml
services:

 # ...... #

 # Infrastructure Services
 ollama:
 build:
 context: ./build/ollama
 dockerfile: Dockerfile
 container_name: ollama
 restart: unless-stopped

 # Docker Compose에서 GPU를 할당할 땐 이런식으로 한다.
 deploy:
 resources:
 reservations:
 devices:
 - driver: nvidia
 count: all
 capabilities: [gpu]
 volumes:
 - Ollama.Data:/root/.ollama
 logging:
 options:
 max-size: 50m

 docling:
 container_name: docling
 build:
 context: ./build/docling
 dockerfile: Dockerfile
 restart: unless-stopped
 environment:
 DOCLING_SERVE_ENABLE_UI: 'false'

 # (매우 중요!) 이 항목이 없으면 모델을 내장시켜도 Offline에서 자꾸 에러가 난다.
 HF_HUB_OFFLINE: 1
 logging:
 options:
 max-size: 50m

 # ...... #

volumes:
 Ollama.Data:

build 디렉토리는 docker-compose.yml과 같은 경로에 배치 해두었다.
build 디렉토리 내부 구조는 다음과 같다.

1
2
3
4
5
6


build
├── docling
│   └── Dockerfile
└── ollama
 ├── Dockerfile
 └── entrypoint.sh

각 파일들은 다음과 같이 작성했다.

build/docling/Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


FROM quay.io/docling-project/docling-serve-cpu

# Docling의 기본 모델 다운로드
RUN docling-tools models download

# Hybrid Chunker용 추가 모델 다운로드
RUN python3 -c "from transformers import AutoTokenizer, AutoModel; \
 AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2'); \
 AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2');"

# 공식/이미지 분석용 모델 다운로드
RUN docling-tools models \
 download-hf-repo \
 ds4sd/CodeFormulaV2 \
 HuggingFaceTB/SmolVLM-256M-Instruct 

EXPOSE 5001

build/ollama/Dockerfile

1
2
3
4
5
6
7
8
9


FROM ollama/ollama

COPY ./entrypoint.sh /entrypoint.sh

RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

EXPOSE 11434

Ollama는 Ollama 서버가 실행되고 나서야 모델을 받을 수 있으므로, 별도의 Entrypoint를 추가해줬다.

build/ollama/entrypoint.sh

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


#!/bin/bash

set -e

echo "Starting Ollama server..."
ollama serve & # 백그라운드에서 Ollama 실행
SERVER_PID=$!

echo "Waiting for Ollama server to be active..."
until ollama list >/dev/null 2>&1; do # Ollama process가 정상적으로 동작 될 때까지 대기
sleep 1
done

echo "Pulling models..."
# For embedding
ollama pull bona/bge-m3-korean:latest || true
# For text generation
ollama pull joonoh/HyperCLOVAX-SEED-Text-Instruct-1.5B:latest || true

trap "kill -TERM $SERVER_PID" SIGTERM SIGINT
wait $SERVER_PID

마치며

위 방법 2를 사용해서 Offline에서도 임베딩부터 텍스트 생성까지 정상 동작하는게 확인되었다.

“Docling이란?” 포스트의 동작 테스트 문단에 실제로 테스트 한 영상을 올려두었다.

Docling이란?

Thu, 09 Oct 2025 00:00:00 +0900

연관 포스트

오프라인 환경에서 RAG 앱 동작시키기

RAG(Retrieval-Augmented Generation, 검색 증강 생성)

인공지능 시스템을 구축할 때, AI 모델(이하 LLM)에게 회사 내부 문서와 같이 사전에 학습되지 않은 정보를 활용한 답변을 기대한다고 생각해보자.

1~2개 정도의 PDF 파일이라면 통째로 첨부해서 사용해도 상관 없겠지만,
수십, 수백 개의 문서들을 모조리 LLM에게 입력할 수는 없는 노릇이다.

이 문제를 해결하고자 나온 방법론 중 하나가 바로 RAG이다.
RAG의 정의는 다음과 같다.

LLM의 출력을 최적화하여 응답을 생성하기 전에 훈련 데이터 소스 외부의 신뢰할 수 있는 기술 자료를 참조하도록 하는 프로세스

소스가 되는 문서(가령 PDF 파일)를 AI가 쉽고 빠르게 관련성을 유추할 수 있는 형태의 데이터(vector)로 변환하고, 사용자의 질문(query)에 맞춰 검색된 데이터를 가져와(retrieving) prompt의 context로 넣어서 동작한다.

이렇게 문자나 이미지같은 복잡한 데이터를 LLM이 이해하고 처리하기 쉬운 숫자 형태의 Vector로 변환하는 과정 혹은 변환된 결과물 그 자체를 Embedding이라고 하며, 그러한 작업을 수행하는 AI Model을 Embedding Model이라고 한다.

Embedding Model이 하는 일은 다음과 같다.

텍스트/이미지 등을 Vector로 변환, VectorStore_{(혹은 Vector DB라고도 한다)} 에 저장
사용자의 Query를 Vector로 변환, VectorStore에서 유사한 값들을 검색(Retrieval)

Embedding 전처리

Chunking

Embedding Model이 VectorStore에서 문서 데이터를 가져올 때, 가져온 결과 하나하나는 특별한 사유가 없는 한 있는 그대로 LLM에 전달된다.

만일 텍스트로만 이루어진 어떤 문서의 글자 수가 5,000개이고, 이 5,000개가 한 덩어리로 VectorStore에 저장되어 있다면 LLM은 엄청난 크기의 Context에 적지 않은 부담을 지게 될 것이다. _{(혹은 당신의 지갑이…)}

이에 따라 VectorStore에 문서를 저장할 땐 어떠한 방식으로든 원문을 잘게 잘라(chunking),
사용자 Query와의 관련성은 유지하면서 불필요하게 많은 Context가 사용되는 일은 피하게 할 필요가 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[
 {
 "pageContent": "하지만 무작정 글자 수나 Token 수에 맞춰"
 },
 {
 "pageContent": "잘랐다가는, 이렇게 하나의 문장이 다 끝나"
 },
 {
 "pageContent": "기도 전에 잘려진 조각이 만들어질 것이다."
 }
]

이와 같은 문제를 막겠다고 일부러 각 조각들 간 겹치는 부분을 만드는 게 일반적이나, 근본적인 해결책은 아니다.

구조 분석

더욱이 원문이 PDF와 같이 구조화된 형태일 경우(이미지, 그래프, 테이블, 수식 등), 단순하게 텍스트만 추출하고
구조는 무시해버린다면 최종적으로 LLM이 답변을 낼 때 전혀 엉뚱한 소리를 하는 경우가 생긴다.

이런 식으로 Text로만 이루어진 경우는 오히려 드물다

Embedding 과정은 전통적으로

원본 파일에서 Text만 추출
Token 수에 맞춰 쪼개기
Text를 Vectorizing
VectorStore에 저장

이렇게 단순하게 이루어져 왔었다. 3/4번은 Embedding 모델이 하는 것이므로 여기선 논하지 않겠다.
문제는 1/2번인데, 앞서 언급했듯 이렇게 텍스트만 추출하게 되면 원본 문서가 가지고 있던 구조적 특징이 유실되는 문제가 있다.

PDF Parser나 OCR 같은 도구들을 활용해서 보완할 수는 있겠으나, PDF는 일반적으로 생각하는 것보다
훨씬 복잡한 형태가 많고, 이를 완벽하게 추출해내는 것은 아직도 매우 어렵다.

Docling(도클링)이란?

Docling은 IBM Research에서 개발한 생성형 AI 애플리케이션을 위한 문서 처리 및 변환을 위한 오픈소스 툴킷이다.
MIT 라이선스로 공개되어 있어 상업적으로도 자유롭게 활용할 수 있다.

앞서 얘기한 Embedding 전처리 과정에서 생기는 문제점을 해결하고자 나온 오픈소스로,
자체적인 인공지능 모델을 활용해 원본 문서를 분석/변환/Chunking 해준다.

제공해주는 기능은 GitHub에 보다 잘 정리되어 있다.
기본적으로 다양한 문서 포맷을 지원하고, Page Layout, Order, Table 등을 해석할 수 있으며, LangChain과 쉽게 통합 가능한 것이 특징이다.

현재 이 글을 쓰고 있는 시점을 기준으로 언급된 기능들은 다음과 같다.

🗂️ Parsing of multiple document formats incl. PDF, DOCX, PPTX, XLSX, HTML, WAV, MP3, VTT, images (PNG, TIFF, JPEG, …), and more
📑 Advanced PDF understanding incl. page layout, reading order, table structure, code, formulas, image classification, and more
🧬 Unified, expressive DoclingDocument representation format
↪️ Various export formats and options, including Markdown, HTML, DocTags and lossless JSON
🔒 Local execution capabilities for sensitive data and air-gapped environments
🤖 Plug-and-play integrations incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI
🔍 Extensive OCR support for scanned PDFs and images
👓 Support of several Visual Language Models (GraniteDocling)
🎙️ Audio support with Automatic Speech Recognition (ASR) models
🔌 Connect to any agent using the MCP server
💻 Simple and convenient CLI

다른 솔루션들과의 비교

문서 변환은 오랫동안 논의된 주제로, 이미 많은 솔루션이 존재한다. 최근 널리 사용되는 방식은 크게 두 가지로 나뉜다.

1. VLM(Visual Language Model) 기반 솔루션

Closed-source: GPT-4, Claude, Gemini
Open-source: LLaVA 기반 모델들

이러한 생성 모델 기반 솔루션은 강력하지만 다음과 같은 문제점이 있다:

할루시네이션(Hallucination): 문서 변환 시 정확성이 중요한데, 모델이 존재하지 않는 내용을 생성할 수 있다
높은 계산 비용: 대규모 모델을 사용하기 때문에 비용이 매우 비싸고 비효율적이다

2. Task-specific 모델 기반 솔루션

대표 사례: Adobe Acrobat, Grobid, Marker, MinerU, Unstructured
Docling의 접근 방식도 여기에 해당

이 방식은 OCR, 레이아웃 분석, 테이블 인식 등 특화된 모델들을 조합하여 사용한다.

장점: 할루시네이션 문제가 적고, 정확하고 예측 가능한 변환 결과를 보장
단점: 상대적으로 커버리지가 작고, 다양한 특화 모델을 유지해야 하는 복잡성

Docling의 아키텍처

Docling은 크게 3가지 주요 컴포넌트로 구성되어 있다:

Pipelines: 문서 처리 파이프라인
Parser Backends: 다양한 문서 형식 처리기
DoclingDocument: Pydantic 기반의 통합 문서 표현 모델

Pipeline의 종류

1. StandardPdfPipeline

PDF 및 이미지 입력을 DoclingDocument 형태로 변환하는 파이프라인
여러 AI 모델들을 단계적으로 사용하여 정보를 구조화
다음과 같은 특화 모델들을 활용:
- Layout Analysis Model: 페이지 내 각 요소들의 위치와 레이아웃 분석
- TableFormer: 테이블 구조를 인식하고 복원 (행/열 정보 보존)
- OCR Engine: 스캔된 문서나 이미지 내 텍스트 추출

2. SimplePipeline

PDF를 제외한 다른 문서 형식(DOCX, PPTX, HTML 등)을 처리
상대적으로 단순한 구조로, 빠른 처리가 가능

이러한 모듈 형태의 설계 덕분에 필요에 따라 각 단계를 교체하거나 확장할 수 있는 유연성을 제공한다.

동작 테스트

오프라인 환경에서 RAG 앱 동작시키기 포스트에서 작업한 내용을 이쪽으로 가져왔다.

테스트에 사용된 파일은 영화진흥위원회에서 공개한 25년 8월 영화산업 결산 보고서 PDF의 일부이다.

텍스트 생성에 쓰인 LLM은 joonoh/HyperCLOVAX-SEED-Text-Instruct-1.5B:latest로
예시로 쓰인 2025년 8월 대한민국 외국영화 흥행작 상위 10위에 대한 정보는 모델에 사전 학습되어 있는 것이 아니다.
임베딩
텍스트 생성 테스트

마치며

프로젝트 제한사항으로 인해 Docling에서 GPU 가속을 못 쓰다 보니, 전반적으로 만족스러운 속도는 아니었다.
하지만, 표 등이 포함된 소스 파일에서 단순한 텍스트 추출만 해서는 LLM이 이해할 수 있는 형태로
전달되지 않았던 문제를 해결할 수 있는 좋은 방법이라고 생각한다.

장단점 정리

장점:

VLM 기반 솔루션 대비 훨씬 저렴한 비용
MIT 라이선스로 상업적 활용 자유
LangChain, LlamaIndex 등 주요 프레임워크와의 쉬운 통합
오프라인 환경(Air-gapped)에서도 사용 가능
Mac에서 MPS device를 활용한 빠른 처리 지원

단점:

Runtime에 실시간으로 사용하기보단 RAG 인덱싱용으로 적합
VLM 대비 상대적으로 제한적인 커버리지

권장 사용 사례

Docling은 다음과 같은 경우에 특히 유용하다:

RAG 시스템을 위한 문서 인덱싱 작업
테이블이나 복잡한 레이아웃이 포함된 PDF 처리
정확성이 중요한 문서 변환 작업
비용 효율적인 문서 처리 파이프라인 구축

이제까지 PDF Parser 같은 기본적인 라이브러리만 사용해봤다면, 한 번 결과를 보고 도입을 고려해봐도 괜찮을 것 같다.

취향에 따라 Docker Container로 혹은 Python script에 모듈을 설치해 Import할 수도 있고, 아예 CLI로 동작시킬 수도 있다.