AI 채팅 파이프라인 구조

Part I — The Big Picture

다섯 개의 관문

사용자가 채팅창에 메시지를 입력하고 전송 버튼을 누른다. 화면에는 텍스트가 한 글자씩 나타난다. 이 단순해 보이는 과정 뒤에서 인증, 저장, 검색, 선택, 생성, 정산을 포함한 다단계 처리가 순차 실행된다. 사용자가 "응답 중..."을 보는 몇 초 안에 전부 끝난다.

전체 흐름을 다섯 묶음으로 나눴다. 빨간 테두리가 쳐진 세 곳 — RAG 판단, 모델 선택, 멀티스텝 폴백 — 이 이 글의 핵심이다. 나머지는 패턴대로 하면 된다. 그 셋은 설계 판단이 필요하다.

Phase A Gate

인증/인가 → 요청 검증 → SSE 연결

Phase B Context

메시지 저장 → 이력 로드 → 프롬프트 → 페르소나

Phase C Intelligence

RAG 판단 → 모델 선택 → 도구 로드 → 시스템 조립

Phase D Stream

텍스트 생성 → 도구 실행 → 멀티스텝 폴백

Phase E Settle

비용 계산 → DB 저장 → 크레딧 차감

Part II — The Easy Parts

그냥 하면 되는 것들

대부분의 단계는 구현 패턴이 정해져 있다. 판단할 게 없다. 입력을 받고, 처리하고, 저장하고, 내보낸다. 그중 세 가지 핵심 메커니즘만 짚는다.

첫째, SSE(Server-Sent Events). 클라이언트와 서버 사이의 실시간 통신 채널이다. HTTP 응답을 열어두고, 서버가 이벤트를 밀어넣는다. 글자가 한 글자씩 나타나는 효과의 정체다.

status

파이프라인 상태

connecting → generating 등 10개 상태를 순서대로 전송

chunk

텍스트 조각

생성된 텍스트를 실시간 전송. 한 글자씩 나타나는 효과의 원리

reasoning

사고 과정

Extended Thinking 모드에서 AI의 추론 과정을 별도 전송

tool_call

도구 호출

AI가 도구를 호출할 때 이름과 인자를 전송

tool_result

도구 결과

실행 완료 후 결과 반환. 파일 생성 시 다운로드 이벤트 추가

done

완료

전체 파이프라인 종료 신호와 요약 정보 포함

둘째, 시스템 프롬프트 조립. AI에게 역할, 맥락, 도구, 규칙을 알려주는 텍스트다. 8개의 블록을 아래 순서대로 이어붙인다. 순서가 중요하다 — AI는 앞에 있는 지시를 더 강하게 따르는 경향이 있다.

기본 프롬프트 — 대화/워크스페이스/글로벌 설정에서 가져온 기본 지시문
페르소나 — 역할, 톤, 스타일 정의
메모리 — 사용자에 대해 기억하고 있는 것 (자동 추출 + 수동 메모)
RAG 컨텍스트 — 지식베이스에서 검색한 참조 문서
스킬 가이드 — 사용 가능한 스킬 목록과 사용법
언어 지시 — 응답 언어 설정 (한국어/영어/자동)
도구 가이드 — 사용 가능한 도구 17개의 호출 규칙 (~3,000자)
현재 시각 — Asia/Seoul 기준 날짜와 시간

셋째, 완료 핸들러. 응답 생성이 끝나면 비용 계산, 어시스턴트 메시지 DB 저장, 대화 타임스탬프 갱신, 사용량 기록, 크레딧 차감이 순차 실행된다. 이 중 크레딧 차감과 로그 기록은 비동기로 처리해서 응답 지연에 영향을 주지 않는다.

Part III — The Hard Three

여기서 멈춰라

구현은 어렵지 않다. 코드만 놓고 보면 조건문과 API 호출의 조합이다. 어려운 건 왜 이 분기인가, 실패하면 어떻게 되는가, 비용은 얼마나 드는가를 결정하는 일이다.

첫 번째 결정: 어떤 모델을 쓸 것인가. 모든 질문에 최고급 모델을 쓰면 품질은 좋지만 비용이 터진다. 저가형만 쓰면 복잡한 질문에서 엉뚱한 답이 나온다. 해답은 질문마다 다른 모델을 자동 배정하는 것이다.

Model Routing — Strategy to Model

manual

관리자가 지정한 특정 모델을 직접 사용. 지정 모델이 없으면 auto로 전환

cost_saving

fast 티어 모델 강제. 단순 질문이 대부분인 워크스페이스에 적합

high_quality

deep 티어 모델 강제. 분석/비교가 많은 업무에 적합

auto

Fast 모델이 질문을 분류 → 유형에 따라 fast 또는 deep 자동 배정. 분류 실패 시 규칙 기반 폴백

