[온프레미스 AI Assistant 아키텍처 — Qwen3·Qwen3-VL 14일 설계] 14/14화: AI Assistant 레퍼런스 아키텍처 7계층 종합 설계 2026
온프레미스 AI Assistant 아키텍처 시리즈 — 14일차, 종합 설계
이 글은 「온프레미스 AI Assistant 아키텍처 — Qwen3·Qwen3-VL 14일 설계」 시리즈 14일차(최종회)입니다. 13일차에서 가드레일·평가 아키텍처로 시스템의 안전 계층을 완성했습니다. 오늘은 13일간 쌓아 올린 모든 계층을 하나의 AI Assistant 레퍼런스 아키텍처로 통합하고, 단일 노드에서 클러스터로의 확장 경로, 운영 현실, 그리고 챗봇에서 자율 에이전트로의 진화 전략까지 정리합니다.
14일 동안 모델 선정(1화)부터 하드웨어(3화), 서빙(4~7화), 컨텍스트·RAG·메모리(8~11화), 에이전트·안전(12~13화)까지 — 각 계층을 독립적으로 깊이 파고들었습니다. 이제 이 모든 조각이 하나의 시스템으로 작동하는 전체 그림을 그릴 차례입니다.
오늘의 핵심 3가지
- 7계층 레퍼런스 아키텍처 — 클라이언트·게이트웨이·컨텍스트·지식·메모리·에이전트·안전 계층을 단일 다이어그램으로 통합하고 계층 간 데이터 흐름을 정의합니다.
- 단일 노드 → 클러스터 확장 로드맵 — Mac Studio 1대 + CUDA 1대의 최소 구성에서, 로드 밸런서·모델 샤딩·RAG 클러스터로 확장하는 3단계 경로를 설계합니다.
- 챗봇 → 에이전트 진화 체크리스트 — 단순 Q&A에서 멀티스텝 툴 호출·자율 실행까지, Qwen3의 function calling과 MCP를 활용한 성숙도 모델을 제시합니다.
AI Assistant 레퍼런스 아키텍처 — 7계층 통합 설계
13일간의 설계를 하나로 엮으면, 온프레미스 AI Assistant는 7개의 논리 계층(layer)으로 구성됩니다. 각 계층은 독립 배포·교체가 가능하며, 계층 간 인터페이스는 OpenAI 호환 API와 gRPC로 표준화됩니다.
7계층 아키텍처 다이어그램
graph TB
subgraph L1["Layer 1: 클라이언트"]
WEB["웹 UI
(Next.js / Open WebUI)"]
API_CLIENT["API 클라이언트
(내부 시스템)"]
MOBILE["모바일 앱"]
MCP_CLIENT["MCP 클라이언트
(IDE 플러그인)"]
end
subgraph L2["Layer 2: 게이트웨이"]
GW["LLM 게이트웨이
(LiteLLM / Custom)"]
AUTH["인증·인가
(JWT / API Key)"]
RATE["레이트 리밋
(토큰 버짓)"]
ROUTER["모델 라우터
(복잡도 분류)"]
end
subgraph L3["Layer 3: 컨텍스트 조립"]
PROMPT["프롬프트 템플릿
(Jinja2 + 버전관리)"]
CTX["컨텍스트 파이프라인
(시스템·RAG·메모리·도구 조립)"]
COMPRESS["컨텍스트 압축
(요약 / 토큰 예산)"]
end
subgraph L4["Layer 4: 지식 계층"]
EMB["임베딩 서버
(bge-m3)"]
QDRANT["벡터 DB
(Qdrant)"]
GRAPH["그래프 DB
(Neo4j)"]
RERANK["리랭커
(bge-reranker-v2-m3)"]
CHUNK["청크 파이프라인
(문서·이미지)"]
end
subgraph L5["Layer 5: 메모리 계층"]
SHORT["단기 메모리
(세션 요약 버퍼)"]
LONG["장기 메모리
(PostgreSQL)"]
PROFILE["사용자 프로파일
(선호·컨텍스트)"]
end
subgraph L6["Layer 6: 에이전트·도구"]
ORCH["오케스트레이터
(ReAct / Plan-Execute)"]
TOOLS["도구 레지스트리
(MCP 서버)"]
VIS_AGENT["Visual Agent
(Qwen3-VL)"]
SANDBOX["샌드박스
(코드 실행)"]
end
subgraph L7["Layer 7: 안전·관측"]
GUARD_IN["입력 가드레일"]
GUARD_OUT["출력 가드레일"]
PII["PII 마스킹"]
AUDIT["감사 로그"]
EVAL["평가 파이프라인"]
MONITOR["메트릭·알림
(Prometheus + Grafana)"]
end
subgraph INFRA["추론 인프라"]
MLX["Mac Studio
mlx-lm
(Qwen3-8B/14B)"]
VLLM["CUDA 서버
vLLM
(Qwen3-30B-A3B)"]
VLLM_VL["CUDA 서버
vLLM
(Qwen3-VL-8B)"]
end
L1 --> L2
L2 --> L7
L7 --> L3
L3 --> L4
L3 --> L5
L3 --> L6
L6 --> L3
L3 --> INFRA
INFRA --> L7
L7 --> L2
L2 --> L1
계층 간 데이터 흐름 — 요청 한 건의 여정
사용자가 “지난달 매출 보고서에서 전년 대비 성장률을 차트로 보여줘”라고 요청하면, 시스템 내부에서는 다음 흐름이 발생합니다.
# 요청 흐름 시퀀스 (14일 시리즈 전 계층 통합)
request_flow:
1_gateway:
- 인증 검증 (JWT / API Key)
- 레이트 리밋 확인 (사용자별 토큰 버짓)
- 입력 가드레일 통과 (L7 → 유해 콘텐츠·프롬프트 인젝션 차단)
- 복잡도 분류 → 모델 라우팅 결정
simple_query: "Qwen3-8B (Mac Studio)"
complex_reasoning: "Qwen3-30B-A3B (vLLM)"
visual_task: "Qwen3-VL-8B (vLLM)"
2_context_assembly:
- 사용자 프로파일 로드 (L5: 장기 메모리)
- 세션 히스토리 인출 (L5: 단기 메모리, 최근 요약)
- RAG 검색 트리거:
query_rewrite: "Qwen3-8B로 검색 쿼리 재작성"
vector_search: "bge-m3 임베딩 → Qdrant 하이브리드 검색"
graph_search: "Neo4j 엔터티 관계 탐색 (매출→부서→기간)"
rerank: "bge-reranker-v2-m3로 상위 5개 선별"
- 도구 호출 판단: "차트 생성 필요 → 에이전트 오케스트레이터 위임"
3_agent_orchestration:
- Plan-Execute 패턴 활성화
- Step 1: DB 조회 도구 호출 (MCP → 사내 데이터 API)
- Step 2: 계산 도구 호출 (전년 대비 성장률 산출)
- Step 3: 차트 생성 도구 호출 (matplotlib 코드 → 샌드박스 실행)
- 각 Step 결과를 컨텍스트에 누적
4_inference:
- 조립된 컨텍스트 → Qwen3-30B-A3B (vLLM) 추론
- Thinking 모드: reasoning 토큰으로 분석 과정 생성
- 스트리밍 응답 시작
5_safety_and_response:
- 출력 가드레일 통과 (환각 검증, PII 마스킹)
- 감사 로그 기록 (입력·출력·도구 호출·지연시간)
- 메트릭 수집 (TTFT, 토큰/초, GPU 사용률)
- 응답 스트리밍 → 클라이언트
이 흐름에서 핵심은 컨텍스트 조립 계층(L3)이 허브 역할을 한다는 점입니다. 지식(L4), 메모리(L5), 에이전트(L6) 모두 L3을 통해 추론 엔진에 주입되고, 에이전트의 도구 호출 결과도 L3으로 되돌아와 다음 추론 턴의 컨텍스트가 됩니다.
계층별 핵심 설계 결정 — 13일의 압축
각 계층에서 내린 핵심 설계 결정을 한 장의 표로 정리합니다. 상세 구현은 해당 회차를 참조하세요.
| 계층 | 핵심 결정 | 선택 | 근거 | 회차 |
|---|---|---|---|---|
| 모델 | 기준 모델 | Qwen3 (Dense+MoE) + Qwen3-VL | Apache 2.0, 한국어, 사이즈 스펙트럼 | 1~2화 |
| 하드웨어 | 이종 클러스터 | Mac Studio (MLX) + CUDA (vLLM) | 저지연 경량 + 고처리량 대형 분리 | 3화 |
| 서빙 (Apple) | 런타임 | mlx-lm + OpenAI 호환 서버 | 통합 메모리 활용, 저전력 | 4화 |
| 서빙 (CUDA) | 런타임 | vLLM + FP8 + 텐서 병렬 | PagedAttention, 동시 배치 | 5화 |
| 게이트웨이 | 라우팅 | LiteLLM + 복잡도 분류기 | 단일 엔드포인트, 폴백 체인 | 6화 |
| 멀티모달 | VLM 서빙 | Qwen3-VL-8B (vLLM) | 문서·차트·UI 이해 | 7화 |
| 프롬프트 | 컨텍스트 관리 | 계층형 시스템 프롬프트 + 토큰 예산 | 32K 윈도우 최적 활용 | 8화 |
| RAG | 검색 스택 | bge-m3 + Qdrant + RRF 하이브리드 | 외부 의존 제로, 자체 호스팅 | 9화 |
| 고급 RAG | 지식 그래프 | Graph RAG + 멀티모달 RAG | 멀티홉 추론, 이미지 검색 | 10화 |
| 메모리 | 영속 저장 | PostgreSQL + 요약 버퍼 | 세션 복원, 사용자 프로파일 | 11화 |
| 에이전트 | 오케스트레이션 | ReAct + MCP + 권한 샌드박스 | 도구 안전성, 사내 시스템 연동 | 12화 |
| 안전 | 가드레일 | 입출력 이중 필터 + PII 마스킹 | 규제 대응, 환각 억제 | 13화 |
구축 성숙도 모델 — 4단계 진화 경로
모든 계층을 한 번에 구축하는 것은 비현실적입니다. 아래 성숙도 모델에 따라 단계적으로 진화시키는 것을 권장합니다.
Stage 0: 기초 서빙 (1~2주)
목표: Qwen3 모델이 API로 응답하는 최소 동작 확인.
- Mac Studio에 mlx-lm으로 Qwen3-8B 서빙 (4화 구성)
- 또는 CUDA 서버에 vLLM으로 Qwen3-30B-A3B 서빙 (5화 구성)
- OpenAI 호환 엔드포인트 확인
- Open WebUI 연결하여 대화 테스트
# Stage 0: Mac Studio에서 Qwen3-8B 즉시 서빙
pip install mlx-lm
mlx_lm.server \
--model mlx-community/Qwen3-8B-4bit \
--host 0.0.0.0 \
--port 8080
# 동작 확인
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mlx-community/Qwen3-8B-4bit",
"messages": [{"role": "user", "content": "안녕하세요"}],
"max_tokens": 256
}'
Stage 1: 게이트웨이 + RAG (3~4주)
목표: 복수 모델 라우팅과 문서 기반 응답.
- LiteLLM 게이트웨이로 MLX + vLLM 통합 (6화)
- bge-m3 임베딩 + Qdrant 벡터 DB 구축 (9화)
- 기본 RAG 파이프라인 연결 (검색 → 컨텍스트 주입 → 생성)
- 프롬프트 템플릿 버전 관리 시작 (8화)
Stage 2: 메모리 + 에이전트 (5~8주)
목표: 대화 연속성과 도구 사용.
- 세션 메모리 + 장기 메모리 구현 (11화)
- Qwen3 function calling + MCP 서버 연동 (12화)
- ReAct 오케스트레이터로 멀티스텝 작업 처리
- Qwen3-VL 멀티모달 파이프라인 추가 (7화)
Stage 3: 안전 + 관측 + 확장 (9~12주)
목표: 프로덕션 수준의 안정성과 규제 대응.
- 입출력 가드레일 + PII 마스킹 적용 (13화)
- Prometheus + Grafana 메트릭 대시보드
- 감사 로그 영속화 + 평가 파이프라인
- Graph RAG + 멀티모달 RAG 고도화 (10화)
- 노드 추가 시 수평 확장 계획 수립
단일 노드에서 클러스터로 — 3단계 확장 로드맵
온프레미스의 장점은 점진적 확장입니다. 클라우드처럼 즉시 스케일아웃은 불가능하지만, 물리 장비 추가로 예측 가능하게 성장시킬 수 있습니다.
Phase 1: 단일 노드 최적화 (사용자 1~10명)
# Phase 1: 단일 노드 구성
infrastructure:
node_1:
type: "Mac Studio M4 Ultra (192GB)"
models:
- name: "Qwen3-8B-4bit"
role: "라우팅·분류·경량 대화"
memory: "~6GB"
- name: "Qwen3-30B-A3B-4bit"
role: "메인 생성"
memory: "~22GB"
- name: "bge-m3"
role: "임베딩"
memory: "~2GB"
services:
- "mlx-lm 서버 (포트 8080, 8081)"
- "Qdrant (Docker, 포트 6333)"
- "PostgreSQL (메모리·세션, 포트 5432)"
- "LiteLLM 게이트웨이 (포트 4000)"
concurrency:
max_parallel_requests: 2 # MLX 동시성 한계
queue_overflow: "503 + 클라이언트 재시도"
limitations:
- "MLX 동시 배치 미지원 → 직렬 처리"
- "VLM 서빙 불가 (MLX Qwen3-VL 지원 제한적)"
- "10명 초과 시 응답 지연 급증"
Mac Studio 단일 노드의 핵심 한계는 동시성입니다. MLX는 vLLM의 continuous batching에 해당하는 기능이 없어, 동시 요청이 3개를 넘으면 큐 대기가 급격히 늘어납니다. M4 Ultra 192GB 기준 Qwen3-30B-A3B 4bit 모델의 추론 속도는 약 35~45 tok/s(단일 요청)이지만, 동시 요청 시 선형 분할됩니다.
Phase 2: 이종 2노드 (사용자 10~50명)
# Phase 2: Mac Studio + CUDA 서버 이종 클러스터
infrastructure:
node_mac:
type: "Mac Studio M4 Ultra (192GB)"
role: "경량 모델 + 임베딩"
models:
- "Qwen3-8B-4bit (라우팅·분류)"
- "bge-m3 (임베딩)"
services:
- "mlx-lm 서버"
- "LiteLLM 게이트웨이 (라우터)"
node_cuda:
type: "듀얼 RTX 5090 (32GB×2 = 64GB VRAM)"
role: "대형 모델 + VLM"
models:
- name: "Qwen3-30B-A3B-FP8"
role: "메인 생성"
vram: "~28GB (텐서 병렬 2-way)"
throughput: "~80 tok/s (단일), ~200 tok/s (배치 8)"
- name: "Qwen3-VL-8B"
role: "멀티모달"
vram: "~18GB"
services:
- "vLLM 서버 (포트 8000)"
- "vLLM VL 서버 (포트 8001)"
shared_services:
qdrant: "별도 서버 또는 NAS Docker"
postgresql: "NAS Docker (세션·메모리·감사 로그)"
routing_strategy:
simple: "Mac Studio → Qwen3-8B"
complex: "CUDA → Qwen3-30B-A3B"
visual: "CUDA → Qwen3-VL-8B"
fallback: "CUDA 다운 시 Mac Studio로 전체 폴백"
concurrency:
cuda_parallel: 16 # vLLM continuous batching
mac_parallel: 2
effective_total: "~18 동시 요청"
Phase 2에서 가장 큰 변화는 vLLM의 continuous batching이 주는 동시성입니다. 듀얼 RTX 5090에서 Qwen3-30B-A3B를 FP8 텐서 병렬로 서빙하면, 배치 크기 8 기준 약 200 tok/s의 처리량을 달성합니다(5화 벤치마크 참조). 이는 Mac Studio 단독 대비 약 4~5배의 동시 사용자 수용력입니다.
Phase 3: 멀티노드 클러스터 (사용자 50명 이상)
# Phase 3: 멀티노드 확장 아키텍처
infrastructure:
inference_pool:
- type: "CUDA 서버 ×2"
models: ["Qwen3-30B-A3B-FP8"]
load_balancer: "라운드 로빈 + 최소 큐 길이"
- type: "Mac Studio ×2"
models: ["Qwen3-8B-4bit"]
role: "라우팅·분류·임베딩·경량 대화"
- type: "CUDA 서버 (VLM 전용) ×1"
models: ["Qwen3-VL-8B"]
knowledge_cluster:
qdrant: "3노드 클러스터 (샤딩 + 복제)"
neo4j: "단일 인스턴스 (Graph RAG)"
embedding: "bge-m3 × 2 (부하 분산)"
shared_infra:
postgresql: "Primary + Standby (스트리밍 복제)"
redis: "세션 캐시 + 큐"
prometheus: "메트릭 수집"
grafana: "대시보드"
gateway:
type: "LiteLLM + nginx"
features:
- "가중 라운드 로빈 (GPU 성능 비례)"
- "헬스체크 기반 자동 제외"
- "토큰 버짓 레이트 리밋"
- "A/B 라우팅 (모델 버전 비교)"
estimated_capacity:
concurrent_users: "50~100"
throughput: "~500 tok/s (전체 클러스터)"
monthly_power: "~800W 평균 → 약 580 kWh"
비용·전력·발열 — 온프레미스 운영의 현실
클라우드 API 비용과의 손익분기점은 가장 자주 받는 질문입니다. 솔직한 숫자로 비교합니다.
하드웨어 초기 투자
| 구성 | 장비 | 예상 비용 (2026 기준) |
|---|---|---|
| Phase 1 | Mac Studio M4 Ultra 192GB | 약 700~900만원 |
| Phase 2 추가 | 듀얼 RTX 5090 워크스테이션 | 약 600~800만원 |
| Phase 2 인프라 | NAS (Qdrant·PG·Gateway) | 약 100~200만원 |
| Phase 2 합계 | 2노드 이종 클러스터 | 약 1,400~1,900만원 |
월간 운영비 vs 클라우드 API
| 항목 | 온프레미스 (Phase 2) | 클라우드 API (동일 처리량) |
|---|---|---|
| 전력비 | 약 5~8만원/월 (400W 평균, 한국 산업용 전력) | – |
| API 비용 | 0원 | 약 200~500만원/월 (일 10만 토큰 × 30일 기준) |
| 유지보수 인건비 | 엔지니어 공수 10~20% (겸직 기준) | 최소 |
| 네트워크 | 사내망 (추가 비용 없음) | 아웃바운드 트래픽 비용 가능 |
일 10만 토큰(약 50~100건의 복합 대화) 이상의 사용량이면, 보통 6~12개월 내에 하드웨어 투자가 회수됩니다. 다만 이는 순수 API 비용 비교이며, 운영 인건비·장애 대응 시간·모델 업데이트 비용은 온프레미스가 더 높습니다.
발열 관리 — 간과하기 쉬운 물리적 제약
온프레미스 운영에서 자주 간과되는 것이 열 관리입니다.
- Mac Studio: TDP 약 100~150W. 팬 소음은 낮지만, 밀폐된 서버실에서 24/7 구동 시 주변 온도가 30°C를 넘으면 쓰로틀링이 발생할 수 있습니다. 데스크 아래 또는 환기가 좋은 랙에 배치해야 합니다.
- 듀얼 RTX 5090: TDP 약 450W (GPU만). 시스템 전체로 650~800W. 일반 사무실 에어컨으로는 여름철 냉각이 부족할 수 있습니다. 전용 환기 또는 서버실 배치를 권장합니다.
- UPS: 추론 중 전원 차단은 모델 가중치 재로딩(Qwen3-30B-A3B 기준 약 2~5분)을 유발합니다. 1kVA 이상의 UPS로 안전 종료 시간을 확보하세요.
챗봇에서 에이전트로 — Qwen3 기반 진화 경로
온프레미스 AI Assistant의 진화는 “응답 생성”에서 “자율 작업 수행”으로의 전환입니다. Qwen3의 function calling과 Thinking 모드가 이 전환을 가능하게 합니다.
성숙도 레벨 정의
| 레벨 | 명칭 | 특징 | 필요 계층 | 예시 |
|---|---|---|---|---|
| L0 | Q&A 챗봇 | 단일 턴, 모델 지식만 사용 | L1+L2+INFRA | “Python sort 함수 사용법” |
| L1 | RAG 챗봇 | 외부 지식 기반 응답 | +L3+L4 | “사내 휴가 규정 알려줘” |
| L2 | 대화형 어시스턴트 | 멀티턴 + 메모리 + 맥락 유지 | +L5 | “지난번에 물어봤던 프로젝트 진행 상황 업데이트해줘” |
| L3 | 도구 사용 에이전트 | function calling으로 외부 시스템 조작 | +L6 | “JIRA에 버그 티켓 생성하고 담당자 배정해줘” |
| L4 | 자율 에이전트 | 멀티스텝 계획·실행·검증 루프 | +L7 (강화) | “매월 1일에 매출 보고서를 생성해서 팀 채널에 공유해” |
L3 → L4 전환의 핵심 과제
L3(도구 사용)에서 L4(자율 에이전트)로의 전환이 가장 어렵습니다. 핵심 과제 3가지:
- 계획의 신뢰성: Qwen3-30B-A3B의 Thinking 모드를 활용하면 plan 수립 정확도가 올라가지만, 5스텝 이상의 장기 계획에서는 여전히 누락·순서 오류가 발생합니다. 해결책: 각 스텝 완료 시 중간 검증 게이트를 둡니다.
- 오류 복구: 도구 호출 실패 시 자동 재시도·대안 경로 탐색이 필요합니다. ReAct 루프에 최대 재시도 횟수와 폴백 전략을 명시적으로 설정합니다 (12화 참조).
- 권한 경계: 자율 에이전트는 “읽기”를 넘어 “쓰기” 작업을 수행합니다. 12화에서 설계한 MCP 도구별 권한 매트릭스와 human-in-the-loop 승인이 반드시 필요합니다.
"""
L4 자율 에이전트 — Plan-Execute 루프 (Qwen3 + MCP)
12화 ReAct 오케스트레이터를 확장한 프로덕션 패턴
"""
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
class StepStatus(Enum):
PENDING = "pending"
RUNNING = "running"
SUCCESS = "success"
FAILED = "failed"
NEEDS_APPROVAL = "needs_approval"
@dataclass
class ExecutionStep:
description: str
tool_name: str
tool_args: dict[str, Any]
status: StepStatus = StepStatus.PENDING
result: Any = None
retry_count: int = 0
max_retries: int = 2
requires_approval: bool = False # 쓰기 작업은 True
@dataclass
class ExecutionPlan:
goal: str
steps: list[ExecutionStep] = field(default_factory=list)
current_step: int = 0
@property
def is_complete(self) -> bool:
return all(s.status == StepStatus.SUCCESS for s in self.steps)
@property
def has_failure(self) -> bool:
return any(
s.status == StepStatus.FAILED and s.retry_count >= s.max_retries
for s in self.steps
)
async def plan_and_execute(
goal: str,
llm_client: Any, # OpenAI 호환 클라이언트
tool_registry: Any, # MCP 도구 레지스트리
approval_callback: Any, # human-in-the-loop 승인 함수
max_plan_steps: int = 8,
max_replan_attempts: int = 2,
) -> dict[str, Any]:
"""
Qwen3-30B-A3B Thinking 모드로 계획을 수립하고,
MCP 도구를 순차 실행하며,
실패 시 재계획을 시도하는 자율 에이전트 루프.
"""
replan_count = 0
# Step 1: 계획 수립 (Thinking 모드)
plan = await _generate_plan(llm_client, goal, max_plan_steps)
while not plan.is_complete and replan_count < max_replan_attempts:
step = plan.steps[plan.current_step]
step.status = StepStatus.RUNNING
# Step 2: 쓰기 작업이면 승인 요청
if step.requires_approval:
step.status = StepStatus.NEEDS_APPROVAL
approved = await approval_callback(step)
if not approved:
step.status = StepStatus.FAILED
step.result = "사용자가 승인을 거부했습니다."
break
step.status = StepStatus.RUNNING
# Step 3: 도구 실행
try:
result = await tool_registry.execute(
step.tool_name, step.tool_args
)
step.result = result
step.status = StepStatus.SUCCESS
plan.current_step += 1
except Exception as e:
step.retry_count += 1
if step.retry_count >= step.max_retries:
step.status = StepStatus.FAILED
step.result = str(e)
# 재계획 시도
replan_count += 1
plan = await _replan(
llm_client, goal, plan, step, max_plan_steps
)
# else: 루프 반복으로 자동 재시도
# Step 4: 중간 검증 (매 스텝 후)
if step.status == StepStatus.SUCCESS:
verification = await _verify_step(
llm_client, goal, plan, step
)
if not verification["valid"]:
step.status = StepStatus.FAILED
step.result = verification["reason"]
replan_count += 1
plan = await _replan(
llm_client, goal, plan, step, max_plan_steps
)
# Step 5: 최종 결과 요약
summary = await _summarize_execution(llm_client, goal, plan)
return {
"goal": goal,
"success": plan.is_complete,
"steps_executed": plan.current_step,
"total_steps": len(plan.steps),
"summary": summary,
"plan": plan,
}
async def _generate_plan(
llm_client: Any, goal: str, max_steps: int
) -> ExecutionPlan:
"""Thinking 모드로 실행 계획 생성."""
response = await llm_client.chat.completions.create(
model="qwen3-30b-a3b",
messages=[
{
"role": "system",
"content": (
"당신은 작업 계획 수립 전문가입니다. "
"주어진 목표를 달성하기 위한 단계별 계획을 "
"JSON 형식으로 출력하세요. "
f"최대 {max_steps}단계 이내로 제한하세요."
),
},
{"role": "user", "content": f"목표: {goal}"},
],
extra_body={"chat_template_kwargs": {"enable_thinking": True}},
)
# JSON 파싱 → ExecutionPlan 변환 (생략)
return ExecutionPlan(goal=goal, steps=[])
async def _replan(
llm_client: Any,
goal: str,
current_plan: ExecutionPlan,
failed_step: ExecutionStep,
max_steps: int,
) -> ExecutionPlan:
"""실패한 스텝을 분석하고 대안 계획 생성."""
# 실패 컨텍스트를 포함하여 재계획 요청
return ExecutionPlan(goal=goal, steps=[])
async def _verify_step(
llm_client: Any,
goal: str,
plan: ExecutionPlan,
step: ExecutionStep,
) -> dict[str, Any]:
"""각 스텝 완료 후 목표 정합성 검증."""
return {"valid": True, "reason": ""}
async def _summarize_execution(
llm_client: Any, goal: str, plan: ExecutionPlan
) -> str:
"""실행 결과를 사용자에게 보고할 요약 생성."""
return ""
안티패턴 체크리스트 — 14일간의 교훈
13일간의 설계에서 반복적으로 등장한 안티패턴을 정리합니다. 온프레미스 AI Assistant 구축 시 이 체크리스트로 자가 진단하세요.
아키텍처 안티패턴
| # | 안티패턴 | 증상 | 해결 |
|---|---|---|---|
| A1 | 모놀리식 프롬프트 | 시스템 프롬프트에 모든 지시를 욱여넣어 토큰 40% 소모 | 계층형 프롬프트 + 조건부 로딩 (8화) |
| A2 | RAG 만능주의 | 모든 질문에 RAG를 적용하여 불필요한 지연 추가 | 라우터에서 RAG 필요 여부 사전 분류 (6화) |
| A3 | 메모리 무한 누적 | 장기 메모리에 모든 대화를 저장하여 검색 노이즈 증가 | 요약 + TTL + 중요도 필터 (11화) |
| A4 | 가드레일 없는 에이전트 | 도구 호출 무한 루프·의도하지 않은 데이터 변경 | 최대 루프 횟수 + 권한 매트릭스 + human-in-the-loop (12·13화) |
| A5 | 단일 모델 만능 의존 | 235B 모델 하나로 모든 작업 처리 → GPU 병목 | 복잡도별 모델 분리 + 라우팅 (2·6화) |
운영 안티패턴
| # | 안티패턴 | 증상 | 해결 |
|---|---|---|---|
| O1 | 메트릭 없는 운영 | 장애를 사용자 보고로만 인지, TTFT/처리량 추이 불명 | Prometheus + Grafana + 알림 (13화) |
| O2 | KV 캐시 무시 | vLLM에서 OOM 빈발, 동시성 급감 | gpu_memory_utilization 0.85 + KV 캐시 프리얼로케이션 (5화) |
| O3 | 양자화 과도 적용 | 2bit 양자화로 응답 품질 급락, 한국어 오류 빈발 | 4bit 이상 유지, 품질 벤치마크 필수 (2화) |
| O4 | 백업 미비 | Qdrant 인덱스 손상 시 재구축에 수 시간 소요 | 스냅샷 + 영속 볼륨 + 자동 백업 스크립트 (9화) |
| O5 | 모델 업데이트 무중단 미고려 | 새 모델 배포 시 다운타임 발생 | 블루-그린 배포 또는 A/B 라우팅 (6화) |
보안 안티패턴 (금융IT 관점)
| # | 안티패턴 | 증상 | 해결 |
|---|---|---|---|
| S1 | 프롬프트 로그 평문 저장 | 감사 시 민감 정보 노출 | PII 마스킹 후 로깅, 암호화 스토리지 (13화) |
| S2 | 모델 응답 무검증 출력 | 환각 데이터가 의사결정에 사용됨 | 출력 가드레일 + 인용 의무화 (13화) |
| S3 | 네트워크 분리 미적용 | 추론 서버가 인터넷에 직접 노출 | 게이트웨이 단일 진입점 + 방화벽 (ADR-022 참조) |
| S4 | API 키 하드코딩 | 코드 저장소에 인증 정보 노출 | 환경변수 주입 + Secret Manager |
완전한 배포 체크리스트 — Stage 0에서 Stage 3까지
아래는 14일 시리즈 전체를 관통하는 구축 체크리스트입니다. 각 항목에 해당 회차 번호를 표기했으므로, 상세 구현이 필요할 때 해당 회차를 참조하세요.
# 온프레미스 AI Assistant — 전체 구축 체크리스트 (2026)
# 각 항목의 [N화] 는 상세 설명이 있는 시리즈 회차
stage_0_foundation:
hardware:
- "[ ] Mac Studio M4 Ultra 또는 CUDA GPU 서버 준비 [3화]"
- "[ ] 네트워크 구성 (사내망, 고정 IP 할당) [3화]"
- "[ ] UPS 설치 (1kVA 이상) [14화]"
model_selection:
- "[ ] 용도별 모델 사이즈 결정 (8B/14B/30B-A3B) [2화]"
- "[ ] 양자화 포맷 결정 (FP8/AWQ/4bit-GGUF/MLX) [2화]"
- "[ ] Hugging Face / ModelScope에서 모델 다운로드 [4·5화]"
basic_serving:
- "[ ] mlx-lm 서버 구동 + 헬스체크 확인 [4화]"
- "[ ] 또는 vLLM 서버 구동 + 헬스체크 확인 [5화]"
- "[ ] OpenAI 호환 엔드포인트로 curl 테스트 [4·5화]"
- "[ ] Open WebUI 연결하여 대화 테스트 [4화]"
stage_1_gateway_and_rag:
gateway:
- "[ ] LiteLLM config.yaml 작성 (모델 목록, 폴백) [6화]"
- "[ ] 복잡도 분류기 구현 (경량 모델 라우팅) [6화]"
- "[ ] 타임아웃·재시도 정책 설정 [6화]"
- "[ ] 스트리밍 SSE 엔드투엔드 테스트 [6화]"
embedding_and_vectordb:
- "[ ] bge-m3 임베딩 모델 로컬 서빙 [9화]"
- "[ ] Qdrant Docker 컨테이너 배포 [9화]"
- "[ ] 컬렉션 생성 + 하이브리드 인덱스 설정 [9화]"
- "[ ] 문서 청킹 파이프라인 구현 [9화]"
- "[ ] 하이브리드 검색 (dense + sparse + RRF) 테스트 [9화]"
- "[ ] 리랭커 (bge-reranker-v2-m3) 통합 [9화]"
rag_pipeline:
- "[ ] 검색 → 컨텍스트 주입 → 생성 파이프라인 연결 [9화]"
- "[ ] 프롬프트 템플릿 git 버전 관리 시작 [8화]"
- "[ ] RAG 응답 품질 초기 평가 (골든셋 5개) [13화]"
stage_2_memory_and_agent:
context_management:
- "[ ] 시스템 프롬프트 계층화 (base/domain/user) [8화]"
- "[ ] 토큰 예산 관리 로직 구현 [8화]"
- "[ ] 컨텍스트 압축 (요약) 파이프라인 [8화]"
memory:
- "[ ] PostgreSQL 배포 (세션·장기 메모리) [11화]"
- "[ ] 세션 메모리 스키마 설계 [11화]"
- "[ ] 장기 메모리 인출 전략 구현 [11화]"
- "[ ] 사용자 프로파일 저장·로딩 [11화]"
- "[ ] 메모리 TTL + 정리 크론 설정 [11화]"
agent:
- "[ ] Qwen3 function calling 테스트 [12화]"
- "[ ] MCP 서버 구축 (사내 시스템 연동) [12화]"
- "[ ] 도구 권한 매트릭스 정의 [12화]"
- "[ ] ReAct 오케스트레이터 구현 [12화]"
- "[ ] 샌드박스 환경 (코드 실행) 구축 [12화]"
multimodal:
- "[ ] Qwen3-VL 서빙 (vLLM) [7화]"
- "[ ] 이미지 입력 파이프라인 구현 [7화]"
- "[ ] Visual Agent 통합 (UI 이해·문서 분석) [7화]"
stage_3_safety_and_scale:
guardrails:
- "[ ] 입력 가드레일 (프롬프트 인젝션·유해 콘텐츠) [13화]"
- "[ ] 출력 가드레일 (환각 검증·형식 검증) [13화]"
- "[ ] PII 마스킹 파이프라인 [13화]"
- "[ ] human-in-the-loop 승인 워크플로 [12·13화]"
observability:
- "[ ] Prometheus 메트릭 수집 (TTFT, tok/s, GPU%) [13화]"
- "[ ] Grafana 대시보드 구축 [13화]"
- "[ ] 알림 규칙 설정 (p95 지연, 에러율, GPU 온도) [13화]"
- "[ ] 감사 로그 영속화 + 보존 정책 [13화]"
evaluation:
- "[ ] 골든셋 평가 파이프라인 (50~100건) [13화]"
- "[ ] LLM-as-judge 자동 평가 스크립트 [13화]"
- "[ ] A/B 테스트 라우팅 (모델 버전 비교) [6화]"
advanced_rag:
- "[ ] Graph RAG 구축 (Neo4j + 엔터티 추출) [10화]"
- "[ ] 멀티모달 RAG (이미지 검색) [10화]"
- "[ ] 쿼리 재작성 + 멀티홉 검색 [10화]"
scaling:
- "[ ] 2노드 이종 클러스터 구성 [14화]"
- "[ ] 로드 밸런서 설정 (가중 라운드 로빈) [14화]"
- "[ ] Qdrant 클러스터링 (샤딩 + 복제) [9화]"
- "[ ] 블루-그린 배포 파이프라인 [6화]"
- "[ ] 장애 복구 런북 작성 [5·14화]"
compliance: # 금융IT/규제 산업
- "[ ] 망분리 환경 네트워크 설계 확인"
- "[ ] 데이터 잔존 정책 문서화"
- "[ ] 로그 보존 기간 설정 (규제 요건 충족)"
- "[ ] 접근 통제 + 감사 추적 검증"
- "[ ] 모델 가중치 라이선스 (Apache 2.0) 법무 확인"
금융IT 규제 환경에서의 온프레미스 AI — 실무 고려사항
규제 산업에서 온프레미스 AI Assistant를 운영할 때, 기술 아키텍처 외에 반드시 해결해야 할 비기술적 과제가 있습니다.
데이터 주권과 망분리
금융권의 가장 강력한 동기이자 제약입니다. 고객 데이터가 외부로 나가지 않는다는 점은 온프레미스의 핵심 가치이지만, 동시에 모델 업데이트·패치 적용에 제약을 줍니다.
- 모델 다운로드: 폐쇄망에서는 Hugging Face 직접 접근이 불가합니다. 별도의 모델 반입 절차(USB/보안 파일 전송 시스템)를 수립하세요.
- 임베딩 모델: bge-m3 역시 초기 다운로드가 필요합니다. RAG 파이프라인의 모든 모델 아티팩트를 사전에 반입 목록화하세요.
- Python 패키지: pip 미러 서버를 사내에 구축하거나, 의존성을 오프라인 번들로 관리합니다.
감사 대응 설계
규제 기관의 AI 사용 감사에 대비한 기록 체계가 필요합니다.
- 입출력 쌍 저장: 모든 요청·응답을 (PII 마스킹 후) 영속 저장. 보존 기간은 규제 요건에 따라 1~7년.
- 의사결정 추적: 에이전트의 도구 호출 이력, RAG 검색 결과, 모델 라우팅 결정을 감사 로그에 포함.
- 모델 버전 기록: 어떤 시점에 어떤 모델·양자화·프롬프트 버전이 사용되었는지 추적 가능해야 합니다.
모델 업그레이드 전략 — Qwen3 이후
Qwen3를 기준 모델로 고정한 이 시리즈의 아키텍처는, 모델 교체를 의도적으로 쉽게 만들었습니다. 향후 Qwen4나 다른 오픈소스 모델이 출시될 때의 업그레이드 전략입니다.
교체가 쉬운 이유
- OpenAI 호환 API 표준화: 모든 계층이 OpenAI chat completion 인터페이스로 통신합니다. 모델을 교체해도 상위 계층 코드는 변경 불필요.
- 게이트웨이 라우팅: LiteLLM config에서 모델 엔드포인트만 교체하면 됩니다. A/B 라우팅으로 점진적 전환 가능.
- 프롬프트 버전 관리: chat template이 달라져도, 프롬프트 계층에서 템플릿만 교체하면 됩니다.
교체 시 주의할 점
- function calling 포맷: 모델마다 도구 호출 포맷이 다릅니다. Qwen3의
<tool_call>포맷에 맞춘 파서를 교체 모델에 맞게 수정해야 합니다. - Thinking 모드:
enable_thinking파라미터는 Qwen3 고유입니다. 다른 모델의 reasoning 방식(chain-of-thought prompting 등)으로 전환 필요. - 임베딩 호환성: 임베딩 모델을 교체하면 기존 벡터 인덱스 전체를 재구축해야 합니다. bge-m3는 범용성이 높아 유지하는 것을 권장합니다.
- 품질 회귀 테스트: 골든셋 평가 파이프라인(13화)을 반드시 실행하여 품질 저하가 없는지 확인합니다.
# 모델 교체 체크리스트
model_upgrade_checklist:
pre_upgrade:
- "[ ] 현재 모델의 골든셋 평가 점수 기록 (baseline)"
- "[ ] 새 모델의 라이선스 확인 (상업 사용 가능 여부)"
- "[ ] VRAM/메모리 요구량 확인 (기존 하드웨어 적합성)"
- "[ ] 새 모델의 chat template 확인 + 프롬프트 템플릿 수정"
- "[ ] function calling 포맷 파서 수정"
upgrade_process:
- "[ ] 별도 포트에서 새 모델 서빙 시작"
- "[ ] LiteLLM config에 새 모델 추가 (weight=0 시작)"
- "[ ] 골든셋 평가 실행 → baseline 대비 비교"
- "[ ] A/B 라우팅으로 10% 트래픽 전환"
- "[ ] 1주일 모니터링 (TTFT, 에러율, 사용자 피드백)"
- "[ ] 문제 없으면 50% → 100% 전환"
- "[ ] 이전 모델 서빙 중지 (1주일 대기 후)"
rollback:
- "[ ] 이전 모델 config 보존 (즉시 롤백 가능)"
- "[ ] 롤백 기준 정의 (에러율 5% 초과, 평가 점수 10% 하락 등)"
운영 함정 (Pitfall) 미니 코너 — 최종회 특별판
“전부 다 구축해야 한다”는 함정
14일 시리즈의 가장 큰 함정은 역설적으로 이 모든 것을 한 번에 구축하려는 유혹입니다. A 금융사의 사례: 6개월간 7계층 전체를 동시에 개발하다 어느 계층도 프로덕션 품질에 도달하지 못했습니다. 결국 Stage 0(기본 서빙 + Open WebUI)으로 돌아가 2주 만에 사내 시범 서비스를 시작하고, 사용자 피드백을 받으며 계층을 하나씩 추가했습니다.
권장 접근: Stage 0을 2주 내에 론칭하세요. “동작하는 최소 시스템”이 존재해야 나머지 계층의 우선순위를 실제 사용 데이터로 결정할 수 있습니다. RAG가 먼저인지, 메모리가 먼저인지, 에이전트가 먼저인지는 사용자가 알려줍니다.
이 함정은 MVP(Minimum Viable Product) 원칙과 같습니다 — AI 시스템도 예외가 아닙니다.
14일 시리즈 총정리 — 한 장의 지도
14일간의 여정을 한 문단씩으로 압축합니다.
1~3화 (개관·모델·하드웨어): 온프레미스 AI의 “왜”를 정의하고, Qwen3를 기준 모델로 선정했습니다. Apache 2.0 라이선스, 한국어 지원, 0.6B부터 235B까지의 사이즈 스펙트럼, Dense와 MoE의 이중 아키텍처, vLLM과 MLX 양쪽 생태계 지원이 선정 이유였습니다. 하드웨어는 Mac Studio(저지연·저전력)와 CUDA(고처리량·동시성)의 이종 구성으로 결정했습니다.
4~7화 (서빙): 두 트랙의 실제 서빙을 구축했습니다. Mac Studio에서 mlx-lm으로 Qwen3-8B/14B를 서빙하고(4화), CUDA에서 vLLM으로 Qwen3-30B-A3B를 FP8 텐서 병렬로 서빙했습니다(5화). LiteLLM 게이트웨이로 이 둘을 단일 엔드포인트로 통합하고, 복잡도 기반 라우팅·폴백·타임아웃을 설계했습니다(6화). Qwen3-VL을 추가하여 멀티모달 추론까지 확장했습니다(7화).
8~11화 (컨텍스트·지식·메모리): 모델이 “아는 것”을 넘어 “찾고 기억하는” 능력을 부여했습니다. 프롬프트 계층화와 토큰 예산 관리(8화), bge-m3 + Qdrant 자체 호스팅 RAG(9화), Graph RAG와 멀티모달 RAG로 복합 검색(10화), 세션·장기·프로파일 메모리로 대화 연속성(11화)을 구현했습니다.
12~14화 (에이전트·안전·종합): 모델이 “행동하는” 능력을 갖추되, “안전하게” 행동하도록 제어했습니다. Function calling과 MCP로 사내 시스템을 연동하고 ReAct 오케스트레이터를 설계했습니다(12화). 입출력 가드레일·PII 마스킹·감사 로그·평가 파이프라인으로 안전 계층을 완성했습니다(13화). 그리고 오늘(14화), 이 모든 것을 7계층 AI Assistant 레퍼런스 아키텍처로 통합하고, 확장·진화·운영의 현실적 경로를 제시했습니다.
이 시리즈가 남기는 것
이 시리즈의 핵심 메시지는 단순합니다: 온프레미스 AI Assistant는 더 이상 대기업의 전유물이 아닙니다. Qwen3 같은 Apache 2.0 모델, vLLM과 MLX 같은 오픈소스 서빙 스택, Qdrant와 PostgreSQL 같은 자체 호스팅 인프라를 조합하면, 소규모 팀이나 중소기업도 데이터 주권을 유지하면서 실용적인 AI 시스템을 구축할 수 있습니다.
물론 클라우드 API 대비 운영 부담은 존재합니다. 하드웨어 투자, 열 관리, 모델 업데이트, 장애 대응 — 이 모든 것이 “우리의 일”이 됩니다. 그러나 14일간 다룬 각 계층의 설계 원칙과 안티패턴 체크리스트가 그 부담을 예측 가능한 범위로 줄여줄 것입니다.
Stage 0부터 시작하세요. 오늘 mlx-lm이나 vLLM으로 Qwen3를 띄우는 것이 첫 걸음입니다. 나머지 계층은 사용자의 피드백이 알려줄 것입니다.
14일간 함께해 주셔서 감사합니다.
Photo by zeng jinwen on Pexels
◀ 이전 13화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
온프레미스 AI Assistant 7계층 레퍼런스 아키텍처는 어떤 계층으로 구성되나요?
클라이언트, 게이트웨이, 컨텍스트 조립, 지식(RAG), 메모리, 에이전트·도구, 안전·관측의 7개 논리 계층으로 구성됩니다. 각 계층은 독립 배포와 교체가 가능하며, 계층 간 인터페이스는 OpenAI 호환 API와 gRPC로 표준화됩니다.
Mac Studio 단일 노드에서 클러스터로 확장하는 경로는 어떻게 되나요?
Mac Studio 1대와 CUDA GPU 1대의 최소 구성에서 시작하여, 로드 밸런서 도입, 모델 샤딩, RAG 클러스터 확장의 3단계 경로로 설계됩니다. 각 단계는 부하와 사용자 규모에 따라 점진적으로 적용할 수 있습니다.
Qwen3로 단순 챗봇에서 자율 에이전트로 진화하려면 어떤 단계를 거쳐야 하나요?
단순 Q&A에서 멀티스텝 툴 호출, 자율 실행까지의 성숙도 모델을 따릅니다. Qwen3의 function calling 기능과 MCP(Model Context Protocol)를 활용하여 ReAct, Plan-Execute 같은 오케스트레이션 패턴을 적용하고, 도구 레지스트리와 샌드박스를 갖춘 에이전트 계층을 구축하는 방식입니다.
[…] [온프레미스 AI Assistant 아키텍처 — Qwen3·Qwen3-VL 14일 설계] 14/14화: AI Assistant … […]