README.md

metadata

title: Insurance Chatbot
emoji: 🏥
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

AI TMR Assistant — Tool Routing 고도화

Intelligent Tool Routing으로 정확도를 개선하고, Scalable Tool Architecture로 운영 효율과 확장성을 동시에 확보함

---

1. 문제

12개 보험 상품 × 9개 기능(조회·산출·심사·보장·청구 등) = 54개 도구. 도구가 많아지면서 세 가지 문제가 생김.

문제	원인	영향
오호출	유사 도구 혼동 (premium_estimate ↔ plan_options)	잘못된 답변
비용 증가	매 요청마다 54개 스키마가 LLM 컨텍스트에 포함됨	토큰 낭비
지연 증가	컨텍스트 길이에 비례하여 응답 시간이 상승함	UX 저하

도구 10개를 넘으면 정확도가 떨어지고, 37개 기준 ~6,200 토큰이 소비됨 (참고). "전부 넘기지 말고 필요한 것만 검색해서 넘기자" — 이것이 RAG-MCP 패턴의 핵심임 (참고).

---

2. 설계 — 두 축의 전략

이 프로젝트는 두 개의 축으로 문제를 해결함.

전략 축	핵심	목표
Intelligent Tool Routing	오호출을 줄이고 정확한 호출만 남김	정확도·비용·지연 개선
Scalable Tool Architecture	신규 도구 추가가 운영 부담이 되지 않도록 자동화	확장성·운영 효율

아래는 두 축이 실제 시스템에서 어떻게 연결되는지를 나타냄.

┌─────────────────────────────────────────────────────────┐
│                Intelligent Tool Routing                  │
│                                                         │
│  사용자 질문                                              │
│      ▼                                                  │
│  [Guardrail] ─── 비보험 질문 차단 ──→ 거절 응답            │
│      │ (통과)                                            │
│      ▼                                                  │
│  [Tool Card 매칭] ─── ChromaDB 멀티벡터 → Top-5 추출      │
│      ▼                                                  │
│  [LLM Tool Call] ─── 후보 중 최종 선택 → 실행              │
│                                                         │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ Vector Index 참조
                          │
┌─────────────────────────────────────────────────────────┐
│              Scalable Tool Architecture                  │
│                                                         │
│  새 Tool 추가 → Tool Card 작성 → 임베딩 자동 생성          │
│                                  → Vector Index 자동 갱신 │
│                                                         │
│  Validation: Recall@k 평가 → 수치 기반 의사결정 근거        │
└─────────────────────────────────────────────────────────┘

---

3. 축 ① — Intelligent Tool Routing

3-1. 3단계 필터링으로 54개를 5개로 줄임

단계	모듈	기능	속도
Guardrail	정규식(L1) + 임베딩(L2)	탈옥·비보험 질문 사전 차단	<5ms
Tool Search	ChromaDB 멀티벡터	54개 → Top-K 후보 추출	~10ms
LLM Selection	bind_tools()	후보 중 최종 도구 선택·호출	1~5s

Guardrail이 먼저 동작하므로 "오늘 날씨 어때?" 같은 질문은 벡터 검색이나 LLM 호출 없이 즉시 차단됨.

3-2. Tool Card로 검색 정확도를 높임

LLM 도구 description은 보통 한두 줄이라, 유사 도구끼리 벡터가 거의 같아져서 구분이 어려움. 이를 해결하기 위해 도구마다 ToolCard를 작성하여 임베딩 표면을 확장함.

ToolCard(
    name="premium_estimate",
    purpose="나이·성별을 입력해 특정 상품의 예상 월 보험료를 산출한다.",
    when_to_use=("보험료 얼마야?", "40세 남성 보험료 계산해줘"),
    when_not_to_use=("납입 플랜이 궁금하다 → plan_options 사용",),
    tags=("보험료", "산출"),
)

필드	임베딩 포함	역할
purpose	O	도구의 핵심 기능을 한 문장으로 설명
when_to_use	O	실제 사용자 발화 예시 → 검색 표면 확장
tags	O	도메인 키워드 → 클러스터링 보조
when_not_to_use	X	혼동 가능한 도구 안내 → LLM 최종 선택 시에만 사용

when_not_to_use를 임베딩에서 제외하는 이유: 타 도구 이름("premium_estimate 사용")이 포함되면 벡터가 오염됨. Tool-DE (Lu et al., 2025) ablation에서도 negative example 포함 시 성능이 저하됨.

