DOCS/journey/plans/260313_pydantic_ai_부분도입_llm_출력안정화_계획.md

tags

tags
plans pydantic-ai langgraph llm structured-output ir-analysis

Pydantic AI 부분 도입 LLM 출력안정화 계획

작성일: 2026-03-13
상태: planned
목표: LangGraph는 유지하면서 IR Deck 종합 평가 경로에 우선 Pydantic-only 기반 typed validation 계층을 도입해, 모순된 점수/등급/추천이 저장·노출되지 않게 합니다.

관련 문서

• Pydantic AI 도입 기반 LLM 출력 안정화 아이디어
• Pydantic AI 도입 기반 LLM 출력 안정화 방향확정 리서치
• 콜드메일 IR 분석이 첫 번째 PDF를 잘못 선택하는 상태

1. 이번 계획의 결정

• 1차는 Pydantic-only로 갑니다.
• Pydantic AI는 버리지 않되, 후속 2차 후보로 둡니다.
• 전면 교체는 하지 않고, IR Deck 종합 평가 경로에만 부분 도입합니다.
• LangGraph 워크플로는 유지합니다.
• 첫 단계에서는 raw output -> Pydantic model_validate -> semantic validation -> final output -> save 경계를 추가합니다.

2. 왜 지금 이 계획으로 가는가

• 실측 기준으로 현재 _evaluate_comprehensive()는 total_score=100, grade=B 같은 모순값을 그대로 통과시킵니다.
• 실측 기준으로 Pydantic validator만으로도 같은 입력을 차단했습니다.
• 따라서 지금 필요한 것은 Pydantic AI까지 바로 올리는 것보다, 먼저 가장 작은 변경으로 IR Deck 종합 평가 출력에 검증 경계를 추가하는 것입니다.

3. 범위

• 포함:
  • rb8001/app/services/ir_deck_analyzer.py 종합 평가 출력 경로
  • 필요 시 rb8001/app/services/ir_deck_output_models.py 또는 동등한 전용 모델 파일 추가
  • rb8001/tests/test_ir_deck_json_parsing.py 보강
  • rb8001/tests/test_ir_deck_workflow.py 보강
  • Pydantic typed output 모델 및 validator 추가
  • 저장 전 final_evaluation_result 생성
  • 모순 출력 테스트 추가
• 제외:
  • LangGraph 제거 또는 재설계
  • Pydantic AI 의존성 즉시 추가
  • 브리핑, 콜드메일, 투자의견 전 경로 동시 적용
  • 운영용 공통 출력 정책 프레임워크 전면화

4. 구현 원칙

• LangGraph는 상태 관리 계층으로 유지합니다.
• Pydantic-only는 종합 평가 결과 검증 계층으로만 붙입니다.
• raw와 final 결과를 분리합니다.
• grade, recommendation은 서버가 최종 소유합니다.
• 검증 실패는 성공처럼 저장하지 않습니다.

5. 구현 단계

A. 의존성 추가

• 추가 의존성 없이 현재 pydantic 자산을 먼저 사용합니다.
• 첫 적용 범위는 rb8001 한 경로로 제한합니다.

B. 출력 모델 추가

• 권장 위치:
  • 1순위: rb8001/app/services/ir_deck_output_models.py
  • 대안: rb8001/app/services/ir_deck_analyzer.py 내부 보조 모델
• 이유:
  • validator 로직과 LLM 호출 로직을 분리해 테스트 가능성을 높이기 위함입니다.
• IRDeckEvaluationResult에 해당하는 typed output 모델을 추가합니다.
• 최소 필드:
  • total_score
  • grade
  • story_scores
  • summary
  • strengths
  • weaknesses
  • risks
  • investment_opinion
• 함께 둘 보조 모델:
  • StoryScore
  • InvestmentOpinion
• validator 권장 항목:
  • grade == assign_grade(total_score)
  • summary 최소 길이
  • story_scores 개수/범위
  • recommendation 허용값 또는 서버 재계산 대상 표시

C. Pydantic-only 검증 경로 추가

• _evaluate_comprehensive() 내부에서 기존 자유형 JSON 파싱 뒤 Pydantic model_validate()를 수행합니다.
• model validator에서 의미 검증을 수행합니다.
• 필요 시 검증 함수는 parse_raw_evaluation_result()와 finalize_evaluation_result()로 분리합니다.
• 권장 함수 분리:
  • _extract_raw_evaluation_dict(response: str) -> dict
  • _validate_evaluation_result(raw: dict) -> IRDeckEvaluationResult
  • _finalize_evaluation_result(validated: IRDeckEvaluationResult) -> dict
• 이유:
  • 재질의 정책과 validator 테스트를 각각 독립적으로 검증하기 위함입니다.

D. 서버 최종값 재계산

• grade는 total_score 기반으로 서버가 다시 계산합니다.
• recommendation도 서버 정책으로 다시 계산합니다.
• 필요 시 story_scores 기반 총점 재계산 또는 허용 오차 검증을 추가합니다.
• 권장 고정안:
  • 1차에서는 grade, recommendation만 서버 최종값으로 고정
  • total_score는 우선 validator 통과값을 사용하되, 후속 단계에서 재계산 여부 검토
