docs: IR Deck 배치 테스트 문서 업데이트 및 문서 작성 원칙 정리
- IR Deck 배치 테스트: SQLAlchemy JSONB 업데이트 문제, 중복 엔드포인트 정리 교훈 추가 - 문서 작성 원칙: 핵심만 간결하게 정리 최우선 원칙 추가, 중복 내용 정리
This commit is contained in:
Claude-51124
parent
d0b287f864
commit
83c0fa4d5f
@ -1,6 +1,7 @@
|
|||||||
# 문서 작성 원칙
|
# 문서 작성 원칙
|
||||||
|
|
||||||
**작성일**: 2025-10-13
|
**작성일**: 2025-10-13
|
||||||
|
**수정일**: 2025-11-28 (핵심 원칙 명확화, 중복 내용 정리)
|
||||||
**참고**: CLAUDE.md, 311_FastAPI_구조_원칙.md
|
**참고**: CLAUDE.md, 311_FastAPI_구조_원칙.md
|
||||||
|
|
||||||
---
|
---
|
||||||
@ -49,43 +50,36 @@
|
|||||||
|
|
||||||
## 2. 작성 규칙
|
## 2. 작성 규칙
|
||||||
|
|
||||||
|
### 핵심 원칙 (최우선)
|
||||||
|
|
||||||
|
**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함
|
||||||
|
- 불필요한 설명, 중복 내용, 장황한 문장 제거
|
||||||
|
- 필요한 정보만 간결하게 기록
|
||||||
|
- 관련 정보는 링크로 참조 (중복 작성 금지)
|
||||||
|
|
||||||
### 절대 금지 사항
|
### 절대 금지 사항
|
||||||
|
|
||||||
| 금지 | 이유 |
|
| 금지 | 이유 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| 의사코드, 추측, 예측 | 실제 동작하는 코드만 작성 |
|
| 핵심 없는 장황한 설명, 중복 내용 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 |
|
||||||
| "아마", "것 같다", "추정" | 확인된 사실만 기록 |
|
| 쓸데없는 코드 작성 (전체 코드 블록) | 파일명:줄번호만 명시 |
|
||||||
| 불필요한 코드 블록 | 파일명:줄번호만 명시 |
|
| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 |
|
||||||
| 이모지 사용 | 명시적 요청 시만 허용 |
|
| 이모지 사용 | 명시적 요청 시만 허용 |
|
||||||
|
|
||||||
### 파일 참조 형식
|
### 파일 참조 형식
|
||||||
|
|
||||||
**올바름**:
|
**올바름** (파일명:줄번호 + 간단 설명):
|
||||||
```markdown
|
```markdown
|
||||||
- naverworks_briefing.py:58-74: 폴백 제거
|
- naverworks_briefing.py:58-74: 폴백 제거
|
||||||
- ir_analyzer.py:28: /api/query → /api/search
|
- ir_analyzer.py:28: /api/query → /api/search
|
||||||
```
|
```
|
||||||
|
|
||||||
**금지**:
|
**금지** (전체 코드 복사, 추상적 표현):
|
||||||
```markdown
|
```markdown
|
||||||
- naverworks_briefing.py에서 폴백 제거
|
- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음
|
||||||
- ir_analyzer.py 파일 수정
|
- ir_analyzer.py 파일 수정 ← 구체적 내용 없음
|
||||||
```
|
|
||||||
|
|
||||||
### 코드 블록 최소화
|
|
||||||
|
|
||||||
**올바름** (파일명:줄번호 + 간단 설명):
|
|
||||||
```markdown
|
|
||||||
**수정 필요:**
|
|
||||||
- ir_analyzer.py:28: url = f"{SKILL_RAG_FILE_URL}/api/search"
|
|
||||||
- ir_analyzer.py:29-32: payload에 team_id 추가
|
|
||||||
```
|
|
||||||
|
|
||||||
**금지** (전체 코드 복사):
|
|
||||||
```markdown
|
|
||||||
**수정 필요:**
|
|
||||||
```python
|
```python
|
||||||
# ir_analyzer.py 전체 함수 코드 50줄 복사...
|
# 전체 함수 코드 50줄 복사... ← 불필요
|
||||||
```
|
```
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -189,12 +183,15 @@
|
|||||||
## 7. 체크리스트
|
## 7. 체크리스트
|
||||||
|
|
||||||
문서 작성 전:
|
문서 작성 전:
|
||||||
|
- [ ] **핵심만 간결하게 정리** (불필요한 설명/중복 제거, 링크로 대체)
|
||||||
|
- [ ] 파일명:줄번호로 위치 명시 (전체 코드 블록 금지)
|
||||||
|
- [ ] 확인된 사실만 기록 (추측/의사코드 제거)
|
||||||
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
|
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
|
||||||
- [ ] 파일명:줄번호로 위치 명시
|
|
||||||
- [ ] 의사코드/추측 제거
|
|
||||||
- [ ] 100줄 이하 확인
|
- [ ] 100줄 이하 확인
|
||||||
- [ ] 교훈 섹션 작성 (트러블슈팅)
|
- [ ] 교훈 섹션 작성 (트러블슈팅)
|
||||||
- [ ] 이모지 제거 (명시 요청 없으면)
|
|
||||||
|
문서 작성 후:
|
||||||
|
- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
246
journey/troubleshooting/251128_ir_deck_batch_test_issues.md
Normal file
246
journey/troubleshooting/251128_ir_deck_batch_test_issues.md
Normal file
@ -0,0 +1,246 @@
|
|||||||
|
# IR Deck 배치 테스트 문제점 분석
|
||||||
|
|
||||||
|
**작성일**: 2025-11-28
|
||||||
|
**작성자**: Auto
|
||||||
|
**태그**: `#ir-deck #batch-test #troubleshooting #page-splitting #rb8001 #skill-rag-file`
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
- [IR Deck 평가 백엔드 아키텍처](./251128_ir_deck_valuation_backend_architecture.md) - 초기 설계
|
||||||
|
|
||||||
|
## 테스트 개요
|
||||||
|
|
||||||
|
**테스트 파일**: 10개 실제 IR Deck PDF 파일
|
||||||
|
**테스트 시나리오**: 업로드 → 평가 → 질문 → 결과 조회
|
||||||
|
**테스트 결과**: 10/10 성공, 하지만 여러 문제점 발견
|
||||||
|
|
||||||
|
## 통계 결과
|
||||||
|
|
||||||
|
- **성공률**: 10/10 (100%)
|
||||||
|
- **평균 점수**: 10.4/100
|
||||||
|
- **점수 범위**: 0-28점
|
||||||
|
- **등급 분포**: C등급 10개 (S/A/B 등급 없음)
|
||||||
|
- **평균 페이지 수**: 3.7페이지
|
||||||
|
- **페이지 범위**: 2-15페이지
|
||||||
|
- **평균 평가 시간**: 33.5초
|
||||||
|
- **시간 범위**: 14.5초-126.3초
|
||||||
|
|
||||||
|
## 발견된 문제점
|
||||||
|
|
||||||
|
### 1. 중복 파일 처리 문제 (Critical)
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 동일한 파일이 다른 파일명으로 업로드되었을 때, skill-rag-file이 중복 체크하여 같은 `document_id`를 반환
|
||||||
|
- 5개 파일 중 3개 파일이 실제로 동일한 내용 (MD5 해시 확인)
|
||||||
|
|
||||||
|
**증거**:
|
||||||
|
```
|
||||||
|
[5/10] 335f0f6d-aff2-42bd-aedd-341c7e4c8a51.pdf (3444872 bytes)
|
||||||
|
→ document_id: 00260d32-8109-4b9c-bdf1-d3b4534e29c2 (다른 파일의 ID)
|
||||||
|
|
||||||
|
[6/10] 5a443e10-0427-4552-8d5f-57c0769b84cf.pdf (3444005 bytes)
|
||||||
|
→ document_id: 5a7dde23-48f6-4682-820c-786a52bdb4d7 (다른 파일의 ID)
|
||||||
|
|
||||||
|
[10/10] 74c743a7-608e-4597-8d75-8a96f56e56ca.pdf (3444005 bytes)
|
||||||
|
→ document_id: 5a7dde23-48f6-4682-820c-786a52bdb4d7 (다른 파일의 ID)
|
||||||
|
```
|
||||||
|
|
||||||
|
**MD5 해시 확인**:
|
||||||
|
```
|
||||||
|
5580a25d398c07453c1b4de2746c73d1 00260d32-8109-4b9c-bdf1-d3b4534e29c2.pdf
|
||||||
|
5580a25d398c07453c1b4de2746c73d1 335f0f6d-aff2-42bd-aedd-341c7e4c8a51.pdf ← 동일
|
||||||
|
|
||||||
|
1f87473cc465e5008096ef3344a2fcdc 5a443e10-0427-4552-8d5f-57c0769b84cf.pdf ← 동일
|
||||||
|
1f87473cc465e5008096ef3344a2fcdc 5a7dde23-48f6-4682-820c-786a52bdb4d7.pdf ← 동일
|
||||||
|
1f87473cc465e5008096ef3344a2fcdc 74c743a7-608e-4597-8d75-8a96f56e56ca.pdf ← 동일
|
||||||
|
```
|
||||||
|
|
||||||
|
**영향**:
|
||||||
|
- 중복 평가 발생
|
||||||
|
- 평가 결과가 실제 파일과 불일치
|
||||||
|
- 통계 왜곡 (실제로는 8개 고유 파일만 평가됨)
|
||||||
|
|
||||||
|
**해결 방안**:
|
||||||
|
1. 프론트엔드에서 업로드 전 중복 체크 (선택적)
|
||||||
|
2. skill-rag-file의 중복 파일 처리 로직은 유지 (성능상 이점)
|
||||||
|
3. 평가 시 `document_id` 기준으로 중복 평가 방지 로직 추가
|
||||||
|
4. 사용자에게 중복 파일 경고 표시
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. 페이지 분할 부정확 문제 (High) ✅ 해결 완료
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 평균 3.7페이지만 평가됨 (실제 PDF: 25-68페이지)
|
||||||
|
- 텍스트 기반 3000자당 1페이지 추정으로 부정확
|
||||||
|
|
||||||
|
**원인**:
|
||||||
|
1. skill-rag-file이 PDF 추출 시 페이지 정보 손실
|
||||||
|
2. rb8001이 페이지 수를 알 수 없어 텍스트 길이만으로 추정
|
||||||
|
|
||||||
|
**해결** (2025-11-28):
|
||||||
|
1. **skill-rag-file**: PDF 페이지 수 추출 및 메타데이터 저장
|
||||||
|
- `text_extractor.py`: `get_pdf_page_count()` 메서드 추가 (PyPDF2/pdfinfo 사용)
|
||||||
|
- `upload.py`: 새/중복 파일 모두 `file_metadata.page_count`에 저장
|
||||||
|
- 참고: [skill-rag-file/text_extractor.py](../../skill-rag-file/app/services/text_extractor.py)
|
||||||
|
2. **rb8001**: 실제 페이지 수 활용한 페이지 분할
|
||||||
|
- `ir_deck_analyzer.py`: `/api/text/{document_id}`에서 페이지 수 조회
|
||||||
|
- `_split_into_pages()`: 페이지 수 기반 정확한 분할 구현
|
||||||
|
- 참고: [rb8001/app/services/ir_deck_analyzer.py](../../rb8001/app/services/ir_deck_analyzer.py)
|
||||||
|
|
||||||
|
**⚠️ 참고**: JSONB 필드 업데이트는 `update()` 구문 사용 (in-place 변경은 감지 안 됨). `reindex.py:129-134` 구현 방식 참고.
|
||||||
|
|
||||||
|
**태그**: `#ir-deck #page-splitting #skill-rag-file #rb8001`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. 점수 산정 문제 (High)
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 모든 파일이 C등급 (0-28점)
|
||||||
|
- 평균 점수 10.4점으로 매우 낮음
|
||||||
|
- S/A/B 등급 파일이 하나도 없음
|
||||||
|
|
||||||
|
**증거**:
|
||||||
|
```
|
||||||
|
점수 범위: 0-28점
|
||||||
|
등급 분포: {'S': 0, 'A': 0, 'B': 0, 'C': 10}
|
||||||
|
평균 점수: 10.4점
|
||||||
|
```
|
||||||
|
|
||||||
|
**가능한 원인**:
|
||||||
|
1. **평가 기준이 너무 엄격함**: Sequoia Capital 10-story 기준으로 모든 항목을 체크
|
||||||
|
2. **페이지 분할 부정확**: 실제 페이지와 불일치하여 평가 누락
|
||||||
|
3. **RAG 검색 품질**: 관련 정보를 제대로 찾지 못함
|
||||||
|
4. **LLM 프롬프트 문제**: 점수 산정 로직이 너무 보수적
|
||||||
|
|
||||||
|
**해결 방안**:
|
||||||
|
1. **평가 기준 재검토**:
|
||||||
|
- Sequoia 10-story 중 핵심 항목 우선 평가
|
||||||
|
- 항목별 가중치 조정
|
||||||
|
2. **점수 정규화**: 페이지 수에 따른 점수 보정
|
||||||
|
3. **프롬프트 개선**: 평가 기준을 명확히 하고 예시 추가
|
||||||
|
4. **샘플 평가**: 실제 IR Deck 전문가 평가와 비교하여 기준 조정
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. 성능 문제 (Medium)
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 1개 파일이 126.3초 (2분 이상) 소요
|
||||||
|
- 15페이지 평가 시 선형적으로 시간 증가
|
||||||
|
|
||||||
|
**증거**:
|
||||||
|
```
|
||||||
|
평균 시간: 33.5초
|
||||||
|
시간 범위: 14.5초-126.3초
|
||||||
|
- 5b9c34b7...pdf (15페이지): 126.3초
|
||||||
|
- 평균 (3.7페이지): 33.5초
|
||||||
|
```
|
||||||
|
|
||||||
|
**원인 분석**:
|
||||||
|
- 페이지당 평가 시간: 약 8-10초
|
||||||
|
- 15페이지 × 8초 = 120초 (예상)
|
||||||
|
- 각 페이지마다 RAG 검색 + LLM 호출 필요
|
||||||
|
|
||||||
|
**영향**:
|
||||||
|
- 사용자 대기 시간 증가
|
||||||
|
- 타임아웃 위험 (현재 600초 = 10분 타임아웃)
|
||||||
|
|
||||||
|
**해결 방안**:
|
||||||
|
1. **비동기 병렬 처리**: 페이지별 평가를 동시에 실행
|
||||||
|
2. **배치 평가**: 여러 페이지를 한 번에 평가
|
||||||
|
3. **캐싱**: 중복 평가 방지
|
||||||
|
4. **프로그레스 업데이트**: 실시간 진행 상황 표시
|
||||||
|
5. **타임아웃 조정**: 큰 파일을 위한 타임아웃 증가
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. 채팅 답변 품질 문제 (Medium)
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 채팅 답변이 너무 짧음
|
||||||
|
- 정보가 불충분
|
||||||
|
|
||||||
|
**증거**:
|
||||||
|
```
|
||||||
|
[2/10] 062bf655-5580-49f2-a988-610dbf51c1ca.pdf
|
||||||
|
⚠ Chat answer too short: "㈜실크로입니다."
|
||||||
|
질문: "이 회사의 회사명은 무엇인가?"
|
||||||
|
```
|
||||||
|
|
||||||
|
**원인**:
|
||||||
|
- RAG 검색 결과가 부족하거나
|
||||||
|
- LLM 프롬프트가 너무 간결한 답변을 요구
|
||||||
|
|
||||||
|
**해결 방안**:
|
||||||
|
1. **RAG 검색 개선**: 더 많은 컨텍스트 반환
|
||||||
|
2. **프롬프트 개선**: 상세한 답변 요청
|
||||||
|
3. **답변 길이 검증**: 최소 길이 요구사항 추가
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 6. 점수 0점 문제 (Medium)
|
||||||
|
|
||||||
|
**문제**:
|
||||||
|
- 3개 파일이 0점 받음
|
||||||
|
|
||||||
|
**증거**:
|
||||||
|
```
|
||||||
|
[6/10] 5a443e10-0427-4552-8d5f-57c0769b84cf.pdf: 0점
|
||||||
|
[7/10] 5a7dde23-48f6-4682-820c-786a52bdb4d7.pdf: 0점
|
||||||
|
[10/10] 74c743a7-608e-4597-8d75-8a96f56e56ca.pdf: 0점
|
||||||
|
```
|
||||||
|
|
||||||
|
**가능한 원인**:
|
||||||
|
1. 텍스트 추출 실패 (OCR 문제)
|
||||||
|
2. 페이지 분할 실패
|
||||||
|
3. RAG 검색 실패
|
||||||
|
4. LLM 평가 실패
|
||||||
|
|
||||||
|
**해결 방안**:
|
||||||
|
1. **로깅 강화**: 각 단계별 실패 원인 기록
|
||||||
|
2. **폴백 처리**: 실패 시 최소 점수 부여
|
||||||
|
3. **에러 처리**: 명확한 에러 메시지 반환
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 우선순위별 해결 계획
|
||||||
|
|
||||||
|
### Phase 1: Critical (즉시 수정)
|
||||||
|
1. **중복 평가 방지**: `document_id` 기준으로 중복 평가 방지 로직 추가
|
||||||
|
2. **로깅 강화**: 각 단계별 상세 로그 기록
|
||||||
|
|
||||||
|
### Phase 2: High (1주일 이내)
|
||||||
|
3. ✅ **페이지 분할 개선**: skill-rag-file에서 실제 PDF 페이지 정보 활용 (2025-11-28 완료)
|
||||||
|
4. **점수 기준 재검토**: 평가 기준 및 점수 산정 로직 개선
|
||||||
|
|
||||||
|
### Phase 3: Medium (2주일 이내)
|
||||||
|
5. **성능 최적화**: 병렬 처리 및 배치 평가 구현
|
||||||
|
6. **채팅 품질 개선**: RAG 검색 및 프롬프트 개선
|
||||||
|
7. **에러 처리 강화**: 0점 문제 디버깅 및 폴백 처리
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 교훈
|
||||||
|
|
||||||
|
1. **중복 파일 처리**: skill-rag-file의 중복 체크는 성능상 이점이 있지만, 평가 로직에서는 별도 처리 필요
|
||||||
|
2. **페이지 분할**: 텍스트 기반 추정보다 실제 PDF 메타데이터 활용 필요
|
||||||
|
3. **SQLAlchemy JSONB 업데이트**: in-place 변경(`dict[key] = value`)은 DB에 반영 안 됨. 반드시 `update()` 구문 사용. 로그로만 판단하지 말고 API 응답으로 검증 필수
|
||||||
|
4. **중복 엔드포인트 정리**: `upload.py`와 `reindex.py`에 동일한 `/api/reindex` 엔드포인트 존재했음. `upload.py`에서 제거 완료. 같은 기능은 하나의 파일에만 두기
|
||||||
|
5. **점수 정규화**: 페이지 수에 따른 점수 보정 및 평가 기준 명확화 필요
|
||||||
|
6. **성능 최적화**: 페이지별 순차 평가보다 병렬 처리로 시간 단축 가능
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 다음 단계
|
||||||
|
|
||||||
|
1. 중복 평가 방지 로직 구현
|
||||||
|
2. ✅ 페이지 분할 개선 완료 (2025-11-28)
|
||||||
|
3. 페이지별 평가 병렬 처리 구현
|
||||||
|
4. 평가 기준 및 점수 산정 로직 재검토
|
||||||
|
5. 샘플 IR Deck으로 전문가 평가와 비교 검증
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
- [IR Deck 평가 백엔드 아키텍처](./251128_ir_deck_valuation_backend_architecture.md) - 초기 설계
|
||||||
|
- [IR Deck 배치 테스트 스크립트](../../rb8001/scripts/test_ir_deck_batch.py) - 테스트 코드
|
||||||
|
|
||||||
@ -164,5 +164,8 @@ CREATE TABLE ir_deck_feedback (
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
문서 규칙: `DOCS/book/300_architecture/312_문서_작성_원칙.md` 준수
|
## 관련 문서
|
||||||
|
|
||||||
|
- [IR Deck 배치 테스트 문제점 분석](./251128_ir_deck_batch_test_issues.md) - 배치 테스트 결과 및 해결 사항
|
||||||
|
- `DOCS/book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user