3-3. Multi-Vector 인덱싱

각 ToolCard 필드를 별도 문서로 ChromaDB에 인덱싱하고, 검색 시 tool별 max score로 집계함. 단일 벡터로 합치면 여러 예시의 평균으로 희석되지만, 이 방식은 ColBERT 등 multi-vector 모델과 동일한 원리로 희석 없이 정확한 매칭이 가능함 (Pinecone).

---

4. 축 ② — Scalable Tool Architecture

4-1. 도구 추가가 운영 부담이 되지 않도록

새 Tool 추가 → Tool Card 작성 → 임베딩 자동 생성 → 즉시 검색 대상에 포함

방식	절차	서버 재시작
정적 등록	Tool 함수 + ToolCard → 서버 재시작	필요
런타임 핫리로드	Tool 함수 + API 호출	불필요

ToolRegistry가 동적 관리하고, 변경 시 ChromaDB 재인덱싱을 자동 트리거함.

4-2. 코드 변경 없이 운영 중 튜닝

Admin Dashboard(/admin/tools)에서 ToolCard를 수정하면 즉시 챗봇에 반영됨. 배치 Recall 평가와 LLM 분석을 내장하여, 수정 전후 성능 차이를 바로 확인할 수 있음.

Admin UI에서 when_to_use 문장 수정
    ↓  [저장 & 반영] 클릭
① 메모리 REGISTRY 업데이트 + ChromaDB 재인덱싱
② data/toolcard_overrides.json 저장 (서버 재시작 후에도 유지)
③ 버전 이력 기록 → 문제 시 롤백 가능

4-3. Validation — 감이 아닌 수치로 판단

scripts/eval_tool_recall.py로 Recall@k, MRR, Hit@1을 정량 측정함. Admin Dashboard 퀵 테스트 탭에서도 개별 도구의 배치 Recall 평가와 LLM 실패 분석을 수행할 수 있음.

python -m scripts.eval_tool_recall --compare    # k=1,3,5,7,10 비교표
python -m scripts.eval_tool_recall --verbose     # 오판 사례 상세

---

5. 결과

79개 테스트 쿼리(tool-call 64개 + no-call 15개) 평가 결과:

지표	k=1	k=3	k=5 (운영)	k=7	k=10
Recall@k	96.9%	100%	100%	100%	100%
Hit@1	96.9%	—	96.9%	—	96.9%
MRR	0.969	0.984	0.984	—	0.984
No-Call Acc	—	—	80.0%	—	80.0%

• k=1 미탐 2건: 유사 도구 경계 사례 (coverage_detail ↔ benefit_amount, renewal_projection ↔ renewal_notice)
• k=3부터 Recall 100% — 64개 tool-call 쿼리가 전부 Top-3 안에 포함됨
• no-call 오판 3건: 유사도 0.86~0.88로 경계에 걸리지만, Guardrail에서 사전 차단되므로 실운영에서는 Tool Search에 도달하지 않음

54개 → 5개로 90% 축소해도 Recall@5 = 100%, MRR = 0.98. 정확도를 유지하면서 비용과 지연을 동시에 줄임.

5-1. 멀티턴 시나리오 실행 결과

5개 TMR 실전 상담 시나리오를 구축하여 end-to-end 검증을 수행함.

#	시나리오	턴	핵심 검증 포인트	사용된 도구
1	기가입 계약자 암 진단 → 청구	4	계약 조회(2건 유지, 계약일·만료일·갱신일) → 직전 조회한 암보험 기준 청구 안내(가입 불가 아님) → 청구 필요 서류 → 기가입 기반 추가 보장 추천	customer_contract_lookup, event_eligibility_check, claim_required_forms, product_search
2	기가입 계약자 추가 상품 설계	4	계약 확인(55세·여성·3건 유지) → 치매 보장 추가 시 중복 아닌 상품 → 치매간병 vs 실속치매 55세 여성 보험료 비교 → 보유 3건 합산 월 보험료(맥락 사용)	customer_contract_lookup, product_search, premium_compare, premium_estimate
3	해지된 보험 부활 + 대안	4	유지/해지 구분(해지일 표시) → 부활 조건(3년·연체보험료 등) → 60세 여성 대안 암보험 → 유지 중 종신보험 보장 내용	customer_contract_lookup, underwriting_reinstatement_rule, product_search, coverage_summary
4	고위험 직업 + 유병력 심사	4	복합 조건(직업·병력) 인식 → 할증 직군 확인 → 첫날부터암보험 보장 상세 → 간편심사 건강보험	underwriting_precheck, underwriting_high_risk_job_check, coverage_detail, product_search
5	시니어 종합 설계	4	70세 아버지(남성) 사망·치아 상품 추천 → 건강해지는종신 연금전환 → 든든한실버치아 70세 가입·보장 → 직전 두 상품 합산 보험료(70세 남성)	product_search, coverage_summary, premium_estimate

