PrivateGPT Docker 설치 가이드: 프라이빗 문서 AI 시스템 ⋆ Blog * JackerLab

개요

PrivateGPT는 100% 프라이빗한 문서 기반 AI 시스템입니다. 문서를 업로드하고 LLM에게 질문하면, 데이터가 외부로 유출되지 않고 완전히 로컬에서 처리됩니다. 인터넷 연결 없이 오프라인에서도 동작하며, OpenAI API 표준을 따르는 프로덕션 레디 RAG 파이프라인을 제공합니다.

항목	내용
GitHub	https://github.com/zylon-ai/private-gpt
문서	https://docs.privategpt.dev
라이선스	Apache-2.0
GitHub Stars	55K+
엔터프라이즈	Zylon.ai

PrivateGPT란?

왜 PrivateGPT인가?

❌ 일반 ChatGPT 문제점:
   - 기밀 문서를 업로드하면 외부 서버로 전송
   - 데이터 유출 위험
   - 인터넷 필수

✅ PrivateGPT 장점:
   - 100% 로컬 처리, 데이터 유출 없음
   - 인터넷 없이 오프라인 동작
   - 기업 내부 문서, 기밀 자료 안전하게 분석
   - OpenAI API 호환

핵심 철학

"100% 프라이빗, 데이터 유출 없음"
- 모든 처리가 로컬에서 수행
- 인터넷 연결 불필요
- 에어갭(Air-Gapped) 환경 지원
- 온프레미스/프라이빗 클라우드 배포

아키텍처

┌─────────────────────────────────────────────┐
│                PrivateGPT                    │
├─────────────────────────────────────────────┤
│  FastAPI (OpenAI 호환 API)                   │
├─────────────────────────────────────────────┤
│  LlamaIndex (RAG 파이프라인)                 │
├──────────────┬──────────────┬───────────────┤
│   LLM        │  Embeddings  │  Vector Store │
│ (Ollama 등)  │              │  (Qdrant 등)  │
└──────────────┴──────────────┴───────────────┘

주요 기능

📄 문서 수집 (Ingestion)

기능	설명
파싱	PDF, Word, 텍스트, 마크다운 등
청킹	문서를 적절한 크기로 분할
임베딩	벡터 임베딩 생성
저장	벡터 데이터베이스에 저장

💬 채팅 & 질의

기능	설명
RAG 채팅	문서 기반 컨텍스트 답변
소스 인용	답변에 사용된 문서 출처 표시
스트리밍	실시간 응답 스트리밍
컨텍스트 없는 채팅	일반 LLM 채팅

📝 요약 (Summarize)

기능	설명
문서 요약	수집된 문서 자동 요약
커스터마이징	요약 스타일 조정
스트리밍	실시간 요약 생성

🔌 API

엔드포인트	설명
`/v1/chat/completions`	OpenAI 호환 채팅
`/v1/completions`	텍스트 완성
`/v1/embeddings`	임베딩 생성
`/v1/ingest`	문서 수집
`/v1/chunks`	청크 조회

🎨 WebUI

내장 웹 인터페이스
문서 업로드
채팅 인터페이스
시스템 정보

지원 컴포넌트

LLM 백엔드

백엔드	설명
Ollama	로컬 LLM (권장)
llama.cpp	직접 GGUF 실행
OpenAI	GPT-4 등
Azure OpenAI	Azure 호스팅
Gemini	Google AI
Anthropic	Claude
vLLM	고성능 추론

임베딩

백엔드	설명
Ollama	nomic-embed-text 등
HuggingFace	sentence-transformers
OpenAI	text-embedding-ada-002
Azure OpenAI	–
Gemini	–

벡터 스토어

백엔드	설명
Qdrant	권장
Chroma	기본값
Postgres	pgvector
Milvus	–
ClickHouse	–

시스템 요구 사항

항목	최소	권장
CPU	4 코어	8+ 코어
RAM	8GB	16GB+
GPU	없음 (CPU 가능)	NVIDIA 8GB+ VRAM
Python	3.11+	3.11.9
포트	8080	–

Docker 설치

방법 1: Ollama + CPU (가장 간단)

# 저장소 클론
git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt

# CPU 프로파일로 실행
docker compose --profile ollama-cpu up -d

접속: http://localhost:8080

방법 2: Ollama + GPU (NVIDIA CUDA)

