From 7d84def744eece4aa2a890d2705627422f3743f9 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Mon, 1 Dec 2025 12:17:20 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20IR=20Deck=20=ED=8F=89=EA=B0=80=20KeyErr?= =?UTF-8?q?or=20=EC=88=98=EC=A0=95=20=EB=B0=8F=20LLM=20=ED=98=B8=EC=B6=9C?= =?UTF-8?q?=20=EC=B5=9C=EC=A0=81=ED=99=94=20=ED=8A=B8=EB=9F=AC=EB=B8=94?= =?UTF-8?q?=EC=8A=88=ED=8C=85=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ck_evaluation_keyerror_llm_optimization.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 journey/troubleshooting/251201_ir_deck_evaluation_keyerror_llm_optimization.md diff --git a/journey/troubleshooting/251201_ir_deck_evaluation_keyerror_llm_optimization.md b/journey/troubleshooting/251201_ir_deck_evaluation_keyerror_llm_optimization.md new file mode 100644 index 0000000..4a6de54 --- /dev/null +++ b/journey/troubleshooting/251201_ir_deck_evaluation_keyerror_llm_optimization.md @@ -0,0 +1,62 @@ +# IR Deck 평가 KeyError 수정 및 LLM 호출 최적화 + +**날짜**: 2025-12-01 +**작성자**: Auto +**관련 파일**: +- `rb8001/app/state/ir_valuation_repository.py` +- `rb8001/app/services/ir_deck_analyzer.py` +- `rb8001/scripts/migrate_ir_deck_score_nullable.py` + +--- + +## 문제 상황 + +### 1. KeyError: 'score' +- `ir_valuation_repository.py:145`에서 `page_eval["score"]` 참조 시 KeyError 발생 +- `evaluate_by_page()`는 `score` 필드를 반환하지 않음 (페이지별 점수 제거됨) +- DB 스키마: `ir_deck_page_evaluations.score`는 `NOT NULL` 제약 조건 + +### 2. Gemini API 할당량 초과 +- 페이지당 11회 LLM 호출 (10개 스토리 평가 + 1회 피드백 추출) +- 10페이지 기준 110회 호출 → 할당량 초과 (15회/분) +- 429 `ResourceExhausted` 에러 발생 + +## 해결 방안 + +### 1. KeyError 수정 +- `ir_valuation_repository.py:41`: ORM 모델 `score` 필드를 `nullable=True`로 변경 +- `ir_valuation_repository.py:74`: DDL에서 `score INTEGER NULL`로 변경 +- `ir_valuation_repository.py:145`: `page_eval.get("score")` 사용 (없으면 NULL 저장) +- `scripts/migrate_ir_deck_score_nullable.py`: 기존 DB 마이그레이션 스크립트 작성 + +### 2. LLM 호출 최적화 +- `ir_deck_analyzer.py:246-273`: `evaluate_by_page()`에서 `score` 필드 제거 +- `ir_deck_analyzer.py:275-365`: `_evaluate_page_comprehensive()` 메서드 추가 + - 단일 LLM 호출로 10개 스토리 평가 + 피드백 추출 통합 + - 11회 → 1회로 호출 횟수 감소 +- `ir_deck_analyzer.py`: `_evaluate_story_coverage()` 메서드 제거 (기능 통합) + +## 구현 완료 + +- 커밋: TBD (작업 진행 중) +- 테스트: `test_ir_deck_evaluation.py`에 검증 테스트 추가 + - `test_create_evaluation_without_score()`: score 없이 저장 검증 + - `test_evaluate_by_page_single_llm_call()`: 단일 LLM 호출 검증 + +## 교훈 + +### DB 스키마 변경 시 동기화 필수 +- ORM 모델, DDL, Repository 코드를 동시에 수정해야 함 +- 한 곳만 수정 시 런타임 에러 또는 스키마 불일치 발생 +- 교훈: 스키마 변경 시 3곳(ORM/DDL/Repository) 동시 점검 체크리스트 작성 + +### LLM 호출 최적화 필요 +- 페이지별 평가에서 11회 호출은 과도함 +- 단일 프롬프트로 통합 가능한 작업은 반드시 통합 +- 교훈: LLM 호출 전 호출 횟수 계산 및 최적화 검토 필수 + +### TDD 원칙 준수 +- 테스트 작성 후 구현으로 버그 조기 발견 +- `KeyError`는 테스트로 사전 발견 가능했던 문제 +- 교훈: 스키마 변경 시 반드시 테스트 먼저 작성 +