계약자 정보 처리:

• 계약자 이름으로 customer_contract_lookup 호출 → 계약자ID·성별(남성/여성)·나이 + 보유 계약(유지/해지) 즉시 확인
• 계약 정보에 보험 용어 적용: 계약상태(유지·해지·실효·만기), 계약일, 만료일, 해지일, 갱신일
• 반환 데이터에서 전화번호 등 PII를 소스 레벨에서 필터링 (_safe_customer / _safe_contract)
• 기가입 상품에서 질병 진단 시 → 가입 불가가 아닌 보험금 청구 절차 안내로 전환
• 보유 계약 기반 중복 가입 여부 확인 후 추가 상품 추천
• 대화 내내 계약자 맥락 유지 (같은 ID/이름을 재요구하지 않음)

출력 품질 관리:

• 상품코드(B00...) 출력 가드레일에서 자동 제거
• 내부 도구명(snake_case) 출력 가드레일에서 자동 제거
• 면책 문구 중복 방지 (LLM 생성분이 있으면 가드레일 추가 생략)
• 응답 최대 7줄, 핵심 정보만 간결하게 전달

후속 단답 처리:

• "아버지" → 남성으로 인식, "어머니" → 여성으로 인식
• query_rewriter가 1~3글자 단답을 이전 맥락에 합쳐서 완전한 질문으로 재작성

5-2. 시나리오 턴별 검증 포인트 (멀티턴 품질 체크)

멀티턴 시나리오 실행 시 매 턴마다 아래를 확인하면, 맥락 이해·직전 응답 기반 답변 여부를 검증할 수 있음.