git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt

# CUDA 프로파일로 실행
docker compose --profile ollama-cuda up -d

방법 3: 완전 로컬 (llama.cpp)

git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt

# llama.cpp 프로파일 (Ollama 없이)
docker compose --profile local up -d

방법 4: Docker Compose 직접 작성 (CPU)

# docker-compose.yml
services:
  privategpt:
    image: zylonai/private-gpt:0.6.2-ollama-cpu
    container_name: privategpt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./local_data:/home/worker/app/local_data
    environment:
      - PGPT_PROFILES=ollama
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    container_name: privategpt-ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ./ollama:/root/.ollama

방법 5: Docker Compose (GPU)

# docker-compose.yml
services:
  privategpt:
    image: zylonai/private-gpt:0.6.2-ollama-cuda
    container_name: privategpt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./local_data:/home/worker/app/local_data
    environment:
      - PGPT_PROFILES=ollama
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    container_name: privategpt-ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ./ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

방법 6: llama.cpp 직접 실행 (CPU)

# docker-compose.yml
services:
  privategpt:
    image: zylonai/private-gpt:0.6.2-llamacpp-cpu
    container_name: privategpt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./local_data:/home/worker/app/local_data
      - ./models:/home/worker/app/models
    environment:
      - PGPT_PROFILES=local

방법 7: 외부 Ollama 연결

# docker-compose.yml
services:
  privategpt:
    image: zylonai/private-gpt:0.6.2-ollama-cpu
    container_name: privategpt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./local_data:/home/worker/app/local_data
    environment:
      - PGPT_PROFILES=ollama
      - OLLAMA_API_BASE=http://your-ollama-server:11434
    extra_hosts:
      - "host.docker.internal:host-gateway"

방법 8: Qdrant 벡터 스토어

# docker-compose.yml
services:
  privategpt:
    image: zylonai/private-gpt:0.6.2-ollama-cpu
    container_name: privategpt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./local_data:/home/worker/app/local_data
    environment:
      - PGPT_PROFILES=ollama
      - VECTORSTORE__DATABASE=qdrant
      - QDRANT__URL=http://qdrant:6333
    depends_on:
      - ollama
      - qdrant

  ollama:
    image: ollama/ollama:latest
    container_name: privategpt-ollama
    restart: unless-stopped
    volumes:
      - ./ollama:/root/.ollama

  qdrant:
    image: qdrant/qdrant:latest
    container_name: privategpt-qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
    volumes:
      - ./qdrant_data:/qdrant/storage

환경 변수

프로파일

변수	설명	값
`PGPT_PROFILES`	실행 프로파일	`ollama`, `local`, `openai`

LLM 설정

변수	설명
`LLM__MODE`	LLM 모드 (`ollama`, `llamacpp`, `openai`)
`LLM__MODEL`	사용할 모델
`OLLAMA__API_BASE`	Ollama 서버 URL
`OLLAMA__LLM_MODEL`	Ollama LLM 모델
`OLLAMA__EMBEDDING_MODEL`	Ollama 임베딩 모델

임베딩 설정

변수	설명
`EMBEDDING__MODE`	임베딩 모드
`EMBEDDING__MODEL`	임베딩 모델

벡터 스토어

변수	설명
`VECTORSTORE__DATABASE`	벡터DB (`chroma`, `qdrant`, `postgres`)
`QDRANT__URL`	Qdrant 서버 URL
`POSTGRES__URL`	PostgreSQL 연결 문자열

서버 설정

변수	설명	기본값
`PORT`	서버 포트	`8080`
`CORS_ENABLED`	CORS 활성화	`false`
`CORS_ALLOW_CREDENTIALS`	CORS 자격 증명	`false`

모델 설정 (llama.cpp)

변수	설명
`LLAMACPP_LLM_HF_REPO_ID`	HuggingFace 모델 리포
`LLAMACPP_LLM_HF_MODEL_FILE`	모델 파일명
`LLAMACPP_EMBEDDING_HF_REPO_ID`	임베딩 모델 리포

초기 설정

1) 첫 접속

URL: http://localhost:8080
→ WebUI 자동 로드

2) 모델 다운로드 (Ollama 사용 시)

Docker Compose로 시작하면 기본 모델이 자동 다운로드됩니다:

LLM: llama3.1 (또는 설정된 모델)
Embeddings: nomic-embed-text

