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] 데이터 μ „μ²˜λ¦¬
- [x] `app/embedding_utils.py` - `split_text()` ν•¨μˆ˜ κ΅¬ν˜„
- [x] `app/main.py` - `extract_text_from_pdf()` ν•¨μˆ˜ κ΅¬ν˜„
- [x] PDF ν…μŠ€νŠΈ μΆ”μΆœ ν…ŒμŠ€νŠΈ
#### βœ… [Stage: Weekend-1] μž„λ² λ”© 및 벑터 μ €μž₯
- [x] `app/embedding_utils.py` - `get_embedding()` ν•¨μˆ˜ κ΅¬ν˜„
- [x] `app/supabase_utils.py` - `save_embedding()` ν•¨μˆ˜ κ΅¬ν˜„
- [x] 비동기 μž„λ² λ”© 처리 (μ„±λŠ₯ μ΅œμ ν™”)
- [x] Supabase μ—°κ²° ν…ŒμŠ€νŠΈ
#### βœ… [Stage: Weekend-1] RAG νŒŒμ΄ν”„λΌμΈ
- [x] `app/supabase_utils.py` - `search_similar_embeddings()` ν•¨μˆ˜ κ΅¬ν˜„
- [x] `app/main.py` - `/qa` μ—”λ“œν¬μΈνŠΈ κ΅¬ν˜„
- [x] Ollama/OpenAI LLM 연동
- [x] ν• λ£¨μ‹œλ„€μ΄μ…˜ λ°©μ§€ ν”„λ‘¬ν”„νŠΈ μž‘μ„±
#### βœ… [Stage: Midweek] λŒ€ν™” λ§₯락 μœ μ§€
- [ ] λŒ€ν™” νžˆμŠ€ν† λ¦¬ 관리
- [x] Query Rewriting κ΅¬ν˜„ (선택사항)
#### βœ… [Stage: Weekend-2] μ•ˆμ •μ„± 및 μ—λŸ¬ 핸듀링
- [ ] λͺ¨λ“  μ˜ˆμ™Έ 상황 처리
- [ ] μ‚¬μš©μž μΉœν™”μ  μ—λŸ¬ λ©”μ‹œμ§€
- [ ] λ‘œκΉ… μ‹œμŠ€ν…œ ꡬ좕
- [ ] 슀트레슀 ν…ŒμŠ€νŠΈ
---
## πŸ”§ 배포 ν™˜κ²½ μ„€μ •
### ν•„μˆ˜ ν™˜κ²½ λ³€μˆ˜
`.env` νŒŒμΌμ„ μƒμ„±ν•˜κ³  λ‹€μŒ λ³€μˆ˜λ“€μ„ μ„€μ •ν•˜μ„Έμš”:
```ini
# κ³΅κΈ‰μž 선택: "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`을 μƒμ„±ν•˜μ„Έμš”:
```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 포함)
```yaml
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:
```
### 배포 λͺ…λ Ήμ–΄
```bash
# 이미지 λΉŒλ“œ
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](https://huggingface.co)μ—μ„œ 계정 생성 ν›„ **New Space** 클릭
2. SDKλ₯Ό **Docker**둜 μ„ νƒν•˜κ³  Space 생성
3. Space λ¦¬ν¬μ§€ν† λ¦¬μ˜ `README.md` 상단에 μ•„λž˜ 메타데이터 μΆ”κ°€:
```yaml
---
title: DocuFlow
emoji: πŸ“„
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---
```
4. Space 리포지토리에 ν”„λ‘œμ νŠΈ μ½”λ“œλ₯Ό push (λ˜λŠ” GitHub 연동)
5. **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
ν™˜κ²½ λ³€μˆ˜ ν…œν”Œλ¦Ώ 파일 (μ‹€μ œ 값은 μ œμ™Έ):
```ini
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
```
---
## πŸ”’ λ³΄μ•ˆ 체크리슀트
- [x] `.env` νŒŒμΌμ„ `.gitignore`에 μΆ”κ°€
- [x] Supabase ν‚€λ₯Ό ν™˜κ²½ λ³€μˆ˜λ‘œλ§Œ 관리
- [x] OpenAI API ν‚€ 보호
- [ ] 파일 μ—…λ‘œλ“œ 크기 μ œν•œ μ„€μ •
- [ ] CORS μ„€μ • (ν”„λ‘œλ•μ…˜ λ„λ©”μΈλ§Œ ν—ˆμš©)
- [ ] Rate limiting κ΅¬ν˜„ (선택사항)
- [ ] HTTPS μ‚¬μš© (ν”„λ‘œλ•μ…˜)
---
## πŸ“Š λͺ¨λ‹ˆν„°λ§ 및 λ‘œκΉ…
### λ‘œκΉ… μ„€μ •
`app/main.py`에 λ‘œκΉ… μΆ”κ°€:
```python
import logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)
```
### ν—¬μŠ€ 체크 μ—”λ“œν¬μΈνŠΈ
```python
@app.get("/health")
async def health_check():
return {
"status": "healthy",
"ollama": check_ollama_connection(),
"supabase": check_supabase_connection()
}
```
---
## πŸ§ͺ 배포 μ „ ν…ŒμŠ€νŠΈ
### 둜컬 ν…ŒμŠ€νŠΈ
```bash
# μ„œλ²„ μ‹€ν–‰
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`:
```yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Deploy to Railway
run: |
# Railway CLIλ₯Ό μ‚¬μš©ν•œ 배포
# λ˜λŠ” λ‹€λ₯Έ 배포 슀크립트
```
---
## πŸ“š μΆ”κ°€ λ¦¬μ†ŒμŠ€
- [FastAPI 배포 κ°€μ΄λ“œ](https://fastapi.tiangolo.com/deployment/)
- [Supabase 벑터 검색](https://supabase.com/docs/guides/ai)
- [Docker 베슀트 ν”„λž™ν‹°μŠ€](https://docs.docker.com/develop/dev-best-practices/)
- [Ollama 배포 κ°€μ΄λ“œ](https://ollama.com/docs)
---
## πŸ’‘ 배포 μ „ μ΅œμ’… 확인
1. βœ… λͺ¨λ“  κΈ°λŠ₯이 κ΅¬ν˜„λ˜μ—ˆλŠ”κ°€?
2. βœ… ν™˜κ²½ λ³€μˆ˜κ°€ λͺ¨λ‘ μ„€μ •λ˜μ—ˆλŠ”κ°€?
3. βœ… λ°μ΄ν„°λ² μ΄μŠ€κ°€ μ€€λΉ„λ˜μ—ˆλŠ”κ°€?
4. βœ… λ³΄μ•ˆ 섀정이 μ™„λ£Œλ˜μ—ˆλŠ”κ°€?
5. βœ… ν…ŒμŠ€νŠΈκ°€ ν†΅κ³Όν–ˆλŠ”κ°€?
6. βœ… λ‘œκΉ…μ΄ μ„€μ •λ˜μ—ˆλŠ”κ°€?
7. βœ… μ—λŸ¬ 핸듀링이 μ™„λ£Œλ˜μ—ˆλŠ”κ°€?
**μ€€λΉ„κ°€ λ˜μ—ˆλ‹€λ©΄ 배포λ₯Ό μ‹œμž‘ν•˜μ„Έμš”! πŸš€**