시나리오	턴	사용자 질문	직전 맥락	챗봇이 해야 할 일	검증 포인트
1. 김민수 암 진단	1	계약자 김민수님 계약 조회해줘	없음	customer_contract_lookup(이름=김민수)	계약 2건 유지(암+치아), 계약일·만료일 표기
1	2	갑상선암 진단받았는데 가입 중인 암보험으로 보험금 청구 가능해?	김민수 2건 유지(치아+암)	event_eligibility_check → 청구 안내(가입 불가 아님)	기가입 암보험 기준 청구 가능 여부·절차 안내
1	3	청구 절차랑 필요한 서류 알려줘	직전에 청구 가능 안내함	claim_guide	청구서류·방법·처리기간, 직전 대화 맥락 유지
1	4	지금 가입한 상품 외에 추가로 넣으면 좋을 보장 있어?	김민수 보유(치아·암)	중복 확인 후 추가 보장 추천	기가입 기반 중복 아닌 상품만 추천
2. 윤지은 추가 설계	1	계약자 윤지은님 계약 조회해줘	없음	customer_contract_lookup(이름=윤지은)	55세 여성, 3건 유지, 계약일·만료일·갱신일
2	2	치매 보장을 추가하고 싶은데, 지금 가진 상품이랑 안 겹치는 치매보험 있어?	윤지은 3건(간편건강·치아·종신)	product_search(치매) + 중복 여부 판단	치매 상품 2종, 기가입과 겹치지 않는 것만
2	3	치매간병보험이랑 실속치매보험 차이가 뭐야? 55세 여성 기준 보험료도 비교해줘	윤지은 55세 여성	coverage_summary + premium_estimate	55세 여성 기준 비교, 직전 턴 나이·성별 재사용
2	4	지금 유지 중인 세 계약 합산 월 보험료는 얼마쯤 돼?	윤지은 55세 여성, 3건	premium_estimate(55, F) 3건 각각 호출 후 합산	"조회할 수 없습니다" 금지. 3건 합계 제시
3. 최수진 부활	1	계약자 최수진님 계약 현황 알려줘	없음	customer_contract_lookup(이름=최수진)	유지 1건(종신) + 해지 1건(암), 해지일 표기
3	2	해지된 암보험 다시 부활할 수 있어? 조건이 뭐야?	최수진 해지된 암보험(해지일 2023-12-31)	underwriting_reinstatement_rule	부활 기한(해지일+3년), 연체보험료·면책 재적용 등
3	3	부활이 어려우면 60세 여성이 새로 가입할 수 있는 암보험 있어?	최수진 60세 여성	product_search(암) + 가입 조건	60세 여성 기준, 직전 맥락 나이·성별 사용
3	4	유지 중인 간편고지종신보험 보장 내용 자세히 알려줘	최수진 유지 1건 종신	coverage_detail	직전 조회한 종신보험 보장 상세(사망보험금·감액·해약환급금)
4. 택시기사+고혈압	1	48세 남성인데 택시기사야. 고혈압 약 복용 중이고 암보험 가입하고 싶대	없음	직업·유병력 파악	복합 질문 인식, 단계별 답변 가능 안내
4	2	택시기사면 직업 위험등급 때문에 보험료가 더 비싸지거나 거절될 수 있어?	48세 남성, 택시기사	underwriting_high_risk_job_check	할증 직군 확인, 보험료 영향 안내
4	3	첫날부터암보험은 가입 조건이랑 보장이 어떻게 돼?	직업 등급 + 고혈압	product_search, coverage_detail	첫날부터암보험 가입조건·보장, 고혈압·할증 맥락 유지
4	4	간편심사로 가입할 수 있는 건강보험도 있어?	48세 남성, 고혈압, 택시기사	product_search(간편심사 건강)	간편심사 상품 추천, 직전 맥락(직업·병력) 유지
5. 시니어 종합	1	70세 아버지인데 사망보장이랑 치아보험 둘 다 알아보고 싶대	없음	product_search(사망·치아)	70세 가능 상품 추천, '아버지'=남성 맥락
5	2	건강해지는종신보험도 70세에 가입 가능해? 보장 내용이랑 연금전환 조건 알려줘	70세, 직전 상품 맥락	coverage_summary	70세 가입 가능 확인, 보장·연금전환 조건
5	3	든든한실버치아보험은 70세에 보장 범위가 어떻게 돼?	70세	coverage_summary	70세 보장범위(충전·크라운), 직전 나이 재사용
5	4	방금 얘기한 두 상품 다 가입하면 월 보험료 합쳐서 얼마쯤 나와?	70세 남성(아버지), 직전 두 상품(종신·실버치아)	premium_estimate(70, M) 2회 호출 후 합산	직전 맥락 사용. 아버지→남성 자동 인식. "성별 필요" 반복 금지

공통 검증:

• 매 턴 답변이 직전 챗봇 응답·이전 턴 사용자 입력을 참조했는지(재요청·무시 없이) 확인
• 계약자 ID·이름을 이미 조회한 대화에서는 같은 정보를 다시 요구하지 말고, 필요한 추가 인자(나이·성별 등)만 이전 맥락에서 채워서 도구 호출

---

6. 구현 상세

6-1. LangGraph 5노드 파이프라인

START → [input_guardrail] → [query_rewriter] → [agent ↔ tools] → [output_guardrail] → END

노드	역할	소요 시간
input_guardrail	정규식(L1) + 임베딩(L2)으로 이상 요청 차단	<5ms
query_rewriter	"그거 얼마야?" 같은 후속질문을 이전 맥락으로 재작성	0~1s
agent	ChromaDB Top-K 검색 → LLM 도구 호출	1~5s
tools	ToolRegistry 동적 디스패치 → 도구 실행	10~100ms
output_guardrail	PII·금칙어·상품코드·도구명 제거 + 면책 문구 자동 추가	<2ms

쿼리 재작성은 Advanced RAG 핵심 기법인 Query Transformation에 해당함 (참고).

6-2. 상품공시실 PDF RAG

보험 상품공시실에서 12개 상품요약서 + 표준약관 + 회사 정보를 수집함. PyMuPDF로 텍스트 추출 → 500자 청크 → ChromaDB 인제스트(~1,400 벡터). 도구 데이터에 없는 약관 조항·면책 규정을 RAG가 보완함.

6-3. LLM 연동

항목	설명
시스템 프롬프트	12개 상품 목록이 PRODUCTS 딕셔너리에서 동적 반영됨. 도구 체이닝 규칙도 포함
사고과정 필터링	Qwen3 <think> 블록을 스트리밍 중 실시간 필터링. 사용자에게 최종 답변만 노출
도구 레벨 가드	나이/성별 등 필수값 미제공 시 needs_user_input 반환 → LLM이 되묻는 구조

