AI 에이전트 챗봇

1. Overview

게임 기획 문서, 밸런스 Excel, 게임 코드를 근거로 답변하는 사내 AI 챗봇 플랫폼입니다.

기존에는 필요한 수치·규칙을 찾으려면 문서를 직접 뒤지거나 담당자에게 물어야 했고, 일반 LLM 챗봇은 출처 없는 답변이라 기획 검토에 쓰기 어려웠습니다. 이를 해결하기 위해 업로드 문서를 벡터 인덱스로 구축하고, 검색 → 검증 → 재검색 → 합성으로 이어지는 RAG 파이프라인 위에 질문 의도에 따라 도구를 자동 선택하는 오케스트레이터를 설계했습니다.

백엔드 API, 에이전트 파이프라인, 프론트엔드 UI까지 전체 개발을 담당했습니다.

---

2. 주요 성과

• 문서를 뒤지거나 담당자에게 묻던 수치·규칙 확인을 챗봇 질의로 대체
• 모든 답변에 출처(파일·행·컬럼)와 검증 상태(verified / partially_verified / insufficient) 부여
• 문서 Q&A · 시뮬레이션 · 산출물 생성 등 9종 도구를 하나의 채팅 입력으로 자동 라우팅
• "이 스펙이면 몇 턴에 클리어 가능한가" 같은 밸런스 질문을 문서 근거 시뮬레이션으로 검증

---

3. System Architecture

전체 시스템은 3개 영역으로 구성되며, 비중은 AI 파이프라인에 있습니다.

1. Frontend (React + TypeScript + Vite)

채팅 UI, 문서 업로드(파일별 진행률), 에이전트 실행 타임라인, 근거 인용 패널, 검색 중단 버튼을 제공합니다. NDJSON 스트림을 파싱해 타임라인을 실시간 갱신하며, 항목이 많아질 때를 대비해 최대 항목 수 제한과 배치 append로 렌더링 부하를 관리합니다.

2. Backend (Express + TypeScript)

• Lambda 스타일 핸들러 패턴 — 모든 기능을 (HandlerEvent) => HandlerResponse 시그니처로 통일하고 Express 라우트가 HTTP를 어댑팅합니다. 기능 추가 시 라우팅·에러 처리 비용을 최소화한 구조입니다.
• NDJSON 스트리밍 — 오케스트레이터·시뮬레이션·CLI 응답을 이벤트 단위로 스트리밍합니다. 장시간 이미지 생성은 별도로 jobId 폴링 방식의 비동기 잡으로 처리합니다.
• 인터럽트 — requestId 기반 중단 API. 서버가 메모리 플래그를 세우면 각 도구가 폴링으로 감지해 안전하게 정리됩니다.
• 로컬 데이터 파이프라인 — 업로드 원본, LLM 친화 파생 텍스트, 메타데이터 카탈로그, 임베딩 인덱스(manifest + 행렬 + 행별 벡터)를 로컬 저장소에 계층적으로 관리합니다.

3. AI Pipeline — 아래 핵심 구현에서 상세 설명

---

4. 핵심 구현 내용

4.1. 문서 인덱싱 — 업로드에서 검색 가능한 근거까지

RAG 품질은 검색 시점이 아니라 인덱싱 시점에 절반이 결정된다고 판단해, 업로드 파이프라인에 공을 들였습니다.

