diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index efd30a6..8cf566c 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -1,6 +1,7 @@ # 문서 작성 원칙 **작성일**: 2025-10-13 +**수정일**: 2025-11-28 (핵심 원칙 명확화, 중복 내용 정리) **참고**: CLAUDE.md, 311_FastAPI_구조_원칙.md --- @@ -49,43 +50,36 @@ ## 2. 작성 규칙 +### 핵심 원칙 (최우선) + +**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함 +- 불필요한 설명, 중복 내용, 장황한 문장 제거 +- 필요한 정보만 간결하게 기록 +- 관련 정보는 링크로 참조 (중복 작성 금지) + ### 절대 금지 사항 | 금지 | 이유 | |------|------| -| 의사코드, 추측, 예측 | 실제 동작하는 코드만 작성 | -| "아마", "것 같다", "추정" | 확인된 사실만 기록 | -| 불필요한 코드 블록 | 파일명:줄번호만 명시 | +| 핵심 없는 장황한 설명, 중복 내용 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 | +| 쓸데없는 코드 작성 (전체 코드 블록) | 파일명:줄번호만 명시 | +| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 | | 이모지 사용 | 명시적 요청 시만 허용 | ### 파일 참조 형식 -**올바름**: +**올바름** (파일명:줄번호 + 간단 설명): ```markdown - naverworks_briefing.py:58-74: 폴백 제거 - ir_analyzer.py:28: /api/query → /api/search ``` -**금지**: +**금지** (전체 코드 복사, 추상적 표현): ```markdown -- naverworks_briefing.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 -**수정 필요:** +- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음 +- ir_analyzer.py 파일 수정 ← 구체적 내용 없음 ```python -# ir_analyzer.py 전체 함수 코드 50줄 복사... +# 전체 함수 코드 50줄 복사... ← 불필요 ``` ``` @@ -189,12 +183,15 @@ ## 7. 체크리스트 문서 작성 전: +- [ ] **핵심만 간결하게 정리** (불필요한 설명/중복 제거, 링크로 대체) +- [ ] 파일명:줄번호로 위치 명시 (전체 코드 블록 금지) +- [ ] 확인된 사실만 기록 (추측/의사코드 제거) - [ ] 파일명 형식 준수 (yymmdd_주제.md) -- [ ] 파일명:줄번호로 위치 명시 -- [ ] 의사코드/추측 제거 - [ ] 100줄 이하 확인 - [ ] 교훈 섹션 작성 (트러블슈팅) -- [ ] 이모지 제거 (명시 요청 없으면) + +문서 작성 후: +- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 --- diff --git a/journey/troubleshooting/251128_ir_deck_batch_test_issues.md b/journey/troubleshooting/251128_ir_deck_batch_test_issues.md new file mode 100644 index 0000000..8e0f0bb --- /dev/null +++ b/journey/troubleshooting/251128_ir_deck_batch_test_issues.md @@ -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) - 테스트 코드 + diff --git a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md b/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md index 6188400..3e04ed2 100644 --- a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md +++ b/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md @@ -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` - 문서 작성 규칙