Spring Boot 4 + LangChain4j 1.11 + Ollama + Qdrant +MCP 기반 통합 다중 에이전트 지능 시스템, RAG 구축
본 기사는 기업급 프로젝트 경험을 바탕으로 재구성하고 개발한, 진정한 "즉시 사용 가능"한 기업용 지식 시스템입니다. 표준 RAG 질의응답을 지원하는 것을 넘어 에이전트 지능 아키텍처, MCP 파일 샌드박스, 금융 전용 연산자 및 하이브리드 모델 라우팅을 통합하여, 문서 업로드부터 복잡한 추론까지 완전한 폐쇄형 경험을 제공합니다.
1. 개요: 기술 스택과 핵심 기능 ✨
| 구분 | 기술 선택 | 기능 설명 |
|---|---|---|
| 백엔드 프레임워크 | Spring Boot 4 + SQLite | 경량 영구화, 추가 데이터베이스 불필요, 프로덕션에서 mysql,pgsql 등으로 전환 가능 |
| AI 엔진 | LangChain4j 1.11 | 에이전트 도구 호출, 스트리밍 응답, 컨텍스트 메모리 지원 |
| 언어 모델 | Ollama(qwen2.5:7b) + 선택적 DashScope(qwen-plus) |
로컬 프라이빗 배포 + 클라우드 고성능 하이브리드 |
| 임베딩 모델 | Ollama(qwen3-embedding:0.6b) |
로컬 고정 사용, 데이터 도메인 외부 유출 방지, 고성능, 비용 절감 |
| 벡터 데이터베이스 | Qdrant(1024 차원) | 자동 컬렉션 생성, 고효율 검색(minScore=0.5) |
| 프론트엔드 인터페이스 | 순수 정적 HTML/JS | 유리 효과 + 그라데이션 디자인, 5대 기능 페이지, 최소 의존성, 경량화 |
| 특수 기능 | 10+ 분야 문서 관리 🧠 에이전트 다중 도구 협업 📊 금융 계산(IRR/채권/옵션) 📎 MCP 파일 분석 🌤️ 날씨/시간 조회 | 기업 시나리오 완벽 커버리지 |
2. 엔드투엔드 아키텍처 🚀
핵심 설계: 임베딩 모델은 항상 로컬 Ollama를 통해 처리하여 민감 문서 벡터화 과정을 완전히 비공개로 유지; 생성 모델만 동적 라우팅 가능.
3. 모듈 심층 분석
3.1 RAG 검색 증강 생성 📄
- 진입점:
RagService - 프로세스:
- 사용자 질문 → 로컬
qwen3-embedding으로 벡터 생성; - Qdrant에서 상위 5개 유사 문단 검색(
min-score: 0.5); - 컨텍스트 조합 → LLM(로컬/클라우드) 라우팅 → 참조 포함된 응답 스트리밍 반환.
- 문서 지원: PDF/TXT 자동 분할(
chunk-size: 500,overlap: 50), 메타데이터에 파일명 포함하여 추적 용이.
3.2 에이전트 지능 대화 ⭐
LangChain4j 에이전트 아키텍처 기반으로 자체 의사결정과 도구 협업 구현:
- 메모리 메커니즘:
MessageWindowChatMemory, 최근2 × context-window-size메시지(기본 20개) 슬라이딩 윈도우 관리. - 내장 도구 세트(에이전트 자체 호출):
searchKnowledge(): 벡터 지식베이스 검색readFile() / listDirectory() / searchFiles(): MCP 파일 시스템 작업calculate(): 수식 평가(exp4j)calculateAmortization(): 대출 상환 계획getIRR() / getBondPrice() / getOptionPrice(): 금융 전용 계산getCurrentTime()/getWeather(): 실시간 정보 조회- 실행 추적:
AgentExecutionInfo가 전체 사고 체인 기록, 프론트엔드에서 "에이전트가 파일 읽는 중...블랙-숄즈 호출 중..." 표시 가능.
3.3 하이브리드 모델 라우팅 전략 🔀
ModelRouterService를 통한 지능형 분류:
| 전략 | 설정 예시 | 적용 시나리오 |
|---|---|---|
| PERCENTAGE | aliyun: 30, local: 70 |
테스트 환경, 부하 분산 |
| BUSINESS_TYPE | aliyun-types: [COMPLEX_QUERY, LONG_CONTEXT] local-types: [TOOL_CALLING, SIMPLE_QA] |
프로덕션 권장: 복잡 작업은 클라우드, 도호 호출은 로컬 |
안전 장치: DashScope API Key가 설정되지 않으면 자동으로 100% 로컬 Ollama로 라우팅.
3.4 스타일 MCP 파일 샌드박스 📎
Model Context Protocol (MCP)에서 영감을 받은 안전한 파일 상호작용 구현:
- 경격 격리: 모든 파일은
uploads/{conversationId}/에 저장, 대화별로 격리. - 보호 기능:
- 루트 디렉토리 제한(
mcp-allowed-directory) - 디렉토리 순회 방지(
..정규화) - 대용량 파일(>5KB) 자동 미리보기 잘림
- 전형적 시나리오: > 사용자가 《민원 정책.pdf》 업로드 → 에이전트가
readFile()호출로 읽음 →searchKnowledge()로 지식베이스 검색 → 규정 준수성 대비 분석.
3.5 현대적 프론트엔드 인터페이스 🎨
5개 기능 페이지, 통일된 그라데이션 디자인 + 유리 효과:
| 페이지 | 기능 강점 | 미리보기 |
|---|---|---|
파일 업로드 /upload.html |
- PDF / TXT 업로드 지원 - 자동 분할 + Qdrant 벡터화 - 분야 라벨 지정 가능(예: FINANCE) |
|
지능형 질의응답 /chat.html |
- 표준 RAG 스트리밍 대화 - 응답 자동 참조 출처 표시(파일명 + 조각) - 빠른 응답 속도, 원활한 경험 | |
에이전트 대화 /agent-chat.html |
- 에이전트 자체 도호 호출(파일/계산/검색 등) - 실시간 실행 경로 표시: 모델 선택 → 도호 호출 → 결과 통합 - 복잡 다단계 추론 지원 | |
분야 문서 관리 /domain.html |
- 10+ 분야 지식베이스 관리(예: TECH, FINANCE, POLICY) - 각 분야 문서 수 및 상태 조회 - 비동기 처리 진도 피드백 AI 서비스로 개조 가능, 데이터 수신 및 지식베이스 저장. |
|
️ Qdrant 관리 /qdrant.html |
- 기존 벡터 컬렉션(Collections) 조회 - 새 컬렉션 생성(자동 1024차원 구성) - 벡터 저장 상태 디버깅 |
4. 빠른 시작 및 설정 ⚙️
4.1 로컬 전체 스택 실행
# 1. Ollama 시작 및 모델 다운로드
ollama serve
ollama pull qwen2.5:7b
ollama pull qwen3-embedding:0.6b
# 2. Qdrant 시작
docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant
# 3. 애플리케이션 실행
mvn spring-boot:run
# 4. 시스템 접속
open http://localhost:8080
4.2 주요 설정 (application.yaml)
# 모델 라우팅(프로덕션은 BUSINESS_TYPE 권장)
model-router:
strategy: BUSINESS_TYPE
business-type:
aliyun-types: [COMPLEX_QUERY, LONG_CONTEXT]
local-types: [SIMPLE_QA, TOOL_CALLING]
# RAG 매개변수
rag:
chunk-size: 500
chunk-overlap: 50
max-results: 5
min-score: 0.5
# 에이전트 보안 샌드박스
agent:
context-window-size: 10
mcp-allowed-directory: ./uploads # 엄격 제한!
mcp-file-enabled: true
DashScope 설정: 환경 변수
DASHSCOPE_API_KEY설정으로 클라우드 모델 활성화.
5. 기업급 세부사항 및 확장점 💡
- 금융 계식 심층 지원:
- 투자 분석: IRR(뉴턴법), NPV, 상환 계획
- 채권: 가격 책정, 만기 수익률(YTM), 듀레이션, 커브처
- 옵션: 블랙-숄즈 모델 + 그리스(Delta/Gamma/Vega)
- 상세 내용은 Financial-Calculation-Guide.md 참조
- 분야 지식 관리:
TECHNOLOGY,FINANCE등 10+ 분야 지원, 비동기 처리 저장. - 확장 제안:
- 보안: 리버스 프록시 계층에 업로드 크기 제한 추가,
mcp-allowed-directory제한 강화 - 가시성:
AgentExecutionInfo를 로깅 시스템 연결, 전체 감사 체인 구축 - 프론트엔드: 현재 정적 페이지는 React/Vue SPA로 무결합 교체 가능, 백엔드 SSE 인터페이스 준비 완료
6. 결론: 왜 이 프로젝트가 시도할 가치가 있는가? ✅
"데모가 아니라, 기존 기업급 구현에서 추출한 실제 적용 가능한 기업용 지식 기반입니다."
- 전체 프라이빠이제이션: Ollama + Qdrant + SQLite, 외부 의존성 없음;
- 에이전트 준비: 질의응답을 넘어 도호 자체 호출, 파일 분석, 계산 실행 가능;
- 광범위 시나리오 커버리지: 일반 RAG부터 금융/정부 수직 분야까지;
- 즉시 사용 가능: 5분 시작, 5개 페이지로 핵심 요구사항 커버;
- 유연한 확장성: 모델, 도호, 라우팅 전략 모두 플러그 가능.
내부 지식베이스 구축, 지능형 고객 서비스, 또는 에이전트 AI 애플리케이션 탐색이든, 이 프로젝트는 프로덕션급 참고 구현을 제공합니다. 지금 바로 클론하여 기업 지능 여정을 시작하세요!
프로젝트 주소: https://github.com/IdeasForLife/knowledge ⭐ 도움이 되셨다면 Star로 지지해주세요!
최근 계획: MCP 에이전트 × 기업 운영 생태계
프로젝트는 다양한 AI 실제 능력을 제공하며, 현재 MCP(Model Context Protocol) 에이전트를 자동화 운영 시나리오의 심층 통합 개발 중입니다. 자체 인지, 진단 및 조작 능력을 갖춘 AI 운영 조수 구축을 목표로 합니다. 현재 다음 핵심 시스템 연동을 계획 중이며, 플러그 가능한 AI 능력을 구현합니다:
- 코드 및 협업: GitLab(PR 분석, CI 상태 조회), 비서 문서(장애 복구 지식 검색)
- 로그 및 모니터링: 알리클라우드 로그 서비스(SLS), ClickHouse(고성능 로그 분석), SkyWalking(분산 링크 추적), CAT(메이톤 오픈소스 모니터링 플랫폼)
- 인프라: 쿠버네티스(Pod 상태, 이벤트 조회, 리소스 확축축 제안)
- 명령 실행: 보안 샌드박스화된
cat/grep/kubectl등 CLI 도호 호출 - arthas 온라인 Pod JVM 데이터 수집
통일된 MCP 도호 인터페이스를 통해 에이전트는 시스템 간 컨텍스트 연관 가능 - 예:
"사용자가 서비스 속도 저하 피드백" → 자동으로 SkyWalking 링크 조회 → 느린 인터페이스 위치 → 쿠버네티스 Pod 로그 가져오기 → ClickHouse에서 오류 로그 집계 → 근원 가설 생성.
지능 원인 엔진이 개발 중이며, 미래에는 다중 소스 데이터 기반의 자동 근원 위치 파악 및 복구 제안을 지원하여 진정한 "관측이 곧 행동" AIOps 폐쇄를 구현할 예정입니다. 기대해주세요!