작은 모델, 위대한 도구: 프로덕션 환경의 로컬 AI 에이전트 뒤에 숨겨진 엔지니어링

제대로 된 코드 어시스턴트를 구축하려면 반드시 GPT나 Claude를 사용해야 한다는 지속적인 미신이 있습니다. 이는 사실이 아닙니다. 1조 개의 파라미터를 가진 모델이 필요한 것이 아닙니다. 여러분에게 필요한 것은 크기가 작은 로컬 모델과 그 주변을 둘러싼 매우 엄격한 엔지니어링입니다.

이는 기업들에게도 마찬가지입니다. Mark Zuckerberg가 언급했듯이, 미래는 단 하나의 전지전능한 모델에 있는 것이 아니라 _"각 기업이 자신만의 전문화된 AI를 갖는 것"_에 있습니다. 그리고 이러한 전문화는 데이터 보안을 보장하기 위한 파인튜닝 (fine-tuning) 및 로컬 배포(또는 주권 서버 배포)를 반드시 거쳐야 합니다.

Vibrisse Agent 구축의 핵심 논지는 한 문장으로 요약됩니다: Small models, Great tools.

이 글에서는 로컬 모델을 길들이고 프로덕션 환경에서 신뢰할 수 있게 만들기 위해 제가 구축한 기술 스택과 구체적인 엔지니어링 솔루션을 자세히 설명하겠습니다: LangGraph, Ollama, FastAPI, React (빌드 단계 없이 임베디드된 커스텀 CSS 사용), 이 모든 것은 32GB RAM을 갖춘 머신에서 실행됩니다.

지금 바로 자신의 머신에서 에이전트를 실행해보고 싶은 분들을 위해:

// MacOs / Linux
curl -sSL https://agent.vibrisse-studio.dev/install.sh | bash

...

아키텍처: 왜 상태 머신 (LangGraph)인가?

처음에 LLM 애플리케이션을 구축할 때, 우리는 흔히 순차적 체인(sequential chain) 방식으로 생각하는 경향이 있습니다: 입력(Input) -> 프롬프트(Prompt) -> 도구(Tool) -> 출력(Output). 문제는 특정 노드에서 실패할 경우, 오류를 복구하거나 충돌의 맥락을 이해할 수 있는 방법 없이 전체 체인이 중단된다는 점입니다.

여기에서 LangGraph가 등장합니다. Vibrisse의 아키텍처는 체인이 아니라 **상태 머신 (state machine)**입니다. 그래프의 각 노드는 매우 구체적인 책임을 가지며, 대화의 전역 상태(global state)를 공유하고, 다음 노드로 넘어가기 위해 조건부 전이(conditional transitions)를 사용합니다.

저는 Supervisor / Worker 패턴을 구현했습니다:

• Supervisor는 사용자의 의도를 분석합니다. 그는 라우팅(routing) 외에 다른 일은 하지 않습니다.
• 그는 작업을 전문화된 Workers (RAG Worker, Search Worker, Ghost Worker 등)에게 배분합니다.
• 만약 Worker가 실패하거나 더 많은 정보가 필요할 경우, Supervisor에게 상태를 다시 보낼 수 있습니다.

진짜 싸움: 작은 모델의 "게으름" 길들이기

이 프로젝트에서 가장 가치 있는 부분이자, 아주 적은 수의 튜토리얼만이 정직하게 기록하고 있는 부분은 바로 작은 LLM (Large Language Models)의 본성과 싸우는 것이었습니다.

무기 선택: 승리한 모델들

제 충돌 테스트(crash-tests)에서 어떤 모델들이 살아남았는지 궁금하시다면: 저는 에이전트의 모든 핵심을 **Gemma 4 (e4b)**를 중심으로 구축했습니다. 왜일까요? 이 모델은 시각(vision) 처리와 "생각(thoughts)" 기능을 기본적으로 통합하고 있으면서도, Google 특유의 매우 구조화된 응답 스타일을 제공하기 때문입니다. 반면, 평가 및 메트릭(metrics)과 관련된 모든 작업에는 Llama 3 8B로 전환해야 했습니다. 너무 작은 모델은 자신의 응답을 신뢰할 수 있는 방식으로 평가하는 데 한계가 있음이 드러났습니다.

제약 조건과 생각하며 말하기 (Chain-of-Thought)

엄격한 제약 조건이 없다면, 로컬 모델은 항상 저항이 가장 적은 경로를 택할 것입니다. 구체적으로, 만약 당신이 새벽 3시에 확고한 지침 없이 복잡한 파일을 리팩터링(refactor)해달라고 요청한다면, 모델은 자랑스럽게 이렇게 작성할 것입니다: // ... 나머지 코드는 여기에 작성됨.