수동 다운로드:

docker exec privategpt-ollama ollama pull llama3.2
docker exec privategpt-ollama ollama pull nomic-embed-text

3) 문서 업로드

WebUI에서:

좌측 사이드바 → Upload 영역
파일 드래그 앤 드롭 또는 클릭
지원 형식: PDF, DOCX, TXT, MD 등

API로:

curl -X POST "http://localhost:8080/v1/ingest/file" \
  -F "file=@document.pdf"

4) 질문하기

WebUI에서:

채팅 입력창에 질문 입력
“Use context” 토글로 RAG 활성화/비활성화

API로:

curl -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "이 문서의 핵심 내용은?"}],
    "use_context": true
  }'

API 사용 예시

문서 수집

# 파일 업로드
curl -X POST "http://localhost:8080/v1/ingest/file" \
  -F "file=@report.pdf"

# 텍스트 직접 수집
curl -X POST "http://localhost:8080/v1/ingest/text" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "notes.txt",
    "text": "이것은 테스트 문서입니다..."
  }'

RAG 채팅

# 문서 컨텍스트 사용
curl -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "2024년 매출 실적을 알려줘"}
    ],
    "use_context": true,
    "include_sources": true
  }'

일반 채팅 (컨텍스트 없음)

curl -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Python에서 리스트를 정렬하는 방법은?"}
    ],
    "use_context": false
  }'

문서 요약

curl -X POST "http://localhost:8080/v1/summarize" \
  -H "Content-Type: application/json" \
  -d '{
    "use_context": true,
    "prompt": "다음 문서를 3줄로 요약해주세요"
  }'

임베딩 생성

curl -X POST "http://localhost:8080/v1/embeddings" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "임베딩을 생성할 텍스트"
  }'

수집된 문서 조회

# 모든 문서 목록
curl "http://localhost:8080/v1/ingest/list"

# 특정 문서 삭제
curl -X DELETE "http://localhost:8080/v1/ingest/{doc_id}"

Python SDK 사용

from openai import OpenAI

# PrivateGPT 연결
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

# RAG 채팅
response = client.chat.completions.create(
    model="private-gpt",
    messages=[
        {"role": "user", "content": "문서에서 주요 결론을 알려줘"}
    ],
    extra_body={
        "use_context": True,
        "include_sources": True
    }
)

print(response.choices[0].message.content)

설정 파일

settings.yaml 또는 settings-{profile}.yaml:

# settings-ollama.yaml
server:
  port: 8080
  cors:
    enabled: false

llm:
  mode: ollama

ollama:
  api_base: http://ollama:11434
  llm_model: llama3.1
  embedding_model: nomic-embed-text

vectorstore:
  database: chroma

embedding:
  mode: ollama
  
rag:
  similarity_top_k: 5
  rerank:
    enabled: false

백업 및 업데이트

데이터 구조

./
├── local_data/          # PrivateGPT 데이터
│   ├── private_gpt/     # 벡터 스토어, 설정
│   └── ...
├── ollama/              # Ollama 모델
└── qdrant_data/         # Qdrant 데이터 (사용 시)

백업

# 컨테이너 정지
docker compose down

# 데이터 백업
tar -czvf privategpt-backup-$(date +%Y%m%d).tar.gz \
  local_data/

# 컨테이너 재시작
docker compose --profile ollama-cpu up -d

업데이트

# 최신 코드 가져오기
git pull

# 이미지 업데이트 및 재시작
docker compose --profile ollama-cpu down
docker compose --profile ollama-cpu pull
docker compose --profile ollama-cpu up -d

트러블슈팅

모델 다운로드 안 됨

# Ollama 로그 확인
docker logs privategpt-ollama

# 수동 모델 다운로드
docker exec privategpt-ollama ollama pull llama3.2

임베딩 차원 불일치

Error: Embedding dimensions mismatch

모든 문서를 다시 수집하거나, local_data 폴더 삭제 후 재시작.

GPU 인식 안 됨

# NVIDIA Container Toolkit 확인
docker run --rm --gpus all nvidia/cuda:12.0.0-base nvidia-smi

메모리 부족

작은 모델 사용:

environment:
  - OLLAMA__LLM_MODEL=llama3.2:3b

HuggingFace 게이트 모델

일부 모델은 HuggingFace 토큰이 필요:

