docuflow / docs /04-weekend2 /deployment.md
woongmin's picture
[Delta-02] 배포 체크리슀트 OpenAI νŠΈλž™μœΌλ‘œ μ—…λ°μ΄νŠΈ
99d6a79
|
Raw History Blame Contribute Delete
10.2 kB

πŸš€ DocuFlow 배포 κ°€μ΄λ“œ

πŸ“‹ 배포 μ „ 체크리슀트

1. μ½”λ“œ κ΅¬ν˜„ μ™„λ£Œ 확인

ν˜„μž¬ ν”„λ‘œμ νŠΈμ˜ 핡심 κΈ°λŠ₯듀이 아직 κ΅¬ν˜„λ˜μ§€ μ•Šμ•˜μŠ΅λ‹ˆλ‹€. 배포 전에 λ‹€μŒμ„ μ™„λ£Œν•΄μ•Ό ν•©λ‹ˆλ‹€:

βœ… [Stage: Weekend-1] 데이터 μ „μ²˜λ¦¬

  • app/embedding_utils.py - split_text() ν•¨μˆ˜ κ΅¬ν˜„
  • app/main.py - extract_text_from_pdf() ν•¨μˆ˜ κ΅¬ν˜„
  • PDF ν…μŠ€νŠΈ μΆ”μΆœ ν…ŒμŠ€νŠΈ

βœ… [Stage: Weekend-1] μž„λ² λ”© 및 벑터 μ €μž₯

  • app/embedding_utils.py - get_embedding() ν•¨μˆ˜ κ΅¬ν˜„
  • app/supabase_utils.py - save_embedding() ν•¨μˆ˜ κ΅¬ν˜„
  • 비동기 μž„λ² λ”© 처리 (μ„±λŠ₯ μ΅œμ ν™”)
  • Supabase μ—°κ²° ν…ŒμŠ€νŠΈ

βœ… [Stage: Weekend-1] RAG νŒŒμ΄ν”„λΌμΈ

  • app/supabase_utils.py - search_similar_embeddings() ν•¨μˆ˜ κ΅¬ν˜„
  • app/main.py - /qa μ—”λ“œν¬μΈνŠΈ κ΅¬ν˜„
  • Ollama/OpenAI LLM 연동
  • ν• λ£¨μ‹œλ„€μ΄μ…˜ λ°©μ§€ ν”„λ‘¬ν”„νŠΈ μž‘μ„±

βœ… [Stage: Midweek] λŒ€ν™” λ§₯락 μœ μ§€

  • λŒ€ν™” νžˆμŠ€ν† λ¦¬ 관리
  • Query Rewriting κ΅¬ν˜„ (선택사항)

βœ… [Stage: Weekend-2] μ•ˆμ •μ„± 및 μ—λŸ¬ 핸듀링

  • λͺ¨λ“  μ˜ˆμ™Έ 상황 처리
  • μ‚¬μš©μž μΉœν™”μ  μ—λŸ¬ λ©”μ‹œμ§€
  • λ‘œκΉ… μ‹œμŠ€ν…œ ꡬ좕
  • 슀트레슀 ν…ŒμŠ€νŠΈ

πŸ”§ 배포 ν™˜κ²½ μ„€μ •

ν•„μˆ˜ ν™˜κ²½ λ³€μˆ˜

.env νŒŒμΌμ„ μƒμ„±ν•˜κ³  λ‹€μŒ λ³€μˆ˜λ“€μ„ μ„€μ •ν•˜μ„Έμš”:

# κ³΅κΈ‰μž 선택: "ollama" λ˜λŠ” "openai"
PROVIDER="ollama"

# Ollama μ„€μ • (둜컬 λ˜λŠ” 원격 μ„œλ²„)
OLLAMA_BASE="http://localhost:11434"
OLLAMA_EMBED_MODEL="nomic-embed-text"
OLLAMA_CHAT_MODEL="llama3.1"

# Supabase μ„€μ • (ν•„μˆ˜)
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_KEY="your-anon-key"

# OpenAI μ„€μ • (PROVIDER=openai일 λ•Œλ§Œ ν•„μš”)
# OPENAI_API_KEY="sk-..."
# OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
# OPENAI_CHAT_MODEL="gpt-3.5-turbo"

# μ„œλ²„ μ„€μ •
HOST="0.0.0.0"
PORT=8000
DEBUG=false

# λ³΄μ•ˆ μ„€μ •
SECRET_KEY="your-secret-key-here"
ALLOWED_ORIGINS="http://localhost:8000,https://yourdomain.com"

λ°μ΄ν„°λ² μ΄μŠ€ μ„€μ •

