# πŸš€ 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. βœ… μ—λŸ¬ 핸듀링이 μ™„λ£Œλ˜μ—ˆλŠ”κ°€? **μ€€λΉ„κ°€ λ˜μ—ˆλ‹€λ©΄ 배포λ₯Ό μ‹œμž‘ν•˜μ„Έμš”! πŸš€**