ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md

7.3 KiB
Raw Blame History

IR Deck 평가 백엔드 아키텍처 설계

날짜: 2025-11-28
작성자: Claude (AI)
관련 파일:

  • rb8001/app/router/ir_deck.py (예정)
  • rb8001/app/services/ir_deck_analyzer.py (예정)
  • rb8001/app/state/ir_valuation_repository.py (예정)
  • rb8001/app/pipelines/langgraph_document.py (기존 활용)

목적

IR Deck 평가 기능을 위한 rb8001 백엔드 구조 설계. 기존 RAG 스킬(skill-rag-file)을 활용하여 PDF 업로드, 텍스트 추출, 분석, 평가 결과 저장까지의 전체 파이프라인 구축.

아키텍처 설계

1. 라우트 구조 (router/)

파일: rb8001/app/router/ir_deck.py

엔드포인트:

  • POST /api/ir-deck/upload - PDF 파일 업로드 및 인덱싱
  • POST /api/ir-deck/chat - IR Deck에 대한 질문/답변
  • POST /api/ir-deck/evaluate - Sequoia Capital 기준 평가 실행
  • GET /api/ir-deck/evaluation/{evaluation_id} - 평가 결과 조회

책임:

  • HTTP 요청/응답 처리만
  • 요청 검증 (Pydantic schemas)
  • 서비스 계층 호출
  • DB 직접 접근 금지

참고: DOCS/book/300_architecture/311_FastAPI_구조_원칙.md 준수

2. 서비스 구조 (services/)

파일: rb8001/app/services/ir_deck_analyzer.py

주요 클래스/함수:

  • IRDeckAnalyzer.analyze() - 전체 평가 파이프라인 실행
  • IRDeckAnalyzer.evaluate_by_page() - 페이지별 평가
  • IRDeckAnalyzer.calculate_score() - 종합 점수 계산 (100점 만점)
  • IRDeckAnalyzer.assign_grade() - 등급 분류 (S/A/B/C)

기존 RAG 스킬 활용:

  • pipelines/langgraph_document.py의 PDF 업로드/텍스트 추출 로직 재사용
  • skill-rag-file 서비스 연동 (포트 8508)
    • /api/upload - PDF 업로드 및 인덱싱
    • /api/text/{document_id} - 전체 텍스트 조회
    • /api/search - RAG 검색 (페이지별 분석 시 활용)

Sequoia Capital 10가지 스토리 기준:

  1. 문제 정의 (Problem)
  2. 시장 기회 (Market Opportunity)
  3. 솔루션 (Solution)
  4. 제품/서비스 (Product/Service)
  5. 비즈니스 모델 (Business Model)
  6. 경쟁 우위 (Competitive Advantage)
  7. 팀 (Team)
  8. 트랙션 (Traction)
  9. 재무 (Financials)
  10. 비전 (Vision)

평가 로직:

  • 각 페이지를 10가지 스토리 기준으로 분석
  • 페이지별로 잘된 점(strengths)과 부족한 점(weaknesses) 추출
  • 페이지별 점수 계산 (0-100점)
  • 전체 점수 = 페이지별 점수의 가중 평균
  • 등급 분류: S(90-100), A(80-89), B(70-79), C(0-69)

LLM 모델: gemini-2.5-flash-lite (기본 모델)

3. DB 구조 (state/)

파일: rb8001/app/state/ir_valuation_repository.py

테이블 설계:

ir_deck_evaluations 테이블

CREATE TABLE ir_deck_evaluations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID NOT NULL,  -- skill-rag-file의 document_id
    total_score INTEGER NOT NULL,  -- 0-100
    grade VARCHAR(1) NOT NULL,  -- S, A, B, C
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

ir_deck_page_evaluations 테이블

CREATE TABLE ir_deck_page_evaluations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    evaluation_id UUID REFERENCES ir_deck_evaluations(id) ON DELETE CASCADE,
    page_number INTEGER NOT NULL,
    score INTEGER NOT NULL,  -- 0-100
    strengths TEXT[],  -- 잘된 점 배열
    weaknesses TEXT[],  -- 부족한 점 배열
    created_at TIMESTAMP DEFAULT NOW()
);

ir_deck_feedback 테이블 (베이지안 학습용)