• 이유:
  • 변경 범위를 줄이면서도 사용자에게 보이는 핵심 모순을 먼저 닫기 위함입니다.

E. 저장 경계 분리

• 저장은 raw_evaluation_result가 아니라 final_evaluation_result만 사용합니다.
• 검증 실패 시 저장하지 않거나, 실패 상태를 명시적으로 반환합니다.
• 권장 구현:
  • raw dict는 지역 변수로만 유지
  • repository에는 final_evaluation_result에서 꺼낸 값만 전달
  • 실패 시 ValueError 또는 명시적 커스텀 예외를 발생시켜 상위 경로에서 실패 처리

E-1. 라우터/워크플로 영향 범위 확인

• 확인 대상:
  • rb8001/app/services/workflows/ir_deck_workflow.py
  • rb8001/app/router/ir_deck.py
• 확인 항목:
  • _evaluate_comprehensive() 반환 구조가 바뀌어도 기존 evaluate_node, save_node, EvaluationResponse가 깨지지 않는지
  • 실패 시 비동기 평가 잡이 침묵 성공으로 끝나지 않는지
• 이유:
  • 이번 수정은 analyzer 내부가 중심이지만, 실제 저장/응답 경로는 workflow/router까지 이어지기 때문입니다.

F. 테스트 추가

• 최소 테스트:
  • 100점 + B등급 입력 차단
  • 잘못된 enum 차단
  • story_scores와 총점 불일치 차단 또는 보정
  • summary 최소 길이 미달 처리
• 권장 반영 위치:
  • rb8001/tests/test_ir_deck_json_parsing.py
    • validator 단위 테스트
    • raw dict -> model_validate 실패 테스트
    • 재질의 필요 판정 테스트
  • rb8001/tests/test_ir_deck_workflow.py
    • validator 통과 결과가 workflow save까지 정상 전달되는지
    • validator 실패 시 workflow가 실패를 드러내는지
• 가능하면 _evaluate_comprehensive() 파싱 경로와 validator를 분리해 단위 테스트를 우선 추가합니다.

6. 실패 정책

• 1차 원칙:
  • validator 실패 시 조용히 저장하지 않습니다.
• 기본안:
  • 기존 call_llm() 응답 검증 실패 시 직접 재질의 1회
  • 1회 재시도 후에도 실패하면 명시적 실패 처리
• 보조안:
  • grade, recommendation은 서버 재계산으로 보정 가능
  • 구조 자체가 깨진 경우는 실패 처리
• 권장 세부 순서:
  1. 첫 응답 JSON 추출
  2. Pydantic model_validate()
  3. 실패 시 같은 프롬프트로 1회 재호출
  4. 2차도 실패하면 저장하지 않고 실패 로그 남김
  5. 단, grade/recommendation 같은 서버 소유 필드는 validator 통과 후에도 서버가 다시 계산
• 이렇게 두는 이유:
  • 재질의는 최소 1회만 허용해 비용과 지연을 제한하고
  • 서버 소유 필드는 보정 가능하지만 구조 실패는 숨기지 않기 위함입니다.

7. 완료 판정 기준

1. IR Deck 종합 평가 경로가 Pydantic typed validation을 사용합니다.
2. total_score=100, grade=B 같은 모순 입력은 저장되지 않습니다.
3. 저장 전 final_evaluation_result 경계가 코드에 존재합니다.
4. grade, recommendation은 서버 정책을 거친 값만 저장됩니다.
5. 관련 테스트가 추가되고 통과합니다.

7-1. 검증 실행 기준

• 코드 수정 후 최소 검증:
  • pytest rb8001/tests/test_ir_deck_json_parsing.py
  • pytest rb8001/tests/test_ir_deck_workflow.py
• 가능하면 추가 검증:
  • 기존 IR Deck 관련 대표 테스트 1회
• 배포 후 확인 기준:
  • 실제 평가 1건에서 100점 + B등급 같은 모순 저장이 발생하지 않는지
  • 실패 케이스가 있으면 성공처럼 completed로만 남지 않는지 로그 확인
• 이유:
  • 이번 수정의 핵심은 parser/validator/workflow 경계이므로 이 세 축을 직접 검증해야 합니다.

8. 후속 경계

• 이번 계획이 닫혀도 브리핑, 콜드메일, 투자 의견 경로는 별도 확대 계획으로 다룹니다.
• 2차 단계에서 retry, output validator, 생성-검증 일체화를 더 강하게 원하면 Pydantic AI 확장 계획을 별도로 검토합니다.

9. 이번 계획의 한 줄 결론

• 지금은 LangGraph를 바꾸는 단계가 아니라, IR Deck 종합 평가에 Pydantic-only를 먼저 붙여 typed validation 계약을 실제 코드에 고정하는 단계입니다.