Supabaseμ—μ„œ λ‹€μŒμ„ μ™„λ£Œν•΄μ•Ό ν•©λ‹ˆλ‹€:

  1. pgvector ν™•μž₯ ν™œμ„±ν™”
  2. document_chunks ν…Œμ΄λΈ” 생성 (README.md의 SQL 슀크립트 μ‹€ν–‰)
  3. match_documents ν•¨μˆ˜ 생성
  4. HNSW 인덱슀 생성

🐳 Docker 배포 (ꢌμž₯)

Dockerfile 생성

ν”„λ‘œμ νŠΈ λ£¨νŠΈμ— Dockerfile을 μƒμ„±ν•˜μ„Έμš”:

FROM python:3.11-slim

WORKDIR /app

# μ‹œμŠ€ν…œ μ˜μ‘΄μ„± μ„€μΉ˜
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Python μ˜μ‘΄μ„± μ„€μΉ˜
COPY Pipfile Pipfile.lock ./
RUN pip install pipenv && \
    pipenv install --deploy --ignore-pipfile

# μ• ν”Œλ¦¬μΌ€μ΄μ…˜ μ½”λ“œ 볡사
COPY . .

# μ—…λ‘œλ“œ 디렉토리 생성
RUN mkdir -p app/uploads

# 포트 λ…ΈμΆœ
EXPOSE 8000

# ν™˜κ²½ λ³€μˆ˜ μ„€μ •
ENV PYTHONUNBUFFERED=1