6-4. 서빙

방식	설명	대상
FastAPI (REST/SSE)	웹 Chat UI + REST API + Admin Dashboard	일반 사용자·운영자
MCP Server (SSE/stdio)	도구 54 + 리소스 17 + 프롬프트 8 노출	Claude Desktop, Cursor 등

---

7. 운영

7-1. 도구 추가 체크리스트

새 도구를 추가할 때 아래 순서를 따름.

① 도구 함수 작성 — app/tools/ 아래 해당 모듈에 @tool 함수를 추가함. tool.name이 이후 모든 연동의 키가 됨.

② ToolCard 등록 — app/tool_search/tool_cards.py의 _CARDS 리스트에 카드를 추가함.

필드	규칙
name	tool.name과 정확히 일치해야 함
purpose	한 문장으로 도구 기능을 설명
when_to_use	실제 사용자 발화 패턴으로 작성
when_not_to_use	혼동 도구를 → tool_name 사용 형식으로 명시
tags	도메인 키워드 (필터링용)

③ 혼동 쌍 관리 — 기능이 유사한 도구가 있으면 양방향으로 when_not_to_use와 CONFUSION_PAIRS에 등록함.

④ 검증 — python -m scripts.eval_tool_recall --compare로 Recall@k 확인.

연동 지점	자동/수동	비고
ChromaDB 임베딩	자동	서버 시작 시 해시 비교 → 변경분만 재인덱싱
LLM tool description	자동	when_not_to_use가 description에 자동 주입
도구 함수	수동	카드만 있고 함수가 없으면 동작하지 않음
CONFUSION_PAIRS	수동	유사 도구 존재 시 반드시 등록

7-2. Admin Dashboard

CLI 대신 브라우저(/admin/tools)에서 도구 레지스트리를 관리하는 웹 UI임.

기능	설명
대시보드	도구 수, ChromaDB 벡터 수, Registry 버전, 상태 모니터링
ToolCard 편집	purpose, when_to_use, when_not_to_use, tags 수정 → 즉시 반영
버전 이력	변경 이력 조회, Diff 비교, 특정 버전으로 롤백
퀵 테스트	실시간 쿼리 검색, 배치 Recall 평가, LLM 실패 분석
도구 해제	확인 모달 → DELETE → ChromaDB 벡터 즉시 삭제
모듈 핫리로드	8개 모듈 선택 → 코드 변경분 서버 재시작 없이 반영

퀵 테스트 탭에서 수정 전후 Recall@k를 비교하고, 실패 쿼리에 대해 LLM이 ToolCard 개선안을 제안하므로 코드 변경 없이 검색 정확도를 튜닝할 수 있음.

7-3. 런타임 API

curl http://localhost:8080/api/tools                              # 전체 도구 목록
curl -X DELETE http://localhost:8080/api/tools/premium_estimate    # 도구 해제
curl -X POST http://localhost:8080/api/tools/reload-module/premium # 모듈 핫리로드

---

8. 기술 선택 근거

8-1. 벡터 DB — 8개 후보 비교 후 ChromaDB 선택

이 프로젝트는 무료 오픈소스만 사용 가능하고, HF Spaces Docker 단일 컨테이너 배포가 필수 조건임. 이 조건으로 8개 벡터 DB를 비교·필터링함.

Step 1. 유료/클라우드 전용 제외

DB	제외 사유
Pinecone	완전 관리형(SaaS 전용), 자체 호스팅 불가. 프로덕션 $50/월 최소 과금 (Pinecone Pricing)
MongoDB Atlas Search	벡터 검색은 Atlas 클라우드 전용. 연간 $5,000~$70,000 (Firecrawl). 로컬 MongoDB CE에는 벡터 검색 미지원

Step 2. 오픈소스이나 인프라 과잉인 후보 제외

DB	라이선스	제외 사유
Milvus	Apache 2.0	프로덕션 분산 모드에 K8s 필수. Standalone 가능하나 etcd+MinIO 의존성. ~1,800 벡터에 오버엔지니어링 (dev.to)
OpenSearch	Apache 2.0	JVM 기반 검색 엔진. 메모리 1GB+ 필요, Docker 내 Java 프로세스 추가 부담. 벡터 검색은 knn_vector 필드로 지원하나, 검색 엔진 수준 운영 복잡도 (Firecrawl)
Redis Stack	SSPL / RSALv2	2024년부터 Redis 라이선스가 SSPL로 변경되어 순수 오픈소스가 아님. 벡터 검색은 RediSearch 모듈에 의존. 별도 Redis 서버 프로세스 필요 (Redis Blog)

