Ken Huh commited on
Commit
1e570c8
·
unverified ·
0 Parent(s):

Initial commit

Browse files
.dockerignore ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ *.pyd
5
+ .Python
6
+ .env
7
+ .venv
8
+ venv/
9
+ ENV/
10
+ .git
11
+ .gitignore
12
+ README.md
13
+ *.md
14
+ .DS_Store
15
+ app/uploads/*
16
+ .vscode/
17
+ .idea/
18
+ *.swp
19
+ *.swo
20
+ *~
21
+
.env.example ADDED
@@ -0,0 +1,28 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ============================================
2
+ # Provider 선택 (실제 코드에서 사용)
3
+ # ============================================
4
+ # ollama | openai
5
+ PROVIDER=ollama
6
+
7
+ # ============================================
8
+ # Ollama 설정 (PROVIDER=ollama일 때 사용)
9
+ # ============================================
10
+ OLLAMA_BASE=http://localhost:11434
11
+ OLLAMA_EMBED_MODEL=nomic-embed-text
12
+ OLLAMA_CHAT_MODEL=llama3.1
13
+
14
+ # ============================================
15
+ # OpenAI 설정 (PROVIDER=openai일 때 사용)
16
+ # ============================================
17
+ # PROVIDER=openai
18
+ OPENAI_API_KEY=
19
+ OPENAI_EMBEDDING_MODEL=text-embedding-3-small
20
+ OPENAI_CHAT_MODEL=gpt-4o-mini
21
+
22
+ # ============================================
23
+ # 공통 설정 (필수)
24
+ # ============================================
25
+ # Settings → General → Project ID → https://<project-id>.supabase.co
26
+ SUPABASE_URL=https://your-project-id.supabase.co
27
+ # Settings → API Keys → Legacy API keys → anon 키 (eyJ...로 시작하는 JWT 형식)
28
+ SUPABASE_KEY=eyJ...
.gitattributes ADDED
@@ -0,0 +1,4 @@
 
 
 
 
 
1
+ *.pdf filter=lfs diff=lfs merge=lfs -text
2
+ *.jpg filter=lfs diff=lfs merge=lfs -text
3
+ *.jpeg filter=lfs diff=lfs merge=lfs -text
4
+ *.png filter=lfs diff=lfs merge=lfs -text
.gitignore ADDED
@@ -0,0 +1,41 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ develop-eggs/
9
+ dist/
10
+ downloads/
11
+ eggs/
12
+ .eggs/
13
+ lib/
14
+ lib64/
15
+ parts/
16
+ sdist/
17
+ var/
18
+ wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+
23
+ # Virtual Environment
24
+ .env
25
+ .venv
26
+ env/
27
+ venv/
28
+ ENV/
29
+
30
+ # IDE
31
+ .idea/
32
+ .vscode/
33
+ *.swp
34
+ *.swo
35
+
36
+ # OS
37
+ .DS_Store
38
+ Thumbs.db
39
+
40
+ # Project specific
41
+ uploads/
.pre-commit-config.yaml ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ repos:
2
+ - repo: https://github.com/psf/black
3
+ rev: 24.4.2
4
+ hooks:
5
+ - id: black
.python-version ADDED
@@ -0,0 +1 @@
 
 
1
+ 3.11
Dockerfile ADDED
@@ -0,0 +1,30 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ FROM python:3.11-slim
2
+
3
+ WORKDIR /app
4
+
5
+ # 시스템 의존성 설치
6
+ RUN apt-get update && apt-get install -y \
7
+ gcc \
8
+ postgresql-client \
9
+ && rm -rf /var/lib/apt/lists/*
10
+
11
+ # Python 의존성 설치
12
+ COPY Pipfile Pipfile.lock ./
13
+ RUN pip install pipenv && \
14
+ pipenv install --deploy --ignore-pipfile
15
+
16
+ # 애플리케이션 코드 복사
17
+ COPY . .
18
+
19
+ # 업로드 디렉토리 생성
20
+ RUN mkdir -p app/uploads
21
+
22
+ # 포트 노출
23
+ EXPOSE 8000
24
+
25
+ # 환경 변수 설정
26
+ ENV PYTHONUNBUFFERED=1
27
+
28
+ # 서버 실행
29
+ CMD ["pipenv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
30
+
Pipfile ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ [[source]]
2
+ url = "https://pypi.org/simple"
3
+ verify_ssl = true
4
+ name = "pypi"
5
+
6
+ [packages]
7
+ fastapi = "==0.109.2"
8
+ uvicorn = "==0.27.1"
9
+ langchain-openai = "==0.0.2"
10
+ python-multipart = "==0.0.9"
11
+ psycopg2-binary = "==2.9.9"
12
+ supabase = "==1.0.3"
13
+ python-dotenv = "*"
14
+ jinja2 = "*"
15
+ langchain = "*"
16
+ pdfplumber = "*"
17
+ requests = "*"
18
+
19
+ [dev-packages]
20
+ pre-commit = "*"
21
+ black = "==24.4.2"
22
+
23
+ [requires]
24
+ python_version = "3.11"
Pipfile.lock ADDED
The diff for this file is too large to render. See raw diff
 
README.md ADDED
@@ -0,0 +1,363 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <br>
2
+ <br>
3
+
4
+ > Pi Lab(파이랩)의 모든 과제는 실제 기업에서 주어지는 과제에 기반하여 제작되었으며, 저작권법의 보호를 받습니다.
5
+
6
+ <br>
7
+ <br>
8
+
9
+ # Project DocuFlow: Intelligent Document Agent
10
+
11
+ <br>
12
+
13
+ <p align="center">
14
+ <img src="/assets/docuflow.jpg" width="100%">
15
+ </p>
16
+
17
+ <br>
18
+
19
+ **🧠 The Future of Document Processing**
20
+
21
+ _📍 HQ: 42 Silicon Valley Blvd, Palo Alto, CA_
22
+
23
+ <br>
24
+
25
+ > "Read less, Understand more."
26
+
27
+ <br>
28
+
29
+ **DocuFlow AI**는 전 세계의 비정형 문서 데이터를 지능형 지식 베이스로 전환하는 실리콘밸리 기반의 AI 스타트업입니다. 우리는 단순히 문서를 저장하는 것을 넘어, 문서와 대화하고 숨겨진 통찰력을 즉시 찾아내는 경험을 제공합니다.
30
+
31
+ 그리고 오늘, 당신 **Alex**는 AI 엔지니어로 팀에 합류했습니다.
32
+
33
+ <br>
34
+ <br>
35
+
36
+ ## 💬 [Slack] `#docuflow-engineering`
37
+
38
+ ### 🧑‍💼 Sarah (PM)
39
+
40
+ > 고객사들로부터 피드백이 왔는데, 기존 챗봇이 문서에 없는 내용을 지어내서 답변한다고 해요(Hallucination).
41
+ > 이번 MVP의 핵심은 **정확성**입니다. 사용자가 업로드한 PDF 문서 내에서만 근거를 찾아 답변하는 **고성능 RAG(검색 증강 생성) 파이프라인**이 반드시 필요해요.
42
+
43
+ <br>
44
+
45
+ ### 👨‍💻 Dave (CTO)
46
+
47
+ > Alex, 이번 과제의 핵심은 LLM을 단순히 호출하는 게 아니라, **'어떻게 문서를 검색하느냐'** 에 달려있네.
48
+ > 단순히 API를 연결하는 수준을 넘어, **대량의 문서를 처리하는 성능**과 **정확한 정보를 찾아내는 품질**까지 고민해야 해.
49
+ > 2주 동안 주말 집중 실습과 평일 준비를 반복하며, 우리 서비스의 코어 엔진을 완성해주게.
50
+
51
+ <br>
52
+ <br>
53
+
54
+ ## 🧩 프로젝트 목표
55
+
56
+ **DocuFlow Agent**는 RAG(Retrieval-Augmented Generation) 기술을 활용하여 PDF 문서의 지식을 AI에게 주입하는 지능형 검색 시스템입니다.
57
+
58
+ 본 프로젝트는 2주 운영(주말 페어프로그래밍 + 평일 준비/조사)을 통해, 빈 껍데기뿐인 서버를 **상용 수준의 RAG 엔진**으로 발전시키는 것을 목표로 합니다.
59
+
60
+ <br>
61
+ <br>
62
+
63
+ ## ⚙️ 환경 설정
64
+
65
+ 아래 1~6단계를 순서대로 완료해야 프로젝트를 실행할 수 있습니다.
66
+
67
+ ### 1. pyenv 설치 (최초 1회, macOS)
68
+
69
+ pyenv가 이미 설치되어 있다면 이 단계를 건너뛰세요.
70
+
71
+ ```bash
72
+ # Homebrew로 pyenv 설치
73
+ brew install pyenv
74
+
75
+ # 셸 설정에 pyenv 초기화 추가 (zsh 기준)
76
+ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
77
+ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
78
+ echo 'eval "$(pyenv init -)"' >> ~/.zshrc
79
+
80
+ # 설정 반영
81
+ source ~/.zshrc
82
+
83
+ # 설치 확인 (버전 번호가 출력되면 정상)
84
+ pyenv --version
85
+ ```
86
+
87
+ ---
88
+
89
+ ### 2. Python 3.11 및 의존성 설치
90
+
91
+ ```bash
92
+ # Python 3.11 설치 및 설정
93
+ pyenv install 3.11
94
+ pyenv local 3.11
95
+
96
+ # 설치 확인 (3.11.x 가 출력되면 정상)
97
+ python --version
98
+
99
+ # pipenv 설치 (최초 1회)
100
+ pip install pipenv
101
+
102
+ # 프로젝트 의존성 설치
103
+ pipenv install
104
+ ```
105
+
106
+ ---
107
+
108
+ ### 3. Ollama 설치 및 모델 다운로드
109
+
110
+ 이 프로젝트는 기본적으로 로컬 Ollama 서버를 사용합니다.
111
+
112
+ **macOS 설치:**
113
+
114
+ ```bash
115
+ # Homebrew로 설치
116
+ brew install --cask ollama
117
+
118
+ # 또는 공식 웹사이트에서 다운로드
119
+ # https://ollama.com/download
120
+ ```
121
+
122
+ **서버 실행:**
123
+
124
+ 설치 후 **Ollama 앱을 실행**하면 메뉴 바에 아이콘이 표시되고 서버가 자동으로 시작됩니다.
125
+
126
+ > 앱 방식으로 설치한 경우 `ollama serve`를 별도로 실행하지 않아도 됩니다. 앱이 서버를 자동으로 관리합니다.
127
+
128
+ **모델 다운로드 (서버 실행 후 실행):**
129
+
130
+ ```bash
131
+ # 임베딩 모델 (약 274MB)
132
+ ollama pull nomic-embed-text
133
+
134
+ # 채팅 모델 (약 4.9GB, 네트워크 환경에 따라 10분 이상 소요)
135
+ ollama pull llama3.1
136
+ ```
137
+
138
+ > ⚠️ `llama3.1` 다운로드는 시간이 많이 소요됩니다.
139
+ > 주말 세션 당일이 아닌 **사전에 반드시 완료**해두세요.
140
+
141
+ **서버 상태 확인:**
142
+
143
+ ```bash
144
+ curl http://localhost:11434/api/tags
145
+ ```
146
+
147
+ 모델 목록이 JSON 형태로 출력되면 정상입니다.
148
+
149
+ > Ollama 서버는 **프로젝트 실행 중에는 계속 켜둔 상태를 유지**해야 합니다. 서버가 꺼진 상태에서는 임베딩/채팅 요청이 실패합니다.
150
+
151
+ **서버 종료 (실습 종료 후):**
152
+
153
+ - **메뉴 바** 상단의 Ollama 아이콘 클릭 → **Quit Ollama**
154
+ - 또는 터미널에서 `killall Ollama`
155
+
156
+ ---
157
+
158
+ ### 4. Supabase 프로젝트 생성 및 환경 변수 설정 (.env)
159
+
160
+ **Supabase 프로젝트 생성:**
161
+
162
+ 1. [supabase.com](https://supabase.com)에 접속하여 계정을 만들고 새 프로젝트를 생성하세요.
163
+ 2. 프로젝트 생성 후 아래 경로에서 두 값을 복사해 둡니다.
164
+ - **Settings → General → Project ID** 확인 → `https://<project-id>.supabase.co` 형태로 `SUPABASE_URL`에 입력
165
+ - **Settings → API Keys → Legacy API keys → `anon` 키** → `SUPABASE_KEY`에 입력
166
+
167
+ **환경 변수 설정:**
168
+
169
+ ```bash
170
+ cp .env.example .env
171
+ # .env 파일을 열어 복사한 값을 채우세요
172
+ ```
173
+
174
+ ```ini
175
+ # 기본: 로컬 Ollama 사용
176
+ PROVIDER="ollama"
177
+ OLLAMA_BASE="http://localhost:11434"
178
+ OLLAMA_EMBED_MODEL="nomic-embed-text"
179
+ OLLAMA_CHAT_MODEL="llama3.1"
180
+
181
+ # 공통
182
+ SUPABASE_URL="https://your-project-id.supabase.co" # Settings → General → Project ID
183
+ SUPABASE_KEY="eyJ..." # Settings → API Keys → Legacy API keys → anon
184
+
185
+ # 선택: OpenAI 사용 시
186
+ # PROVIDER="openai"
187
+ # OPENAI_API_KEY="sk-..."
188
+ # OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
189
+ # OPENAI_CHAT_MODEL="gpt-4o-mini"
190
+ ```
191
+
192
+ ---
193
+
194
+ ### 5. 데이터베이스(Supabase) 구성
195
+
196
+ Supabase 대시보드의 **SQL Editor**에서 아래 쿼리를 실행하세요.
197
+
198
+ <details>
199
+ <summary><b>📜 SQL 쿼리 (기본: Ollama 768차원)</b></summary>
200
+ <br>
201
+
202
+ ```sql
203
+ -- 1. 벡터 확장 활성화
204
+ CREATE EXTENSION IF NOT EXISTS vector;
205
+
206
+ -- 2. 문서 청크 테이블 생성
207
+ CREATE TABLE IF NOT EXISTS document_chunks (
208
+ id BIGSERIAL PRIMARY KEY,
209
+ document_id TEXT NOT NULL,
210
+ content TEXT NOT NULL,
211
+ embedding vector(768), -- nomic-embed-text 차원
212
+ chunk_index INTEGER NOT NULL,
213
+ metadata JSONB DEFAULT '{}',
214
+ created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
215
+ );
216
+
217
+ -- 3. 검색 함수(RPC) 생성
218
+ CREATE OR REPLACE FUNCTION match_documents (
219
+ query_embedding vector(768),
220
+ match_count int,
221
+ p_document_id text
222
+ ) RETURNS TABLE (
223
+ id BIGINT,
224
+ document_id TEXT,
225
+ content TEXT,
226
+ similarity FLOAT
227
+ )
228
+ LANGUAGE plpgsql
229
+ AS $$
230
+ BEGIN
231
+ RETURN QUERY
232
+ SELECT
233
+ dc.id,
234
+ dc.document_id,
235
+ dc.content,
236
+ 1 - (dc.embedding <=> query_embedding) as similarity
237
+ FROM document_chunks AS dc
238
+ WHERE dc.document_id = p_document_id
239
+ ORDER BY dc.embedding <=> query_embedding
240
+ LIMIT match_count;
241
+ END;
242
+ $$;
243
+
244
+ -- 4. 인덱스 생성 (HNSW 방식)
245
+ CREATE INDEX ON document_chunks USING hnsw (embedding vector_cosine_ops);
246
+ ```
247
+
248
+ </details>
249
+
250
+ <details>
251
+ <summary><b>📜 대안: OpenAI 1536차원 스키마</b></summary>
252
+ <br>
253
+
254
+ ```sql
255
+ CREATE EXTENSION IF NOT EXISTS vector;
256
+
257
+ CREATE TABLE IF NOT EXISTS document_chunks (
258
+ id BIGSERIAL PRIMARY KEY,
259
+ document_id TEXT NOT NULL,
260
+ content TEXT NOT NULL,
261
+ embedding vector(1536), -- text-embedding-3-small 차원
262
+ chunk_index INTEGER NOT NULL,
263
+ metadata JSONB DEFAULT '{}',
264
+ created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
265
+ );
266
+
267
+ CREATE OR REPLACE FUNCTION match_documents (
268
+ query_embedding vector(1536),
269
+ match_count int,
270
+ p_document_id text
271
+ ) RETURNS TABLE (
272
+ id BIGINT,
273
+ document_id TEXT,
274
+ content TEXT,
275
+ similarity FLOAT
276
+ )
277
+ LANGUAGE plpgsql
278
+ AS $$
279
+ BEGIN
280
+ RETURN QUERY
281
+ SELECT
282
+ dc.id,
283
+ dc.document_id,
284
+ dc.content,
285
+ 1 - (dc.embedding <=> query_embedding) as similarity
286
+ FROM document_chunks AS dc
287
+ WHERE dc.document_id = p_document_id
288
+ ORDER BY dc.embedding <=> query_embedding
289
+ LIMIT match_count;
290
+ END;
291
+ $$;
292
+
293
+ CREATE INDEX ON document_chunks USING hnsw (embedding vector_cosine_ops);
294
+ ```
295
+
296
+ </details>
297
+
298
+ 실행 후 Supabase 대시보드의 **Table Editor**에서 `document_chunks` 테이블이 생성되었는지 확인하세요.
299
+
300
+ ---
301
+
302
+ ### 6. 서버 실행
303
+
304
+ ```bash
305
+ pipenv run uvicorn app.main:app --reload
306
+ ```
307
+
308
+ 실행 후 브라우저에서 `http://127.0.0.1:8000` 접속으로 UI를 확인하세요.
309
+
310
+ ---
311
+
312
+ ### 7. 코드 포매터 설정 (선택)
313
+
314
+ 커밋 전 자동으로 코드 스타일을 정리하는 `black` 포매터를 pre-commit hook으로 설정할 수 있습니다.
315
+
316
+ ```bash
317
+ # dev 의존성 설치 (pre-commit, black 포함)
318
+ pipenv install --dev
319
+
320
+ # git hook 등록 (최초 1회)
321
+ pipenv run pre-commit install
322
+ ```
323
+
324
+ 등록 후에는 `git commit` 시 `black`이 자동 실행됩니다. 코드 스타일이 수정된 경우 파일을 다시 `git add` 한 뒤 커밋하면 됩니다.
325
+
326
+ > 이 단계를 건너뛰어도 프로젝트 실행에는 영향이 없습니다.
327
+
328
+ <br>
329
+ <br>
330
+
331
+ ## 🗓️ 2주 진행 구조
332
+
333
+ 환경 설정을 완료한 후, 아래 순서대로 단계별 문서를 따라 진행하세요.
334
+
335
+ - 주말(토/일, 9:00-18:00): 페어프로그래밍으로 구현/검증
336
+ - 평일: 사전 준비, 조사, 실험 기록, 의사결정 정리
337
+
338
+ | 단계 | 기간 | 문서 |
339
+ |---|---|---|
340
+ | **Prework** | Week 1 전 평일 | [`docs/01-prework/README.md`](./docs/01-prework/README.md) |
341
+ | **Weekend-1** | Week 1 주말 | [`docs/02-weekend1/README.md`](./docs/02-weekend1/README.md) |
342
+ | **Midweek** | Week 1~2 사이 평일 | [`docs/03-midweek/README.md`](./docs/03-midweek/README.md) |
343
+ | **Weekend-2** | Week 2 주말 | [`docs/04-weekend2/README.md`](./docs/04-weekend2/README.md) |
344
+
345
+ <br>
346
+ <br>
347
+
348
+ ## 📚 참고 학습 자료
349
+
350
+ ### 프로젝트 내부 문서
351
+
352
+ - **[RAG 시스템 기술 심층 분석](./docs/00-shared/reference.md)**: RAG 아키텍처와 기술 스택 전반. **필독하세요.**
353
+ - **[배포 가이드](./docs/04-weekend2/deployment.md)**: 배포 상세 가이드(심화/참고)입니다.
354
+
355
+ ### 외부 참고 자료
356
+
357
+ - **[What is RAG? (IBM)](https://www.ibm.com/topics/retrieval-augmented-generation)**: RAG 개념을 그림과 함께 설명하는 입문 자료입니다.
358
+ - **[RAG from Scratch (LangChain YouTube)](https://www.youtube.com/playlist?list=PLfaIDFEXuae2LXbO1_PKyVJiQ23ZztA0x)**: LangChain 공식 RAG 구현 영상 시리즈입니다 (영어).
359
+ - **[pgvector GitHub](https://github.com/pgvector/pgvector)**: `<=>` 연산자와 HNSW 인덱스 작동 방식을 확인하세요.
360
+ - **[Supabase Vector 가이드](https://supabase.com/docs/guides/ai)**: PostgreSQL을 벡터 데이터베이스로 사용하는 방법입니다.
361
+ - **[LangChain RecursiveCharacterTextSplitter](https://reference.langchain.com/python/langchain-text-splitters/character/RecursiveCharacterTextSplitter)**: 텍스트 청킹 전략에 대한 Python 공식 레퍼런스입니다.
362
+ - **[OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings)**: 텍스트를 숫자로 변환하는 원리를 이해해야 합니다.
363
+ - **[Vector Similarity Explained (Pinecone)](https://www.pinecone.io/learn/vector-similarity/)**: 유사도 측정 방식 비교 자료입니다.
app/__init__.py ADDED
File without changes
app/config.py ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import os
2
+ from dotenv import load_dotenv
3
+
4
+ load_dotenv()
5
+
6
+ # 공급자 설정: ollama(로컬, 기본) | openai(클라우드, 선택)
7
+ PROVIDER = os.getenv("PROVIDER", "ollama").lower()
8
+
9
+ # Ollama 설정 (기본값 - 로컬 모델 사용)
10
+ OLLAMA_BASE = os.getenv("OLLAMA_BASE", "http://localhost:11434")
11
+ OLLAMA_EMBED_MODEL = os.getenv("OLLAMA_EMBED_MODEL", "nomic-embed-text")
12
+ OLLAMA_CHAT_MODEL = os.getenv("OLLAMA_CHAT_MODEL", "llama3.1")
13
+
14
+ # OpenAI 설정 (선택사항 - PROVIDER=openai 일 때만 사용)
15
+ # OpenAI를 사용하려면 .env에서 PROVIDER=openai로 설정하고 아래 주석을 해제하세요.
16
+ # OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
17
+ # OPENAI_EMBEDDING_MODEL = os.getenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
18
+ # OPENAI_CHAT_MODEL = os.getenv("OPENAI_CHAT_MODEL", "gpt-3.5-turbo")
19
+
20
+ # OpenAI 사용 시 필수 키 검증
21
+ if PROVIDER == "openai":
22
+ OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
23
+ OPENAI_EMBEDDING_MODEL = os.getenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
24
+ OPENAI_CHAT_MODEL = os.getenv("OPENAI_CHAT_MODEL", "gpt-3.5-turbo")
25
+ if not OPENAI_API_KEY:
26
+ raise ValueError("PROVIDER=openai로 설정했지만 OPENAI_API_KEY가 설정되지 않았습니다.")
27
+
28
+ UPLOAD_DIR = "app/uploads"
29
+
30
+ if not os.path.exists(UPLOAD_DIR):
31
+ os.makedirs(UPLOAD_DIR)
32
+
33
+ ALLOWED_EXTENSIONS = {"pdf"}
34
+
35
+ SUPABASE_URL = os.getenv("SUPABASE_URL")
36
+ SUPABASE_KEY = os.getenv("SUPABASE_KEY")
app/embedding_utils.py ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from typing import List
2
+
3
+
4
+ def split_text(
5
+ text: str, chunk_size: int = 1000, chunk_overlap: int = 100
6
+ ) -> List[str]:
7
+ """
8
+ [TODO Day 1] 긴 텍스트를 적절한 크기의 청크로 분할하는 함수를 구현하세요.
9
+
10
+ 요구사항:
11
+ 1. 텍스트를 의미 단위로 분할할 수 있는 방법을 직접 조사하여 구현하세요.
12
+ - 어떤 라이브러리를 사용할지, 어떤 방식으로 분할할지는 스스로 결정하세요.
13
+ 2. chunk_size와 chunk_overlap 파라미터가 실제 분할 결과에 어떤 영향을 미치는지
14
+ 이해한 상태에서 구현하세요.
15
+ 3. (Deep Dive) 다양한 chunk_size를 실험해보고 최적의 값을 찾아보세요.
16
+ 힌트: REFERENCE.md의 청킹 섹션을 먼저 읽고, 어떤 파라미터가 품질에 영향을 주는지 파악하세요.
17
+
18
+ Args:
19
+ text (str): 분할할 전체 텍스트
20
+ chunk_size (int): 청크 당 최대 크기
21
+ chunk_overlap (int): 청크 간 중복 크기
22
+
23
+ Returns:
24
+ List[str]: 분할된 텍스트 청크 리스트
25
+ """
26
+ # ---------------------------------------------------------
27
+ # [Day 1] 과제: 여기에 텍스트 분할 로직을 작성하세요.
28
+ # ---------------------------------------------------------
29
+ pass
30
+
31
+
32
+ def get_embedding(text: str) -> List[float]:
33
+ """
34
+ [TODO Day 2] 텍스트의 벡터 임베딩을 생성하는 함수를 구현하세요.
35
+
36
+ 요구사항:
37
+ 1. 로컬에서 실행 중인 Ollama 서버를 통해 임베딩 벡터를 생성하세요.
38
+ - Ollama API 스펙을 직접 조사하세요: https://github.com/ollama/ollama/blob/main/docs/api.md
39
+ - 사용할 모델과 반환 벡터 차원은 README.md의 환경 설정 섹션을 참고하세요.
40
+ 2. 반환값은 float 숫자로 구성된 리스트여야 합니다.
41
+ 3. Ollama 서버가 응답하지 않는 경우를 적절히 처리하세요.
42
+
43
+ (선택사항) OpenAI 사용:
44
+ - .env에서 PROVIDER=openai로 설정한 경우에만 사용됩니다.
45
+ - OpenAI Embeddings API 스펙을 직접 조사하세요.
46
+
47
+ Args:
48
+ text (str): 임베딩할 텍스트
49
+
50
+ Returns:
51
+ List[float]: 임베딩 벡터
52
+ """
53
+ # ---------------------------------------------------------
54
+ # [Day 2] 과제: 여기에 임베딩 생성 로직을 작성하세요.
55
+ # 기본: Ollama 로컬 API 호출
56
+ # 선택: OpenAI API 호출 (PROVIDER=openai일 때)
57
+ # ---------------------------------------------------------
58
+ pass
app/main.py ADDED
@@ -0,0 +1,128 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from fastapi import FastAPI, UploadFile, File, HTTPException, Body
2
+ from fastapi.templating import Jinja2Templates
3
+ from fastapi.responses import HTMLResponse
4
+ from fastapi.staticfiles import StaticFiles
5
+ from fastapi import Request
6
+ import os
7
+ from uuid import uuid4
8
+ from typing import Dict, List
9
+
10
+ # 필요한 모듈 임포트 (여러분이 구현한 모듈)
11
+ from .embedding_utils import split_text, get_embedding
12
+ from .supabase_utils import save_embedding, search_similar_embeddings
13
+ from .config import UPLOAD_DIR, ALLOWED_EXTENSIONS
14
+
15
+ app = FastAPI(title="DocuFlow AI Agent")
16
+
17
+ # 템플릿 및 정적 파일 설정
18
+ templates = Jinja2Templates(directory="app/templates")
19
+ app.mount("/static", StaticFiles(directory="app/static"), name="static")
20
+
21
+
22
+ def allowed_file(filename: str) -> bool:
23
+ return "." in filename and filename.rsplit(".", 1)[1].lower() in ALLOWED_EXTENSIONS
24
+
25
+
26
+ def extract_text_from_pdf(file_path: str) -> str:
27
+ """
28
+ [TODO Day 1] PDF 파일에서 텍스트를 추출하는 함수입니다.
29
+
30
+ 요구사항:
31
+ 1. PDF에서 텍스트를 추출할 수 있는 방법을 직접 조사하여 구현하세요.
32
+ - 어떤 라이브러리를 사용할지는 스스로 결정하세요. (Pipfile에 설치된 패키지를 확인하세요.)
33
+ 2. 모든 페이지의 텍스트를 추출하여 하나의 문자열로 합치세요.
34
+ """
35
+ # ---------------------------------------------------------
36
+ # [Day 1] 과제: PDF 텍스트 추출 로직 작성
37
+ # ---------------------------------------------------------
38
+ pass
39
+
40
+
41
+ @app.get("/", response_class=HTMLResponse)
42
+ async def root_page(request: Request):
43
+ return templates.TemplateResponse("index.html", {"request": request})
44
+
45
+
46
+ @app.post("/documents/")
47
+ async def upload_document(file: UploadFile = File(...)):
48
+ """
49
+ [TODO Day 1 & 2] 문서 업로드 및 임베딩 처리 엔드포인트
50
+
51
+ 프로세스:
52
+ 1. 업로드된 파일을 로컬(UPLOAD_DIR)에 저장
53
+ 2. PDF에서 텍스트 추출
54
+ 3. 텍스트를 청크로 분할
55
+ 4. 각 청크를 임베딩하고 DB에 저장
56
+ 5. (Deep Dive) 대량의 청크를 처리할 때 속도 저하를 막기 위한 방법을 조사해보세요.
57
+ 힌트: Python의 비동기 처리 방식을 검토해보세요.
58
+ """
59
+ document_id = str(uuid4())
60
+
61
+ try:
62
+ # ---------------------------------------------------------
63
+ # [Day 1 & 2] 과제: 파이프라인 구현
64
+ # 1. 파일 저장
65
+ # 2. 텍스트 추출
66
+ # 3. 청크 분할
67
+ # 4. 임베딩 및 저장
68
+ # ---------------------------------------------------------
69
+
70
+ return {
71
+ "message": "문서 처리가 완료되었습니다.",
72
+ "document_id": document_id,
73
+ # "chunks_count": ...
74
+ }
75
+
76
+ except Exception as e:
77
+ print(f"오류 발생: {str(e)}")
78
+ raise HTTPException(status_code=500, detail=str(e))
79
+ finally:
80
+ # 임시 파일 삭제
81
+ # if os.path.exists(file_path):
82
+ # os.remove(file_path)
83
+ pass
84
+
85
+
86
+ @app.post("/qa")
87
+ async def question_answering(question: Dict[str, str] = Body(...)):
88
+ """
89
+ [TODO Day 3 & 4] RAG 기반 질의응답 엔드포인트
90
+
91
+ 프로세스:
92
+ 1. 사용자의 질문을 임베딩
93
+ 2. 유사한 문서 청크 검색
94
+ 3. 검색된 컨텍스트와 질문을 프롬프트로 구성
95
+ - 시스템 프롬프트는 어떻게 설계해야 환각을 방지할 수 있는지 직접 고민하세요.
96
+ - entry-task.md에서 작성한 시스템 프롬프트 초안을 적용해보세요.
97
+ 4. LLM에게 답변 요청
98
+ - 어떤 LLM API를 어떻게 호출해야 하는지 직접 조사하세요.
99
+ - 사용할 API 스펙: README.md의 외부 참고 자료에서 Ollama API 문서를 확인하세요.
100
+ 5. (Deep Dive) 이전 대화 내용을 기억하도록 messages 리스트를 관리해보세요.
101
+ REFERENCE.md의 Query Rewriting 섹션을 참고하세요.
102
+
103
+ (선택사항) OpenAI 사용:
104
+ - .env에서 PROVIDER=openai로 설정한 경우에만 사용됩니다.
105
+ """
106
+ try:
107
+ if "document_id" not in question:
108
+ raise HTTPException(status_code=400, detail="document_id is required")
109
+
110
+ user_question = question["query"]
111
+ document_id = question["document_id"]
112
+
113
+ # ---------------------------------------------------------
114
+ # [Day 3] 과제: RAG 로직 구현
115
+ # 1. 질문 임베딩
116
+ # 2. 벡터 검색
117
+ # 3. 프롬프트 구성 (System Prompt + Context + Question)
118
+ # 4. LLM 응답 생성
119
+ # ---------------------------------------------------------
120
+
121
+ # answer = ...
122
+ # similar_chunks = ...
123
+
124
+ return {"answer": "아직 AI가 연결되지 않았습니다. 코드를 완성해주세요!", "sources": []}
125
+
126
+ except Exception as e:
127
+ print(f"오류 발생: {str(e)}")
128
+ raise HTTPException(status_code=500, detail=str(e))
app/static/css/style.css ADDED
@@ -0,0 +1,233 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ body {
2
+ font-family: "Arial", sans-serif;
3
+ margin: 0;
4
+ line-height: 1.6;
5
+ background-image: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5)),
6
+ url("https://images.unsplash.com/photo-1550684376-efcbd6e3f031?q=80&w=2070&auto=format&fit=crop");
7
+ background-size: cover;
8
+ background-position: center;
9
+ background-attachment: fixed;
10
+ color: #333;
11
+ }
12
+
13
+ h1 {
14
+ text-align: center;
15
+ margin-bottom: 2rem;
16
+ color: #fff;
17
+ }
18
+
19
+ .main-wrapper {
20
+ max-width: 800px;
21
+ margin: 2rem auto;
22
+ padding: 2rem;
23
+ background: #fff;
24
+ border-radius: 8px;
25
+ box-shadow: 0 0 20px rgba(0, 0, 0, 0.05);
26
+ }
27
+
28
+ .container {
29
+ display: flex;
30
+ gap: 20px;
31
+ }
32
+ .upload-section,
33
+ .qa-section {
34
+ flex: 1;
35
+ padding: 20px;
36
+ border: none;
37
+ border-radius: 5px;
38
+ position: relative;
39
+ }
40
+ textarea {
41
+ width: 100%;
42
+ height: 100px;
43
+ margin: 10px 0;
44
+ }
45
+ .btn {
46
+ display: grid;
47
+ place-items: center;
48
+ padding: 10px 20px;
49
+ font-size: 16px;
50
+ text-align: center;
51
+ white-space: nowrap;
52
+ vertical-align: middle;
53
+ cursor: pointer;
54
+ border: 1px solid transparent;
55
+ border-radius: 5px;
56
+ color: white;
57
+ background-color: #007bff;
58
+ user-select: none; /* Prevent text selection */
59
+ position: relative;
60
+ }
61
+ .btn:hover {
62
+ background-color: #0056b3;
63
+ }
64
+ .btn:disabled {
65
+ background-color: #cccccc;
66
+ cursor: not-allowed;
67
+ border-color: #cccccc;
68
+ }
69
+ .btn > * {
70
+ grid-area: 1 / 1;
71
+ }
72
+
73
+ #uploadButton,
74
+ #askButton {
75
+ min-width: 110px; /* Adjust as needed */
76
+ min-height: 45px; /* Adjust as needed */
77
+ }
78
+
79
+ .error {
80
+ color: red;
81
+ margin-top: 10px;
82
+ }
83
+ .success {
84
+ color: green;
85
+ margin-top: 10px;
86
+ }
87
+ #answer {
88
+ margin-top: 20px;
89
+ padding: 10px;
90
+ border: 1px solid #ddd;
91
+ border-radius: 5px;
92
+ min-height: 100px;
93
+ }
94
+ .status {
95
+ margin-top: 10px;
96
+ padding: 10px;
97
+ border-radius: 5px;
98
+ display: none;
99
+ }
100
+ .status.processing {
101
+ background-color: #fff3cd;
102
+ color: #856404;
103
+ display: block;
104
+ }
105
+ .status.success {
106
+ background-color: #d4edda;
107
+ color: #155724;
108
+ display: block;
109
+ }
110
+ .status.error {
111
+ background-color: #f8d7da;
112
+ color: #721c24;
113
+ display: block;
114
+ }
115
+
116
+ .qa-section textarea {
117
+ width: 100%;
118
+ min-height: 100px;
119
+ padding: 10px;
120
+ box-sizing: border-box;
121
+ border: 1px solid #ccc;
122
+ border-radius: 5px;
123
+ font-size: 16px;
124
+ line-height: 1.5;
125
+ margin-bottom: 10px;
126
+ resize: vertical;
127
+ transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;
128
+ }
129
+
130
+ .qa-section textarea:focus {
131
+ border-color: #007bff;
132
+ outline: 0;
133
+ box-shadow: 0 0 0 0.2rem rgba(0, 123, 255, 0.25);
134
+ }
135
+
136
+ #answer-container {
137
+ margin-top: 20px;
138
+ position: relative;
139
+ min-height: 50px;
140
+ }
141
+
142
+ #answer {
143
+ white-space: pre-wrap;
144
+ word-wrap: break-word;
145
+ padding: 15px;
146
+ border-radius: 5px;
147
+ background-color: #f9f9f9;
148
+ border: 1px solid #ddd;
149
+ min-height: 24px;
150
+ }
151
+
152
+ .spinner {
153
+ border: 3px solid rgba(255, 255, 255, 0.3);
154
+ border-top-color: #fff;
155
+ border-radius: 50%;
156
+ width: 18px;
157
+ height: 18px;
158
+ animation: spin 0.8s linear infinite;
159
+ }
160
+
161
+ @keyframes spin {
162
+ 0% {
163
+ transform: rotate(0deg);
164
+ }
165
+ 100% {
166
+ transform: rotate(360deg);
167
+ }
168
+ }
169
+
170
+ .hidden {
171
+ display: none;
172
+ }
173
+
174
+ .file-input-container {
175
+ margin-bottom: 15px;
176
+ display: flex;
177
+ align-items: center;
178
+ }
179
+
180
+ .file-input-hidden {
181
+ display: none;
182
+ }
183
+
184
+ .file-input-label {
185
+ display: inline-block;
186
+ padding: 10px 20px;
187
+ background-color: #007bff;
188
+ color: white;
189
+ border: none;
190
+ border-radius: 5px;
191
+ cursor: pointer;
192
+ white-space: nowrap;
193
+ }
194
+
195
+ .file-input-label:hover {
196
+ background-color: #0056b3;
197
+ }
198
+
199
+ .file-name {
200
+ margin-left: 10px;
201
+ font-style: italic;
202
+ color: #555;
203
+ }
204
+
205
+ .btn-back {
206
+ position: absolute;
207
+ top: 20px;
208
+ right: 20px;
209
+ background: none;
210
+ border: none;
211
+ font-size: 16px;
212
+ color: #007bff;
213
+ cursor: pointer;
214
+ padding: 5px;
215
+ font-weight: bold;
216
+ }
217
+
218
+ .btn-back:hover {
219
+ text-decoration: underline;
220
+ }
221
+
222
+ .info-text {
223
+ color: #555;
224
+ font-size: 14px;
225
+ margin-bottom: 15px;
226
+ }
227
+
228
+ .upload-actions {
229
+ display: flex;
230
+ align-items: center;
231
+ gap: 15px;
232
+ margin-top: 15px;
233
+ }
app/static/js/main.js ADDED
@@ -0,0 +1,155 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ let currentDocumentId = null;
2
+
3
+ async function uploadDocument() {
4
+ const fileInput = document.getElementById("file");
5
+ const uploadButton = document.getElementById("uploadButton");
6
+ const uploadSpinner = document.getElementById("uploadSpinner");
7
+ const uploadButtonText = uploadButton.querySelector(".btn-text");
8
+
9
+ const file = fileInput.files[0];
10
+ if (!file) {
11
+ alert("파일을 선택해주세요.");
12
+ return;
13
+ }
14
+
15
+ uploadButton.disabled = true;
16
+ uploadSpinner.classList.remove("hidden");
17
+ uploadButtonText.classList.add("hidden");
18
+
19
+ const formData = new FormData();
20
+ formData.append("file", file);
21
+
22
+ try {
23
+ const uploadResponse = await fetch("/documents/", {
24
+ method: "POST",
25
+ body: formData,
26
+ });
27
+
28
+ if (!uploadResponse.ok) {
29
+ const errorData = await uploadResponse
30
+ .json()
31
+ .catch(() => ({ detail: uploadResponse.statusText }));
32
+ throw new Error(
33
+ `문서 처리 실패: ${errorData.detail || uploadResponse.status}`
34
+ );
35
+ }
36
+
37
+ const uploadData = await uploadResponse.json();
38
+ currentDocumentId = uploadData.document_id;
39
+
40
+ document.getElementById("qaDocumentIdDisplay").textContent =
41
+ currentDocumentId;
42
+ document.getElementById("qaFileNameDisplay").textContent = file.name;
43
+
44
+ document.getElementById("upload-section").classList.add("hidden");
45
+ document.getElementById("qa-section").classList.remove("hidden");
46
+ document.getElementById("askButton").disabled = false;
47
+ } catch (error) {
48
+ console.error("Error:", error);
49
+ alert(`오류 발생: ${error.message}`);
50
+ } finally {
51
+ uploadSpinner.classList.add("hidden");
52
+ uploadButtonText.classList.remove("hidden");
53
+ uploadButton.disabled = false;
54
+ }
55
+ }
56
+
57
+ async function askQuestion() {
58
+ const questionInput = document.getElementById("question");
59
+ const question = questionInput.value;
60
+ const askButton = document.getElementById("askButton");
61
+ const answerDiv = document.getElementById("answer");
62
+ const loadingSpinner = document.getElementById("loadingSpinner");
63
+ const answerContainer = document.getElementById("answer-container");
64
+ const askButtonText = askButton.querySelector(".btn-text");
65
+
66
+ if (!question) {
67
+ alert("질문을 입력해주세요.");
68
+ return;
69
+ }
70
+
71
+ if (!currentDocumentId) {
72
+ alert("문서를 먼저 업로드해주세요.");
73
+ return;
74
+ }
75
+
76
+ try {
77
+ askButton.disabled = true;
78
+ loadingSpinner.classList.remove("hidden");
79
+ askButtonText.classList.add("hidden");
80
+
81
+ answerDiv.textContent = "";
82
+ answerContainer.classList.remove("hidden");
83
+ answerDiv.classList.add("hidden");
84
+
85
+ const response = await fetch("/qa", {
86
+ method: "POST",
87
+ headers: {
88
+ "Content-Type": "application/json",
89
+ },
90
+ body: JSON.stringify({
91
+ query: question,
92
+ document_id: currentDocumentId,
93
+ }),
94
+ });
95
+
96
+ if (!response.ok) {
97
+ throw new Error(`HTTP error! status: ${response.status}`);
98
+ }
99
+
100
+ const data = await response.json();
101
+ answerDiv.textContent = data.answer;
102
+ } catch (error) {
103
+ console.error("Error:", error);
104
+ answerDiv.textContent = `오류 발생: ${error.message}`;
105
+ } finally {
106
+ askButton.disabled = false;
107
+ loadingSpinner.classList.add("hidden");
108
+ askButtonText.classList.remove("hidden");
109
+ answerDiv.classList.remove("hidden");
110
+ }
111
+ }
112
+
113
+ document.addEventListener("DOMContentLoaded", function () {
114
+ const uploadButton = document.getElementById("uploadButton");
115
+ uploadButton.addEventListener("click", uploadDocument);
116
+
117
+ const askButton = document.getElementById("askButton");
118
+ askButton.addEventListener("click", askQuestion);
119
+
120
+ const fileInput = document.getElementById("file");
121
+ const fileNameSpan = document.getElementById("fileName");
122
+
123
+ fileInput.addEventListener("change", function () {
124
+ const uploadButton = document.getElementById("uploadButton");
125
+ if (fileInput.files.length > 0) {
126
+ fileNameSpan.textContent = fileInput.files[0].name;
127
+ uploadButton.classList.remove("hidden");
128
+ } else {
129
+ fileNameSpan.textContent = "선택된 파일 없음";
130
+ uploadButton.classList.add("hidden");
131
+ }
132
+ });
133
+
134
+ const backButton = document.getElementById("backButton");
135
+ backButton.addEventListener("click", function () {
136
+ // Hide QA section, show Upload section
137
+ document.getElementById("qa-section").classList.add("hidden");
138
+ document.getElementById("upload-section").classList.remove("hidden");
139
+
140
+ // Reset state
141
+ currentDocumentId = null;
142
+ document.getElementById("question").value = "";
143
+ document.getElementById("answer").textContent = "";
144
+ document.getElementById("answer-container").classList.add("hidden");
145
+ document.getElementById("askButton").disabled = true;
146
+ document.getElementById("qaFileNameDisplay").textContent = "";
147
+
148
+ // Reset file input
149
+ const fileInput = document.getElementById("file");
150
+ const fileNameSpan = document.getElementById("fileName");
151
+ fileInput.value = "";
152
+ fileNameSpan.textContent = "선택된 파일 없음";
153
+ document.getElementById("uploadButton").classList.add("hidden");
154
+ });
155
+ });
app/supabase_utils.py ADDED
@@ -0,0 +1,68 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from supabase import create_client, Client
2
+ from typing import List, Dict, Any
3
+ import os
4
+
5
+ # 환경 변수 로드 및 Supabase 클라이언트 초기화
6
+ SUPABASE_URL = os.getenv("SUPABASE_URL")
7
+ SUPABASE_KEY = os.getenv("SUPABASE_KEY")
8
+
9
+ if not SUPABASE_URL or not SUPABASE_KEY:
10
+ raise ValueError("SUPABASE_URL과 SUPABASE_KEY가 설정되어 있어야 합니다.")
11
+
12
+ supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
13
+
14
+
15
+ def save_embedding(
16
+ document_id: str, chunk: str, embedding: List[float], chunk_index: int
17
+ ) -> Dict:
18
+ """
19
+ [TODO Day 2] 문서 청크와 임베딩 벡터를 Supabase DB에 저장하는 함수입니다.
20
+
21
+ 요구사항:
22
+ 1. README.md의 데이터베이스 구성 섹션에서 생성한 테이블에 데이터를 저장하세요.
23
+ - 어떤 컬럼에 어떤 값을 저장해야 하는지 SQL 스키마를 직접 확인하세요.
24
+ 2. Supabase Python 클라이언트 사용 방법은 직접 조사하세요.
25
+ - 힌트: 위에서 이미 초기화된 `supabase` 클라이언트를 활용하세요.
26
+
27
+ Args:
28
+ document_id (str): 문서 ID
29
+ chunk (str): 텍스트 청크 내용
30
+ embedding (List[float]): 임베딩 벡터
31
+ chunk_index (int): 청크 순서 인덱스
32
+
33
+ Returns:
34
+ Dict: 저장된 데이터 정보
35
+ """
36
+ # ---------------------------------------------------------
37
+ # [Day 2] 과제: 여기에 DB 저장 로직을 작성하세요.
38
+ # ---------------------------------------------------------
39
+ pass
40
+
41
+
42
+ def search_similar_embeddings(
43
+ query_embedding: List[float],
44
+ document_id: str,
45
+ limit: int = 5,
46
+ similarity_threshold: float = 0.7,
47
+ ) -> List[Dict[str, Any]]:
48
+ """
49
+ [TODO Day 3] 사용자의 질문 벡터와 유사한 문서 청크를 검색하는 함수입니다.
50
+
51
+ 요구사항:
52
+ 1. README.md의 데이터베이스 구성 섹션에서 생성한 RPC 함수를 활용하여 유사도 검색을 수행하세요.
53
+ - 어떤 인자를 전달해야 하는지 SQL 스키마의 RPC 함수 정의를 직접 확인하세요.
54
+ 2. 유사도(similarity)가 similarity_threshold 이상인 결과만 필터링하세요. (선택사항)
55
+
56
+ Args:
57
+ query_embedding (List[float]): 질문의 임베딩 벡터
58
+ document_id (str): 검색할 문서 ID
59
+ limit (int): 반환할 최대 결과 수
60
+ similarity_threshold (float): 유사도 임계값
61
+
62
+ Returns:
63
+ List[Dict[str, Any]]: 유사한 문서 청크 리스트
64
+ """
65
+ # ---------------------------------------------------------
66
+ # [Day 3] 과제: 여기에 벡터 검색 로직을 작성하세요.
67
+ # ---------------------------------------------------------
68
+ pass
app/templates/index.html ADDED
@@ -0,0 +1,56 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!DOCTYPE html>
2
+ <html lang="ko">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>문서 도우미 AI 에이전트</title>
7
+ <link rel="stylesheet" href="/static/css/style.css" />
8
+ </head>
9
+ <body>
10
+ <h1>문서 도우미 AI 에이전트</h1>
11
+ <div class="main-wrapper">
12
+ <div class="container">
13
+ <div id="upload-section" class="upload-section">
14
+ <h2>문서 업로드</h2>
15
+ <div class="file-input-container">
16
+ <input
17
+ type="file"
18
+ id="file"
19
+ accept=".pdf"
20
+ class="file-input-hidden"
21
+ />
22
+ <label for="file" class="btn">파일 선택</label>
23
+ <span id="fileName" class="file-name">선택된 파일 없음</span>
24
+ </div>
25
+ <div class="upload-actions">
26
+ <button id="uploadButton" class="btn hidden">
27
+ <span class="btn-text">업로드</span>
28
+ <div id="uploadSpinner" class="spinner hidden"></div>
29
+ </button>
30
+ </div>
31
+ </div>
32
+
33
+ <div id="qa-section" class="qa-section hidden">
34
+ <button id="backButton" class="btn-back">
35
+ &larr; 새로 업로드하기
36
+ </button>
37
+ <h2>질문하기</h2>
38
+ <p class="info-text">
39
+ 현재 문서 ID: <span id="qaDocumentIdDisplay">N/A</span>
40
+ </p>
41
+ <p class="info-text">파일명: <span id="qaFileNameDisplay"></span></p>
42
+ <textarea id="question" placeholder="질문을 입력하세요..."></textarea>
43
+ <button id="askButton" class="btn" disabled>
44
+ <span class="btn-text">질문하기</span>
45
+ <div id="loadingSpinner" class="spinner hidden"></div>
46
+ </button>
47
+ <div id="answer-container" class="hidden">
48
+ <div id="answer"></div>
49
+ </div>
50
+ </div>
51
+ </div>
52
+ </div>
53
+
54
+ <script src="/static/js/main.js"></script>
55
+ </body>
56
+ </html>
assets/docuflow.jpg ADDED