# μ„œλ²„ μ‹€ν–‰
CMD ["pipenv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml (Ollama 포함)

version: '3.8'

services:
  app:
    build: .
    ports:
      - '8000:8000'
    environment:
      - PROVIDER=ollama
      - OLLAMA_BASE=http://ollama:11434
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_KEY=${SUPABASE_KEY}
    volumes:
      - ./app/uploads:/app/app/uploads
      - ./.env:/app/.env
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    ports:
      - '11434:11434'
    volumes:
      - ollama_data:/root/.ollama

volumes:
  ollama_data:

배포 λͺ…λ Ήμ–΄

# 이미지 λΉŒλ“œ
docker build -t docuflow:latest .

# μ»¨ν…Œμ΄λ„ˆ μ‹€ν–‰
docker-compose up -d

# 둜그 확인
docker-compose logs -f app

☁️ ν΄λΌμš°λ“œ 배포 μ˜΅μ…˜

AI ν”„λ‘œμ νŠΈ 배포 λ‚œμ΄λ„ 비ꡐ: HF Spaces β‰ˆ Railway < Render < Fly.io < AWS/GCP

1. Hugging Face Spaces (μΆ”μ²œ - AI ν”„λ‘œμ νŠΈμ— 졜적)

μž₯점:

  • AI/ML ν”„λ‘œμ νŠΈ 배포에 νŠΉν™”λœ ν”Œλž«νΌ
  • Docker 기반 무료 배포 (CPU 2μ½”μ–΄, RAM 16GB)
  • 곡개 URL μžλ™ 생성, ν™˜κ²½ λ³€μˆ˜(Secrets) 관리 제곡
  • GitHub 연동 μžλ™ 배포 지원

μ œμ•½μ‚¬ν•­:

  • 일정 μ‹œκ°„ λ―Έμ‚¬μš© μ‹œ 슬립 λͺ¨λ“œ μ§„μž… β†’ 첫 μš”μ²­ μ‹œ 30~60초 μž¬μ‹œμž‘ μ§€μ—°
  • 무료 ν‹°μ–΄λŠ” μ˜μ† μŠ€ν† λ¦¬μ§€ μ—†μŒ (μ—…λ‘œλ“œ νŒŒμΌμ€ μž¬μ‹œμž‘ μ‹œ μ΄ˆκΈ°ν™”, μž„λ² λ”©μ€ Supabase에 μ €μž₯λ˜λ―€λ‘œ 무관)
  • OllamaλŠ” CPU μ‹€ν–‰ μ‹œ 응닡이 맀우 λŠλ¦¬λ―€λ‘œ OpenAI νŠΈλž™ ꢌμž₯

단계:

  1. huggingface.coμ—μ„œ 계정 생성 ν›„ New Space 클릭
  2. SDKλ₯Ό Docker둜 μ„ νƒν•˜κ³  Space 생성
  3. Space λ¦¬ν¬μ§€ν† λ¦¬μ˜ README.md 상단에 μ•„λž˜ 메타데이터 μΆ”κ°€:
---
title: DocuFlow
emoji: πŸ“„
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---
  1. Space 리포지토리에 ν”„λ‘œμ νŠΈ μ½”λ“œλ₯Ό push (λ˜λŠ” GitHub 연동)
  2. Settings β†’ Variables and secretsμ—μ„œ ν™˜κ²½ λ³€μˆ˜ 등둝:
    • PROVIDER = openai
    • OPENAI_API_KEY = sk-...
    • OPENAI_EMBEDDING_MODEL = text-embedding-3-small
    • OPENAI_CHAT_MODEL = gpt-3.5-turbo
    • SUPABASE_URL, SUPABASE_KEY

2. Railway (간단함)

μž₯점:

  • Supabase와 톡합 용이
  • μžλ™ 배포
  • 무료 ν‹°μ–΄ 제곡

단계:

  1. Railway 계정 생성
  2. GitHub μ €μž₯μ†Œ μ—°κ²°
  3. ν™˜κ²½ λ³€μˆ˜ μ„€μ •
  4. OllamaλŠ” 별도 μ„œλ²„ ν•„μš” (λ˜λŠ” OpenAI μ‚¬μš©)

3. Render

μž₯점:

  • 무료 ν‹°μ–΄
  • Docker 지원
  • μžλ™ HTTPS

단계:

  1. Render 계정 생성
  2. Dockerfile 기반 배포
  3. ν™˜κ²½ λ³€μˆ˜ μ„€μ •

4. AWS/GCP/Azure

μž₯점:

  • ν™•μž₯μ„±
  • κ³ μ„±λŠ₯
  • μ—”ν„°ν”„λΌμ΄μ¦ˆκΈ‰

고렀사항:

  • OllamaλŠ” EC2/Compute Engineμ—μ„œ 별도 μ‹€ν–‰
  • λ˜λŠ” OpenAI API μ‚¬μš© ꢌμž₯
  • λ‘œλ“œ λ°ΈλŸ°μ„œ μ„€μ • ν•„μš”

5. Fly.io

μž₯점:

  • μ „ 세계 μ—£μ§€ 배포
  • Docker 지원
  • κ°„λ‹¨ν•œ μ„€μ •

πŸ“¦ 배포 μ „ ν•„μˆ˜ 파일

μ˜μ‘΄μ„± κΈ°μ€€

이 ν”„λ‘œμ νŠΈμ˜ μ˜μ‘΄μ„±/μ‹€ν–‰ 기쀀은 pipenvμž…λ‹ˆλ‹€.

  • 둜컬 μ„€μΉ˜: pipenv install
  • Docker λΉŒλ“œ: Pipfile, Pipfile.lock 기반 μ„€μΉ˜

μ˜μ‘΄μ„± κ΄€λ¦¬λŠ” pipenv 단일 경둜둜 ν†΅μΌν•©λ‹ˆλ‹€.

.dockerignore

__pycache__/
*.pyc
*.pyo
*.pyd
.Python
.env
.venv
venv/
ENV/
.git
.gitignore
README.md
*.md
.DS_Store
app/uploads/*
!app/uploads/.gitkeep

.env.example

ν™˜κ²½ λ³€μˆ˜ ν…œν”Œλ¦Ώ 파일 (μ‹€μ œ 값은 μ œμ™Έ):

PROVIDER=ollama
OLLAMA_BASE=http://localhost:11434
OLLAMA_EMBED_MODEL=nomic-embed-text
OLLAMA_CHAT_MODEL=llama3.1
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key

πŸ”’ λ³΄μ•ˆ 체크리슀트

  • .env νŒŒμΌμ„ .gitignore에 μΆ”κ°€
  • Supabase ν‚€λ₯Ό ν™˜κ²½ λ³€μˆ˜λ‘œλ§Œ 관리
  • OpenAI API ν‚€ 보호
  • 파일 μ—…λ‘œλ“œ 크기 μ œν•œ μ„€μ •
  • CORS μ„€μ • (ν”„λ‘œλ•μ…˜ λ„λ©”μΈλ§Œ ν—ˆμš©)
  • Rate limiting κ΅¬ν˜„ (선택사항)
  • HTTPS μ‚¬μš© (ν”„λ‘œλ•μ…˜)

πŸ“Š λͺ¨λ‹ˆν„°λ§ 및 λ‘œκΉ…

λ‘œκΉ… μ„€μ •

app/main.py에 λ‘œκΉ… μΆ”κ°€:

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

ν—¬μŠ€ 체크 μ—”λ“œν¬μΈνŠΈ

@app.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "ollama": check_ollama_connection(),
        "supabase": check_supabase_connection()
    }

πŸ§ͺ 배포 μ „ ν…ŒμŠ€νŠΈ

둜컬 ν…ŒμŠ€νŠΈ

# μ„œλ²„ μ‹€ν–‰
pipenv run uvicorn app.main:app --reload

# ν…ŒμŠ€νŠΈ
curl http://localhost:8000/health

톡합 ν…ŒμŠ€νŠΈ 체크리슀트

  • PDF μ—…λ‘œλ“œ ν…ŒμŠ€νŠΈ
  • ν…μŠ€νŠΈ μΆ”μΆœ 확인
  • μž„λ² λ”© 생성 확인
  • Supabase μ €μž₯ 확인
  • 질문-λ‹΅λ³€ ν…ŒμŠ€νŠΈ
  • μ—λŸ¬ 핸듀링 ν…ŒμŠ€νŠΈ
  • λŒ€μš©λŸ‰ 파일 ν…ŒμŠ€νŠΈ

🚨 νŠΈλŸ¬λΈ”μŠˆνŒ…

Ollama μ—°κ²° μ‹€νŒ¨

문제: Ollama μ„œλ²„μ— μ—°κ²°ν•  수 μ—†μŒ

ν•΄κ²°:

  • Ollama μ„œλ²„κ°€ μ‹€ν–‰ 쀑인지 확인: curl http://localhost:11434/api/tags
  • Docker ν™˜κ²½μ—μ„œλŠ” OLLAMA_BASE=http://ollama:11434 μ‚¬μš©
  • λ°©ν™”λ²½ μ„€μ • 확인

Supabase μ—°κ²° μ‹€νŒ¨

문제: Supabase에 μ—°κ²°ν•  수 μ—†μŒ

ν•΄κ²°:

  • ν™˜κ²½ λ³€μˆ˜ 확인: SUPABASE_URL, SUPABASE_KEY
  • Supabase ν”„λ‘œμ νŠΈ μƒνƒœ 확인
  • λ„€νŠΈμ›Œν¬ μ—°κ²° 확인

μž„λ² λ”© 차원 뢈일치

문제: 벑터 차원이 λ§žμ§€ μ•ŠμŒ

ν•΄κ²°:

  • Ollama (768차원) vs OpenAI (1536차원) 확인
  • Supabase ν…Œμ΄λΈ” μŠ€ν‚€λ§ˆμ™€ μΌμΉ˜ν•˜λŠ”μ§€ 확인
  • .env의 PROVIDER μ„€μ • 확인

πŸ“ 배포 ν›„ 체크리슀트

  • μ„œλ²„κ°€ μ •μƒμ μœΌλ‘œ μ‹œμž‘λ˜λŠ”μ§€ 확인
  • ν—¬μŠ€ 체크 μ—”λ“œν¬μΈνŠΈ 응닡 확인
  • PDF μ—…λ‘œλ“œ κΈ°λŠ₯ ν…ŒμŠ€νŠΈ
  • 질문-λ‹΅λ³€ κΈ°λŠ₯ ν…ŒμŠ€νŠΈ
  • μ—λŸ¬ 둜그 λͺ¨λ‹ˆν„°λ§
  • μ„±λŠ₯ λͺ¨λ‹ˆν„°λ§ (응닡 μ‹œκ°„, λ©”λͺ¨λ¦¬ μ‚¬μš©λŸ‰)
  • λ°±μ—… μ „λž΅ 수립

πŸ”„ CI/CD νŒŒμ΄ν”„λΌμΈ (선택사항)

GitHub Actions μ˜ˆμ‹œ

.github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to Railway
        run: |
          # Railway CLIλ₯Ό μ‚¬μš©ν•œ 배포
          # λ˜λŠ” λ‹€λ₯Έ 배포 슀크립트

πŸ“š μΆ”κ°€ λ¦¬μ†ŒμŠ€


πŸ’‘ 배포 μ „ μ΅œμ’… 확인

  1. βœ… λͺ¨λ“  κΈ°λŠ₯이 κ΅¬ν˜„λ˜μ—ˆλŠ”κ°€?
  2. βœ… ν™˜κ²½ λ³€μˆ˜κ°€ λͺ¨λ‘ μ„€μ •λ˜μ—ˆλŠ”κ°€?
  3. βœ… λ°μ΄ν„°λ² μ΄μŠ€κ°€ μ€€λΉ„λ˜μ—ˆλŠ”κ°€?
  4. βœ… λ³΄μ•ˆ 섀정이 μ™„λ£Œλ˜μ—ˆλŠ”κ°€?
  5. βœ… ν…ŒμŠ€νŠΈκ°€ ν†΅κ³Όν–ˆλŠ”κ°€?
  6. βœ… λ‘œκΉ…μ΄ μ„€μ •λ˜μ—ˆλŠ”κ°€?
  7. βœ… μ—λŸ¬ 핸듀링이 μ™„λ£Œλ˜μ—ˆλŠ”κ°€?

μ€€λΉ„κ°€ λ˜μ—ˆλ‹€λ©΄ 배포λ₯Ό μ‹œμž‘ν•˜μ„Έμš”! πŸš€