Step 3. 최종 후보 — ChromaDB vs pgvector

기준	ChromaDB	PostgreSQL + pgvector
라이선스	Apache 2.0	PostgreSQL License
설치	pip install chromadb	PostgreSQL 서버 + CREATE EXTENSION vector
아키텍처	임베디드 (in-process)	별도 DB 서버 프로세스
Docker 배포	추가 프로세스 없음	PostgreSQL 데몬 필요
메타데이터 필터링	O (where 절)	O (SQL WHERE)
실시간 upsert	O	O
영속성	O (SQLite + parquet)	O
한국어 커스텀 임베딩	직접 전달 가능	직접 전달 가능
운영 복잡도	최소 (파일 기반)	중간 (DB 관리 필요)

ChromaDB를 선택한 이유:

1. Docker 단일 컨테이너 적합성 — HF Spaces는 하나의 Docker 컨테이너로 서빙함. ChromaDB는 임베디드 모드로 FastAPI 프로세스 안에서 동작하므로 별도 DB 프로세스가 필요 없음. pgvector는 PostgreSQL 데몬을 함께 띄워야 함.

2. 인프라 제로 — pip install chromadb 한 줄로 끝남. DB 설정, 스키마 생성, 커넥션 풀 관리가 없음.

3. 실시간 upsert — ToolCard 수정 시 서버 재시작 없이 즉시 벡터를 갱신해야 함. ChromaDB는 collection.upsert()로 해결됨. FAISS는 인덱스 전체를 rebuild 해야 함.

4. 규모 적합성 — 도구 54개 × 필드 7개 = ~1,800 벡터. 10M 벡터 미만 프로토타입에서 ChromaDB 권장 (Firecrawl) (dev.to).

5. LangChain 생태계 통합 — LangGraph/LangChain과 네이티브 연동이 검증되어 있음 (TrueFoundry).

스케일 아웃 시나리오: 벡터가 10M을 넘거나 멀티노드 HA가 필요해지면 Qdrant(Rust 기반, 고성능 필터링) 또는 Milvus(K8s 분산)로 마이그레이션하는 것이 일반적 경로임 (Firecrawl).

8-2. 임베딩 모델 — multilingual-e5-large

기준	e5-base	e5-large	OpenAI ada-002
Kor-IR NDCG@10	—	80.35 (OSS 최상위)	—
Mr. TyDi 한국어 MRR@10	55.8	61.6 (+10%)	—
비용	무료 로컬	무료 로컬	$0.13/1M tokens
추론 속도	~5ms	~10ms	네트워크 의존

Kor-IR 벤치마크 오픈소스 최상위. 비대칭 검색 시 "query: " / "passage: " 프리픽스 필수 (논문). 로컬 추론(~10ms/쿼리)으로 외부 API에 의존하지 않음 (모델 카드).

8-3. Tool Card 학술 근거

출처	핵심 기여
Tool-DE (Lu et al., 2025)	도구 문서 확장으로 NDCG@10 +6~7ppt, Recall@10 +10ppt
Re-Invoke (Google, EMNLP 2024)	합성 쿼리 생성으로 nDCG@5 유의미 향상
ToolBench (ICLR 2024)	도구 수 증가 시 cross-reference가 정확도 저하를 방지
RAG-MCP (WRITER, 2025)	메타데이터 기반 인덱싱 → 토큰 50%+ 절감

---

9. 알려진 한계 및 고도화 방향

한계	현상	방향
when_to_use 오버핏	product_search에 타 도구 영역 발화가 임베딩을 희석함	순수 상품 검색 발화만 유지
cross-reference 누락	renewal_projection ↔ renewal_notice 양방향 가이드 부재	when_not_to_use 양방향 보완
수동 작성 한계	54개 × ~7개 = ~380개 when_to_use를 수동 관리 중	Re-Invoke 방식 LLM 합성 쿼리 자동 생성
정적 no-call 임계값	tool-call min(0.867)과 no-call max(0.877)이 겹침	Reranker 2단계 도입

---

Quick Start