해결책은 무엇일까요? 역할, 엄격한 JSON 출력 형식, 그리고 무엇보다 "생각하며 말하기(think aloud)"의 의무를 부과하는 초구조화된 시스템 프롬프트(system prompts)입니다. 행동을 실행하기 전에 <thought> 태그를 사용하도록 강제하는 것은 두 가지 측면에서 매우 중요합니다: 에이전트가 왜 잘못된 라우팅 결정을 내렸는지 디버깅하는 것, 그리고 UX(사용자 경험)를 개선하는 것입니다.

3중 레이어 견고한 파싱 (Triple-Layer Robust Parsing)

LLM이 JSON으로 응답하도록 강제하는 것은 싸움의 절반에 불과합니다. 모델이 "지치거나" 문맥(Context) 속에서 엉키게 되면, 잘못된 형식의 JSON을 생성할 수 있습니다. 에이전트가 중단되지 않도록 하기 위해, 저는 다음과 같은 3중 레이어 파싱(Parsing) 시스템을 설계해야 했습니다:

1. 레이어 1: 클래식 JSON 파싱 (Classic JSON Parsing).
2. 레이어 2: 모델이 주변에 텍스트를 추가했을 경우, 객체를 추출하기 위한 폴백 정규식 (Fallback Regex).
3. 레이어 3: JSON이 완전히 깨진 경우, 키워드 기반의 폴백(Fallback)을 통해 의도를 추측하여 후퇴 동작(Fallback action)을 수행합니다. 중단(Crash)은 제로입니다.

일화: 이 접근 방식은 프로젝트 후반부의 사고 실험에서 탄생했습니다: "만약 매우 사양이 낮은 기기에서 매우 불안정한 SLM (Small Language Model)으로 이 에이전트를 실행해야 한다면 어떻게 될까?". 강제된 제약 조건들이 제가 유지해 온 이러한 회복 탄력성(Resilience) 기술들을 낳았습니다. (어쩌면 미래의 "Vibrisse-Lite"의 시작점이 될지도 모르겠네요? 지켜보자고요...)

3중 레이어 검색 (Triple-Layer Retrieval): 노이즈 없는 정밀한 RAG

RAG는 모델에게 문맥을 퍼붓기 위해 만들어진 것이 아닙니다. 작은 모델에 더 많은 텍스트를 보낼수록 환각(Hallucination)은 더 심해집니다. 문맥은 타겟팅되어야 하며 초정밀해야 합니다. Vibrisse 에이전트는 **3중 레이어 검색 (Triple-Layer Retrieval)**을 사용합니다:

1. 결정론적 레이어 (Ripgrep): 정확한 쿼리(예: "API_KEY 변수가 어디에 정의되어 있나요?")를 위한 레이어입니다. 100% 정확하며, 환각은 0%입니다.
2. 의미론적 레이어 (ChromaDB): 의도를 이해하기 위한 레이어입니다 (예: "에러를 어떻게 처리하는지 보여줘").
3. 통계적 레이어 (BM25): 클래식한 안전망입니다.

우리는 하나의 방법만을 선택하는 것이 아니라, 세 가지를 모두 실행하고 결과를 병합합니다.

에이전트의 근육: MCP Hub, 웹 검색(Web Search) 및 고스트 모드(Ghost Mode)

LLM 단독으로는 그저 "병 속의 뇌"에 불과합니다. 에이전트에게 근육을 이식하려면 모든 사소한 동작 하나하나를 설계하고 코드로 구현해야 한다는 점을 반드시 인지해야 하며, 이 과정에서 소위 말하는 "마법 같은" 느낌은 금방 깨지기 마련입니다. 에이전트가 단순한 grep 명령어를 수행하기를 원하시나요? 그렇다면 도구를 코딩해야 하고, 단독으로 테스트해야 하며, Vision 액션 이후에, 그리고 웹 검색(Web Search) 이후에 다시 테스트하여 LangGraph가 충돌하지 않는지 확인해야 합니다.

에이전트는 로컬 도구뿐만 아니라, 답변을 내놓기 전 가장 최신 문서를 찾아오는 데 필수적인 웹 검색 (Tavily API) 과 같은 연결된 도구들도 보유하고 있습니다.

MCP Hub (Model Context Protocol)

바퀴를 새로 발명하는 대신, 저는 Anthropic의 MCP 표준을 통합했습니다. Vibrisse는 MCP Client 역할을 수행합니다. 도구를 추가하는 것은 단순히 외부 서버를 연결하는 것과 같습니다. 이러한 아키텍처는 Google의 webMCP와 같은 진화에 대비할 수 있는 "미래 보장형 (future-proof)" 구조입니다.

Ghost Mode: 파일 내 지시어 (In-File Directives)

이것이 바로 워크플로우의 킬러 기능(killer-feature)입니다. 에이전트의 목적은 사용자가 채팅창에서 대화하도록 강요하는 것이 아닙니다.