Git LFS Details

  • SHA256: ead7377f75685e60ac43f3026e2b457d82081226ef34f5c2d6e3e05b0a631e85
  • Pointer size: 131 Bytes
  • Size of remote file: 965 kB
docker-compose.yml ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ version: '3.8'
2
+
3
+ services:
4
+ # 기본 실행 서비스
5
+ # - pipenv 기반 Dockerfile로 앱이 실행됩니다.
6
+ # - PROVIDER 값에 따라 ollama 또는 openai 트랙을 사용합니다.
7
+ app:
8
+ build: .
9
+ ports:
10
+ - "8000:8000"
11
+ environment:
12
+ - PROVIDER=${PROVIDER:-ollama}
13
+ - OLLAMA_BASE=${OLLAMA_BASE:-http://ollama:11434}
14
+ - OLLAMA_EMBED_MODEL=${OLLAMA_EMBED_MODEL:-nomic-embed-text}
15
+ - OLLAMA_CHAT_MODEL=${OLLAMA_CHAT_MODEL:-llama3.1}
16
+ - SUPABASE_URL=${SUPABASE_URL}
17
+ - SUPABASE_KEY=${SUPABASE_KEY}
18
+ - OPENAI_API_KEY=${OPENAI_API_KEY:-}
19
+ - OPENAI_EMBEDDING_MODEL=${OPENAI_EMBEDDING_MODEL:-text-embedding-3-small}
20
+ - OPENAI_CHAT_MODEL=${OPENAI_CHAT_MODEL:-gpt-3.5-turbo}
21
+ volumes:
22
+ - ./app/uploads:/app/app/uploads
23
+ - ./.env:/app/.env:ro
24
+ restart: unless-stopped
25
+
26
+ # 로컬 Ollama 트랙용 서비스
27
+ # - PROVIDER=openai여도 이 서비스는 기본으로 올라옵니다.
28
+ # - OpenAI 전용 운영 시 필요 없으면 `docker compose stop ollama`로 중지 가능합니다.
29
+ ollama:
30
+ image: ollama/ollama:latest
31
+ ports:
32
+ - "11434:11434"
33
+ volumes:
34
+ - ollama_data:/root/.ollama
35
+ restart: unless-stopped
36
+
37
+ volumes:
38
+ ollama_data:
39
+
docs/00-shared/reference.md ADDED
@@ -0,0 +1,590 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 🔬 AI Q&A 시스템 기술 심층 분석
2
+
3
+ <br/>
4
+
5
+ ## ❓ 1. 문제 정의: 일반 LLM의 한계
6
+
7
+ **"왜 그냥 ChatGPT API에 바로 질문하면 안 되나요?"**
8
+
9
+ 이는 매우 합리적인 질문입니다. 그에 대한 답변은 LLM(거대 언어 모델)의 근본적인 특징에 있습니다.
10
+
11
+ - **LLM의 지식은 훈련 시점에 멈춰있습니다:** LLM은 인터넷의 방대한 공개 데이터를 학습하지만, 그 지식은 특정 과거 시점에 고정되어 있습니다. 우리가 방금 업로드한 비공개 PDF 파일이나 최신 정보에 대해서는 전혀 알지 못합니다.
12
+ - **거짓말을 할 수 있습니다 (환각, Hallucination):** LLM은 모르는 정보에 대해 "모르겠습니다"라고 답하기보다, 그럴듯한 거짓 정보를 지어내는 경향이 있습니다. 이는 정확성이 중요한 Q&A 시스템에서는 치명적인 단점입니다.
13
+
14
+ 이 환각 현상을 이해하려면, LLM이 인간처럼 '사고'하는 존재가 아니라 극도로 정교한 **'다음 단어 예측 기계'** 라는 본질을 알아야 합니다. LLM의 가장 기본적인 임무는 주어진 문맥 다음에 올 가장 확률이 높은 단어를 예측하는 것이기 때문입니다. 예를 들어, "하늘의 색깔은" 이라는 텍스트를 받으면, 방대한 훈련 데이터 속에서 "파란색"이라는 단어가 뒤따를 통계적 확률이 압도적으로 높다는 것을 학습했기 때문에 "파란색입니다"라고 답변을 완성합니다.
15
+
16
+ 이때 LLM은 왜 "모르겠습니다"라고 솔직하게 답하지 않을까요? 그 이유는 **LLM의 훈련 목표**에 있습니다. LLM은 '진실만을 말하도록' 훈련되지 않았습니다. LLM의 훈련 목표는 '주어진 텍스트 다음에 이어질, 통계적으로 가장 그럴듯한 텍스트를 생성'하는 것입니다. '진실성'은 훈련의 목표가 아니라, 방대한 데이터 속의 사실들을 학습한 결과로 나타나는 부수적인 특징일 뿐입니다. '모르겠다'는 답변은 통계적으로 등장 확률이 낮기 때문에, LLM은 그보다 그럴듯한 무언가를 지어내는 것을 더 자연스러운 문장 완성이라고 판단하는 경향이 있습니다.
17
+
18
+ 이는 마치 정교한 **가짜 API(Mock API)** 와 같습니다. 요청의 형식이 올바르기만 하면, 실제 데이터베이스에 연결되어 있지 않더라도 항상 그럴듯한 구조와 데이터 타입의 JSON 응답을 생성해서 보내주는 것과 같습니다. 응답의 내용은 진짜가 아니지만, 형식은 완벽한 것과 마찬가지입니다.
19
+
20
+ 🚀 따라서, **우리만의 데이터를 기반으로 정확한 답변을 얻기 위해서는 LLM을 그냥 사용하는 것이 아니라, 특별한 방식이 필요합니다.**
21
+
22
+ <br/>
23
+ <br/>
24
+
25
+ ## 💡 2. 해결책: RAG (Retrieval-Augmented Generation)
26
+
27
+ RAG (검색-증강 생성)는 위에서 언급된 LLM의 한계를 극복하기 위한 강력하고 표준적인 아키텍처 패턴입니다.
28
+
29
+ LLM에 그냥 질문하는 것은, 마치 애플리케이션의 로컬 DB나 캐시는 전혀 확인하지 않고 모든 요청을 외부 API에 보내는 것과 비슷합니다. **RAG**는 사용자의 질문이 들어오면, 먼저 우리 **로컬 데이터베이스(Vector DB)** 에서 질문과 가장 관련된 정보를 **검색(Retrieve)** 하고, 그 검색 결과를 LLM에 대한 API 요청 본문에 **포함(Augment)** 하여 보냅니다. LLM은 추가로 전달된 이 정보를 바탕으로 **답변을 생성(Generate)** 합니다.
30
+
31
+ 쉽게 말해, LLM에게 '오픈북 테스트'를 보게 하여, 우리가 제공한 자료(업로드된 문서) 안에서만 답변을 만들도록 유도하는 기술입니다.
32
+
33
+ <br/>
34
+
35
+ ### 🌐 RAG의 실제 활용 사례
36
+
37
+ RAG는 이제 아이디어 단계를 넘어, 수많은 글로벌 및 국내 서비스에서 핵심 기술로 사용되며 사용자 경험을 혁신하고 있습니다.
38
+
39
+ - **차세대 고객 지원 챗봇 (토스, 카카오뱅크 등):**
40
+
41
+ - 회사의 내부 도움말 문서, 금융상품 약관, 이전 상담 기록 등을 기반으로 고객의 복잡한 질문에 24시간 정확하고 일관된 답변을 제공합니다. 상담원의 반복적인 업무를 줄여주고, 고객은 기다릴 필요 없이 즉시 해결책을 얻을 수 있습니다.
42
+
43
+ - **지능형 상품 검색 및 추천 (네이버 쇼핑, 쿠팡 등):**
44
+
45
+ - "가성비 좋은 캠핑 의자 찾아줘"와 같이, 사용자의 추상적인 자연어 질문의 '의도'를 파악합니다. 수많은 상품의 상세 설명과 구매 후기(지식)를 바탕으로, 단순 키워드 매칭을 넘어 가장 적합한 상품을 찾아 제시합니다.
46
+
47
+ - **지식 기반 질의응답 및 요약 (Notion Q&A 등):**
48
+ - "지난 1분기 마케팅 예산 보고서 찾아줘"와 같이 사내 문서를 검색하는 것을 넘어, 사용자가 업로드한 자료나 웹 페이지의 내용을 기반으로 질문에 답하고, 긴 글을 핵심만 요약해주는 등 지식 관리의 효율���을 극대화합니다.
49
+
50
+ 이처럼 RAG는 우리가 가진 '데이터'의 가치를 극대화하여, LLM을 더욱 똑똑하고 유용하게 만드는 가장 현실적이고 강력한 방법 중 하나입니다.
51
+
52
+ <br/>
53
+ <br/>
54
+
55
+ ## 🧩 3. RAG의 핵심 구성 요소
56
+
57
+ RAG 워크플로우를 가능하게 하는 두 가지 핵심 기술입니다.
58
+
59
+ <br/>
60
+
61
+ ### ✨ 3-1. 텍스트 임베딩 (Text Embedding): 단어를 '의미의 좌표'로 바꾸기
62
+
63
+ - **핵심 아이디어:** 컴퓨터가 글자의 모양이 아니라 '의미'를 이해하고 비교하게 만드는 기술입니다.
64
+
65
+ #### 🧐 벡터(Vector)란 무엇인가? (수학 없이 이해하기)
66
+
67
+ "벡터"라는 말에 겁먹을 필요 없습니다. 복잡한 수학 공식은 전혀 필요 없고, **'좌표'** 라는 개념만 이해하면 충분합니다.
68
+
69
+ 1. **2차원 지도 위의 '좌표'**:
70
+
71
+ - 우리는 지도 위 특정 도시의 위치를 '위도'와 '경도'라는 2개의 숫자로 표현합니다. 예를 들어, 서울은 대략 `[위도 37.5, 경도 127.0]` 이라는 **좌표**를 가집니다.
72
+ - 이 `[37.5, 127.0]` 이라는 숫자 배열이 바로 **2차원 벡터**입니다.
73
+ - 중요한 것은, 이 좌표 덕분에 컴퓨터는 서울과 부산 사이의 '거리'를 계산할 수 있습니다.
74
+
75
+ 2. **'의미'의 지도 위의 '좌표'**:
76
+
77
+ - 이제 지도의 축을 '위도/경도'가 아니라 '의미'라고 상상해봅시다. 예를 들어, 한쪽 축은 '격식성'을, 다른 축은 '주제가 기술인가?'를 나타낼 수 있습니다.
78
+ - "서버 점검 일정을 공지드립니다"라는 문장은 '격식성' 축에서는 높은 값을, '기술 주제' 축에서도 높은 값을 가질 겁니다.
79
+ - "오늘 서버 터졌음 ㅋㅋ"라는 문장은 두 축 모두에서 낮은 값을 갖겠죠.
80
+ - 이런 의미에 따라 위치를 찍을 수 있는 '의미의 지도'를 생각해 볼 수 있습니다.
81
+
82
+ 3. **N차원 '의미 공간'의 '좌표'**:
83
+
84
+ - 임베딩 모델이 하는 일은 바로 이것입니다. 단, '격식성', '기술 주제'와 같이 단순한 2개의 축이 아니라, AI가 학습한 **수백~수천 개의 추상적인 의미 축**을 가진 '의미 공간'을 만듭니다. 이 차원의 수는 사용하는 임베딩 모델에 따라 달라집니다. (참고: 현재 우리 프로젝트가 사용하는 `nomic-embed-text` 모델은 768차원의 벡터를 생성합니다. OpenAI의 `text-embedding-ada-002`는 1536차원입니다.)
85
+ - 우리가 "오늘 날씨가 좋다"라는 문장을 모델에 보내면, 모델은 이 문장이 N차원의 의미 공간에서 어디에 위치하는지를 나타내는 **N개의 숫자 리스트(좌표)** 를 돌려줍니다. 이것이 바로 **N차원 벡터**입니다.
86
+ - `[0.01, -0.23, 0.45, ..., -0.09]` (숫자가 N개)
87
+
88
+ 4. **그래서 이게 왜 강력한가?**:
89
+ - 이제 모든 문서는 자신만의 고유한 '의미 좌표'를 갖게 됩니다.
90
+ - 컴퓨터는 이 좌표들 사이의 **'거리'를 계산**할 수 있습니다.
91
+ - "자동차가 고장났어요"라는 문장의 좌표와 "차에 문제가 생겼어요"라는 문장의 좌표는 의미 공간에서 매우 **가까운 거리에** 위치하게 됩니다.
92
+ - 반면 "차를 마시고 있어요"라는 문장의 좌표는 훨씬 **먼 거리에** 위치합니다.
93
+ - **결론: 벡터는 컴퓨터가 텍스트의 '의미적 유사도'를 '물리적 거리'로 계산할 수 있게 해주는 마법 같은 번역기입니다.**
94
+
95
+ <br/>
96
+
97
+ 아래 다이어그램은 단어들이 '의미 공간' 속에서 어떻게 관계를 형성하는지 시각적으로 보여줍니다. '강아지'와 '개'의 관계는 '새끼 고양이'와 '고양이'의 관계와 기하학적으로 유사한 방향과 거리를 갖게 됩니다.
98
+
99
+ ```mermaid
100
+ graph TD
101
+ subgraph "의미 공간 (Semantic Space)"
102
+ puppy[강아지]
103
+ dog[개]
104
+ kitten[새끼 고양이]
105
+ cat[고양이]
106
+ end
107
+
108
+ dog --"새끼 관계"--> puppy
109
+ cat --"새끼 관계"--> kitten
110
+ dog --"종(Species) 관계"--> cat
111
+ ```
112
+
113
+ <br/>
114
+
115
+ #### 🧠 임베딩 모델은 어떻게 '의미'를 학습하나요?
116
+
117
+ 이제 "벡터"가 '의미의 좌표'라는 것을 알았으니, 한 가지 질문이 남습니다. "대체 어떤 규칙으로 그 좌표를 정하는 걸까?"
118
+
119
+ 결론부터 말하면, **사람이 규칙을 정해주지 않습니다. 모델이 방대한 텍스트 데이터 속에서 단어와 문장들의 '관계'를 스스로 학습하여 규칙을 만듭니다.**
120
+
121
+ - **관계로부터 의미 배우기:** 모델은 수십억 개의 문장을 읽으며 어떤 단어들이 함께, 혹은 비슷한 맥락에서 등장하는지 통계적으로 학습합니다.
122
+ - "어린 강아지는 개의 새끼이다."
123
+ - "새끼 고양이는 고양이의 새끼이다."
124
+ - "개는 멍멍 짖는다."
125
+ - "고양이는 야옹 하고 운다."
126
+ - 이런 문장들을 무수히 많이 학습하면서, 모델은 '강아지'와 '개', 그리고 '새끼 고양이'와 '고양이'가 유사한 관계('새끼' 관계)에 있다는 것을 파악합니다.
127
+
128
+ - **'의미의 방향'과 '거리'로 관계 표현:**
129
+
130
+ - 학습이 끝나면, 모델은 이 관계들을 앞서 설명한 '의미 공간'이라는 가상의 지도에 배치합니다.
131
+ - 그 결과, '강아지' 좌표에서 '개' 좌표를 뺀 **방향과 거리**는, '새끼 고양이' 좌표에서 '고양이' 좌표를 뺀 방향과 거리와 거의 똑같아집니다. (`강아지 - 개 ≈ 새끼 고양이 - 고양이`)
132
+ - 마찬가지로, '걷다'에서 '걸었다'로 가는 방향은 '뛰다'에서 '뛰었다'로 가는 방향과 비슷해집니다. (시제 관계 학습)
133
+ - 이것이 바로 모델이 단어 사이의 문법적, 의미적 관계를 '기하학적 관계'로 이해하는 방식입니다.
134
+
135
+ - **추상적인 N개의 축:**
136
+ - 우리가 비유로 들었던 '격식성' 같은 축은 사람이 이해하기 쉬운 예시일 뿐입니다.
137
+ - 실제 모델이 사용하는 수백~수천 개의 축은 AI 모델이 스스로 찾아낸, 인간이 직관적으로 이름을 붙이기 어려운 매우 복잡하고 추상적인 '의미의 구성 요소'들입니다.
138
+ - 이 축들이 모여 단어와 문장의 미묘한 뉘앙스 차이까지 표현하는 정교한 '의미의 좌표'를 만들어내는 것입니다.
139
+
140
+ <br/>
141
+
142
+ #### 🤔 잠깐, '차원 수'는 누가 어떻게 정하나요?
143
+
144
+ 결론부터 말하면, **벡터의 차원 수는 모델을 훈련시키기 전에 사람이 미리 정하는 중요한 '하이퍼파라미터(Hyperparameter)'** 입니다.
145
+
146
+ > 하이퍼파라미터란, 모델이 데이터로부터 스스로 '학습'하는 값(Parameter)이 아니라, 학습 과정과 모델의 구조를 제어하기 위해 사람이 사전에 직접 설정하는 값들을 의미합니다.
147
+
148
+ 웹 개발에 비유하자면, 이는 애플리케이션의 아키텍처(예: MSA vs Monolith)를 결정하거나, DB 필드의 `VARCHAR` 길이를 미리 정하는 것과 비슷합니다. 한 번 정해지면 바꾸기 어렵고, 시스템 전체의 성능과 비용에 큰 영향을 미칩니다.
149
+
150
+ - **고차원 (High Dimension, 예: 1536 - OpenAI)**
151
+ - **장점:** 더 많은 '의미의 축'으로 텍스트의 미묘한 뉘앙스를 정교하게 표현할 수 있습니다. (성능 잠재력 ↑)
152
+ - **단점:** 벡터 크기가 커져 저장 공간을 많이 차지하고, 검색 속도도 느려집니다. (비용/속도 ↓)
153
+ - **중차원 (Medium Dimension, 예: 768 - Ollama nomic-embed-text)**
154
+ - **장점:** 성능과 효율성의 균형이 잘 잡혀있어 대부분의 RAG 작업에 충분한 성능을 제공하면서도 저장 공간과 검색 속도 면에서 효율적입니다.
155
+ - **단점:** 매우 복잡한 의미 구분이 필요한 경우 고차원 모델 대비 약간의 성능 차이가 있을 수 있습니다.
156
+ - **저차원 (Low Dimension, 예: 384)**
157
+ - **장점:** 벡터가 작고 가벼워 저장과 검색이 빠르고 경제적입니다. (비용/속도 ↑)
158
+ - **단점:** 표현력이 부족하여 서로 다른 의미가 충돌할 가능성이 있습니다. (성능 잠재력 ↓)
159
+
160
+ 우리가 사용하는 `nomic-embed-text` 모델의 `768`이라는 차원 수는, 모델을 만든 개발팀이 수많은 실험을 통해 '성능'과 '효율성' 사이의 최적의 균형점을 찾아 결정한 값입니다. (참고: OpenAI의 `text-embedding-ada-002`는 1536차원입니다.) 우리는 이미 만들어진 모델을 사용하므로 이 값을 직접 바꿀 수는 없지만, 이 개념을 이해하는 것은 왜 특정 모델을 선택하는지, 그리고 그 선택이 시스템에 어떤 영향을 미치는지 이해하는 데 매우 중요합니다.
161
+
162
+ <br/>
163
+ <br/>
164
+
165
+ ### 🗄️ 3-2. 벡터 데이터베이스 (Vector Database)
166
+
167
+ - **무엇인가?:** 위에서 생성된 수많은 벡터(의미 좌표)들을 저장하고, 특정 벡터와 가장 '가까운(유사한)' 다른 벡터들을 초고속으로 검색하는 데 특화된 데이터베이스입니다.
168
+ - **왜 필요한가?:** 수백만 개의 벡터 중에서 특정 벡터와 가장 유사한 것을 찾기 위해 모든 벡터와 일일이 거리를 계산하는 것은 매우 비효율적입니다(Full Scan). 벡터 데이터베이스는 특수한 인덱스를 사용하여 이 검색 속도를 획기적으로 높여줍니다. 이는 관계형 데이터베이스에서 `WHERE` 절의 검색 속도를 높이기 위해 `B-Tree 인덱스`를 거는 것과 정확히 같은 원리입니다.
169
+ - **주요 솔루션들:** 우리 프로젝트에서는 PostgreSQL의 확장 기능인 `pgvector`를 Supabase를 통해 사용하고 있지만, 시장에는 다양한 벡터 DB 솔루션이 존재합니다.
170
+ - **전문 벡터 DB (Managed):** `Pinecone`, `Weaviate` 등. 벡터 검색 전용으로 설계된 완전 관리형 클라우드 서비스입니다.
171
+ - **오픈소스 라이브러리/DB:** `Milvus`, `Faiss` (by Meta) 등. 직접 설치하고 운영해야 하는 높은 유연성을 제공하는 솔루션입니다.
172
+ - **기존 DB의 확장 기능:** `pgvector` (in PostgreSQL), `Redis`, `Elasticsearch`, `MongoDB Atlas Vector Search` 등. 이미 사용 중인 DB에 벡터 검색 기능을 추가하는 방식입니다.
173
+
174
+ <br/>
175
+ <br/>
176
+
177
+ ## 🔄 4. 전체 워크플로우 정리
178
+
179
+ 우리 프로젝트에서 RAG가 작동하는 전체 흐름은 다음과 같습니다.
180
+
181
+ ```mermaid
182
+ graph TD
183
+ subgraph "인덱싱 (문서 → 지식 베이스)"
184
+ A[PDF 문서] --> B(텍스트 청크 분할)
185
+ B --> C{임베딩 모델}
186
+ C -- "벡터와 원본 텍스트<br/>쌍으로 저장" --> D((벡터 DB))
187
+ end
188
+
189
+ subgraph "답변 생성 (질문 → 답변)"
190
+ E[사용자 질문] --> F{임베딩 모델}
191
+ D & F -- "유사도 검색" --> G[관련성 높은 정보]
192
+ E & G -- "프롬프트 구성" --> H{LLM}
193
+ H --> I((사용자에게 답변))
194
+ end
195
+ ```
196
+
197
+ <br/>
198
+ <br/>
199
+
200
+ ### 📥 1단계: 인덱싱 (Indexing / 문서 처리)
201
+
202
+ 1. **업로드**: 사용자가 PDF를 업로드합니다.
203
+ 2. **분할 (Chunking)**: 서버(FastAPI)는 PDF를 여러 개의 작은 텍스트 **청크(Chunk)** 로 분할합니다. (자세한 내용은 아래를 참고하세요)
204
+ 3. **임베딩 (Embedding)**: 각 청크는 로컬 Ollama 서버의 Embedding API로 전송되어 **벡터**로 변환됩니다. (기본: `nomic-embed-text`, 768차원)
205
+ 4. **저장 (Storing)**: `(원본 텍스트 청크, 벡터)` 쌍이 **Supabase(PostgreSQL + pgvector) DB**에 저장됩니다.
206
+
207
+ <br/>
208
+
209
+ #### 🤔 청킹(Chunking)은 왜, 어떻게 해야 할까요?
210
+
211
+ **"문서를 그냥 통째로 임베딩하면 안 되나요?"**
212
+
213
+ 좋은 질문입니다. 문서를 '청크'라는 작은 단위로 나누는 데에는 몇 가지 중요한 기술적, 전략적 이유가 있습니다.
214
+
215
+ 1. **의미의 명확성 확보:**
216
+
217
+ - 거대한 문서 전체를 하나의 벡터로 만들면, 그 벡터는 문서의 '평균적인' 의미를 나타내게 됩니다. 이는 너무 광범위해서, 사용자의 구체적인 질문과 관련된 부분을 정확히 찾아내기 어렵습니다.
218
+ - 작은 청크로 나누면, 각 청크는 더 집중되고 구체적인 의미를 가진 벡터를 갖게 됩니다. 이를 통해 사용자의 질문과 정말로 '관련성 높은' 정보 조각을 정확히 찾아낼 수 있습니다.
219
+
220
+ 2. **LLM 및 임베딩 모델의 토큰 한계:**
221
+ - LLM 모델과 임베딩 모델은 한 번에 처리할 수 있는 텍스트의 양(토큰 수)에 제한이 있습니다. LLM의 경우 이를 '컨텍스트 창(Context Window)'이라고 부릅니다.
222
+ - 수백 페이지짜리 문서를 통째로 임베딩하거나 LLM에게 전달할 수는 없습니다. 따라서 우리는 검색을 통해 가장 관련 있는 '청크'들만 골라서 LLM의 컨텍스트 창 안에 효율적으로 넣어주어야 합니다.
223
+
224
+ **청킹(Chunking)의 Best Practices**
225
+
226
+ 그렇다면 어떻게 청크를 나누는 것이 가장 효율적일까요? 이는 RAG 시스템의 성능에 큰 영향을 미치는 중요한 과정이며, 보통 다음 두 가지 요소를 핵심 하이퍼파라미터로 고려합니다.
227
+
228
+ - **청크 크기 (Chunk Size):**
229
+
230
+ - **너무 작으면?** 문장의 의미가 중간에 잘릴 수 있고, 질문에 답하기에 충분한 맥락을 포함하지 못할 수 있습니다.
231
+ - **너무 크면?** 관련 없는 정보가 너무 많이 포함되어, 검색된 결과의 핵심 의미가 희석될 수 있습니다.
232
+ - 정답은 없으며, 문서의 종류와 내용에 따라 적절한 크기를 실험적으로 찾아야 합니다. 보통 256, 512, 1024 토큰 등을 기준으로 잡습니다.
233
+
234
+ - **청크 겹침 (Chunk Overlap):**
235
+ - 청크와 청크 사이에 걸쳐 있는 중요한 문장이나 아이디어가 잘리는 것을 방지하기 위해, 의도적으로 청크의 일부를 겹치게 만듭니다.
236
+ - 예를 들어, 512 토큰 크기로 자르되, 각 청크가 이전 청크의 마지막 50개 토큰을 포함하게 만드는 식입니다. 이렇게 하면 정보의 연속성을 유지하는 데 큰 도움이 됩니다.
237
+
238
+ > 📌 실제 구현에 사용할 청킹 라이브러리의 동작 방식은 직접 조사해보세요.
239
+ > 어떤 구분자(separator)를 어떤 순서로 적용하는지, `chunk_size`가 토큰 기준인지 문자 기준인지 확인하면
240
+ > 청킹 파라미터 튜닝 시 훨씬 정확한 판단을 내릴 수 있습니다.
241
+
242
+ <br/>
243
+
244
+ #### 🤔 왜 벡터와 원본 텍스트를 함께 저장할까요?
245
+
246
+ **"검색은 벡터로 할 텐데, 왜 원본 텍스트까지 DB에 저장해야 하나요?"**
247
+
248
+ 이는 RAG의 최종 목표를 생각하면 명확해집니다.
249
+
250
+ - **벡터는 '주소', 원본 텍스트는 '내용물'입니다.**
251
+
252
+ - 벡터는 텍스트의 의미를 나타내는 '좌표' 또는 '주소'일 뿐, 그 자체로 원본 정보를 담고 있지는 않습니다. `[0.01, -0.23, ...]` 같은 숫자 배열을 LLM에게 줘봐야 아무 의미가 없습니다.
253
+ - 우리의 최종 목표는 사용자의 질문과 가장 유사한 **'정보(텍스트)'** 를 찾아서 LLM에게 '참고 자료'로 제공하는 것입니다.
254
+
255
+ - **따라서 워크플로우는 다음과 같이 이루어집니다.**
256
+ 1. 사용자의 '질문 벡터'를 사용하여 벡터 DB에서 가장 가까운 **'주소(벡터)'** 들을 찾습니다.
257
+ 2. 찾아낸 '주소'에 해당하는 **'내용물(원본 텍스트 청크)'** 을 DB에서 꺼냅니다.
258
+ 3. 이 '내용물'들을 모아 컨텍스트로 구성한 뒤, LLM에게 질문과 함께 전달합니다.
259
+
260
+ 결론적으로, `(벡터, 원본 텍스트)` 쌍으로 저장하는 것은, 초고속으로 관련 정보를 찾기 위한 **인덱스(벡터)** 와, 찾은 후에 LLM에게 실제로 제공할 **데이터(원본 텍스트)** 를 함께 관리하는, 매우 효율적인 방식입니다.
261
+
262
+ <br/>
263
+ <br/>
264
+
265
+ ### 💬 2단계: 검색 및 생성 (Retrieval & Generation / Q&A)
266
+
267
+ 1. **사용자 질문**: 사용자가 웹 UI에서 질문을 입력합니다.
268
+ 2. **질문 임베딩**: 질문 텍스트 역시 로컬 Ollama 서버의 Embedding API로 전송되어 **'질문 벡터'** 로 변환됩니다.
269
+ 3. **유사도 검색**: 서버는 이 '질문 벡터'를 가지고 Supabase DB에 쿼리를 실행합니다 (`match_documents` 함수). DB는 벡터 검색을 통해 질문 벡터와 가장 의미적으로 유사한(가까운) **상위 5개의 텍스트 청크**를 반환합니다.
270
+ 4. **컨텍스트 생성**: 서버는 이 5개의 청크를 조합하여 **'컨텍스트(Context)'** 라는 하나의 긴 문자열을 만듭니다.
271
+ 5. **증강된 프롬프트 생성**: 최종적으로 로컬 Ollama 서버의 Chat API(`llama3.1`)에 다음과 같은 **증강된 프롬프트(Augmented Prompt)** 를 전송합니다.
272
+
273
+ > **컨텍스트:** [DB에서 찾은 관련 내용 5개] > **질문:** [사용자의 원본 질문]
274
+ >
275
+ > "위 컨텍스트를 바탕으로 질문에 답해주세요."
276
+
277
+ 6. **답변 생성**: LLM은 이 '쪽지(Context)'를 참고하여 답변을 생성하고, 서버는 이 답변을 사용자에게 보여줍니다.
278
+
279
+ (참고: OpenAI를 사용하려면 `.env`에서 `PROVIDER=openai`로 설정하면 GPT-3.5-turbo를 사용할 수 있습니다.)
280
+
281
+ <br/>
282
+ <br/>
283
+
284
+ ## 🎯 5. 심화 고려사항: RAG 시스템 성능 높이기
285
+
286
+ 지금까지 설명한 워크플로우는 RAG의 기본 뼈대입니다. 실제 운영 환경에서는 더 나은 답변 품질을 위해 다음과 같은 요소들을 추가로 고려하게 됩니다.
287
+
288
+ <br/>
289
+
290
+ ### 📏 5-1. 유사도 측정 방식: 선택과 집중
291
+
292
+ - **"벡터가 '가깝다'는 것을 계산하는 방법은 한 가지뿐인가요?"**
293
+
294
+ - 그렇지 않습니다. 벡터 공간에서 두 벡터의 '유사도' 또는 '거리'를 측정하는 방법은 여러 가지가 있으며, 각각의 장단점이 있어 사용 사례에 맞게 선택해야 합니다.
295
+
296
+ 가장 중요한 원칙은 **임베딩 모델을 훈련할 때 사용된 측정 방식과 동일한 방식을 벡터 DB에서도 사용하는 것**입니다. 예를 들어, 코사인 유사도로 훈련된 `all-MiniLM-L6-v2` 모델을 사용한다면, DB에서도 코사인 유사도를 사용해야 최상의 결과를 얻을 수 있습니다. 만약 어떤 방식을 사용했는지 불분명하거나, LSH처럼 특정 손실 함수 없이 만들어진 임베딩이라면, 데이터와 사용 사례의 특성에 따라 가장 적합한 방식을 선택해야 합니다.
297
+
298
+ <br/>
299
+
300
+ ### 🤔 잠깐, 코사인 유사도는 정말 '크기'와 무관한가요?
301
+
302
+ 네, 그렇습니다. 하지만 코사인 유사도 계산식에 '내적(Dot Product)'이 포함되어 있어 이 부분이 헷갈릴 수 있습니다. 내적은 두 벡터의 크기와 방향을 모두 반영하기 때문입니다.
303
+
304
+ 핵심은 코사인 유사도의 마지막 단계인 **'정규화(Normalization)'**, 즉 각 벡터 크기의 곱으로 나눠주는 과정에 있습니다. 이 과정이 벡터의 '크기'라는 요소를 수학적으로 완벽하게 제거하고, 순수하게 '방향' 정보만을 남깁니다. 아래 다이어그램은 두 계산 방식의 차이를 명확히 보여줍니다.
305
+
306
+ ```mermaid
307
+ graph TD
308
+ subgraph "내적: 방향과 크기를 모두 고려"
309
+ direction LR
310
+ style C fill:#FFE6CC,stroke:#D79B00
311
+ style D fill:#FFE6CC,stroke:#D79B00
312
+ A["벡터 A (힘: 3)"] --> C("점수 = 방향 유사도 × <b>3</b> × <b>5</b>");
313
+ B["벡터 B (힘: 5)"] --> C;
314
+ C -- "결과값은<br/><b>방향과 크기</b><br/>모두에 영향을 받음" --> D(높은 점수);
315
+ end
316
+
317
+ subgraph "코사인 유사도: 오직 방향만 고려"
318
+ direction LR
319
+ style G fill:#DAE8FC,stroke:#6C8EBF
320
+ style H fill:#DAE8FC,stroke:#6C8EBF
321
+ E["벡터 A (힘: 3)"] -- "크기를 1로 정규화" --> F["벡터 A'<br/>(힘: 1)"];
322
+ I["벡터 B (힘: 5)"] -- "크기를 1로 정규화" --> J["벡터 B'<br/>(힘: 1)"];
323
+
324
+ F --> G("점수 = 방향 유사도 × <b>1</b> × <b>1</b>");
325
+ J --> G
326
+ G -- "결과값은<br/>오직 <b>방향</b>에만<br/>영향을 받음" --> H(방향 점수)
327
+ end
328
+ ```
329
+
330
+ 가장 대표적인 3가지는 다음과 같습니다.
331
+
332
+ | 측정 방식 | 핵심 원리 (직관적 의미) | 무엇에 민감한가? | 특징 및 주요 사용 사례 |
333
+ | ---------------------- | ------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
334
+ | **코사인 유사도** | "두 벡터가 같은 방향을 바라보는가?" (각도 측정) | **방향(Direction)** 에만 민감. | **(우리 프로젝트의 선택)** 텍스트의 '주제'나 '맥락'이 중요할 때 사용합니다. "차가 고장났다"와 "자동차가 망가졌다"는 문장 길이(벡터 크기)가 달라도 방향이 비슷해 유사도가 높게 나옵니다. |
335
+ | **유클리드 거리** | "두 점 사이의 최단 직선 거리는 얼마인가?" | **절대적 위치(Magnitude & Direction)** 에 민감. | 이미지 유사도(픽셀값 차이), 수치 데이터 분석 등 벡터의 각 요소값이 절대적인 의미를 가질 때 사용합니다. 추천 시스템에서 "A는 영화를 5번, B는 1번 봤다" 같은 절대적인 횟수 차이를 반영하고 싶을 때 적합합니다. |
336
+ | **내적 (Dot Product)** | "한 벡터가 다른 벡터 방향으로 얼마나 기여하는가?" | **방향과 크기(Direction & Magnitude)** 모두에 민감. | 같은 방향일 때, 크기가 클수록(예: 더 인기 있거나 중요할수록) 더 높은 점수를 부여하고 싶을 때 사용합니다. 정규화(normalize)된 벡터에서는 코사인 유사도와 동일한 결과를 내면서 계산이 더 빠르다는 장점이 있어, 검색 시스템 내부 최적화에 자주 사용됩니다. |
337
+
338
+ > 참고 자료: [Vector Similarity Explained (Pinecone)](https://www.pinecone.io/learn/vector-similarity/)
339
+
340
+ <br/>
341
+
342
+ #### 💡 심화: 왜 참고 자료에서는 내적과 코사인 유사도를 혼용해서 설명하나요?
343
+
344
+ 앞선 설명으로 혼란스러울 수 있는 지점입니다. "코사인 유사도는 크기와 무관하다"고 배웠는데, 왜 Pinecone 같은 기술 문서에서는 내적(크기에 영향을 받음)을 코사인 유사도와 거의 같은 것처럼 설명할까요?
345
+
346
+ **결론부터 말하면, 이는 '성능 최적화'를 위해 널리 사용되는 기법 때문입니다.**
347
+
348
+ 핵심은 **'사전 정규화(Pre-normalization)'** 라는 개념에 있습니다.
349
+
350
+ 1. **저장 시점에 정규화:** 벡터를 데이터베이스에 저장할 때, 모든 벡터의 크기(Magnitude, L2-norm)를 **1**로 정규화해서 저장합니다.
351
+ 2. **검색 시점에는 내적 사용:** 이렇게 모든 벡터의 크기가 1이 되면, 코사인 유사도 계산 공식 `cos(θ) = (A • B) / (||A|| * ||B||)`에서 분모 `||A|| * ||B||`가 항상 `1 * 1 = 1`이 됩니다.
352
+ 3. **결과:** 결국 **코사인 유사도 계산이 내적(`A • B`) 계산과 완전히 동일**해집니다.
353
+
354
+ 내적 연산은 나누셈이 포함된 코사인 유사도 계산보다 훨씬 빠르기 때문에, 대부분의 고성능 벡터 검색 시스템은 이런 최적화 기법을 사용합니다.
355
+
356
+ 따라서 기술 문서들이 두 용어를 혼용하는 것은, **'원리'** 보다는 **'최적화된 실제 구현'** 의 관점에서 설명하기 때문입니다. 원리적으로는 코사인 유사도는 여전히 방향만을, 내적은 방향과 크기를 모두 고려하는 것이 맞습니다.
357
+
358
+ <br/>
359
+
360
+ #### 🤔 그렇다면 왜 우리 프로젝트는 코사인 유사도를 사용했나요?
361
+
362
+ - **1. 개념: '의미'를 찾기 위한 최적의 지표**
363
+
364
+ - RAG의 목적은 텍스트의 '의미'가 비슷한 것을 찾는 것이고, 이는 벡터의 '방향'으로 표현됩니다. 여기서 한 가지 오해하기 쉬운 점이 있습니다. 코사인 유사도의 계산식에는 벡터의 크기와 방향을 모두 반영하는 '내적(Dot Product)'이 포함되지만, 이 값을 각 벡터 크기의 곱으로 나누는 **정규화(Normalization)** 과정이 핵심입니다.
365
+ - 이 정규화 덕분에 벡터의 '크기' 정보는 상쇄되고, 최종적으로는 순수하게 두 벡터가 가리키는 **'방향'의 유사성**만이 남게 됩니다. 문장의 길이나 단어 사용 빈도와 같은 요소(벡터의 크기에 영향을 줄 수 있는)에 상관없이, 내용의 '의미'가 얼마나 비슷한지를 측정해야 하는 우리 프로젝트의 목적에 가장 잘 부합하는 방���입니다.
366
+
367
+ - **2. 현실: 인덱스 친화적인 '거리'의 필요성**
368
+
369
+ - 데이터베이스의 벡터 인덱스(우리가 사용한 IVFFlat 등)는 '유사도'(클수록 좋음)가 아닌 '거리'(작을수록 좋음) 개념에 맞춰 성능이 최적화되어 있습니다.
370
+
371
+ - **3. `pgvector`의 해결책: 최적화된 연산자**
372
+
373
+ - `pgvector`는 이 문제를 해결하기 위해, 내부적으로는 가장 빠른 '내적' 연산을 활용하면서도 결과를 '거리' 개념으로 반환해주는 최적화된 연산자들을 제공합니다.
374
+ - **`<=>`** (코사인 거리): `1 - (코사인 유사도)`를 계산합니다. 인덱스를 활용한 유사도 검색을 위한 가장 표준적이고 직관적인 연산자입니다.
375
+
376
+ <br/>
377
+ <br/>
378
+
379
+ ### ✅ 5-2. LLM 모델 선택의 중요성 (The Importance of LLM Choice)
380
+
381
+ - 최종 답변의 품질을 결정하는 가장 중요한 요소 중 하나는 바로 마지막에 답변 생성을 요청할 **LLM 모델의 선택**입니다.
382
+ - 우리 프로젝트는 기본적으로 **로컬 Ollama(`llama3.1`)** 를 사용합니다. 이는 수많은 선택지 중 하나이며, 각 모델은 다음과 같은 장단점을 가집니다.
383
+
384
+ - **성능 (Performance):** 모델이 얼마나 복잡한 추론을 잘하고, 지시를 잘 따르며, 자연스러운 문장을 만드는가?
385
+ - **비용 (Cost):** API 호출에 얼마의 비용이 드는가? (보통 처리하는 텍스트의 양에 따라 과금됩니다)
386
+ - **속도 (Speed):** 요청을 보냈을 때 답변이 생성되기까지 얼마나 걸리는가?
387
+
388
+ - **주요 모델 비교:**
389
+
390
+ - **`Ollama` (로컬 오픈소스 모델, 우리 프로젝트의 기본 선택):**
391
+ - **임베딩 모델:** `nomic-embed-text` (768차원) - 경량이면서도 우수한 성능을 제공하는 오픈소스 임베딩 모델
392
+ - **채팅 모델:** `llama3.1` (8B) - Meta의 Llama 3 계열. GPT-3.5 수준의 성능을 로컬에서 무료로 사용 가능. Ollama에서 `llama3.3`, `qwen2.5`, `gemma3` 등 다양한 최신 모델도 선택 가능
393
+ - **장점:**
394
+ - 완전 무료 (API 비용 없음)
395
+ - 데이터 프라이버시 보장 (로컬에서 실행)
396
+ - 인터넷 연결 없이도 동작 가능
397
+ - 모델을 직접 제어하고 커스터마이징 가능
398
+ - **단점:**
399
+ - 로컬 하드웨어(CPU/GPU, 메모리) 성능에 의존
400
+ - 초기 모델 다운로드 시간 필요
401
+ - 클라우드 모델 대비 응답 속도가 느릴 수 있음
402
+ - **사용 사례:** 프라이버시가 중요한 문서 처리, 개발/학습 환경, 비용 절감이 필요한 프로젝트
403
+
404
+ - **`GPT-4o` / `GPT-4o mini` (by OpenAI, 선택사항):** 현재 OpenAI의 주력 모델. `GPT-4o`는 고성능, `GPT-4o mini`는 빠르고 저렴하면서도 충분한 성능을 제공해 RAG 작업에 가장 합리적인 클라우드 선택지입니다. (구형 `GPT-3.5-turbo`를 대체)
405
+ - **`o3-mini` / `o1` (by OpenAI):** 복잡한 추론이 필요한 작업에 특화된 추론 모델(Reasoning Model). 단순 Q&A보다는 다단계 논리 추론이 필요한 경우에 적합합니다.
406
+ - **`Claude 3.7 Sonnet` / `Claude 3.5 Haiku` (by Anthropic):** Anthropic의 최신 모델. `Claude 3.7 Sonnet`은 최고 성능, `Claude 3.5 Haiku`는 빠르고 저렴합니다. 긴 문서 처리에 강한 대용량 컨텍스트 창(200K 토큰)이 특징입니다.
407
+ - **`Gemini 2.0 Flash` (by Google):** 빠른 응답 속도와 낮은 비용이 강점인 Google의 최신 경량 모델. 멀티모달(텍스트+이미지) 처리도 지원합니다.
408
+
409
+ - **우리 프로젝트가 `Ollama`를 기본으로 선택한 이유:**
410
+ - **비용 효율성:** API 호출 비용이 전혀 발생하지 않아 개발 및 학습 단계에서 부담이 없습니다.
411
+ - **프라이버시:** 민감한 문서를 외부 서버로 전송하지 않고 로컬에서 처리할 수 있어 보안이 강화됩니다.
412
+ - **학습 목적:** 오픈소스 모델의 동작 원리를 직접 확인하고 실험할 수 있습니다.
413
+ - **충분한 성능:** Llama 3.1은 대부분의 RAG 작업에 충분한 성능을 제공합니다.
414
+
415
+ (선택사항) 배포 환경에서 더 높은 성능이나 안정적인 응답 속도가 필요하다면 `.env`에서 `PROVIDER=openai`로 설정하여 OpenAI 모델을 사용할 수 있습니다.
416
+
417
+ <br/>
418
+ <br/>
419
+
420
+ ## 🎓 6. RAG를 넘어서: 파인튜닝의 필요성
421
+
422
+ 지금까지 우리는 RAG가 어떻게 외부 지식을 LLM에 주입하여 정확하고 근거 있는 답변을 생성하는지 알아보았습니다. RAG는 LLM에게 '오픈북 테스트'를 보게 하여, 우리가 제공한 문서 내에서 답을 찾게 하는 매우 강력한 접근법입니다.
423
+
424
+ 하지만 만약 우리의 요구사항이 단순히 **'무엇'** 을 아는 것을 넘어, **'어떻게'** 말해야 하는지에 대한 것이라면 어떨까요?
425
+
426
+ - **특정 브랜드의 목소리:** 고객 서비스 챗봇이 항상 회사의 정해진 톤앤매너(친근함, 전문적임 등)로만 대답해야 할 때
427
+ - **특정 분야의 전문 용어:** 의료 AI가 일반적인 단어 대신, 정확한 의학 용어를 일관되게 사용해야 할 때
428
+ - **정해진 출력 형식:** 법률 AI가 항상 계약서의 특정 조항 형식에 맞춰 텍스트를 생성해야 할 때
429
+
430
+ 이런 경우, 우리는 LLM에게 단순히 새로운 '지식'을 제공하는 것을 넘어, LLM의 근본적인 **'행동'이나 '스타일' 자체를 변화**시키고 싶습니다. RAG는 LLM에게 '참고 자료'를 쥐여주는 것이지만, LLM의 말투나 사고방식을 바꾸지는 못합니다.
431
+
432
+ 바로 이 지점에서 **파인튜닝(Fine-tuning)** 의 필요성이 대두됩니다.
433
+
434
+ 파인튜닝은 특정 작업이나 도메인에 맞는 수많은 '질문과 정답'(각각 전통적인 머신러닝의 Feature와 Label에 해당) 예시 데이터를 가지고 LLM을 추가로 훈련시키는 과정입니다. 이는 마치 LLM을 특정 분야의 '전문가'로 만들기 위한 집중 훈련과 같습니다. 이를 통해 우리는 LLM이 단순히 주어진 정보를 활용하는 것을 넘어, 우리가 원하는 스타일과 형식으로 생각하고 응답하도록 그 '본성'을 바꿀 수 있습니다.
435
+
436
+ 따라서, 다음 단계에서는 RAG로 해결하기 어려운 문제들을 파인튜닝을 통해 어떻게 해결할 수 있는지 알아볼 것입니다.
437
+
438
+ <br/>
439
+ <br/>
440
+
441
+ ### ⚖️ RAG vs 파인튜닝: 언제 무엇을 써야 할까?
442
+
443
+ | 구분 | RAG (검색-증강 생성) | 파인튜닝 (Fine-tuning) |
444
+ | :----------------- | :-------------------------------------------------------- | :------------------------------------------------------------- |
445
+ | **목표** | LLM에게 **새로운 '지식'** 을 제공하여 사실 기반 답변 생성 | LLM의 **'행동'이나 '스타일'** 을 특정 목적에 맞게 변화 |
446
+ | **핵심 원리** | '오픈북 테스트' (외부 지식 참조) | '전문가 집중 훈련' (모델의 내부 지식과 행동 교정) |
447
+ | **주요 사용 사례** | 최신 정보 반영, 사내 문서 기반 Q&A, 환각 현상 감소 | 특정 톤앤매너(말투) 적용, 정해진 형식으로 출력, 전문 용어 사용 |
448
+ | **장점** | 데이터 추가/수정이 용이, 비용이 저렴, 환각이 적음 | LLM의 근본적인 '성격'을 바꿀 수 있음 |
449
+ | **단점** | LLM의 말투나 스타일은 바꾸지 못함, 검색 성능에 의존적 | 높은 훈련 비용과 시간, 새로운 지식 추가의 어려움, 환각 위험성 |
450
+
451
+ 따라서, 다음 단계에서는 RAG로 해결하기 어려운 문제들을 파인튜닝을 통해 어떻게 해결할 수 있는지 알아볼 것입니다.
452
+
453
+ <br/>
454
+ <br/>
455
+
456
+ ## 📊 7. RAG 시스템 품질을 어떻게 측정할까?
457
+
458
+ RAG 파이프라인을 만들었다면, 이제 "이 시스템이 얼마나 잘 작동하는가?"를 측정해야 합니다.
459
+ 웹 서비스에 비유하면, 기능 개발 후 QA 테스트를 하는 것과 같습니다.
460
+
461
+ RAG 시스템의 품질을 측정하는 핵심 지표는 3가지입니다.
462
+
463
+ <br/>
464
+
465
+ ### 📏 7-1. 정확성 (Correctness)
466
+
467
+ **"답이 맞나요?"**
468
+
469
+ 가장 직관적인 지표입니다. 사용자가 질문했을 때 시스템이 옳은 답을 주었는지를 측정합니다.
470
+
471
+ **측정 방법 (수동 평가)**
472
+
473
+ 1. 테스트 질문 10개를 미리 만들어둡니다. (업로드한 문서에서 답을 찾을 수 있는 질문들)
474
+ 2. 각 질문에 대한 '정답'을 미리 정해둡니다.
475
+ 3. RAG 시스템이 내놓은 답변을 정답과 비교하여 맞으면 1점, 틀리면 0점을 줍니다.
476
+ 4. 정확성(%) = (정답 수 / 전체 질문 수) × 100
477
+
478
+ **예시**
479
+
480
+ | 질문 | 정답 | 시스템 답변 | 판정 |
481
+ |---|---|---|---|
482
+ | "이 계약서의 만료일은?" | 2026년 3월 31일 | "2026년 3월 31일입니다." | ✅ 정답 |
483
+ | "계약 갱신 조건은?" | 90일 전 서면 통보 | "60일 전에 통보해야 합니다." | ❌ 오답 |
484
+
485
+ <br/>
486
+
487
+ ### 📐 7-2. 근거성 (Faithfulness)
488
+
489
+ **"문서를 보고 답했나요, 아니면 지어냈나요?"**
490
+
491
+ 정확성과 다른 개념입니다. 답이 '맞더라도' 문서가 아닌 LLM의 학습 데이터에서 나온 답이라면, 이 지표는 낮습니다. 이것이 RAG를 도입한 핵심 이유를 점검하는 지표입니다.
492
+
493
+ 오픈북 시험에 비유하면, '책을 보고 답을 썼는가'를 확인하는 것입니다. 정답을 알고 있어서 책을 안 보고 썼더라도, 오픈북 시험의 취지에는 어긋납니다.
494
+
495
+ **측정 방법 (수동 평가)**
496
+
497
+ 1. 시스템의 답변과 함께 '어떤 청크를 근거로 사용했는지'를 확인합니다. (sources 필드)
498
+ 2. 답변 내용이 실제로 그 청크에서 왔는지 확인합니다.
499
+ 3. 청크에 없는 내용이 답변에 포함되어 있으면 근거성 ❌
500
+
501
+ **예시**
502
+
503
+ ```
504
+ 청크 내용: "계약 기간은 2026년 1월 1일부터 2026년 12월 31일까지이다."
505
+
506
+ 시��템 답변: "계약 기간은 2026년 1월 1일부터 2026년 12월 31일까지이며,
507
+ 자동 갱신 옵션도 있습니다."
508
+
509
+ → '자동 갱신'은 청크에 없는 내용 → 근거성 ❌ (LLM이 지어낸 것)
510
+ ```
511
+
512
+ <br/>
513
+
514
+ ### 🚫 7-3. 응답 실패율 (Failure Rate)
515
+
516
+ **"답을 아예 못 했나요?"**
517
+
518
+ 시스템이 에러를 내거나, 타임아웃이 되거나, 빈 응답을 반환한 비율입니다. 시스템의 안정성을 나타냅니다.
519
+
520
+ 응답 실패율(%) = (에러 + 타임아웃 + 무응답 수 / 전체 질문 수) × 100
521
+
522
+ <br/>
523
+
524
+ ### 🔍 7-4. 세 가지 지표를 함께 보는 방법
525
+
526
+ 이 3가지 지표를 함께 보면 "어디서 문제가 생기는지" 진단할 수 있습니다.
527
+
528
+ | 정확성 | 근거성 | 의심 원인 및 조치 방향 |
529
+ |---|---|---|
530
+ | 낮음 | 낮음 | 검색된 청크 자체가 관련 없음 → `chunk_size`, `top-k` 조정 |
531
+ | 높음 | 낮음 | LLM이 문서 외 내용을 지어냄 → 시스템 프롬프트 강화 |
532
+ | 낮음 | 높음 | 관련 청크를 못 찾음 → 청크가 너무 작거나 문서 구조 문제 |
533
+ | 높음 | 높음 | ✅ 잘 작동 중 |
534
+
535
+ > 📌 현재 프로젝트에서는 이 지표를 **수동으로** 측정합니다.
536
+ > 실제 프로덕션 환경에서는 [RAGAS](https://github.com/explodinggradients/ragas) 같은 자동화 평가 프레임워크를 사용하기도 합니다. 관심 있다면 조사해보세요.
537
+
538
+ <br/>
539
+ <br/>
540
+
541
+ ## 🔁 8. 멀티턴 대화와 Query Rewriting
542
+
543
+ ### 문제: 대화 맥락이 끊어지는 RAG
544
+
545
+ 기본 RAG 시스템은 질문 하나를 독립적으로 처리합니다.
546
+ 그런데 사람은 대화를 이어가면서 이전 맥락을 자연스럽게 참조합니다.
547
+
548
+ 다음 대화를 보세요.
549
+
550
+ ```
551
+ 사용자: "계약서의 만료일이 언제야?"
552
+ 시스템: "2026년 3월 31일입니다."
553
+ 사용자: "그럼 그 전에 갱신하려면 어떻게 해야 해?" ← "그"가 무엇인지 시스템이 모름
554
+ ```
555
+
556
+ 두 번째 질문 "그 전에 갱신하려면"에서 "그"는 만료일(2026년 3월 31일)을 가리킵니다.
557
+ 하지만 기본 RAG는 각 질문을 독립적으로 임베딩하기 때문에, "그 전에 갱신하려면 어떻게 해야 해?"를 그대로 벡터로 변환합니다. "그"가 무엇인지 모르는 상태에서 검색하면 엉뚱한 청크를 가져올 수 있습니다.
558
+
559
+ <br/>
560
+
561
+ ### 해결책: Query Rewriting (질문 재작성)
562
+
563
+ **핵심 아이디어:** 사용자의 질문을 그대로 사용하는 대신, 이전 대화 맥락을 반영하여 독립적으로 이해 가능한 질문으로 LLM이 먼저 재작성합니다.
564
+
565
+ ```
566
+ [대화 히스토리]
567
+ 사용자: "계약서의 만료일이 언제야?"
568
+ 시스템: "2026년 3월 31일입니다."
569
+
570
+ [원본 질문]
571
+ "그럼 그 전에 갱신하려면 어떻게 해야 해?"
572
+
573
+ [재작성된 질문 — LLM이 생성]
574
+ "계약서 만료일(2026년 3월 31일) 이전에 계약을 갱신하려면 어떤 절차가 필요한가?"
575
+ ```
576
+
577
+ 이렇게 재작성된 질문을 임베딩하면, 관련 청크를 훨씬 정확하게 검색할 수 있습니다.
578
+
579
+ <br/>
580
+
581
+ ### 워크플로우 비교
582
+
583
+ | 구분 | 기본 RAG | Query Rewriting 적용 |
584
+ |---|---|---|
585
+ | 입력 | 현재 질문만 임베딩 | 대화 히스토리 + 현재 질문 → LLM 재작성 → 재작성된 질문 임베딩 |
586
+ | 장점 | 단순, 빠름 | 멀티턴 맥락 유지 |
587
+ | 단점 | 맥락 참조 불가 | LLM 호출 1회 추가 (지연 증가) |
588
+
589
+ > 📌 현재 프로젝트의 `/qa` 엔드포인트 **Deep Dive** 항목입니다.
590
+ > 기본 구현을 완성한 후, 대화 히스토리를 `messages` 리스트로 관리하면서 Query Rewriting을 적용해보세요.
docs/01-prework/README.md ADDED
@@ -0,0 +1,89 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 사전학습 패킷 (Week 1 진입 게이트)
2
+
3
+ [Stage: Prework]
4
+
5
+ Week 1 온라인 라이브 실습에 참여하려면 아래 3가지를 사전에 완료해야 합니다.
6
+
7
+ 1. 필독 범위 학습
8
+ 2. RAG 이론 자가 셀프 체크 작성
9
+ 3. 진입 과제 제출
10
+
11
+ ---
12
+
13
+ ## 1) 필독 범위
14
+
15
+ 아래 문서는 **읽기만 하는 것**이 아니라, 이후 제출물에 직접 반영되어야 합니다.
16
+
17
+ ### A. 핵심 이론
18
+
19
+ - [`docs/00-shared/reference.md`](../00-shared/reference.md)
20
+ - `1. 문제 정의: 일반 LLM의 한계`
21
+ - `2. 해결책: RAG (Retrieval-Augmented Generation)`
22
+ - `3. RAG의 핵심 구성 요소`
23
+ - `4. 전체 워크플로우 정리`
24
+ - `5. 심화 고려사항: RAG 시스템 성능 높이기`
25
+
26
+ ### B. 구현/운영 기준
27
+
28
+ - [`README.md`](../../README.md)
29
+ - `2주 진행 구조` 섹션
30
+ - `환경 설정` 섹션
31
+ - `참고 학습 자료` 섹션
32
+
33
+ ---
34
+
35
+ ## 2) RAG 이론 자가 셀프 체크
36
+
37
+ - 작성 파일: [`docs/01-prework/self-check.md`](./self-check.md)
38
+ - 작성 방식:
39
+ - 각 문항마다 `설명(1~2문장)` + `프로젝트 적용 예시(1개)` 작성
40
+ - 통과 기준:
41
+ - 필수 문항 6개 모두 작성
42
+ - 각 문항이 본인 기준으로 명확히 설명 가능한 상태
43
+
44
+ ---
45
+
46
+ ## 3) 진입 과제 (필수 제출)
47
+
48
+ 문서에 없는 질문에 대해 환각을 방지하는 **시스템 프롬프트 초안**을 작성합니다.
49
+
50
+ - 작성 파일: [`docs/01-prework/entry-task.md`](./entry-task.md)
51
+ - 분량:
52
+ - 시스템 프롬프트 본문 8~15줄
53
+ - 테스트 질문 3개 + 기대 동작
54
+ - 필수 포함 요소:
55
+ - 문서 근거 우선 원칙
56
+ - 문서 외 질문 거절 또는 한계 고지
57
+ - 불확실성 표현(추정 금지)
58
+ - 가능한 경우 근거 출처 표기 방식
59
+
60
+ ---
61
+
62
+ ## 제출물 체크리스트
63
+
64
+ 아래 2개 파일이 모두 채워져 있으면 사전학습 패킷 완료로 간주합니다.
65
+
66
+ - [ ] [`docs/01-prework/self-check.md`](./self-check.md) 작성 완료
67
+ - [ ] [`docs/01-prework/entry-task.md`](./entry-task.md) 작성 완료
68
+
69
+ ## 권장 제출 순서
70
+
71
+ 1. 필독 범위 정독
72
+ 2. [`self-check.md`](./self-check.md) 작성
73
+ 3. [`entry-task.md`](./entry-task.md) 작성 및 자가 테스트
74
+
75
+ ---
76
+
77
+ ## Prework DoD (페어 기준)
78
+
79
+ - [ ] 사전학습 제출물 2개 작성 완료
80
+ - [ ] 로컬 환경 변수/모델/DB 연결 준비 완료 (README 환경 설정 완료 기준)
81
+ - [ ] Weekend-1 구현을 막는 리스크와 대응 메모 작성
82
+ - [ ] 페어 상대방이 내 제출물을 보고 내용을 이해할 수 있는지 확인
83
+
84
+ ## 검증 명령
85
+
86
+ ```bash
87
+ # 환경 구성 확인(예시)
88
+ python -c "from app.config import PROVIDER; print(PROVIDER)"
89
+ ```
docs/01-prework/entry-task.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 진입 과제: 환각 방지 시스템 프롬프트 초안
2
+
3
+ [Stage: Prework]
4
+
5
+ 아래 템플릿을 채워 제출하세요.
6
+
7
+ ---
8
+
9
+ ## 1) 시스템 프롬프트 초안
10
+
11
+ ```text
12
+ [역할]
13
+ - 너는 업로드된 문서를 근거로만 답변하는 RAG 어시스턴트다.
14
+
15
+ [행동 원칙]
16
+ - 제공된 Context에 근거가 있는 내용만 답변한다.
17
+ - Context에 없는 사실은 추정하지 않는다.
18
+ - 질문이 모호하면 필요한 정보를 먼저 물어본다.
19
+ - 문서 외 질문이면 "문서에서 확인할 수 없다"라고 명시한다.
20
+
21
+ [응답 형식]
22
+ - 답변:
23
+ - 근거:
24
+ - 한계/추가 확인 필요사항:
25
+ ```
26
+
27
+ ---
28
+
29
+ ## 2) 테스트 질문과 기대 동작
30
+
31
+ ### 테스트 1
32
+
33
+ - 질문:
34
+ - 기대 동작:
35
+
36
+ ### 테스트 2
37
+
38
+ - 질문:
39
+ - 기대 동작:
40
+
41
+ ### 테스트 3
42
+
43
+ - 질문:
44
+ - 기대 동작:
45
+
46
+ ---
47
+
48
+ ## 3) 자가 점검
49
+
50
+ - [ ] 문서 밖 내용을 단정적으로 말하지 않도록 설계했다.
51
+ - [ ] 근거를 함께 제시하도록 형식을 명시했다.
52
+ - [ ] 모호한 질문에서 재질문하도록 지시했다.
53
+ - [ ] 불확실할 때 한계를 명확히 밝히도록 했다.
54
+
55
+ ## 제출 전 확인 (페어 기준)
56
+
57
+ - [ ] 위 자가 점검 4개 항목 모두 체크
58
+ - [ ] 페어 상대방이 내 시스템 프롬프트를 읽고 환각 방지 원칙이 담겼는지 확인
59
+
docs/01-prework/self-check.md ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # RAG 이론 자가 셀프 체크 (사전학습 필수)
2
+
3
+ [Stage: Prework]
4
+
5
+ 관련 문서: [`docs/01-prework/README.md`](./README.md), [`docs/00-shared/reference.md`](../00-shared/reference.md)
6
+
7
+ 아래 각 문항에 대해 다음 형식으로 답변하세요.
8
+
9
+ - 설명: 1~2문장
10
+ - 프로젝트 적용 예시: 1개
11
+
12
+ ---
13
+
14
+ ## ✅ 필수 문항 (6개 — 모두 작성)
15
+
16
+ Weekend-1 구현 전에 반드시 이해해야 할 핵심 개념입니다.
17
+
18
+ 1. 왜 일반 LLM 호출만으로는 문서 기반 QA에서 환각 문제가 생기나요?
19
+ 2. RAG에서 Retrieval과 Generation의 역할은 각각 무엇인가요?
20
+ 3. 청킹에서 `chunk_size`와 `chunk_overlap`을 함께 조정해야 하는 이유는?
21
+ 4. `(벡터, 원문 텍스트)`를 같이 저장해야 하는 이유는?
22
+ 5. 문서에 없는 질문에 안전하게 응답하려면 프롬프트를 어떻게 설계해야 하나요?
23
+ 6. 멀티턴 대화에서 Query Rewriting이 왜 필요한가요?
24
+
25
+ ---
26
+
27
+ ## 💡 부가 문항 (6개 — 여유 있으면 도전)
28
+
29
+ 심화 기술 및 운영 관점의 질문입니다. 작성하면 이해도가 높아지지만, 필수는 아닙니다.
30
+
31
+ 7. `top-k`를 너무 작게/크게 잡으면 각각 어떤 문제가 생기나요?
32
+ 8. 임베딩 차원(예: 768 vs 1536)이 비용/속도/품질에 주는 영향은?
33
+ 9. 코사인 유사도와 내적이 같은 결과가 되는 조건은?
34
+ 10. RAG 배포에서 웹 서버 외에 반드시 점검해야 할 컴포넌트는?
35
+ 11. Self-hosted LLM과 Hosted API의 운영 리스크 차이는?
36
+ 12. 배포 후 장애 진단 순서(모델 → DB → 앱 → 네트워크)를 어떻게 가져갈 건가요?
37
+
38
+ ---
39
+
40
+ ## 자가 점수
41
+
42
+ - 필수 6개 + 부가 4개 이상: 실무 적용 준비도 높음
43
+ - 필수 6개 + 부가 1~3개: 구현 가능, 운영 대응 학습 보강 권장
44
+ - 필수 미완성: [`docs/00-shared/reference.md`](../00-shared/reference.md) 재학습 후 보완
45
+
46
+ ## 제출 전 확인 (페어 기준)
47
+
48
+ - [ ] 필수 문항 6개 모두 작성 완료
49
+ - [ ] 각 문항에 설명(1~2문장) + 적용 예시(1개) 포함
50
+ - [ ] 페어 상대방이 내 답변을 읽고 이해했는지 확인
docs/02-weekend1/README.md ADDED
@@ -0,0 +1,74 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Week 1 주말 패킷 (핵심 구현)
2
+
3
+ [Stage: Weekend-1]
4
+
5
+ 관련 문서: [`README.md`](../../README.md), [`docs/00-shared/reference.md`](../00-shared/reference.md)
6
+
7
+ 주말(토/일, 9:00-18:00) 페어프로그래밍으로 아래 흐름을 완성합니다.
8
+
9
+ - 문서 업로드/텍스트 추출
10
+ - 청킹/임베딩/벡터 저장
11
+ - 검색/답변 생성(RAG)
12
+
13
+ ---
14
+
15
+ ## 목표
16
+
17
+ - 로컬에서 업로드 → 검색 → 답변까지 E2E 동작
18
+ - 문서 외 질문에 대해 안전 응답 기본 동작 확보
19
+ - 최소 3개 실패 케이스를 재현/기록
20
+
21
+ ---
22
+
23
+ ## 구현 범위
24
+
25
+ - `app/main.py`
26
+ - `extract_text_from_pdf()`
27
+ - `/documents/` 파이프라인
28
+ - `/qa` RAG 파이프라인
29
+ - `app/embedding_utils.py`
30
+ - `split_text()`
31
+ - `get_embedding()`
32
+ - `app/supabase_utils.py`
33
+ - `save_embedding()`
34
+ - `search_similar_embeddings()`
35
+
36
+ ---
37
+
38
+ ## Weekend-1 DoD (페어 기준)
39
+
40
+ ### 기능 구현
41
+
42
+ - [ ] PDF 업로드 성공
43
+ - [ ] 최소 1개 문서의 청크/임베딩 저장 성공
44
+ - [ ] `/qa` 질의 3회 성공
45
+ - [ ] 문서 외 질문에 대해 안전 응답 확인
46
+ - [ ] 실패 케이스 3개 이상 기록
47
+
48
+ ### 시스템 프롬프트 품질 검증
49
+
50
+ - [ ] [`docs/01-prework/entry-task.md`](../01-prework/entry-task.md)에서 작성한 시스템 프롬프트 초안을 실제 구현에 적용
51
+ - [ ] 문서에 없는 질문 3가지에서 환각 없이 거절/한계 고지 응답 확인
52
+ - [ ] 문서에 있는 질문 3가지에서 근거(sources)를 포함한 답변 확인
53
+ - [ ] 프롬프트 1회 이상 수정 후 수정 전/후 답변 차이 기록
54
+
55
+ ### 이해도 확인 (페어 구두 설명)
56
+
57
+ 구현 완료 후 아래 질문에 서로 구두로 설명할 수 있어야 합니다.
58
+ 설명하지 못하는 항목은 코드와 [`docs/00-shared/reference.md`](../00-shared/reference.md)를 다시 확인하세요.
59
+
60
+ - [ ] "`chunk_size`를 줄이면 검색 결과와 답변 품질이 어떻게 달라지는가?"
61
+ - [ ] "같은 문서를 두 번 업로드하면 어떤 문제가 생기는가? 어떻게 해결할 수 있는가?"
62
+ - [ ] "`similarity_threshold`를 0.7에서 0.3으로 낮추면 어떤 일이 벌어지는가?"
63
+ - [ ] "현재 구현에서 대용량 PDF를 업로드할 때 병목이 어디에서 생기는가?"
64
+
65
+ ---
66
+
67
+ ## 검증 명령
68
+
69
+ ```bash
70
+ # 서버 실행
71
+ pipenv run uvicorn app.main:app --reload
72
+ ```
73
+
74
+ 검증은 UI 또는 API 방식 중 팀에서 합의한 하나로 통일하세요.
docs/03-midweek/README.md ADDED
@@ -0,0 +1,42 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 주중 과제 패킷 (Week 1~2 사이)
2
+
3
+ [Stage: Midweek]
4
+
5
+ 주중 과제의 핵심은 **실패를 재현하고, 수치로 개선을 증명하는 것**입니다.
6
+
7
+ 아래 1개 문서를 완성하면 제출 기준을 충족합니다.
8
+
9
+ - [`docs/03-midweek/improvement-report.md`](./improvement-report.md)
10
+
11
+ ---
12
+
13
+ ## 제출 목표
14
+
15
+ - 발견한 문제(엣지케이스) 최소 5개를 정의하고 기록한다.
16
+ - 개선 실험을 3회 이상 수행하고, 어떤 파라미터를 왜 바꿨는지 설명한다.
17
+ - Before/After 지표로 품질 개선 여부를 수치로 제시한다.
18
+
19
+ ---
20
+
21
+ ## 권장 진행 순서
22
+
23
+ 1. [`improvement-report.md`](./improvement-report.md)의 1) 섹션에서 발견한 문제를 먼저 정의한다.
24
+ 2. 각 문제에 대한 가설을 세우고 2) 섹션에 실험을 기록한다.
25
+ 3. 기준선(Before)과 개선 후(After) 지표를 측정하여 3) 섹션을 채운다.
26
+ 4. 지표가 악화된 케이스도 숨기지 않고 원인을 함께 기록한다.
27
+
28
+ ---
29
+
30
+ ## Midweek DoD (페어 기준)
31
+
32
+ - [ ] [`docs/03-midweek/improvement-report.md`](./improvement-report.md) 작성 완료
33
+ - [ ] 문제 5개 이상 기록
34
+ - [ ] 실험 3회 이상 (파라미터 + 프롬프트 각 1개 이상)
35
+ - [ ] Before/After 지표 표 채움 (정확성, 근거성, 실패율 필수)
36
+
37
+ ## 검증 명령
38
+
39
+ ```bash
40
+ # 지표 기록 내용 빠른 확인
41
+ rg "Before|After|정확성|근거성|실패율" docs/03-midweek/improvement-report.md
42
+ ```
docs/03-midweek/improvement-report.md ADDED
@@ -0,0 +1,118 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 품질 개선 리포트
2
+
3
+ [Stage: Midweek]
4
+
5
+ 이 문서의 핵심은 **"문제를 발견하고, 실험으로 개선하고, 수치로 증명하는 것"** 입니다.
6
+
7
+ 아래 3개 섹션을 순서대로 채우세요.
8
+
9
+ 1. 발견한 문제 → 2. 개선 실험 → 3. Before/After 지표
10
+
11
+ 지표가 악화된 실험도 숨기지 말고 원인과 함께 기록하세요.
12
+
13
+ ---
14
+
15
+ ## 1) 발견한 문제 (최소 5개)
16
+
17
+ Weekend-1 구현을 실행하면서 예상과 다르게 동작한 상황을 기록하세요.
18
+
19
+ 권장 카테고리:
20
+ - 문서 외 질문 / 모호한 질문 / 긴 문서 처리 / 중복 문서 / 모델 장애 / DB 지연
21
+
22
+ | # | 카테고리 | 시나리오 | 입력 조건 (문서/질문) | 기대 결과 | 실제 결과 | 추정 원인 |
23
+ |---|---|---|---|---|---|---|
24
+ | 1 | | | | | | |
25
+ | 2 | | | | | | |
26
+ | 3 | | | | | | |
27
+ | 4 | | | | | | |
28
+ | 5 | | | | | | |
29
+
30
+ ---
31
+
32
+ ## 2) 개선 실험 (최소 3회)
33
+
34
+ 위 문제를 해결하기 위해 어떤 파라미터/프롬프트를 어떻게 바꿨는지 기록하세요.
35
+ 서로 다른 조절 포인트를 최소 2종류 이상 포함하세요. (예: 청킹 파라미터, 프롬프트 변경)
36
+
37
+ ### 실험 1
38
+
39
+ - 날짜:
40
+ - 가설: (예: "chunk_size를 줄이면 특정 질문의 정확성이 올라갈 것이다")
41
+ - 변경 내용:
42
+ - Before:
43
+ - After:
44
+ - 결과:
45
+ - 정량: (정확성/근거성/실패율 수치)
46
+ - 정성: (체감 품질 변화)
47
+ - 결론 및 다음 액션:
48
+
49
+ ### 실험 2
50
+
51
+ - 날짜:
52
+ - 가설:
53
+ - 변경 내용:
54
+ - Before:
55
+ - After:
56
+ - 결과:
57
+ - 정량:
58
+ - 정성:
59
+ - 결론 및 다음 액션:
60
+
61
+ ### 실험 3
62
+
63
+ - 날짜:
64
+ - 가설:
65
+ - 변경 내용:
66
+ - Before:
67
+ - After:
68
+ - 결과:
69
+ - 정량:
70
+ - 정성:
71
+ - 결론 및 다음 액션:
72
+
73
+ ---
74
+
75
+ ## 3) Before / After 지표
76
+
77
+ > 지표 측정 방법은 [`docs/00-shared/reference.md`](../00-shared/reference.md) 섹션 7을 먼저 읽고 참고하세요.
78
+
79
+ ### 측정 조건
80
+
81
+ - 테스트 질문 수:
82
+ - 측정 기간:
83
+ - PROVIDER / 임베딩 모델 / 채팅 모델:
84
+ - chunk_size / chunk_overlap / top-k:
85
+
86
+ ### 핵심 지표
87
+
88
+ | 지표 | Before | After | 변화량 | 목표치 | 달성 여부 |
89
+ |---|---:|---:|---:|---:|---|
90
+ | 정확성(%) | | | | | |
91
+ | 근거성(%) | | | | | |
92
+ | 응답 실패율(%) | | | | | |
93
+ | 평균 응답 시간(ms) | | | | | |
94
+
95
+ > 계산 방법:
96
+ > - 정확성(%) = (정답 판정 수 / 전체 질문 수) × 100
97
+ > - 근거성(%) = (근거 제시 + 근거 일치 판정 수 / 전체 질문 수) × 100
98
+ > - 응답 실패율(%) = (에러 + 타임아웃 + 무응답 수 / 전체 질문 수) × 100
99
+
100
+ ### 해석 및 후속 계획
101
+
102
+ - 가장 크게 개선된 지표:
103
+ - 개선이 부족한 지표 및 추정 원인:
104
+ - Weekend-2 배포 전에 반영할 최종 설정값:
105
+ - chunk_size:
106
+ - chunk_overlap:
107
+ - top-k:
108
+ - 프롬프트 버전:
109
+
110
+ ---
111
+
112
+ ## 완료 체크 (페어 기준)
113
+
114
+ - [ ] 문제 5개 이상 기록
115
+ - [ ] 실험 3회 이상 기록 (청킹/검색 파라미터, 프롬프트 중 각각 1개 이상 포함)
116
+ - [ ] Before/After 지표 표 채움 (정확성, 근거성, 실패율 필수)
117
+ - [ ] 개선이 안 된 케이스도 원인과 함께 기록
118
+ - [ ] 페어 상대방이 실험 결과를 보고 재현 가능한지 확인
docs/04-weekend2/README.md ADDED
@@ -0,0 +1,138 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Week 2 배포 트랙 패킷
2
+
3
+ [Stage: Weekend-2]
4
+
5
+ 이 트랙의 핵심은 **모델 서빙 트랙을 선택하고, 실제 공개 URL에서 E2E를 검증하는 것**입니다.
6
+
7
+ **진행 순서:**
8
+ 1. 이 문서를 읽고 트랙을 결정한다.
9
+ 2. [`deployment-checklist-lab.md`](./deployment-checklist-lab.md)를 채우며 배포를 완료한다.
10
+ 3. 막히면 [`deployment.md`](./deployment.md)를 참고한다.
11
+
12
+ ---
13
+
14
+ ## 트랙 목표
15
+
16
+ - `Ollama 자체 호스팅`과 `OpenAI API 연동`의 배포 차이를 설명할 수 있다.
17
+ - 선택한 트랙으로 `문서 업로드 → /qa 질의응답` E2E를 외부 URL에서 확인한다.
18
+ - 장애 상황(모델 다운, API 제한, DB 지연)에 대해 최소 복구 절차를 문서화한다.
19
+
20
+ ---
21
+
22
+ ## 1) 트랙 선택: Ollama vs OpenAI
23
+
24
+ ### A. Ollama 자체 호스팅 트랙
25
+
26
+ 다음에 해당하면 Ollama 트랙이 유리합니다.
27
+
28
+ - 데이터가 외부 API로 나가면 안 되는 환경
29
+ - 고정 비용(서버 비용)으로 운영하고 싶은 경우
30
+ - 모델 동작 원리를 직접 확인하고 싶은 경우
31
+
32
+ 운영 리스크:
33
+
34
+ - 서버 자원(CPU/GPU/RAM) 부족 시 응답 지연
35
+ - 모델 다운로드/업데이트/헬스체크를 직접 운영해야 함
36
+ - 클라우드 배포 시 충분한 RAM의 서버 필요 (llama3.1 기준 최소 8GB)
37
+
38
+ ### B. OpenAI API 연동 트랙
39
+
40
+ 다음에 해당하면 OpenAI 트랙이 유리합니다.
41
+
42
+ - 인프라 운영 부담을 줄이고 빠르게 배포하고 싶은 경우
43
+ - 트래픽 편차에 따라 탄력적으로 사용하고 싶은 경우
44
+ - HF Spaces / Railway 등 무료 클라우드에 배포하고 싶은 경우
45
+
46
+ 운영 리스크:
47
+
48
+ - API rate limit, 쿼터, 비용 급증 관리 필요
49
+ - 외부 네트워크 장애에 직접 영향받음
50
+ - 시크릿 키 노출 방지와 키 롤테이션 정책 필요
51
+
52
+ ---
53
+
54
+ ## 2) 트랙별 필수 설정
55
+
56
+ ### 공통
57
+
58
+ - `SUPABASE_URL`, `SUPABASE_KEY` 설정
59
+ - `document_chunks` 테이블 + `match_documents` RPC + 인덱스 준비
60
+ - `GET /health` 및 업로드/질의 E2E 테스트 가능 상태
61
+
62
+ ### Ollama 트랙 (`PROVIDER=ollama`)
63
+
64
+ - `OLLAMA_BASE` 설정 (로컬/원격 주소)
65
+ - `OLLAMA_EMBED_MODEL=nomic-embed-text`
66
+ - `OLLAMA_CHAT_MODEL=llama3.1`
67
+ - 임베딩 차원: `768`
68
+ - 모델 서버 헬스 확인: `curl <OLLAMA_BASE>/api/tags`
69
+
70
+ ### OpenAI 트랙 (`PROVIDER=openai`)
71
+
72
+ - `OPENAI_API_KEY` 설정
73
+ - `OPENAI_EMBEDDING_MODEL=text-embedding-3-small`
74
+ - `OPENAI_CHAT_MODEL=gpt-4o-mini` (또는 팀 정책 모델)
75
+ - 임베딩 차원: `1536`
76
+ - rate limit/쿼터 초과 시 재시도 및 에러 메시지 기준 정의
77
+
78
+ ---
79
+
80
+ ## 3) 배포 시나리오
81
+
82
+ ### 시나리오 A: Docker + Ollama (자체 호스팅)
83
+
84
+ 1. `.env`에서 `PROVIDER=ollama`로 설정
85
+ 2. `OLLAMA_BASE`를 컨테이너 네트워크에 맞게 지정 (`http://ollama:11434`)
86
+ 3. `docker-compose up -d`로 앱 + Ollama 동시 실행
87
+ 4. 공개 URL에서 `/health`, 업로드, `/qa` 테스트
88
+
89
+ 체크 포인트:
90
+
91
+ - Ollama 컨테이너 재시작 후 앱 복구 시간
92
+ - 모델 미다운로드 상태에서의 사용자 안내 메시지
93
+ - 동시 요청 증가 시 응답 시간 변동
94
+
95
+ ### 시나리오 B: HF Spaces / Railway + OpenAI API (권장)
96
+
97
+ 1. `.env` 또는 플랫폼 시크릿에 `PROVIDER=openai` 및 API 키 설정
98
+ 2. Supabase 스키마를 1536차원으로 정합성 확인
99
+ 3. 앱만 클라우드 배포 (모델 서버 별도 운영 없음)
100
+ 4. 공개 URL에서 `/health`, 업로드, `/qa` 테스트
101
+
102
+ 체크 포인트:
103
+
104
+ - API 키 누락/오타 시 감지 가능 여부
105
+ - rate limit 발생 시 재시도/안내 동작
106
+ - 호출 비용 모니터링 지표 수집 여부
107
+
108
+ > 클라우드 플랫폼별 상세 설정은 [`deployment.md`](./deployment.md)를 참고하세요.
109
+
110
+ ---
111
+
112
+ ## 4) 트랙 선택 기록 (작성 후 팀 문서에 남길 것)
113
+
114
+ ```md
115
+ ### 모델 서빙 트랙 선택 기록
116
+ - 선택 트랙: (ollama / openai)
117
+ - 선택 이유: (비용, 보안, 운영, 성능 관점 3줄 이상)
118
+ - 임베딩 차원: (768 / 1536)
119
+ - 예상 리스크: (최소 2개)
120
+ - 대응 계획: (리스크별 1개 이상)
121
+ ```
122
+
123
+ ---
124
+
125
+ ## Weekend-2 DoD (페어 기준)
126
+
127
+ - [ ] 선택한 모델 서빙 트랙의 근거(비용/운영/성능)를 3줄 이상 작성
128
+ - [ ] 벡터 DB 스키마 차원(768 또는 1536)과 실제 설정 일치 확인
129
+ - [ ] 공개 URL에서 `GET /health` 성공
130
+ - [ ] 공개 URL에서 PDF 업로드 + `/qa` 답변 성공
131
+ - [ ] 장애 대응 드릴 3개 수행 및 복구 시간 기록
132
+ - [ ] 페어 상대방이 공개 URL에서 직접 E2E 검증 가능한지 확인
133
+
134
+ ## 검증 명령
135
+
136
+ ```bash
137
+ curl <PUBLIC_URL>/health
138
+ ```
docs/04-weekend2/deployment-checklist-lab.md ADDED
@@ -0,0 +1,97 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 배포 체크리스트 실습 (Week 2)
2
+
3
+ [Stage: Weekend-2]
4
+
5
+ 관련 문서: [`docs/04-weekend2/README.md`](./README.md), [`docs/04-weekend2/model-serving-guide.md`](./model-serving-guide.md)
6
+
7
+ 실습 목표: 선택한 모델 서빙 트랙으로 공개 URL에서 RAG E2E를 검증하고, 장애 대응 드릴까지 완료합니다.
8
+
9
+ ---
10
+
11
+ ## 0) 트랙 선택
12
+
13
+ - [ ] 선택 트랙: `ollama` / `openai`
14
+ - [ ] 선택 근거(비용/운영/성능) 작성 완료
15
+ - [ ] 임베딩 차원 확정: `768` / `1536`
16
+
17
+ ---
18
+
19
+ ## 1) 사전 준비 체크
20
+
21
+ ## 공통
22
+
23
+ - [ ] `.env` 또는 배포 플랫폼 시크릿 설정 완료
24
+ - [ ] `SUPABASE_URL`, `SUPABASE_KEY` 유효성 확인
25
+ - [ ] `document_chunks` 테이블 확인
26
+ - [ ] `match_documents` RPC 시그니처 확인
27
+ - [ ] 벡터 차원과 현재 provider 일치 확인
28
+
29
+ ## Ollama 트랙 전용
30
+
31
+ - [ ] `OLLAMA_BASE` 연결 확인
32
+ - [ ] `nomic-embed-text`, `llama3.1` 다운로드 확인
33
+ - [ ] 모델 서버 재시작 후 자동 복구 여부 확인
34
+
35
+ ## OpenAI 트랙 전용
36
+
37
+ - [ ] `OPENAI_API_KEY` 유효성 확인
38
+ - [ ] `OPENAI_EMBEDDING_MODEL`, `OPENAI_CHAT_MODEL` 설정 확인
39
+ - [ ] rate limit/쿼터 초과 메시지 시나리오 점검
40
+
41
+ ---
42
+
43
+ ## 2) 배포 실행 체크
44
+
45
+ - [ ] 배포 로그에서 앱 기동 성공 확인
46
+ - [ ] 공개 URL 접속 성공
47
+ - [ ] `GET /health` 200 응답 확인
48
+ - [ ] 업로드 API(또는 UI)로 샘플 PDF 업로드 성공
49
+ - [ ] `/qa` 3회 질의 성공 (문서 근거 포함 응답)
50
+
51
+ ---
52
+
53
+ ## 3) 장애 대응 드릴
54
+
55
+ 아래 3개를 반드시 수행하고 복구 시간을 기록하세요.
56
+
57
+ ### Drill A: 모델 계층 장애
58
+
59
+ - [ ] Ollama 트랙: 모델 서버 중지 후 오류 메시지 확인 -> 재기동 복구
60
+ - [ ] OpenAI 트랙: API 키를 의도적으로 무효화 후 오류 메시지 확인 -> 복구
61
+ - 관찰 내용:
62
+ - 복구 시간(분):
63
+
64
+ ### Drill B: 벡터 DB 지연/오류
65
+
66
+ - [ ] Supabase 연결 실패 상황(키 오타/네트워크 제한) 재현
67
+ - [ ] 사용자 안내 메시지와 로그 분리 확인
68
+ - 관찰 내용:
69
+ - 복구 시간(분):
70
+
71
+ ### Drill C: 외부 API 제한 또는 타임아웃
72
+
73
+ - [ ] rate limit 또는 timeout 유사 상황 재현
74
+ - [ ] retry/backoff 또는 graceful fallback 동작 확인
75
+ - 관찰 내용:
76
+ - 복구 시간(분):
77
+
78
+ ---
79
+
80
+ ## 4) 최종 결과 제출 템플릿
81
+
82
+ 아래를 복사해 발표/리뷰 자료에 포함하세요.
83
+
84
+ ```md
85
+ ## 배포 트랙 실습 결과
86
+ - 선택 트랙: (ollama/openai)
87
+ - 공개 URL:
88
+ - 헬스체크: (성공/실패 + 근거)
89
+ - E2E 결과: (업로드/질의 성공 여부)
90
+ - 장애 드릴 결과:
91
+ - 모델 계층:
92
+ - 벡터 DB:
93
+ - 외부 API:
94
+ - 남은 리스크(최소 2개):
95
+ - 다음 개선 우선순위(최소 2개):
96
+ ```
97
+
docs/04-weekend2/deployment.md ADDED
@@ -0,0 +1,460 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 🚀 DocuFlow 배포 가이드
2
+
3
+ ## 📋 배포 전 체크리스트
4
+
5
+ ### 1. 코드 구현 완료 확인
6
+
7
+ 현재 프로젝트의 핵심 기능들이 아직 구현되지 않았습니다. 배포 전에 다음을 완료해야 합니다:
8
+
9
+ #### ✅ [Stage: Weekend-1] 데이터 전처리
10
+ - [ ] `app/embedding_utils.py` - `split_text()` 함수 구현
11
+ - [ ] `app/main.py` - `extract_text_from_pdf()` 함수 구현
12
+ - [ ] PDF 텍스트 추출 테스트
13
+
14
+ #### ✅ [Stage: Weekend-1] 임베딩 및 벡터 저장
15
+ - [ ] `app/embedding_utils.py` - `get_embedding()` 함수 구현
16
+ - [ ] `app/supabase_utils.py` - `save_embedding()` 함수 구현
17
+ - [ ] 비동기 임베딩 처리 (성능 최적화)
18
+ - [ ] Supabase 연결 테스트
19
+
20
+ #### ✅ [Stage: Weekend-1] RAG 파이프라인
21
+ - [ ] `app/supabase_utils.py` - `search_similar_embeddings()` 함수 구현
22
+ - [ ] `app/main.py` - `/qa` 엔드포인트 구현
23
+ - [ ] Ollama/OpenAI LLM 연동
24
+ - [ ] 할루시네이션 방지 프롬프트 작성
25
+
26
+ #### ✅ [Stage: Midweek] 대화 맥락 유지
27
+ - [ ] 대화 히스토리 관리
28
+ - [ ] Query Rewriting 구현 (선택사항)
29
+
30
+ #### ✅ [Stage: Weekend-2] 안정성 및 에러 핸들링
31
+ - [ ] 모든 예외 상황 처리
32
+ - [ ] 사용자 친화적 에러 메시지
33
+ - [ ] 로깅 시스템 구축
34
+ - [ ] 스트레스 테스트
35
+
36
+ ---
37
+
38
+ ## 🔧 배포 환경 설정
39
+
40
+ ### 필수 환경 변수
41
+
42
+ `.env` 파일을 생성하고 다음 변수들을 설정하세요:
43
+
44
+ ```ini
45
+ # 공급자 선택: "ollama" 또는 "openai"
46
+ PROVIDER="ollama"
47
+
48
+ # Ollama 설정 (로컬 또는 원격 서버)
49
+ OLLAMA_BASE="http://localhost:11434"
50
+ OLLAMA_EMBED_MODEL="nomic-embed-text"
51
+ OLLAMA_CHAT_MODEL="llama3.1"
52
+
53
+ # Supabase 설정 (필수)
54
+ SUPABASE_URL="https://your-project.supabase.co"
55
+ SUPABASE_KEY="your-anon-key"
56
+
57
+ # OpenAI 설정 (PROVIDER=openai일 때만 필요)
58
+ # OPENAI_API_KEY="sk-..."
59
+ # OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
60
+ # OPENAI_CHAT_MODEL="gpt-3.5-turbo"
61
+
62
+ # 서버 설정
63
+ HOST="0.0.0.0"
64
+ PORT=8000
65
+ DEBUG=false
66
+
67
+ # 보안 설정
68
+ SECRET_KEY="your-secret-key-here"
69
+ ALLOWED_ORIGINS="http://localhost:8000,https://yourdomain.com"
70
+ ```
71
+
72
+ ### 데이터베이스 설정
73
+
74
+ Supabase에서 다음을 완료해야 합니다:
75
+
76
+ 1. **pgvector 확장 활성화**
77
+ 2. **document_chunks 테이블 생성** (README.md의 SQL 스크립트 실행)
78
+ 3. **match_documents 함수 생성**
79
+ 4. **HNSW 인덱스 생성**
80
+
81
+ ---
82
+
83
+ ## 🐳 Docker 배포 (권장)
84
+
85
+ ### Dockerfile 생성
86
+
87
+ 프로젝트 루트에 `Dockerfile`을 생성하세요:
88
+
89
+ ```dockerfile
90
+ FROM python:3.11-slim
91
+
92
+ WORKDIR /app
93
+
94
+ # 시스템 의존성 설치
95
+ RUN apt-get update && apt-get install -y \
96
+ gcc \
97
+ postgresql-client \
98
+ && rm -rf /var/lib/apt/lists/*
99
+
100
+ # Python 의존성 설치
101
+ COPY Pipfile Pipfile.lock ./
102
+ RUN pip install pipenv && \
103
+ pipenv install --deploy --ignore-pipfile
104
+
105
+ # 애플리케이션 코드 복사
106
+ COPY . .
107
+
108
+ # 업로드 디렉토리 생성
109
+ RUN mkdir -p app/uploads
110
+
111
+ # 포트 노출
112
+ EXPOSE 8000
113
+
114
+ # 환경 변수 설정
115
+ ENV PYTHONUNBUFFERED=1
116
+
117
+ # 서버 실행
118
+ CMD ["pipenv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
119
+ ```
120
+
121
+ ### docker-compose.yml (Ollama 포함)
122
+
123
+ ```yaml
124
+ version: '3.8'
125
+
126
+ services:
127
+ app:
128
+ build: .
129
+ ports:
130
+ - "8000:8000"
131
+ environment:
132
+ - PROVIDER=ollama
133
+ - OLLAMA_BASE=http://ollama:11434
134
+ - SUPABASE_URL=${SUPABASE_URL}
135
+ - SUPABASE_KEY=${SUPABASE_KEY}
136
+ volumes:
137
+ - ./app/uploads:/app/app/uploads
138
+ - ./.env:/app/.env
139
+ depends_on:
140
+ - ollama
141
+
142
+ ollama:
143
+ image: ollama/ollama:latest
144
+ ports:
145
+ - "11434:11434"
146
+ volumes:
147
+ - ollama_data:/root/.ollama
148
+
149
+ volumes:
150
+ ollama_data:
151
+ ```
152
+
153
+ ### 배포 명령어
154
+
155
+ ```bash
156
+ # 이미지 빌드
157
+ docker build -t docuflow:latest .
158
+
159
+ # 컨테이너 실행
160
+ docker-compose up -d
161
+
162
+ # 로그 확인
163
+ docker-compose logs -f app
164
+ ```
165
+
166
+ ---
167
+
168
+ ## ☁️ 클라우드 배포 옵션
169
+
170
+ > AI 프로젝트 배포 난이도 비교: HF Spaces ≈ Railway < Render < Fly.io < AWS/GCP
171
+
172
+ ### 1. Hugging Face Spaces (추천 - AI 프로젝트에 최적)
173
+
174
+ **장점:**
175
+ - AI/ML 프로젝트 배포에 특화된 플랫폼
176
+ - Docker 기반 무료 배포 (CPU 2코어, **RAM 16GB**)
177
+ - 공개 URL 자동 생성, 환경 변수(Secrets) 관리 제공
178
+ - GitHub 연동 자동 배포 지원
179
+
180
+ **제약사항:**
181
+ - 일정 시간 미사용 시 슬립 모드 진입 → 첫 요청 시 30~60초 재시작 지연
182
+ - 무료 티어는 영속 스토리지 없음 (업로드 파일은 재시작 시 초기화, 임베딩은 Supabase에 저장되므로 무관)
183
+ - Ollama는 CPU 실행 시 응답이 매우 느리므로 **OpenAI 트랙 권장**
184
+
185
+ **단계:**
186
+
187
+ 1. [huggingface.co](https://huggingface.co)에서 계정 생성 후 **New Space** 클릭
188
+ 2. SDK를 **Docker**로 선택하고 Space 생성
189
+ 3. Space 리포지토리의 `README.md` 상단에 아래 메타데이터 추가:
190
+
191
+ ```yaml
192
+ ---
193
+ title: DocuFlow
194
+ emoji: 📄
195
+ colorFrom: blue
196
+ colorTo: green
197
+ sdk: docker
198
+ pinned: false
199
+ ---
200
+ ```
201
+
202
+ 4. Space 리포지토리에 프로젝트 코드를 push (또는 GitHub 연동)
203
+ 5. **Settings → Variables and secrets**에서 환경 변수 등록:
204
+ - `PROVIDER` = `openai`
205
+ - `OPENAI_API_KEY` = `sk-...`
206
+ - `OPENAI_EMBEDDING_MODEL` = `text-embedding-3-small`
207
+ - `OPENAI_CHAT_MODEL` = `gpt-3.5-turbo`
208
+ - `SUPABASE_URL`, `SUPABASE_KEY`
209
+
210
+ ---
211
+
212
+ ### 2. Railway (간단함)
213
+
214
+ **장점:**
215
+ - Supabase와 통합 용이
216
+ - 자동 배포
217
+ - 무료 티어 제공
218
+
219
+ **단계:**
220
+ 1. Railway 계정 생성
221
+ 2. GitHub 저장소 연결
222
+ 3. 환경 변수 설정
223
+ 4. Ollama는 별도 서버 필요 (또는 OpenAI 사용)
224
+
225
+ ### 3. Render
226
+
227
+ **장점:**
228
+ - 무료 티어
229
+ - Docker 지원
230
+ - 자동 HTTPS
231
+
232
+ **단계:**
233
+ 1. Render 계정 생성
234
+ 2. Dockerfile 기반 배포
235
+ 3. 환경 변수 설정
236
+
237
+ ### 4. AWS/GCP/Azure
238
+
239
+ **장점:**
240
+ - 확장성
241
+ - 고성능
242
+ - 엔터프라이즈급
243
+
244
+ **고려사항:**
245
+ - Ollama는 EC2/Compute Engine에서 별도 실행
246
+ - 또는 OpenAI API 사용 권장
247
+ - 로드 밸런서 설정 필요
248
+
249
+ ### 5. Fly.io
250
+
251
+ **장점:**
252
+ - 전 세계 엣지 배포
253
+ - Docker 지원
254
+ - 간단한 설정
255
+
256
+ ---
257
+
258
+ ## 📦 배포 전 필수 파일
259
+
260
+ ### 의존성 기준
261
+
262
+ 이 프로젝트의 의존성/실행 기준은 `pipenv`입니다.
263
+
264
+ - 로컬 설치: `pipenv install`
265
+ - Docker 빌드: `Pipfile`, `Pipfile.lock` 기반 설치
266
+
267
+ 의존성 관리는 `pipenv` 단일 경로로 통일합니다.
268
+
269
+ ### .dockerignore
270
+
271
+ ```
272
+ __pycache__/
273
+ *.pyc
274
+ *.pyo
275
+ *.pyd
276
+ .Python
277
+ .env
278
+ .venv
279
+ venv/
280
+ ENV/
281
+ .git
282
+ .gitignore
283
+ README.md
284
+ *.md
285
+ .DS_Store
286
+ app/uploads/*
287
+ !app/uploads/.gitkeep
288
+ ```
289
+
290
+ ### .env.example
291
+
292
+ 환경 변수 템플릿 파일 (실제 값은 제외):
293
+
294
+ ```ini
295
+ PROVIDER=ollama
296
+ OLLAMA_BASE=http://localhost:11434
297
+ OLLAMA_EMBED_MODEL=nomic-embed-text
298
+ OLLAMA_CHAT_MODEL=llama3.1
299
+ SUPABASE_URL=your-supabase-url
300
+ SUPABASE_KEY=your-supabase-key
301
+ ```
302
+
303
+ ---
304
+
305
+ ## 🔒 보안 체크리스트
306
+
307
+ - [ ] `.env` 파일을 `.gitignore`에 추가
308
+ - [ ] Supabase 키를 환경 변수로만 관리
309
+ - [ ] OpenAI API 키 보호
310
+ - [ ] 파일 업로드 크기 제한 설정
311
+ - [ ] CORS 설정 (프로덕션 도메인만 허용)
312
+ - [ ] Rate limiting 구현 (선택사항)
313
+ - [ ] HTTPS 사용 (프로덕션)
314
+
315
+ ---
316
+
317
+ ## 📊 모니터링 및 로깅
318
+
319
+ ### 로깅 설정
320
+
321
+ `app/main.py`에 로깅 추가:
322
+
323
+ ```python
324
+ import logging
325
+
326
+ logging.basicConfig(
327
+ level=logging.INFO,
328
+ format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
329
+ )
330
+ logger = logging.getLogger(__name__)
331
+ ```
332
+
333
+ ### 헬스 체크 엔드포인트
334
+
335
+ ```python
336
+ @app.get("/health")
337
+ async def health_check():
338
+ return {
339
+ "status": "healthy",
340
+ "ollama": check_ollama_connection(),
341
+ "supabase": check_supabase_connection()
342
+ }
343
+ ```
344
+
345
+ ---
346
+
347
+ ## 🧪 배포 전 테스트
348
+
349
+ ### 로컬 테스트
350
+
351
+ ```bash
352
+ # 서버 실행
353
+ pipenv run uvicorn app.main:app --reload
354
+
355
+ # 테스트
356
+ curl http://localhost:8000/health
357
+ ```
358
+
359
+ ### 통합 테스트 체크리스트
360
+
361
+ - [ ] PDF 업로드 테스트
362
+ - [ ] 텍스트 추출 확인
363
+ - [ ] 임베딩 생성 확인
364
+ - [ ] Supabase 저장 확인
365
+ - [ ] 질문-답변 테스트
366
+ - [ ] 에러 핸들링 테스트
367
+ - [ ] 대용량 파일 테스트
368
+
369
+ ---
370
+
371
+ ## 🚨 트러블슈팅
372
+
373
+ ### Ollama 연결 실패
374
+
375
+ **문제:** Ollama 서버에 연결할 수 없음
376
+
377
+ **해결:**
378
+ - Ollama 서버가 실행 중인지 확인: `curl http://localhost:11434/api/tags`
379
+ - Docker 환경에서는 `OLLAMA_BASE=http://ollama:11434` 사용
380
+ - 방화벽 설정 확인
381
+
382
+ ### Supabase 연결 실패
383
+
384
+ **문제:** Supabase에 연결할 수 없음
385
+
386
+ **해결:**
387
+ - 환경 변수 확인: `SUPABASE_URL`, `SUPABASE_KEY`
388
+ - Supabase 프로젝트 상태 확인
389
+ - 네트워크 연결 확인
390
+
391
+ ### 임베딩 차원 불일치
392
+
393
+ **문제:** 벡터 차원이 맞지 않음
394
+
395
+ **해결:**
396
+ - Ollama (768차원) vs OpenAI (1536차원) 확인
397
+ - Supabase 테이블 스키마와 일치하는지 확인
398
+ - `.env`의 `PROVIDER` 설정 확인
399
+
400
+ ---
401
+
402
+ ## 📝 배포 후 체크리스트
403
+
404
+ - [ ] 서버가 정상적으로 시작되는지 확인
405
+ - [ ] 헬스 체크 엔드포인트 응답 확인
406
+ - [ ] PDF 업로드 기능 테스트
407
+ - [ ] 질문-답변 기능 테스트
408
+ - [ ] 에러 로그 모니터링
409
+ - [ ] 성능 모니터링 (응답 시간, 메모리 사용량)
410
+ - [ ] 백업 전략 수립
411
+
412
+ ---
413
+
414
+ ## 🔄 CI/CD 파이프라인 (선택사항)
415
+
416
+ ### GitHub Actions 예시
417
+
418
+ `.github/workflows/deploy.yml`:
419
+
420
+ ```yaml
421
+ name: Deploy
422
+
423
+ on:
424
+ push:
425
+ branches: [main]
426
+
427
+ jobs:
428
+ deploy:
429
+ runs-on: ubuntu-latest
430
+ steps:
431
+ - uses: actions/checkout@v2
432
+ - name: Deploy to Railway
433
+ run: |
434
+ # Railway CLI를 사용한 배포
435
+ # 또는 다른 배포 스크립트
436
+ ```
437
+
438
+ ---
439
+
440
+ ## 📚 추가 리소스
441
+
442
+ - [FastAPI 배포 가이드](https://fastapi.tiangolo.com/deployment/)
443
+ - [Supabase 벡터 검색](https://supabase.com/docs/guides/ai)
444
+ - [Docker 베스트 프랙티스](https://docs.docker.com/develop/dev-best-practices/)
445
+ - [Ollama 배포 가이드](https://ollama.com/docs)
446
+
447
+ ---
448
+
449
+ ## 💡 배포 전 최종 확인
450
+
451
+ 1. ✅ 모든 기능이 구현되었는가?
452
+ 2. ✅ 환경 변수가 모두 설정되었는가?
453
+ 3. ✅ 데이터베이스가 준비되었는가?
454
+ 4. ✅ 보안 설정이 완료되었는가?
455
+ 5. ✅ 테스트가 통과했는가?
456
+ 6. ✅ 로깅이 설정되었는가?
457
+ 7. ✅ 에러 핸들링이 완료되었는가?
458
+
459
+ **준비가 되었다면 배포를 시작하세요! 🚀**
460
+
pyproject.toml ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ [tool.black]
2
+ line-length = 88
3
+ target-version = ['py311']