파일 업로드(최대 150MB, Markdown·Excel·C#·이미지) 시 해시 기반 중복 검사 후, Excel·코드·이미지를 LLM 친화 마크다운으로 변환한 파생 텍스트를 생성합니다. 이어서 LLM이 문서를 분류하는 카탈로그 정규화 단계를 거칩니다 — 제목, 데이터 역할, 엔티티 유형, 시맨틱 태그, 신뢰도, 검수 필요 여부를 메타데이터로 저장합니다. 마지막으로 파생 텍스트를 행(row) 단위 청크로 분할해 RunPod 임베딩 API로 벡터를 생성하고 로컬 인덱스에 기록합니다.

이 메타데이터가 이후 검색 필터·스코어 보정·적합성 검증의 기반이 됩니다. LLM 분류가 틀리는 경우를 대비해 분류 결과를 사람이 검토·수정하는 카탈로그 검수 화면을 별도로 두어, 인덱싱 품질을 운영 단계에서 관리합니다.

4.2. Document Agent — 5단계 검색·검증 루프

벡터 검색 결과를 그대로 프롬프트에 붙이면 근거가 부족해도 그럴듯한 답변이 생성됩니다. 이를 막기 위해 검색과 답변 사이에 검증·재검색 루프를 넣은 5단계 실행 모델을 설계했습니다.

단계	처리 내용
1. Search Planning	질문 의도·유형·키워드·검색 우선순위 결정. 20종 이상의 질의 패턴(마스터표 조회, 관계 추적, 밸런스 신호 등)을 사전 분류
2. RAG Retrieval	하이브리드 검색 — 벡터(코사인 유사도 + 어휘 부스트), 키워드, 메타데이터 필터를 조합. 문서·테이블·코드·관계 조회 등 전용 검색 워커 분리
3. Context Compression	근거 병합·중복 제거·모델 입력용 압축
4. Context Validation	충분성·상충·공백·더미 데이터·문서 역할 불일치 검사
5. Tool Calling Loop	공백이 있으면 도구 재호출·보완 검색 후 최종 합성

무한 루프 방지를 위해 반복 3회, 도구 호출 5회, 근거 8건의 예산을 두었고, 마스터 목록형 질의만 상한을 확장합니다. 최종 답변은 자유 텍스트가 아닌 구조화 형태 — 본문, 근거 목록(파일·행·컬럼), 추론, 검증 상태, 후속 질문 — 로 강제하여, 근거가 부족하면 부족하다고 표시됩니다.

4.3. 에이전트 오케스트레이터 — 도구 라우팅

문서 Q&A, 밸런스·경제·TRPG 시뮬레이션, 아이디어 제안, PPT·Python 산출, 이미지 생성 등 9종 도구를 하나의 채팅 입력으로 자동 선택합니다.

라우팅은 3층 구조입니다. 먼저 각 도구 어댑터가 메시지 패턴·세션 상태·선택 파일에 대해 규칙 기반 점수를 산출하고, 도메인 휴리스틱("전투+시뮬 → TRPG", "아이디어 요청 → 문서 검색 강제 선행")으로 보정한 뒤, LLM 라우터가 최종 결정을 JSON으로 정제합니다. 질문이 모호하면 도구를 실행하지 않고 필수 입력·선택지를 되묻는 clarification 분기로 빠지고, 광범위한 밸런스 질의는 범위·기준을 먼저 요구해 의미 없는 시뮬레이션을 차단합니다.

복수 도구는 기본 병렬 실행하되, 선행 산출물이 필요한 조합(아이디어 제안 등)만 순차 실행합니다. Document Agent가 "판단 보류"로 답하면 밸런스·경제 시뮬레이션으로 자동 에스컬레이션되어, 문서 조회와 시뮬 검증이 한 세션에서 이어집니다.

4.4. 문서 근거 기반 시뮬레이션

"이 스펙이면 몇 턴에 클리어 가능한가" 같은 질문은 검색만으로 답할 수 없어, 문서에서 규칙·수치를 검색해 세그먼트 단위로 순환 실행하는 텍스트 시뮬레이션 엔진을 만들었습니다.

각 세그먼트는 검색 → 규칙 추론 → 행동 계획(Planner) → 정책 기반 선택(Resolver) → 상태 델타 적용(State Engine) → 검증 순으로 진행되며, 상태 엔진이 음수·구조 위반을 보정합니다. 추론 스테이지(grounding/planning/state)는 RunPod vLLM + 전용 LoRA로 실행하고, 비활성 시 Gemini API로 폴백합니다. 밸런스 리포트는 확정 사실과 가설을 분리 표기하고, 수치 계산은 LLM 대신 검증을 통과한 경우에만 Python 실행으로 처리해 과신을 줄였습니다.

---

5. 문제 해결 경험

5.1. 문제 1. 검색은 되지만 근거로 부적합한 문서

벡터 유사도만으로는 더미 데이터나 역할이 다른 시트가 근거로 섞였습니다. 인덱싱 시점의 카탈로그 정규화 메타데이터를 검색 필터에 활용하고, 답변 직전에 적합성 리뷰를 두어 lookup 의도인데 문서 역할이 불일치하거나 더미 데이터가 섞이면 자동 재검색하도록 했습니다.

5.2. 문제 2. 그럴듯하지만 검증할 수 없는 답변

구조화 답변(근거 목록 + 검증 상태)에 더해, 데이터 검증 전용 LLM 패스로 수치·관계를 교차 확인했습니다. "근거가 부족하다"를 명확히 표시하자 오히려 사용자 신뢰가 높아졌습니다.

5.3. 문제 3. 수십 초 걸리는 추론에 사용자가 이탈

검색·검증 루프는 수십 초 이상 걸려, 빈 화면이면 멈춘 것으로 오해했습니다. 모든 에이전트 단계를 NDJSON 이벤트(라우팅 결정, 검색 반복, 도구 실행, 검증 완료 등)로 정의해 타임라인으로 실시간 공개하고, 인터럽트 API로 언제든 중단할 수 있게 했습니다. 과정이 보이자 체감 품질 피드백이 눈에 띄게 달라졌습니다.

---

6. 사용 기술

영역	기술
Frontend	React 18, TypeScript, Vite
Backend	Node.js, Express, TypeScript, Lambda-style 핸들러
AI	OpenAI GPT, Anthropic Claude, Google Gemini, 비전 모델
RAG	로컬 벡터 인덱스(코사인 유사도), 하이브리드 검색, 행 단위 청크 임베딩
Infra	RunPod Serverless (임베딩 API, vLLM+LoRA 시뮬 스테이지, ComfyUI)
기타	NDJSON 스트리밍, 인터럽트 API, 마크다운 시스템 프롬프트 런타임 조합, 멀티 LLM 폴백

---

7. 결과 및 배운 점

챗봇의 품질은 모델 성능보다 모델을 둘러싼 구조 — 인덱싱 품질, 검색 전략, 근거 검증, 답변 구조화 — 에서 결정된다는 것을 경험했습니다.

특히 "답변하지 못한다"를 정확히 표시하는 것이 잘못된 답변보다 사용자 신뢰에 훨씬 중요했고, 긴 추론 과정을 가진 에이전트는 결과만큼 과정의 가시성(스트리밍 타임라인, 인터럽트)이 체감 품질을 좌우했습니다. 또한 RAG는 검색 알고리즘보다 인덱싱 시점의 메타데이터 설계와 운영 도구(카탈로그 검수)가 실무 품질을 만든다는 점을 배웠습니다.