AI 시스템 아키텍처
Mind-Log v5.0 | 최종 업데이트: 2026-04-17 14:00
1. 전체 시스템 구조
Frontend (app-4:3000)
↓
Backend 서버 (app-3:8080) ←→ AI 서버 (app-2:8000)
↓ ↓
MySQL LangGraph 파이프라인
(TIER 0~4 + 비동기)
- 프론트엔드는 Backend 서버에만 접속. AI 서버와 직접 통신하지 않음.
- AI 서버와 양방향 통신하는 것은 오직 Backend 서버.
- Save/Load API는 AI → Backend 내부 통신 (
BackendClient경유).
2. TIER 기반 파이프라인 v5.0
사용자 입력
↓
TIER 0: Intent Classifier (Haiku)
│ 의도 분류 + 1차 위기 감지 + complexity_score 산출 + execution_plan 생성
↓
TIER 1 — 병렬 Fan-out (asyncio):
├─ Safety Agent (Sonnet 3.7 APAC CRIS) ← CRISIS 선점
├─ Emotion Agent (Haiku)
├─ Content Analyzer (Haiku)
└─ Podcast Reasoning (Sonnet 3.7 APAC CRIS)
├─ Episode Memory ← complexity ≥ 0.6 시 DI 호출 (KT Cloud + Pinecone)
└─ Knowledge Agent ← complexity ≥ 0.5 시 DI 호출 (Pinecone rag-suite-knowledge)
↓ Fan-in
TIER 2 — 병렬:
├─ Script Generator (Haiku) — 세그먼트 배치 생성
└─ Visualization (Haiku + AWS Bedrock Titan Image v2 + S3)
↓
TIER 3: Batch Validator (Haiku)
│ FAIL 시 → TIER 2 재시도 (max_retries=1)
↓
TIER 4: Script Personalizer (Sonnet 3.7 APAC CRIS)
│ rule-based + optional LLM deep / memory_write 트리거
↓
팟캐스트 에피소드 출력 (final_output)
↓
비동기 후처리 (async_post_processing):
├─ Learning Agent (Sonnet 3.5 APAC CRIS)
└─ Episode Memory 저장 (memory_write=True 시)
3. Safety CRISIS 선점 메커니즘 (PR #159 정상화)
Safety가 safety_flags.status="crisis" 판정 시, cancel_event는 발행되지 않습니다. TIER 1의 Emotion / Content Analyzer / Podcast Reasoning은 정상 완료됩니다. 후속 TIER(2~4)는 safety_flags.status 값을 감지해 LLM을 호출하지 않고 하드코딩된 위기 응답 폴백을 반환합니다. cancel_event.set()은 TIER 1 타임아웃 시에만 호출됩니다 (src/graph/workflow.py:378).
safe → TIER 1~4 정상 완료
warning → TIER 1~4 정상 완료 → Script Personalizer에서 required_in_script 문구 삽입
crisis → TIER 1 정상 완료 (cancel_event 미발행)
→ TIER 2 (Script Generator / Visualization): crisis 감지 → LLM 미호출, 하드코딩 폴백
→ TIER 3 (Batch Validator): crisis 감지 → 검증 스킵, 폴백 전달
→ TIER 4 (Script Personalizer): crisis 감지 → 위기 응답 고정 문구로 final_output 반환
timeout → TIER 1 타임아웃 시에만 cancel_event.set() (workflow.py:378)
관련 단위 테스트 +18건: TIER 2/3/4 crisis 폴백 동작을 검증 (549 → 612).
4. 에이전트 상세
| 에이전트 | TIER | 모델 | 핵심 기능 |
|---|---|---|---|
| Intent Classifier | 0 | Haiku | rule-based + LLM 분류, complexity_score, execution_plan, Redis 캐시(선택) |
| Safety Agent | 1 | Sonnet 3.7 | L0~L4 판정, required_in_script 주입, CRISIS 선점 |
| Emotion Agent | 1 | Haiku | valence(-1 |
| Content Analyzer | 1 | Haiku | depth(light/moderate/deep), target_duration 3~5분, narrative_structure 4종 |
| Podcast Reasoning | 1 | Sonnet 3.7 | GoT→ToT→CoT (full_threshold=0.0, 항상 Full 추론), Neo4j+RDB 저장 |
| Episode Memory | 독립 | Sonnet 3.5 | KT Cloud 임베딩 + Pinecone(rag-suite-knowledge, PR #153), per-user namespace |
| Knowledge Agent | 독립 | Sonnet 3.5 | Expert RAG 5단계, Pinecone(rag-suite-knowledge, PR #153) |
| Script Generator | 2 | Haiku | 세그먼트 배치 생성, 150 WPM, prev context 150자 |
| Visualization | 2 | Haiku+Titan | AWS Bedrock Titan Image v2(us-east-1), S3(mindlog-images/vis/), SKIP_VISUALIZATION 환경변수 |
| Batch Validator | 3 | Haiku | PASS/FAIL/CRITICAL_FAIL, max_retries=1, forced_pass |
| Script Personalizer | 4 | Sonnet 3.7 | FORMALITY/STYLE/ATTITUDE rule-based, deep_personalization=false |
| Learning Agent | 비동기 | Sonnet 3.5 | BackendClient.save(RESOURCE_LEARNING), tier=None |
5. AgentState (공유 상태 스키마)
src/models/agent_state.py — Protected File (3인 합의 필수)
class AgentState(TypedDict, total=False):
# 입력 (Intent Classifier 설정)
user_input: str
user_id: str
session_id: str
mode: Literal["podcast"] # 팟캐스트 모드 전용
# 분석
intent: dict # Intent Classifier
emotion_vectors: dict # Emotion Agent
content_analysis: dict # Content Analyzer
# 추론/생성
memory_results: dict # Episode Memory
knowledge_results: dict # Knowledge Agent
reasoning_result: dict # Podcast Reasoning
script_draft: dict # Script Generator
# 검증/부가
risk_level: int # Safety (0-4)
risk_score: float # Safety (0.0-1.0)
safety_flags: dict # Safety
validation_result: dict # Batch Validator
final_output: str # Script Personalizer
visual_data: dict # Visualization
# 메모리 저장 트리거 (Script Personalizer → async_post)
memory_write: bool
memory_text: str
memory_metadata: dict
# 제어
next_step: str
execution_plan: dict
iteration_count: int # 피드백 루프 (최대 2회)
6. LLM 프로바이더 & 모델
프로바이더: AWS Bedrock (기본). Prompt caching 활성화.
| 역할 | Model ID |
|---|---|
| Haiku | claude-haiku-4-5-20251001 (in-region Bedrock) |
| Sonnet 3.7 | apac.anthropic.claude-3-7-sonnet-* (APAC CRIS) |
| Sonnet 3.5 | apac.anthropic.claude-3-5-sonnet-* (APAC CRIS) |
| Titan Image | amazon.titan-image-generator-v2:0 (us-east-1) |
7. 주요 인프라
| 인프라 | 용도 |
|---|---|
| AWS Bedrock | LLM 호출 (기본 프로바이더) |
AWS S3 mindlog-images/vis/ | Visualization 이미지 |
Pinecone rag-suite-knowledge | Knowledge Agent RAG + Episode Memory (PR #153 단일 통합 인덱스, per-user namespace) |
| KT Cloud | Episode Memory 임베딩 엔드포인트 |
| Neo4j | GoT 감정 그래프 + 누적 그래프 |
| MySQL | RDB 저장 (BackendClient 경유) |
| LangSmith | LLM tracing (project="mind-log", tracing_enabled=true) |
| Redis | Intent Classifier 캐시 (선택적) |
8. 공용 인프라 파일
src/agents/shared/ — 인터페이스 변경 금지
| 파일 | 역할 |
|---|---|
base_agent.py | ABC, A/B 테스트(ContextVar), LangSmith tracing, create_message(), call_llm/json/image_gen() |
llm_client.py | AWS Bedrock 멀티 프로바이더 |
prompt_loader.py | YAML 멀티버전 프롬프트 |
input_sanitizer.py | 프롬프트 인젝션 방어 |
output_sanitizer.py | PII 마스킹 |
9. TIER 타임아웃 & Circuit Breaker
| TIER | 타임아웃 |
|---|---|
| TIER 0 | 20s |
| TIER 1 | 60s |
| TIER 2 | 280s |
| TIER 3 | 100s |
| TIER 4 | 20s |
| async | 60s |
Circuit Breaker: fail_max=5, reset_timeout=30s (settings.yaml)
10. 브랜치 전략
main ← PR 머지 (3명 전원 승인 필수)
└─ develop ← 통합 테스트 (최소 1명 리뷰)
├─ feature/analysis-* (개발자1: Intent Classifier, Knowledge, Script Generator, Script Personalizer)
├─ feature/reasoning-* (개발자2: Safety, Emotion, Visualization, Episode Memory)
└─ feature/validation-* (개발자3: Podcast Reasoning, Content Analyzer, Batch Validator, Learning)
Protected Files (3인 합의 필수): agent_state.py, message.py, contracts.py, workflow.py
11. KT Cloud RAG Suite (Knowledge RAG)
Knowledge Agent RAG 파이프라인이 KT Cloud RAG Suite로 통합되었습니다 (PR #145~#158).
| 컴포넌트 | 용도 |
|---|---|
| Embedding (query) | 사용자 쿼리 임베딩 — Knowledge search() 단계 |
| Embedding (passage) | 지식 문서 인제스트 임베딩 — scripts/ingest_knowledge.py |
| TextGen (Qwen3-32B) | Knowledge Agent 응답 생성 |
| Parser | 인제스트 단계 문서 파싱 전용 (Knowledge search()에서는 PR #158로 제거) |
| Pinecone 인덱스 | rag-suite-knowledge (PR #153에서 단일 인덱스명으로 통일) |
| 유사도 임계값 | 0.25 (PR #155, KT Cloud Query↔Passage 실측 score 0.20~0.35 반영) |
| Backend 엔드포인트 | /api/internal/knowledge 분리 (PR #156, #157) |
12. 프롬프트 버전 핀닝 (settings.yaml)
| 에이전트 | 프롬프트 버전 |
|---|---|
| Content Analyzer | v2.2.0 |
| Podcast Reasoning | v3.2.0 |
| Batch Validator | v2.3.0 |
| Visualization | v1.19.0 |
13. 구현 현황
- 에이전트: 12/12 구현 완료
- 테스트: 612 passed (549 → 612, PR #159 CRISIS 폴백 +18건)
- 보안 감사: 2026-03-24 완료 (키 로테이션, PII 정제, 프롬프트 인젝션 방어)
- Neo4j 통합: GoT→Neo4j + RDB 누적 그래프 (PR #50, #51, #53, #69)
- Pinecone 인프라: CLI 스크립트 3종 + 테스트 59개 (PR #64~#68)
최근 PR 마일스톤 (PR #142~#164)
| PR | 내용 |
|---|---|
| #142 | 구조적 취약점 16건 수정 (CI/CD Job 의존성, SHA 태깅, 롤백 스크립트, 한국어 인젝션 패턴 등) |
| #143 | deploy.yml SSM 배포 신뢰성 강화 (싱글쿼트 파싱, 15초×40회 폴링, unhealthy 즉시 실패) |
| #145~#151 | Knowledge RAG 1차 구현 (KT Cloud RAG Suite 연동, Pinecone 임계값 외부화, phase별 주입, env 회귀 수정) |
| #152 | 호스트 페르소나 8종 연동 (Script Personalizer) |
| #153 | Pinecone 인덱스명 단일화: rag-suite-knowledge |
| #155 | Knowledge Pinecone 유사도 임계값 0.7 → 0.25 |
| #156, #157 | Knowledge Backend API URL 분리 (/api/internal/knowledge) |
| #158 | Knowledge search() Parser 단계 제거 (텍스트 쿼리에 불필요) |
| #159 | CRISIS 파이프라인 출력 정상화 — TIER 1 cancel_event 제거, TIER 2~4 LLM 폴백 하드코딩, +18 테스트 |
| #160~#164 | 최신 PR (최신 develop 머지 내역) |
향후 계획
- cancel_event 기반 CRISIS 선점 메커니즘 구현: 현재 CRISIS 판정 시 TIER 2
4가 하드코딩 폴백으로 처리됨. 향후 cancel_event를 TIER 1에서 발행하여 TIER 24 병렬 태스크를 실제로 취소(cancel)하는 선점 방식으로 전환 검토. - 메시지 프로토콜 v2.0 활성화: 현재 독립 에이전트 호출이 DI 패턴(직접 메서드 호출)으로 구현되어 MessageEnvelope 미사용 상태. 백엔드 통신 확장 시 활성화 검토.
- 세션 리소스 Backend API 연동: sessions 리소스 (
TODO(backend)— 백엔드 팀 협의 필요). - Knowledge Agent Pinecone 관측성 강화: top_k 외부화 완료, Pinecone latency 트래킹 추가 예정 (KA-1).
- Podcast Reasoning Pinecone 연동: PR-1 이슈, Pinecone 연동 완료 후 처리 예정.
변경 이력
| 날짜 | 버전 | 변경 내용 | PR |
|---|---|---|---|
| 2026-04-17 14:00 | v5.0 | 상단 callout 박스 제거, CRISIS cancel_event 동작 명확화, KT Cloud RAG Suite 상세 기재, 향후 계획 섹션 추가, 변경 이력 테이블 추가 | - |
| 2026-04-17 11:35 | v5.0 | PR #159 CRISIS 파이프라인 정상화 반영, 테스트 612 passed 업데이트 | #159 |
| 2026-04-14 | v5.0 | 프롬프트 버전 핀닝 동기화 (CA v2.2.0 / PR v3.2.0 / BV v2.3.0 / VI v1.19.0) | #153~#158 |
| 2026-04-13 | v5.0 | Knowledge RAG KT Cloud RAG Suite 연동 완성 | #145~#151 |
| 2026-04-10 | v5.0 | 구조적 취약점 16건 수정, deploy.yml SSM 신뢰성 강화 | #142, #143 |