auto 전략의 핵심은 태스크 분류기다. 저비용 Fast 모델로 "이 질문은 단순한가, 복잡한가"를 먼저 판단한다. 3초 타임아웃을 걸어두고, 실패하면 메시지 길이와 키워드로 대체 판단한다. 분류기 자체의 비용은 무시할 수준이지만, 분류가 틀리면 비용이나 품질에 직접 영향을 준다.

두 번째 결정: 지식베이스를 검색할 것인가. RAG는 AI가 모르는 내부 문서를 검색해서 답변에 포함시키는 기술이다. 모든 질문에 검색을 걸면 느리고 비싸고, 안 하면 있는 정보도 활용을 못 한다. 3단계 라우터가 이 판단을 대신한다.

RAG Router — 3-Stage Decision

Stage 1

인프라 규칙. RAG 비활성이거나 임베딩 API 키가 없으면 즉시 skip. 판단할 것도 없다

Stage 2

패턴 매칭. QA 모드면 무조건 execute. 30자 이하 인사말이면 skip. 첨부파일 작업이면 skip

Stage 3

LLM 판정. Fast 모델이 "지식베이스가 필요한가"를 판단. 3초 타임아웃, 실패 시 보수적으로 execute

Stage 1 → 2 → 3 순서로 통과하면서 빠르게 빠질 수 있는 질문은 일찍 빠지게 만든다. 대부분의 인사말과 단순 질문은 Stage 2에서 걸러진다. LLM까지 가는 질문은 소수다.

세 번째 결정: 도구를 쓴 뒤 응답이 비면 어떻게 할 것인가. AI가 도구를 호출하고 결과를 받았는데, 그걸 사용자에게 설명하는 텍스트를 생성하지 못하는 경우가 있다. AI SDK의 maxSteps 옵션이 이론상 자동 해결해야 하지만, 실제로는 작동하지 않는 경우가 발생한다. 수동 폴백 체인이 필요한 이유다.

조건

도구 호출 있음 + 텍스트 200자 미만

도구를 썼는데 사용자에게 보여줄 텍스트가 충분하지 않다

Step 2

새 streamText 호출

도구 결과를 컨텍스트에 포함시켜 재생성. 검색 도구는 차단, 파일 생성만 허용

Step 3

마지막 시도

Step 2에서도 200자 미만이고 파일 생성이 없으면 한 번 더 시도. Step 4는 없다

파일 생성 도구가 성공하면 폴백을 중단하고 완료 메시지를 자동 생성한다. 핵심은 "200자 미만"이라는 임계치와 "최대 3스텝"이라는 제한이다. 4스텝 이상의 복잡한 도구 체인은 이 시스템으로는 처리할 수 없다 — 현재 아키텍처의 알려진 한계다.

구현은 조건문이다.
설계는 그 조건의 임계치를 정하는 일이다.

Part IV — Extension Points

나머지 퍼즐 조각

파이프라인의 뼈대 위에 살을 붙이는 것은 도구와 메모리다. 파이프라인 자체를 수정하지 않으면서 AI가 할 수 있는 일의 범위를 넓힌다.

도구 시스템은 17개의 도구를 네 범주로 나눈다. AI가 "이 질문에는 웹 검색이 필요하다" 또는 "엑셀 파일을 만들어야 한다"고 판단하면 해당 도구를 호출한다. 도구 목록과 사용 규칙은 시스템 프롬프트에 포함된다.

File Creation

파일 생성

5개

PDF, Word, Excel, Markdown, Text. 생성된 파일은 다운로드 이벤트로 전달

Chat Output

채팅 출력

4개

테이블, 구조화 문서, 데이터 추출, 포맷 변환. 채팅 내에서 직접 렌더링

검색

4개

시맨틱 검색, 소스 목록/콘텐츠 조회, 외부 웹 검색

Utility

유틸리티

4개

수식 계산, 현재 시각, 템플릿 적용, 사용자 메모 관리

메모리 시스템은 AI가 사용자를 기억하게 만든다. 자동 추출, 수동 관리, 벡터 검색의 3계층 구조다.

자동 메모리

대화에서 자동 추출. 업무 맥락, 개인 맥락, 관심사, 최근 변경사항. 시스템 프롬프트에 자연스럽게 주입

명시적 메모

사용자가 도구를 통해 직접 추가/삭제/수정. 최대 30개. 명시적 선호와 지시사항 저장

대화 검색

과거 대화를 벡터로 검색하는 미래 확장 레이어. pgvector 인덱스 준비 완료, 파이프라인 미연결

마지막으로 설정 우선순위. 모든 설정은 3단계 체인을 따른다 — 워크스페이스 설정이 글로벌 설정을 이기고, 글로벌 설정이 하드코딩 기본값을 이긴다. 단, 모델 선택 전략이나 API 키 같은 핵심 설정은 글로벌 전용이다.