# 1. 설치
python -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 환경변수 (.env)
OPENROUTER_API_KEY=sk-or-v1-your-key
OPENROUTER_MODEL=qwen/qwen3-14b
EMBEDDING_MODEL=intfloat/multilingual-e5-large

# 3. ChromaDB 초기화 (최초 1회)
python scripts/init_vectordb.py

# 4. 서버 실행
python run.py                         # FastAPI → http://localhost:8080
python run_mcp.py                     # MCP Server
python run_mcp.py --inspect           # MCP Inspector UI

# 5. 도구 라우팅 평가
python -m scripts.eval_tool_recall --compare

---

프로젝트 구조

app/
├── main.py                 # FastAPI (REST/SSE + think 필터링)
├── config.py               # Settings + 임베딩 모델 싱글톤
├── graph/                  # LangGraph 5노드 파이프라인
│   ├── builder.py          #   그래프 빌드 + 동적 도구 디스패치
│   ├── nodes.py            #   agent 노드 (ChromaDB 라우팅 + LLM)
│   ├── guardrails.py       #   입력(L1+L2) / 출력 가드레일
│   └── query_rewrite.py    #   후속질문 재작성
├── tools/ (54개, 8모듈)    # product / premium / coverage / underwriting
│   ├── __init__.py         #   ToolRegistry (핫리로드)
│   └── data.py             #   12개 상품 데이터 + 시스템 프롬프트
├── tool_search/            # ChromaDB 멀티벡터 라우팅
│   ├── embedder.py         #   임베딩 + Top-K 검색
│   ├── tool_cards.py       #   54개 ToolCard
│   └── toolcard_store.py   #   ToolCard JSON 영속화 + 버전 이력
├── rag/                    # 상품공시실 PDF RAG
│   ├── retriever.py        #   인제스트 + 검색
│   └── splitter.py         #   한국어 문장경계 청크 분할
└── mcp_server/             # MCP 프로토콜 서버 + Inspector

templates/
├── index.html              # 챗봇 Chat UI (상품 카탈로그, 시나리오)
└── admin_tools.html        # Tool Admin Dashboard

scripts/
├── init_vectordb.py        # ChromaDB 초기화
└── eval_tool_recall.py     # Recall@k / MRR 평가

도구 카탈로그 (54개)

모듈	수	주요 기능
product	10	상품 검색/조회/비교, 특약, FAQ
premium	8	보험료 산출/비교, 플랜, 갱신 추정
coverage	9	보장 요약/상세, 급부 금액
underwriting	12	가입 심사, 녹아웃 룰, 직업 위험도
compliance	6	준법 멘트, 금칙어, PII 마스킹
claims	4	청구 절차, 서류, 계약관리
customer_db	3	고객 검색, 계약 조회
rag_tools	2	약관/요약서 RAG 검색

---

기술 스택

카테고리	기술	역할
LLM 오케스트레이션	LangGraph	ReAct 그래프, 멀티턴, 조건부 분기
LLM	OpenRouter (qwen/qwen3-14b)	다중 모델 라우팅
벡터 DB	ChromaDB	도구 라우팅 + RAG 검색
임베딩	multilingual-e5-large (1024d)	한국어 비대칭 검색
API 서버	FastAPI	REST + SSE 스트리밍
MCP 서버	FastMCP	Claude Desktop/Cursor 연동
PDF 파싱	PyMuPDF	약관/요약서 텍스트 추출
고객 DB	SQLite3	고객/계약 시뮬레이션

---

References

주제	출처
도구 수 증가 시 정확도 저하	How many tools can an AI Agent have?
RAG-MCP: 도구 검색 후 LLM에 전달	WRITER Engineering
Tool Document Expansion (Tool-DE)	arXiv 2510.22670
합성 쿼리 기반 도구 검색 (Re-Invoke)	EMNLP 2024
대규모 도구 벤치마크 (ToolBench)	ICLR 2024
벡터 DB 비교 (2025)	Firecrawl · dev.to · TrueFoundry
벡터 DB 가격 비교	Actian · Pinecone Pricing
Redis 벡터 DB 비교	Redis Blog
한국어 IR 벤치마크 (Kor-IR)	GitHub
multilingual-e5-large	Hugging Face · arXiv 2402.05672
Multi-vector retrieval	Pinecone
Query Rewriting / Advanced RAG	Prompting Guide
LangGraph 공식 문서	LangChain