CREATE TABLE ir_deck_feedback (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    evaluation_id UUID REFERENCES ir_deck_evaluations(id) ON DELETE CASCADE,
    user_grade VARCHAR(1) NOT NULL,  -- 사용자가 부여한 등급
    predicted_grade VARCHAR(1) NOT NULL,  -- 시스템이 예측한 등급
    feedback_text TEXT,  -- 사용자 피드백
    created_at TIMESTAMP DEFAULT NOW()
);

Repository 패턴:

  • IRValuationRepository.create_evaluation() - 평가 결과 저장
  • IRValuationRepository.get_evaluation() - 평가 결과 조회
  • IRValuationRepository.save_feedback() - 피드백 저장
  • IRValuationRepository.get_feedback_history() - 학습 데이터 조회

4. 기존 RAG 스킬 활용

skill-rag-file 서비스 (포트 8508):

  • 업로드: POST /api/upload - PDF 파일 업로드, 자동 OCR, 텍스트 추출, 임베딩/인덱싱
  • 텍스트 조회: GET /api/text/{document_id} - 전체 텍스트 및 메타데이터 조회
  • 검색: POST /api/search - RAG 검색 (페이지별 분석 시 활용)

기존 파이프라인 활용:

  • rb8001/app/pipelines/langgraph_document.py의 업로드/추출 로직 재사용
  • LangGraph를 통한 비동기 처리 (필요 시)

참고 문서:

  • 251021_admin_slack_doc_analysis_pipeline_langgraph.md - LangGraph 파이프라인 구조
  • 251022_admin_ir_deck_rag_mixing_and_ocr_quality.md - OCR 품질 개선 및 RAG 활용

구현 순서

  1. DB 스키마 생성: ir_deck_evaluations, ir_deck_page_evaluations, ir_deck_feedback 테이블 생성
  2. Repository 구현: state/ir_valuation_repository.py 작성
  3. 서비스 구현: services/ir_deck_analyzer.py 작성 (기존 langgraph_document.py 활용)
  4. 라우터 구현: router/ir_deck.py 작성
  5. 라우터 등록: main.py에 라우터 등록

베이지안 학습 계획

학습 데이터 수집:

  • 사용자가 평가 결과에 대해 등급 피드백 제공
  • ir_deck_feedback 테이블에 저장
  • 주기적으로 학습 데이터 추출

학습 모델:

  • 등급 분류를 위한 베이지안 분류기 구현 (향후)
  • 피드백 데이터가 충분히 쌓이면 학습 시작

전체 플로우

  1. 업로드: POST /rb8001/api/ir-deck/upload → document_id 반환
  2. 평가 시작: POST /rb8001/api/ir-deck/evaluate → 비동기 평가 시작, 즉시 evaluation_id + status 반환
  3. 평가 결과 조회: GET /rb8001/api/ir-deck/evaluation/{id} → DB 조회 (프론트는 폴링로 결과 확인)

참고: /rb8001는 Nginx 프록시 경로 (51123 → 51124:8001)

중요한 점

  • 비동기 평가 시작 + 결과 조회 분리: /evaluate는 평가를 비동기 작업으로 등록하고 evaluation_id만 즉시 반환, 실제 점수/등급은 /evaluation/{id}에서 조회 (프론트는 폴링)
    • rb8001/app/router/ir_deck.py:169-256
    • rb8001/app/services/ir_deck_analyzer.py:42-109
    • rb8001/app/state/ir_valuation_repository.py:104-169
    • frontend-ir-valuation/src/services/irDeckService.ts:12-81
  • 중복 방지: force_reevaluate=False 시 기존 평가 반환
  • 의존 서비스: skill-rag-file (포트 8508), 내장 LLM
  • DB 테이블: ir_deck_evaluations, ir_deck_page_evaluations, ir_deck_feedback

교훈

  • 기존 인프라 활용: skill-rag-file의 업로드/검색 기능 재사용으로 개발 시간 단축
  • 계층 분리: router → services → state 구조로 유지보수성 향상
  • 표준 준수: FastAPI 구조 원칙 준수로 일관성 유지
  • 확장성: 베이지안 학습을 위한 피드백 데이터 구조 미리 설계

관련 문서