AI PIPELINE
Data & AI Intelligence
엔터프라이즈급 Agentic AI: 모듈화 아키텍처 가이드북
실무에서 확장 가능한 Agentic AI를 구현하기 위해서는 인프라(LLM/RAG 엔진)와 로직(Retriever)의 분리가 필수입니다. 본 가이드는 Ollama 3.2, LangChain, LangGraph, MCP를 결합한 엔터프라이즈급 모듈형 아키텍처와 상세 코드, 성능 최적화 전략을 안내합니다.
Ollama 3.2
LangGraph
Retrieval Architecture
LangSmith
1. 핵심 기술 용어 해설
LLM (Ollama 3.2)
설명
로컬 인프라 기반 추론용 모델
쉬운설명
내 컴퓨터에서 돌아가는 똑똑한 AI 두뇌
예시
인터넷 없이 동작하는 문서 요약 AI
RAG
설명
검색 기반의 답변 생성 프레임워크
쉬운설명
AI에게 교과서를 주고 시험 문제를 풀게 하는 것
예시
사내 매뉴얼 PDF를 기반으로 답하는 챗봇
LangChain
설명
AI 컴포넌트 오케스트레이션 프레임워크
쉬운설명
AI를 데이터와 도구에 잇는 접착제
예시
사용자 질문을 분석해 DB에서 정보를 가져오는 과정
LangGraph
설명
상태 기반 순환 에이전트 워크플로우
쉬운설명
AI가 막히면 스스로 다른 방법을 시도하는 설계도
예시
검색 실패 시 검색어 수정 후 재검색 시도
MCP
설명
범용 도구 연결 표준 프로토콜
쉬운설명
AI에게 도구를 끼워 쓰는 만능 플러그
예시
구글 드라이브나 SQL을 AI가 직접 제어
LangSmith
설명
AI 파이프라인 관측 및 디버깅 플랫폼
쉬운설명
AI가 왜 틀렸는지 확인하는 블랙박스
예시
잘못된 답변의 근거 문서 출처 추적
2. 프로젝트 모듈 구조 및 파일 역할
전문적인 에이전트 시스템은 관심사의 분리(Separation of Concerns)가 핵심입니다. 데이터베이스 관리(Engine)와 검색 전략(Retriever)을 분리하여 시스템의 확장성을 확보합니다.
project_root/
├── main.py # Orchestrator: 전체 파이프라인 제어
├── src/
│ ├── config.py # 환경 설정 (Pydantic/Ollama 설정)
│ ├── llm_engine.py # Ollama 3.2 모델 추론 엔진
│ ├── rag_engine.py # 벡터 DB 인프라 관리
│ ├── retrieval.py # Retriever 전략 및 검색 로직 (Logic)
│ ├── graph.py # LangGraph 워크플로우 정의
│ ├── mcp_tools.py # MCP 클라이언트 연동 도구
│ └── utils.py # 로깅 및 공통 유틸리티
└── tests/3. 실무 모듈별 상세 코드
파일명: src/config.py 프로젝트 전역 환경 설정 및 설정값 관리from pydantic_settings import BaseSettings
class Settings(BaseSettings):
OLLAMA_MODEL: str = "llama3.2"
CHROMA_DB_PATH: str = "./chroma_db"
settings = Settings()from langchain_ollama import ChatOllama
from src.config import settings
class LLMEngine:
def get_model(self):
return ChatOllama(model=settings.OLLAMA_MODEL, temperature=0)from langchain_chroma import Chroma
from langchain_ollama import OllamaEmbeddings
from src.config import settings
class RAGEngine:
def __init__(self, collection_name: str):
self.embeddings = OllamaEmbeddings(model=settings.OLLAMA_MODEL)
self.vector_store = Chroma(
collection_name=collection_name,
embedding_function=self.embeddings,
persist_directory=settings.CHROMA_DB_PATH
)
def get_vector_store(self):
return self.vector_storeclass RetrievalManager:
def __init__(self, vector_store):
self.vector_store = vector_store
def get_retriever(self, k=5, search_type="similarity"):
return self.vector_store.as_retriever(
search_type=search_type,
search_kwargs={"k": k}
)from langgraph.prebuilt import create_react_agent
def build_agent(llm, retriever):
tools = [retriever]
return create_react_agent(llm, tools)def get_mcp_tools():
# 외부 MCP 서버 연동 세션 로직
return []import logging
def get_logger(name):
logging.basicConfig(level=logging.INFO)
return logging.getLogger(name)import asyncio
from src.llm_engine import LLMEngine
from src.rag_engine import RAGEngine
from src.retrieval import RetrievalManager
from src.graph import build_agent
async def main():
llm = LLMEngine().get_model()
rag_engine = RAGEngine(collection_name="kb")
retriever = RetrievalManager(rag_engine.get_vector_store()).get_retriever()
app = build_agent(llm, retriever)
response = await app.ainvoke({"messages": [("user", "최신 시장 데이터를 분석해줘")]})
print(response["messages"][-1].content)
if __name__ == "__main__":
asyncio.run(main())4. 아키텍처 워크플로우
1. 사용자 입력 (Query) 발생
▼
2. Orchestrator(Main) 제어
▼
3. LangGraph 순환 추론
▼
4. Retrieval Manager (검색/리랭킹)
▼
5. RAG Engine (Vector DB) 데이터 조회
▼
6. Ollama 3.2 모델 응답 생성
이 워크플로우는 데이터 인프라와 검색 전략이 코드 수준에서 분리되어 있어, 비즈니스 로직 수정이 인프라에 영향을 주지 않는 구조를 가집니다.
5. 고급 튜닝 및 최적화 전략
RAG 검색 품질 고도화
설명
검색 정확도 향상을 위한 하이브리드 전략
쉬운설명
단어 의미와 핵심 키워드를 함께 검색하여 정확한 문서 찾기
예시
RRF(Reciprocal Rank Fusion)를 사용하여 Vector+BM25 검색 결과 결합
에이전트 성능 최적화
설명
에이전트 판단 오류 최소화 전략
쉬운설명
AI가 실수를 줄이도록 모범 답안 예시 제공
예시
LangSmith로 대화 로그를 추적하여 Few-Shot 프롬프트 튜닝
인프라 최적화
설명
연산 리소스 및 비용 절감
쉬운설명
AI가 똑같은 생각을 반복하지 않게 미리 기억해두기
예시
Redis를 사용한 임베딩(Embedding) 결과값 캐싱
Data & AI Intelligence