---
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 토큰이 소비됨 [(참고)](https://achan2013.medium.com/how-many-tools-functions-can-an-ai-agent-has-21e0a82b7847).
"전부 넘기지 말고 필요한 것만 검색해서 넘기자" — 이것이 RAG-MCP 패턴의 핵심임 [(참고)](https://writer.com/engineering/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**를 작성하여 임베딩 표면을 확장함.

```python
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)](https://arxiv.org/abs/2510.22670) ablation에서도 negative example 포함 시 성능이 저하됨.

### 3-3. Multi-Vector 인덱싱

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

---

## 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 실패 분석을 수행할 수 있음.

```bash
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에 해당함 [(참고)](https://www.promptingguide.ai/research/rag).

### 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

```bash
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)](https://www.pinecone.io/pricing/) |
| **MongoDB Atlas Search** | 벡터 검색은 Atlas 클라우드 전용. 연간 $5,000~$70,000 [(Firecrawl)](https://www.firecrawl.dev/blog/best-vector-databases). 로컬 MongoDB CE에는 벡터 검색 미지원 |

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

| DB | 라이선스 | 제외 사유 |
|----|---------|-----------|
| **Milvus** | Apache 2.0 | 프로덕션 분산 모드에 K8s 필수. Standalone 가능하나 etcd+MinIO 의존성. ~1,800 벡터에 오버엔지니어링 [(dev.to)](https://dev.to/pascal_cescato_692b7a8a20/from-zero-to-1-b-vectors-the-2025-no-bs-picking-guide-4k9o) |
| **OpenSearch** | Apache 2.0 | JVM 기반 검색 엔진. 메모리 1GB+ 필요, Docker 내 Java 프로세스 추가 부담. 벡터 검색은 knn_vector 필드로 지원하나, 검색 엔진 수준 운영 복잡도 [(Firecrawl)](https://www.firecrawl.dev/blog/best-vector-databases) |
| **Redis Stack** | SSPL / RSALv2 | 2024년부터 Redis 라이선스가 SSPL로 변경되어 순수 오픈소스가 아님. 벡터 검색은 RediSearch 모듈에 의존. 별도 Redis 서버 프로세스 필요 [(Redis Blog)](https://redis.io/blog/best-open-source-vector-databases-comparison/) |

#### 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)](https://www.firecrawl.dev/blog/best-vector-databases) [(dev.to)](https://dev.to/pascal_cescato_692b7a8a20/from-zero-to-1-b-vectors-the-2025-no-bs-picking-guide-4k9o).

5. **LangChain 생태계 통합** — LangGraph/LangChain과 네이티브 연동이 검증되어 있음 [(TrueFoundry)](https://www.truefoundry.com/blog/best-vector-databases).

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

### 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 벤치마크](https://github.com/Atipico1/Kor-IR) 오픈소스 최상위.
비대칭 검색 시 `"query: "` / `"passage: "` 프리픽스 필수 [(논문)](https://arxiv.org/abs/2402.05672).
로컬 추론(~10ms/쿼리)으로 외부 API에 의존하지 않음 [(모델 카드)](https://huggingface.co/intfloat/multilingual-e5-large).

### 8-3. Tool Card 학술 근거

| 출처 | 핵심 기여 |
|------|-----------|
| [Tool-DE (Lu et al., 2025)](https://arxiv.org/abs/2510.22670) | 도구 문서 확장으로 NDCG@10 +6~7ppt, Recall@10 +10ppt |
| [Re-Invoke (Google, EMNLP 2024)](https://arxiv.org/abs/2408.01875) | 합성 쿼리 생성으로 nDCG@5 유의미 향상 |
| [ToolBench (ICLR 2024)](https://arxiv.org/abs/2307.16789) | 도구 수 증가 시 cross-reference가 정확도 저하를 방지 |
| [RAG-MCP (WRITER, 2025)](https://writer.com/engineering/rag-mcp/) | 메타데이터 기반 인덱싱 → 토큰 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

```bash
# 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](https://langchain-ai.github.io/langgraph/) | ReAct 그래프, 멀티턴, 조건부 분기 |
| LLM | [OpenRouter](https://openrouter.ai/) (qwen/qwen3-14b) | 다중 모델 라우팅 |
| 벡터 DB | [ChromaDB](https://www.trychroma.com/) | 도구 라우팅 + RAG 검색 |
| 임베딩 | [multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large) (1024d) | 한국어 비대칭 검색 |
| API 서버 | [FastAPI](https://fastapi.tiangolo.com/) | REST + SSE 스트리밍 |
| MCP 서버 | [FastMCP](https://github.com/jlowin/fastmcp) | Claude Desktop/Cursor 연동 |
| PDF 파싱 | [PyMuPDF](https://pymupdf.readthedocs.io/) | 약관/요약서 텍스트 추출 |
| 고객 DB | SQLite3 | 고객/계약 시뮬레이션 |

---

## References

| 주제 | 출처 |
|------|------|
| 도구 수 증가 시 정확도 저하 | [How many tools can an AI Agent have?](https://achan2013.medium.com/how-many-tools-functions-can-an-ai-agent-has-21e0a82b7847) |
| RAG-MCP: 도구 검색 후 LLM에 전달 | [WRITER Engineering](https://writer.com/engineering/rag-mcp/) |
| Tool Document Expansion (Tool-DE) | [arXiv 2510.22670](https://arxiv.org/abs/2510.22670) |
| 합성 쿼리 기반 도구 검색 (Re-Invoke) | [EMNLP 2024](https://arxiv.org/abs/2408.01875) |
| 대규모 도구 벤치마크 (ToolBench) | [ICLR 2024](https://arxiv.org/abs/2307.16789) |
| 벡터 DB 비교 (2025) | [Firecrawl](https://www.firecrawl.dev/blog/best-vector-databases) · [dev.to](https://dev.to/pascal_cescato_692b7a8a20/from-zero-to-1-b-vectors-the-2025-no-bs-picking-guide-4k9o) · [TrueFoundry](https://www.truefoundry.com/blog/best-vector-databases) |
| 벡터 DB 가격 비교 | [Actian](https://www.actian.com/blog/databases/the-hidden-cost-of-vector-database-pricing-models/) · [Pinecone Pricing](https://www.pinecone.io/pricing/) |
| Redis 벡터 DB 비교 | [Redis Blog](https://redis.io/blog/best-open-source-vector-databases-comparison/) |
| 한국어 IR 벤치마크 (Kor-IR) | [GitHub](https://github.com/Atipico1/Kor-IR) |
| multilingual-e5-large | [Hugging Face](https://huggingface.co/intfloat/multilingual-e5-large) · [arXiv 2402.05672](https://arxiv.org/abs/2402.05672) |
| Multi-vector retrieval | [Pinecone](https://www.pinecone.io/blog/cascading-retrieval-with-multi-vector-representations/) |
| Query Rewriting / Advanced RAG | [Prompting Guide](https://www.promptingguide.ai/research/rag) |
| LangGraph 공식 문서 | [LangChain](https://langchain-ai.github.io/langgraph/) |