Spaces:
Runtime error
Runtime error
[Delta-02] 작업일지 추가 및 체크리스트 업데이트
Browse files- docs/02-weekend1/README.md +1 -1
- study-notes/2026-03-14-작업일지.md +335 -0
docs/02-weekend1/README.md
CHANGED
|
@@ -40,7 +40,7 @@
|
|
| 40 |
### 기능 구현
|
| 41 |
|
| 42 |
- [x] PDF 업로드 성공
|
| 43 |
-
- [
|
| 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 응답 생성
|