Python 라이브러리인 watchdog를 기반으로 한 WatcherService가 백그라운드에서 실행됩니다. 저장된 주석에서 @vibrisse: 태그가 감지되는 즉시, 조용한 Ghost Worker를 트리거하여 코드를 생성하고 에디터에 직접 주입합니다.

Architect Mode: Human-in-the-Loop 및 Artefacts

복잡한 작업의 경우, 자율 에이전트(autonomous agent)가 수십 개의 명령어를 루프(loop)로 실행하게 두는 것은 아키텍처 측면에서 자살 행위와 같습니다. 핸드브레이크(handbrake)가 필요합니다. 그래서 저는 LangGraph를 사용하여 Human-in-the-Loop 패턴을 구현했습니다.

그래프 중단 (interrupt_after)

구조적인 작업이 감지되면, 라우터(router)는 전용 노드(planning_node)로 전환됩니다. 이 노드는 엄격한 XML 태그(<artifact id="plan">)로 감싸진 Markdown 형식의 실행 계획을 생성합니다.
LangGraph의 묘미는 그래프를 interrupt_after=["planning_node"] 명령과 함께 컴파일한다는 점입니다. 계획이 생성되는 즉시 백엔드 측의 실행은 즉시 중단되며, 상태(state)는 데이터베이스에 저장됩니다.

프론트엔드 렌더링 및 상태 재개 (State Resumption)

React 측에서는 UI가 정규 표현식(regular expression)을 사용하여 이러한 태그를 가로채고, 가공되지 않은 XML을 숨긴 뒤 풍부한 인터랙티브 컴포넌트(CodeDiff, Mermaid 다이어그램, 또는 TaskBoard)를 생성합니다. 그러면 사용자는 제안을 "승인(Approve)"하거나 "거절(Reject)"할 수 있는 버튼을 갖게 됩니다.

이 기능의 가장 큰 기술적 함정은 무엇일까요? 바로 **상태 재개 (Resume)**입니다.
사용자가 "승인"을 클릭하면, 프론트엔드는 LangGraph 그래프를 다시 실행하는 라우트(route)를 호출합니다. 하지만 아무런 말 없이 대화를 재개하면, 작은 LLM은 컨텍스트 히스토리(context history) 끝에 자신의 메시지(AIMessage)가 놓인 상태가 되어 대화의 다음 내용을 환각(hallucination)하기 시작합니다.
기발한 해결책: 추론(inference)을 다시 시작하기 전에 상태(state)에 HumanMessage ("계획이 승인되었습니다. 구현을 진행하세요.")를 조용히 주입하는 것입니다. 이렇게 하면 모델은 명확한 지침을 갖게 되며, 무엇을 기대하는지 정확히 알게 됩니다.

지속성 및 컨텍스트 제한

기억상실증 치료하기

2시간 전에 내린 결정을 잊어버리는 에이전트는 쓸모가 없습니다. Vibrisse는 스레드(thread)의 완전한 지속성을 위해 SQLite를 사용하며, 매 실행 시 project_map.json을 자동으로 생성하는 방식과 결합하여 사용합니다.

또 다른 숙적은 컨텍스트 창의 한계입니다 (이 작은 모델들의 경우 보통 8k 토큰). RAG가 너무 많은 파일을 가져오면 컨텍스트가 폭발합니다. 이를 관리하기 위해 Vibrisse는 토큰 소비를 지속적으로 모니터링하고 UI의 _Sidebar_에 실시간으로 표시합니다. 개발자는 이렇게 해서 언제 컨텍스트가 포화되었고 대화를 새로 고칠 시간이 되었는지 정확히 알 수 있습니다.

Sovereign Routing: 지능적인 위임

에이전트는 행동하기 전에 각 요청의 복잡성을 분석합니다:

• 단순 요청 -> 로컬 모델 (Ollama). 즉각적인 결과 제공.
• 복잡한 요청 -> 에이전트가 사용자의 명시적 동의하에 더 강력한 클라우드 모델로 전환할 것을 제안합니다.

현안의 코끼리: 지연 시간과 RAM

로컬 AI의 주요 단점인 **지연 시간(latency)**에 대해 솔직해야 합니다. Vision 분석과 복잡한 React 컴포넌트 생성 기능을 결합하는 것은 일반 소비자용 기기에서 최대 3분(혹은 그 이상)이 걸릴 수 있습니다. 이는 완벽한 프라이버시와 로컬 환경을 선택함으로써 지불해야 할 대가입니다.

이를 관리 가능하게 만들기 위해 Vibrisse는 실제 하드웨어 리소스 추적 기능을 통합했습니다:

• 설치 시 (V)RAM 체크: 온보딩 위자드(Wizard d'onboarding)를 통해 에이전트를 세밀하게 설정할 수 있습니다.
• Sidebar의 리소스 게이지: 기기 부하를 실시간으로 모니터링합니다.
• ThinkingConsole: 생각하는 토큰을

황금률: 블록 단위 테스트