docuflow / docs /04-weekend2 /README.md
Ken Huh
Initial commit
1e570c8 unverified
|
Raw History Blame Contribute Delete
4.52 kB
# Week 2 ๋ฐฐํฌ ํŠธ๋ž™ ํŒจํ‚ท
[Stage: Weekend-2]
์ด ํŠธ๋ž™์˜ ํ•ต์‹ฌ์€ **๋ชจ๋ธ ์„œ๋น™ ํŠธ๋ž™์„ ์„ ํƒํ•˜๊ณ , ์‹ค์ œ ๊ณต๊ฐœ URL์—์„œ E2E๋ฅผ ๊ฒ€์ฆํ•˜๋Š” ๊ฒƒ**์ž…๋‹ˆ๋‹ค.
**์ง„ํ–‰ ์ˆœ์„œ:**
1. ์ด ๋ฌธ์„œ๋ฅผ ์ฝ๊ณ  ํŠธ๋ž™์„ ๊ฒฐ์ •ํ•œ๋‹ค.
2. [`deployment-checklist-lab.md`](./deployment-checklist-lab.md)๋ฅผ ์ฑ„์šฐ๋ฉฐ ๋ฐฐํฌ๋ฅผ ์™„๋ฃŒํ•œ๋‹ค.
3. ๋ง‰ํžˆ๋ฉด [`deployment.md`](./deployment.md)๋ฅผ ์ฐธ๊ณ ํ•œ๋‹ค.
---
## ํŠธ๋ž™ ๋ชฉํ‘œ
- `Ollama ์ž์ฒด ํ˜ธ์ŠคํŒ…`๊ณผ `OpenAI API ์—ฐ๋™`์˜ ๋ฐฐํฌ ์ฐจ์ด๋ฅผ ์„ค๋ช…ํ•  ์ˆ˜ ์žˆ๋‹ค.
- ์„ ํƒํ•œ ํŠธ๋ž™์œผ๋กœ `๋ฌธ์„œ ์—…๋กœ๋“œ โ†’ /qa ์งˆ์˜์‘๋‹ต` E2E๋ฅผ ์™ธ๋ถ€ URL์—์„œ ํ™•์ธํ•œ๋‹ค.
- ์žฅ์•  ์ƒํ™ฉ(๋ชจ๋ธ ๋‹ค์šด, API ์ œํ•œ, DB ์ง€์—ฐ)์— ๋Œ€ํ•ด ์ตœ์†Œ ๋ณต๊ตฌ ์ ˆ์ฐจ๋ฅผ ๋ฌธ์„œํ™”ํ•œ๋‹ค.
---
## 1) ํŠธ๋ž™ ์„ ํƒ: Ollama vs OpenAI
### A. Ollama ์ž์ฒด ํ˜ธ์ŠคํŒ… ํŠธ๋ž™
๋‹ค์Œ์— ํ•ด๋‹นํ•˜๋ฉด Ollama ํŠธ๋ž™์ด ์œ ๋ฆฌํ•ฉ๋‹ˆ๋‹ค.
- ๋ฐ์ดํ„ฐ๊ฐ€ ์™ธ๋ถ€ API๋กœ ๋‚˜๊ฐ€๋ฉด ์•ˆ ๋˜๋Š” ํ™˜๊ฒฝ
- ๊ณ ์ • ๋น„์šฉ(์„œ๋ฒ„ ๋น„์šฉ)์œผ๋กœ ์šด์˜ํ•˜๊ณ  ์‹ถ์€ ๊ฒฝ์šฐ
- ๋ชจ๋ธ ๋™์ž‘ ์›๋ฆฌ๋ฅผ ์ง์ ‘ ํ™•์ธํ•˜๊ณ  ์‹ถ์€ ๊ฒฝ์šฐ
์šด์˜ ๋ฆฌ์Šคํฌ:
- ์„œ๋ฒ„ ์ž์›(CPU/GPU/RAM) ๋ถ€์กฑ ์‹œ ์‘๋‹ต ์ง€์—ฐ
- ๋ชจ๋ธ ๋‹ค์šด๋กœ๋“œ/์—…๋ฐ์ดํŠธ/ํ—ฌ์Šค์ฒดํฌ๋ฅผ ์ง์ ‘ ์šด์˜ํ•ด์•ผ ํ•จ
- ํด๋ผ์šฐ๋“œ ๋ฐฐํฌ ์‹œ ์ถฉ๋ถ„ํ•œ RAM์˜ ์„œ๋ฒ„ ํ•„์š” (llama3.1 ๊ธฐ์ค€ ์ตœ์†Œ 8GB)
### B. OpenAI API ์—ฐ๋™ ํŠธ๋ž™
๋‹ค์Œ์— ํ•ด๋‹นํ•˜๋ฉด OpenAI ํŠธ๋ž™์ด ์œ ๋ฆฌํ•ฉ๋‹ˆ๋‹ค.
- ์ธํ”„๋ผ ์šด์˜ ๋ถ€๋‹ด์„ ์ค„์ด๊ณ  ๋น ๋ฅด๊ฒŒ ๋ฐฐํฌํ•˜๊ณ  ์‹ถ์€ ๊ฒฝ์šฐ
- ํŠธ๋ž˜ํ”ฝ ํŽธ์ฐจ์— ๋”ฐ๋ผ ํƒ„๋ ฅ์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๊ณ  ์‹ถ์€ ๊ฒฝ์šฐ
- HF Spaces / Railway ๋“ฑ ๋ฌด๋ฃŒ ํด๋ผ์šฐ๋“œ์— ๋ฐฐํฌํ•˜๊ณ  ์‹ถ์€ ๊ฒฝ์šฐ
์šด์˜ ๋ฆฌ์Šคํฌ:
- API rate limit, ์ฟผํ„ฐ, ๋น„์šฉ ๊ธ‰์ฆ ๊ด€๋ฆฌ ํ•„์š”
- ์™ธ๋ถ€ ๋„คํŠธ์›Œํฌ ์žฅ์• ์— ์ง์ ‘ ์˜ํ–ฅ๋ฐ›์Œ
- ์‹œํฌ๋ฆฟ ํ‚ค ๋…ธ์ถœ ๋ฐฉ์ง€์™€ ํ‚ค ๋กคํ…Œ์ด์…˜ ์ •์ฑ… ํ•„์š”
---
## 2) ํŠธ๋ž™๋ณ„ ํ•„์ˆ˜ ์„ค์ •
### ๊ณตํ†ต
- `SUPABASE_URL`, `SUPABASE_KEY` ์„ค์ •
- `document_chunks` ํ…Œ์ด๋ธ” + `match_documents` RPC + ์ธ๋ฑ์Šค ์ค€๋น„
- `GET /health` ๋ฐ ์—…๋กœ๋“œ/์งˆ์˜ E2E ํ…Œ์ŠคํŠธ ๊ฐ€๋Šฅ ์ƒํƒœ
### Ollama ํŠธ๋ž™ (`PROVIDER=ollama`)
- `OLLAMA_BASE` ์„ค์ • (๋กœ์ปฌ/์›๊ฒฉ ์ฃผ์†Œ)
- `OLLAMA_EMBED_MODEL=nomic-embed-text`
- `OLLAMA_CHAT_MODEL=llama3.1`
- ์ž„๋ฒ ๋”ฉ ์ฐจ์›: `768`
- ๋ชจ๋ธ ์„œ๋ฒ„ ํ—ฌ์Šค ํ™•์ธ: `curl <OLLAMA_BASE>/api/tags`
### OpenAI ํŠธ๋ž™ (`PROVIDER=openai`)
- `OPENAI_API_KEY` ์„ค์ •
- `OPENAI_EMBEDDING_MODEL=text-embedding-3-small`
- `OPENAI_CHAT_MODEL=gpt-4o-mini` (๋˜๋Š” ํŒ€ ์ •์ฑ… ๋ชจ๋ธ)
- ์ž„๋ฒ ๋”ฉ ์ฐจ์›: `1536`
- rate limit/์ฟผํ„ฐ ์ดˆ๊ณผ ์‹œ ์žฌ์‹œ๋„ ๋ฐ ์—๋Ÿฌ ๋ฉ”์‹œ์ง€ ๊ธฐ์ค€ ์ •์˜
---
## 3) ๋ฐฐํฌ ์‹œ๋‚˜๋ฆฌ์˜ค
### ์‹œ๋‚˜๋ฆฌ์˜ค A: Docker + Ollama (์ž์ฒด ํ˜ธ์ŠคํŒ…)
1. `.env`์—์„œ `PROVIDER=ollama`๋กœ ์„ค์ •
2. `OLLAMA_BASE`๋ฅผ ์ปจํ…Œ์ด๋„ˆ ๋„คํŠธ์›Œํฌ์— ๋งž๊ฒŒ ์ง€์ • (`http://ollama:11434`)
3. `docker-compose up -d`๋กœ ์•ฑ + Ollama ๋™์‹œ ์‹คํ–‰
4. ๊ณต๊ฐœ URL์—์„œ `/health`, ์—…๋กœ๋“œ, `/qa` ํ…Œ์ŠคํŠธ
์ฒดํฌ ํฌ์ธํŠธ:
- Ollama ์ปจํ…Œ์ด๋„ˆ ์žฌ์‹œ์ž‘ ํ›„ ์•ฑ ๋ณต๊ตฌ ์‹œ๊ฐ„
- ๋ชจ๋ธ ๋ฏธ๋‹ค์šด๋กœ๋“œ ์ƒํƒœ์—์„œ์˜ ์‚ฌ์šฉ์ž ์•ˆ๋‚ด ๋ฉ”์‹œ์ง€
- ๋™์‹œ ์š”์ฒญ ์ฆ๊ฐ€ ์‹œ ์‘๋‹ต ์‹œ๊ฐ„ ๋ณ€๋™
### ์‹œ๋‚˜๋ฆฌ์˜ค B: HF Spaces / Railway + OpenAI API (๊ถŒ์žฅ)
1. `.env` ๋˜๋Š” ํ”Œ๋žซํผ ์‹œํฌ๋ฆฟ์— `PROVIDER=openai` ๋ฐ API ํ‚ค ์„ค์ •
2. Supabase ์Šคํ‚ค๋งˆ๋ฅผ 1536์ฐจ์›์œผ๋กœ ์ •ํ•ฉ์„ฑ ํ™•์ธ
3. ์•ฑ๋งŒ ํด๋ผ์šฐ๋“œ ๋ฐฐํฌ (๋ชจ๋ธ ์„œ๋ฒ„ ๋ณ„๋„ ์šด์˜ ์—†์Œ)
4. ๊ณต๊ฐœ URL์—์„œ `/health`, ์—…๋กœ๋“œ, `/qa` ํ…Œ์ŠคํŠธ
์ฒดํฌ ํฌ์ธํŠธ:
- API ํ‚ค ๋ˆ„๋ฝ/์˜คํƒ€ ์‹œ ๊ฐ์ง€ ๊ฐ€๋Šฅ ์—ฌ๋ถ€
- rate limit ๋ฐœ์ƒ ์‹œ ์žฌ์‹œ๋„/์•ˆ๋‚ด ๋™์ž‘
- ํ˜ธ์ถœ ๋น„์šฉ ๋ชจ๋‹ˆํ„ฐ๋ง ์ง€ํ‘œ ์ˆ˜์ง‘ ์—ฌ๋ถ€
> ํด๋ผ์šฐ๋“œ ํ”Œ๋žซํผ๋ณ„ ์ƒ์„ธ ์„ค์ •์€ [`deployment.md`](./deployment.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”.
---
## 4) ํŠธ๋ž™ ์„ ํƒ ๊ธฐ๋ก (์ž‘์„ฑ ํ›„ ํŒ€ ๋ฌธ์„œ์— ๋‚จ๊ธธ ๊ฒƒ)
```md
### ๋ชจ๋ธ ์„œ๋น™ ํŠธ๋ž™ ์„ ํƒ ๊ธฐ๋ก
- ์„ ํƒ ํŠธ๋ž™: (ollama / openai)
- ์„ ํƒ ์ด์œ : (๋น„์šฉ, ๋ณด์•ˆ, ์šด์˜, ์„ฑ๋Šฅ ๊ด€์  3์ค„ ์ด์ƒ)
- ์ž„๋ฒ ๋”ฉ ์ฐจ์›: (768 / 1536)
- ์˜ˆ์ƒ ๋ฆฌ์Šคํฌ: (์ตœ์†Œ 2๊ฐœ)
- ๋Œ€์‘ ๊ณ„ํš: (๋ฆฌ์Šคํฌ๋ณ„ 1๊ฐœ ์ด์ƒ)
```
---
## Weekend-2 DoD (ํŽ˜์–ด ๊ธฐ์ค€)
- [ ] ์„ ํƒํ•œ ๋ชจ๋ธ ์„œ๋น™ ํŠธ๋ž™์˜ ๊ทผ๊ฑฐ(๋น„์šฉ/์šด์˜/์„ฑ๋Šฅ)๋ฅผ 3์ค„ ์ด์ƒ ์ž‘์„ฑ
- [ ] ๋ฒกํ„ฐ DB ์Šคํ‚ค๋งˆ ์ฐจ์›(768 ๋˜๋Š” 1536)๊ณผ ์‹ค์ œ ์„ค์ • ์ผ์น˜ ํ™•์ธ
- [ ] ๊ณต๊ฐœ URL์—์„œ `GET /health` ์„ฑ๊ณต
- [ ] ๊ณต๊ฐœ URL์—์„œ PDF ์—…๋กœ๋“œ + `/qa` ๋‹ต๋ณ€ ์„ฑ๊ณต
- [ ] ์žฅ์•  ๋Œ€์‘ ๋“œ๋ฆด 3๊ฐœ ์ˆ˜ํ–‰ ๋ฐ ๋ณต๊ตฌ ์‹œ๊ฐ„ ๊ธฐ๋ก
- [ ] ํŽ˜์–ด ์ƒ๋Œ€๋ฐฉ์ด ๊ณต๊ฐœ URL์—์„œ ์ง์ ‘ E2E ๊ฒ€์ฆ ๊ฐ€๋Šฅํ•œ์ง€ ํ™•์ธ
## ๊ฒ€์ฆ ๋ช…๋ น
```bash
curl <PUBLIC_URL>/health
```