environment:
  - HUGGINGFACE_TOKEN=hf_your_token

대안 비교

기능	PrivateGPT	AnythingLLM	Open WebUI
RAG	✅ LlamaIndex	✅ 커스텀	✅ 내장
오프라인	✅ 완전	✅	✅
API 제공	✅ OpenAI 호환	✅	❌
요약	✅ 내장	❌	❌
멀티 유저	❌ (엔터프라이즈)	✅	✅
WebUI	✅ 기본	✅ 풍부	✅ 풍부
설치 난이도	중간	쉬움	쉬움

선택 가이드

용도	추천
API 기반 RAG 시스템	PrivateGPT
간단한 문서 Q&A	AnythingLLM
채팅 UI 중심	Open WebUI
엔터프라이즈 배포	PrivateGPT + Zylon

활용 사례

1. 기업 내부 문서 Q&A

목적: 기밀 문서 기반 AI 어시스턴트

사내 정책, 매뉴얼 업로드
직원들이 자연어로 질문
데이터 외부 유출 없음

2. 법률/의료 문서 분석

목적: 민감한 문서 처리

계약서, 의료 기록 분석
완전 오프라인 운영
규정 준수 (HIPAA, GDPR 등)

3. 연구 논문 분석

목적: 학술 연구 지원

PDF 논문 대량 업로드
논문 간 연관성 질의
인용 출처 추적

4. 코드베이스 Q&A

목적: 개발 문서 이해

코드, README, 위키 수집
코드 동작 방식 질문
아키텍처 이해

5. 에어갭 환경

목적: 인터넷 없는 환경

군사/정부 시설
보안 연구실
격리된 네트워크

마무리

PrivateGPT는 프라이버시를 최우선으로 하는 문서 기반 AI 시스템입니다. 100% 로컬에서 동작하며, OpenAI API 호환으로 다양한 애플리케이션에 통합할 수 있습니다.

핵심 장점

장점	설명
100% 프라이빗	데이터가 외부로 나가지 않음
오프라인	인터넷 없이 동작
OpenAI API 호환	기존 코드 재사용
RAG 파이프라인	LlamaIndex 기반
프로덕션 레디	엔터프라이즈급
확장 가능	다양한 LLM/벡터DB 지원

이런 분께 추천

기밀 문서를 AI로 분석해야 하는 기업
데이터 유출이 우려되는 환경
오프라인/에어갭 환경
OpenAI API 호환이 필요한 개발자
RAG 시스템을 구축하려는 분

개요

PrivateGPT란?

왜 PrivateGPT인가?

핵심 철학

아키텍처

주요 기능

📄 문서 수집 (Ingestion)

💬 채팅 & 질의

📝 요약 (Summarize)

🔌 API

🎨 WebUI

지원 컴포넌트

LLM 백엔드

임베딩

벡터 스토어

시스템 요구 사항

Docker 설치

방법 1: Ollama + CPU (가장 간단)

방법 2: Ollama + GPU (NVIDIA CUDA)

방법 3: 완전 로컬 (llama.cpp)

방법 4: Docker Compose 직접 작성 (CPU)

방법 5: Docker Compose (GPU)

방법 6: llama.cpp 직접 실행 (CPU)

방법 7: 외부 Ollama 연결

방법 8: Qdrant 벡터 스토어

환경 변수

프로파일

LLM 설정

임베딩 설정

벡터 스토어

서버 설정

모델 설정 (llama.cpp)

초기 설정

1) 첫 접속

2) 모델 다운로드 (Ollama 사용 시)

3) 문서 업로드

4) 질문하기

API 사용 예시

문서 수집

RAG 채팅

일반 채팅 (컨텍스트 없음)

문서 요약

임베딩 생성

수집된 문서 조회

Python SDK 사용

설정 파일

백업 및 업데이트

데이터 구조

백업

업데이트

트러블슈팅

모델 다운로드 안 됨

임베딩 차원 불일치

GPU 인식 안 됨

메모리 부족

HuggingFace 게이트 모델

대안 비교

선택 가이드

활용 사례

1. 기업 내부 문서 Q&A

2. 법률/의료 문서 분석

3. 연구 논문 분석

4. 코드베이스 Q&A

5. 에어갭 환경

마무리

핵심 장점

이런 분께 추천

댓글 남기기 응답 취소