woongmin commited on
Commit
24b9451
·
1 Parent(s): 05a0b8a

[Delta-02] 작업일지 추가 및 체크리스트 업데이트

Browse files
docs/02-weekend1/README.md CHANGED
@@ -40,7 +40,7 @@
40
  ### 기능 구현
41
 
42
  - [x] PDF 업로드 성공
43
- - [ ] 최소 1개 문서의 청크/임베딩 저장 성공
44
  - [ ] `/qa` 질의 3회 성공
45
  - [ ] 문서 외 질문에 대해 안전 응답 확인
46
  - [ ] 실패 케이스 3개 이상 기록
 
40
  ### 기능 구현
41
 
42
  - [x] PDF 업로드 성공
43
+ - [x] 최소 1개 문서의 청크/임베딩 저장 성공
44
  - [ ] `/qa` 질의 3회 성공
45
  - [ ] 문서 외 질문에 대해 안전 응답 확인
46
  - [ ] 실패 케이스 3개 이상 기록
study-notes/2026-03-14-작업일지.md ADDED
@@ -0,0 +1,335 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 작업일지 — 2026-03-14 (Delta-02)
2
+
3
+ ## 오늘의 목표
4
+
5
+ RAG(Retrieval-Augmented Generation) 파이프라인의 전반부인 **Upload Pipeline**을 완성한다.
6
+ 사용자가 PDF를 업로드하면 텍스트를 추출하고, 의미 단위로 분할한 뒤, 각 청크를 벡터 임베딩으로 변환하여 DB에 저장하는 것까지가 목표다.
7
+
8
+ ---
9
+
10
+ ## 전체 아키텍처에서의 위치
11
+
12
+ ```
13
+ [오늘 완성한 부분] [Day 3~4에서 완성할 부분]
14
+ PDF 업로드 사용자 질문
15
+ → 파일 저장 → 질문 임베딩
16
+ → 텍스트 추출 → 벡터 유사도 검색
17
+ → 의미 기반 청크 분할 → 프롬프트 구성
18
+ → 임베딩 생성 → LLM 응답 생성
19
+ → DB 저장
20
+ ```
21
+
22
+ ---
23
+
24
+ ## 작업 내역
25
+
26
+ ### 1. 환경 설정 (10:13 ~ 10:20)
27
+
28
+ | 커밋 | 내용 |
29
+ | --------- | -------------------------------------------------------- |
30
+ | `412d549` | `.gitignore`에 `.claude/` 추가, CLAUDE.md 커밋 규칙 설정 |
31
+ | `f3fb727` | CLAUDE.md에 Co-Authored-By 미포함 규칙 추가 |
32
+
33
+ - 프로젝트 협업 규칙 정립 (커밋 접두사 `[Delta-02]` 통일 등)
34
+
35
+ ---
36
+
37
+ ### 2. Day 1 — PDF 업로드 및 텍스트 추출 (10:53 ~ 13:43)
38
+
39
+ | 커밋 | 내용 |
40
+ | --------- | ----------------------------------------------------- |
41
+ | `ddacbbe` | 테스트용 PDF 파일 추가 (서울대 학업성적 처리 규정 등) |
42
+ | `47a0998` | PDF 파일 업로드 기능 구현 |
43
+
44
+ #### 2-1. 파일 업로드 — `app/main.py:81-85`
45
+
46
+ ```python
47
+ file_path = os.path.join(UPLOAD_DIR, f"{document_id}_{file.filename}")
48
+ with open(file_path, "wb") as f:
49
+ content = await file.read()
50
+ f.write(content)
51
+ ```
52
+
53
+ **왜 이렇게 했는가:**
54
+
55
+ - 파일명 앞에 `document_id`(UUID)를 붙이는 이유: 서로 다른 사용자가 같은 이름의 PDF를 올려도 파일이 덮어씌워지지 않도록 **고유성을 보장**하기 위함
56
+ - `await file.read()`로 비동기 읽기를 하는 이유: FastAPI의 `UploadFile`은 비동기 파일 객체이므로, `await`를 사용해야 이벤트 루프를 블로킹하지 않음
57
+
58
+ #### 2-2. 파일 확장자 검증 — `app/main.py:69-70`
59
+
60
+ ```python
61
+ if not allowed_file(file.filename):
62
+ raise HTTPException(status_code=400, detail="허용되지 않는 파일 형식입니다.")
63
+ ```
64
+
65
+ **왜 이렇게 했는가:**
66
+
67
+ - `config.py`에서 `ALLOWED_EXTENSIONS = {"pdf"}`로 PDF만 허용
68
+ - 텍스트 추출 로직이 `pdfplumber`에 의존하므로, PDF가 아닌 파일이 들어오면 에러가 발생함 → **사전에 차단**하여 불필요한 서버 에러 방지
69
+
70
+ #### 2-3. PDF 텍스트 추출 — `app/main.py:40-46`
71
+
72
+ ```python
73
+ def extract_text_from_pdf(file_path: str) -> str:
74
+ text = ""
75
+ with pdfplumber.open(file_path) as pdf:
76
+ for page in pdf.pages:
77
+ page_text = page.extract_text()
78
+ if page_text:
79
+ text += page_text + "\n"
80
+ return text
81
+ ```
82
+
83
+ **왜 `pdfplumber`를 선택했는가:**
84
+
85
+ - Pipfile에 이미 설치되어 있는 라이브러리
86
+ - `PyPDF2`보다 표/레이아웃이 있는 PDF에서 텍스트 추출 정확도가 높음
87
+ - `page.extract_text()`가 `None`을 반환할 수 있음 (이미지만 있는 페이지 등) → `if page_text:` 조건으로 **None 페이지를 건너뜀**
88
+ - 페이지 사이에 `\n`을 넣는 이유: 페이지 경계를 구분하여 이후 문장 분리(sentence tokenize)가 더 정확하게 동작하도록 함
89
+
90
+ **변경 파일**: `app/main.py`
91
+
92
+ ---
93
+
94
+ ### 3. Day 2-① — 텍스트 청크 분할 (15:00 ~ 16:00)
95
+
96
+ | 커밋 | 내용 |
97
+ | --------- | ---------------------------------- |
98
+ | `f423522` | 필요 라이브러리 설치 (nltk, numpy) |
99
+ | `ae051f4` | `split_text` 초안 작성 |
100
+ | `9462141` | `split_text` 의미 기반 분할 완성 |
101
+
102
+ #### 3-0. 왜 청크 분할이 필요한가?
103
+
104
+ LLM에는 컨텍스트 윈도우 제한이 있고, 임베딩 모델도 긴 텍스트를 한 번에 처리하면 의미가 희석된다.
105
+ 따라서 문서를 적절한 크기의 청크로 나누어야 하며, **의미적으로 관련 있는 문장들이 같은 청크에 묶여야** 검색 품질이 높아진다.
106
+
107
+ #### 3-1. 임베딩 모델 변경 — `app/config.py:11`
108
+
109
+ ```python
110
+ # 변경 전
111
+ OLLAMA_EMBED_MODEL = os.getenv("OLLAMA_EMBED_MODEL", "nomic-embed-text")
112
+ # 변경 후
113
+ OLLAMA_EMBED_MODEL = os.getenv("OLLAMA_EMBED_MODEL", "bge-m3")
114
+ ```
115
+
116
+ **왜 변경했는가:**
117
+
118
+ - `bge-m3`는 다국어(한국어 포함) 임베딩 성능이 우수한 모델
119
+ - `nomic-embed-text`는 영어 중심 모델로, 한국어 문서를 다루는 이 프로젝트에 적합하지 않음
120
+ - 출력 벡터 차원: 768차원 (Supabase `document_chunks` 테이블의 벡터 컬럼 차원과 일치해야 함)
121
+
122
+ #### 3-2. 헬퍼 함수 — `app/embedding_utils.py:8-21`
123
+
124
+ ```python
125
+ def _ollama_embed(text: str) -> List[float]:
126
+ resp = requests.post(
127
+ f"{OLLAMA_BASE}/api/embeddings",
128
+ json={"model": OLLAMA_EMBED_MODEL, "prompt": text},
129
+ )
130
+ resp.raise_for_status()
131
+ return resp.json()["embedding"]
132
+
133
+ def _cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
134
+ norm = np.linalg.norm(a) * np.linalg.norm(b)
135
+ if norm == 0:
136
+ return 0.0
137
+ return float(np.dot(a, b) / norm)
138
+ ```
139
+
140
+ **왜 이렇게 했는가:**
141
+
142
+ - `_ollama_embed`: Ollama의 `/api/embeddings` 엔드포인트를 호출하는 내부 함수. `_` prefix는 모듈 내부에서만 사용한다는 컨벤션
143
+ - `raise_for_status()`: Ollama 서버가 응답하지 않거나 에러를 반환하면 즉시 예외를 발생시킴
144
+ - `_cosine_similarity`: 두 벡터 간 코사인 유사도를 계산. `norm == 0` 체크는 영벡터(빈 텍스트 등)로 인한 ZeroDivisionError 방지
145
+
146
+ #### 3-3. 의미 기반 청크 분할 — `app/embedding_utils.py:24-103`
147
+
148
+ 이 함수는 5단계로 동작한다:
149
+
150
+ **Step 1: 문장 분리 (line 44-46)**
151
+
152
+ ```python
153
+ sentences = nltk.sent_tokenize(text)
154
+ if len(sentences) <= 1:
155
+ return [text.strip()] if text.strip() else []
156
+ ```
157
+
158
+ - `nltk.sent_tokenize()`는 마침표, 느낌표 등을 기준으로 문장을 분리
159
+ - 문장이 1개 이하면 분할할 필요가 없으므로 바로 반환
160
+ - 빈 텍스트인 경우 빈 리스트 반환
161
+
162
+ **Step 2: 인접 문장 유사도 계산 (line 48-53)**
163
+
164
+ ```python
165
+ embeddings = [np.array(_ollama_embed(s)) for s in sentences]
166
+ similarities = [
167
+ _cosine_similarity(embeddings[i], embeddings[i + 1])
168
+ for i in range(len(embeddings) - 1)
169
+ ]
170
+ ```
171
+
172
+ - 각 문장을 벡터로 변환한 뒤, **인접한 두 문장 사이의 코사인 유사도**를 계산
173
+ - 유사도가 높으면 = 두 문장이 같은 주제, 유사도가 낮으면 = 주제가 바뀌는 경계
174
+
175
+ **Step 3: 적응적 threshold로 의미 경계 감지 (line 55-64)**
176
+
177
+ ```python
178
+ mean_sim = np.mean(similarities)
179
+ std_sim = np.std(similarities)
180
+ threshold = mean_sim - std_sim
181
+ ```
182
+
183
+ - threshold를 `평균 - 1σ(표준편차)`로 설정
184
+ - **왜 고정값이 아닌 적응적 threshold인가:** 문서마다 문장 간 유사도 분포가 다르기 때문. 기술 문서는 전체적으로 유사도가 높고, 여러 주제를 다루는 문서는 낮을 수 있음 → 문서의 통계적 특성에 맞게 자동 조정
185
+ - 유사도가 threshold보다 낮은 지점에서 새로운 그룹을 시작함 (= 의미 경계)
186
+
187
+ **Step 4: chunk_size 적용 — 병합 및 강제 분할 (line 66-89)**
188
+
189
+ ```python
190
+ # 작은 그룹 병합
191
+ for group in groups:
192
+ group_text = " ".join(group)
193
+ if buffer and len(buffer) + len(group_text) + 1 > chunk_size:
194
+ merged.append(buffer.strip())
195
+ buffer = ""
196
+ buffer = (buffer + " " + group_text).strip() if buffer else group_text
197
+
198
+ # 큰 청크 강제 분할
199
+ while len(chunk) > chunk_size:
200
+ split_pos = chunk[:chunk_size].rfind(" ")
201
+ ```
202
+
203
+ - 의미 그룹이 너무 작으면(예: 문장 1~2개) → 다음 그룹과 **병합**하여 chunk_size에 가깝게 만듦
204
+ - 의미 그룹이 너무 크면(chunk_size 초과) → 단어 경계(`rfind(" ")`)에서 **강제 분할**
205
+ - `rfind(" ")`를 쓰는 이유: 단어 중간에서 잘리면 의미가 깨지므로, 가장 가까운 공백 위치에서 자름
206
+
207
+ **Step 5: chunk_overlap 적용 (line 91-101)**
208
+
209
+ ```python
210
+ if chunk_overlap > 0 and len(chunks) > 1:
211
+ overlapped = [chunks[0]]
212
+ for i in range(1, len(chunks)):
213
+ prev = chunks[i - 1]
214
+ overlap_text = prev[-chunk_overlap:]
215
+ space_pos = overlap_text.find(" ")
216
+ if space_pos != -1:
217
+ overlap_text = overlap_text[space_pos + 1:]
218
+ overlapped.append((overlap_text + " " + chunks[i]).strip())
219
+ ```
220
+
221
+ - **왜 overlap이 필요한가:** 청크 경계에서 잘린 문맥을 복원하기 위함. 예를 들어 "이 정책은... (청크1 끝) ...학생들에게 적용된다 (청크2 시작)" → overlap이 없으면 청크2만 검색되었을 때 "이 정책"이 뭔지 알 수 없음
222
+ - 이전 청크의 마지막 `chunk_overlap`글자를 다음 청크 앞에 붙임
223
+ - `space_pos = overlap_text.find(" ")`: 단어 중간에서 잘리지 않도록 첫 번째 공백 이후부터 가져옴
224
+
225
+ **변경 파일**: `app/embedding_utils.py`, `app/config.py`, `Pipfile`, `Pipfile.lock`
226
+
227
+ ---
228
+
229
+ ### 4. Day 2-② — 임베딩 생성 + DB 저장 + 파이프라인 연결 (16:00 ~ 16:46)
230
+
231
+ | 커밋 | 내용 |
232
+ | --------- | --------------------------------------------------------- |
233
+ | `349228b` | `get_embedding`, `save_embedding` 구현 및 파이프라인 연결 |
234
+
235
+ #### 4-1. 임베딩 생성 — `app/embedding_utils.py:106-127`
236
+
237
+ ```python
238
+ def get_embedding(text: str) -> List[float]:
239
+ return _ollama_embed(text)
240
+ ```
241
+
242
+ **왜 `_ollama_embed`를 직접 쓰지 않고 래핑했는가:**
243
+
244
+ - `get_embedding()`��� 외부에서 호출하는 **공개 인터페이스**
245
+ - `_ollama_embed()`는 `_` prefix가 붙은 **내부 구현**
246
+ - 나중에 `PROVIDER=openai`일 때 OpenAI API로 분기하는 로직을 추가할 수 있도록 **확장 포인트를 분리**해둔 구조
247
+ - 현재는 Ollama만 사용하므로 단순히 위임
248
+
249
+ **테스트 결과:**
250
+
251
+ ```
252
+ 벡터 길이: 768
253
+ 처음 5개 값: [-0.032, 0.048, -3.680, 0.230, 1.564]
254
+ 타입: <class 'float'>
255
+ ```
256
+
257
+ #### 4-2. DB 저장 — `app/supabase_utils.py:39-47`
258
+
259
+ ```python
260
+ data = {
261
+ "document_id": document_id,
262
+ "content": chunk,
263
+ "embedding": embedding,
264
+ "chunk_index": chunk_index,
265
+ "metadata": {},
266
+ }
267
+ result = supabase.table("document_chunks").insert(data).execute()
268
+ return result.data
269
+ ```
270
+
271
+ **각 필드의 역할:**
272
+ | 필드 | 타입 | 역할 |
273
+ |------|------|------|
274
+ | `document_id` | `str` (UUID) | 어떤 문서에 속한 청크인지 식별. QA 시 특정 문서 내에서만 검색할 때 사용 |
275
+ | `content` | `str` | 청크 원문 텍스트. 검색 결과로 LLM에 전달할 컨텍스트 |
276
+ | `embedding` | `List[float]` | 768차원 벡터. 벡터 유사도 검색에 사용 |
277
+ | `chunk_index` | `int` | 청크 순서 (0부터 시작). 문서 내 위치 추적 및 정렬에 사용 |
278
+ | `metadata` | `dict` | 확장용 빈 객체. 추후 페이지 번호, 섹션명 등을 저장할 수 있음 |
279
+
280
+ **왜 `result.data`를 반환하는가:**
281
+
282
+ - Supabase의 `.execute()`는 저장된 데이터(생성된 `id`, `created_at` 포함)를 반환
283
+ - 호출한 쪽에서 저장 성공 여부와 생성된 데이터를 확인할 수 있도록 함
284
+
285
+ #### 4-3. 파이프라인 연결 — `app/main.py:90-101`
286
+
287
+ ```python
288
+ # 3. 청크 분할
289
+ chunks = split_text(text)
290
+
291
+ # 4. 임베딩 및 저장
292
+ for i, chunk in enumerate(chunks):
293
+ embedding = get_embedding(chunk)
294
+ save_embedding(document_id, chunk, embedding, i)
295
+
296
+ return {
297
+ "message": "문서 처리가 완료되었습니다.",
298
+ "document_id": document_id,
299
+ "chunks_count": len(chunks),
300
+ }
301
+ ```
302
+
303
+ **전체 파이프라인 흐름 (1→2→3→4 순차 실행):**
304
+
305
+ 1. **파일 저장** → 업로드된 PDF를 `app/uploads/{uuid}_{원본파일명}`으로 저장
306
+ 2. **텍스트 추출** → `pdfplumber`로 전 페이지 텍스트를 하나의 문자열로 합침
307
+ 3. **청크 분할** → 의미 기반으로 텍스트를 청크 리스트로 분할
308
+ 4. **임베딩 및 저장** → 각 청크마다 768차원 벡터를 생성하고 Supabase에 저장
309
+
310
+ **`chunks_count`를 응답에 포함한 이유:**
311
+
312
+ - 클라이언트(웹 UI)에서 몇 개의 청크로 분할되었는지 확인할 수 있도록
313
+ - 디버깅 시 청크 수가 비정상적이면 (0개, 너무 많은 수) 문제를 빠르게 감지 가능
314
+
315
+ **변경 파일**: `app/embedding_utils.py`, `app/supabase_utils.py`, `app/main.py`
316
+
317
+ ---
318
+
319
+ ## 사용 기술 스택 요약
320
+
321
+ | 기술 | 용도 | 선택 이유 |
322
+ | ------------------- | ----------------------------- | -------------------------------------------- |
323
+ | **pdfplumber** | PDF 텍스트 추출 | 표/레이아웃 포함 PDF에서 높은 추출 정확도 |
324
+ | **nltk** | 문장 분리 (sent_tokenize) | 문장 경계를 정확하게 감지 |
325
+ | **Ollama + bge-m3** | 텍스트 → 768차원 벡터 임베딩 | 다국어(한국어) 지원, 로컬 실행으로 비용 무료 |
326
+ | **numpy** | 코사인 유사도 계산 | 벡터 연산 라이브러리 |
327
+ | **Supabase** | 벡터 + 텍스트 저장 (pgvector) | PostgreSQL 기반 벡터 DB, 무료 tier 제공 |
328
+ | **FastAPI** | REST API 서버 | 비동기 지원, 자동 문서화 |
329
+
330
+ ---
331
+
332
+ ## 남은 작업 (Day 3~4)
333
+
334
+ - [ ] `search_similar_embeddings()` 구현 — Supabase RPC로 벡터 유사도 검색
335
+ - [ ] `/qa` 엔드포인트 완성 — 질문 임베딩 → 벡터 검색 → 프롬프트 구성 → LLM 응답 생성