内容
# 保险伴侣代理 MVP
Capstone 原型，用于公共数据健康保险伴侣。该应用程序帮助用户搜索市场计划，比较结构化的计划事实，并通过 ADK 风格的多代理 RAG 系统获得纯英文解释。
## 演示视频
[](https://youtu.be/ydxiY-pUycE)
点击上面的预览，观看 YouTube 上的 Gemini TTS 解说演示视频。
## 问题陈述
健康保险计划购物很困难，因为用户必须同时比较保费、免赔额、自付上限、金属级别、服务区域和受益术语。普通的聊天机器人可以解释术语，但也可能虚构计划事实。普通的数据库搜索可以筛选计划，但无法解释保险语言。
该项目结合了两者的优点：
- 结构化搜索用于事实计划筛选
- RAG 检索用于保险解释
- LLM 生成用于初学者友好的答案
- 计划、发行人、金属级别、服务区域和受益概念之间的知识图链接
- 用于外部代理/工具客户端的 MCP 工具
- 用于提示注入、私人数据、凭证和受监管建议请求的 安全防护措施
## 数据集来源
主要数据集：
- CMS 市场公共使用文件，2026
- 计划属性 PUF
- 费率 PUF
- 受益和成本分担 PUF
- 服务区域 PUF
该项目不提交原始或处理过的 CMS 数据。队友使用以下脚本在本地重建数据。
## 架构
```text
用户问题
-> 安全代理：阻止私人数据、凭证、提示注入、受监管建议
-> 计划代理：选择结构化搜索、RAG 检索、图、答案合成
-> 计划搜索代理：使用 DuckDB SQL 搜索处理过的 CMS 计划事实
-> 检索代理：TF-IDF 关键词检索 + SVD 向量检索
-> 知识图代理：总结计划/发行人/金属/服务区域关系
-> 答案合成代理：提示生成器 + Mistral 聊天完成
-> 答案 + 代理跟踪 + 安全决策 + 计划表 + 引文
```
## 工具
- Python 用于应用程序和数据管道
- pandas 用于 CMS CSV 处理
- DuckDB 用于结构化计划搜索
- scikit-learn TF-IDF 用于关键词检索
- scikit-learn TruncatedSVD 用于本地语义检索
- Mistral API 用于答案生成
- Streamlit 用于 UI
- networkx 用于知识图层
- stdio JSON-RPC MCP 服务器用于工具暴露
## 设置
```powershell
cd "C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local"
python -m pip install -r requirements.txt -t .deps
copy .env.example .env
```
编辑 `.env`:
```env
MISTRAL_API_KEY=你的密钥
MISTRAL_BASE_URL=https://api.mistral.ai/v1/chat/completions
MISTRAL_MODEL=mistral-small-latest
```
永远不要提交 `.env`。
## 构建 CMS 数据
```powershell
$env:PYTHONPATH="C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\.deps"
python scripts\download_cms_pufs.py --year 2026 --datasets plan_attributes rates benefits service_areas
python scripts\build_cms_processed.py --year 2026 --sample-rows 250000
```
在 MVP 稳定时使用所有行：
```powershell
python scripts\build_cms_processed.py --year 2026 --sample-rows 0
```
生成本地文件：
```text
data/processed/plans.csv
data/processed/benefits.csv
data/processed/service_areas.csv
data/processed/docs.csv
```
## 运行 CLI 烟雾测试
```powershell
$env:PYTHONPATH="C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\.deps;C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\app"
python app\cli.py
```
CLI 打印代理跟踪、答案、匹配计划和检索的文档。
## 运行 Streamlit UI
```powershell
$env:PYTHONPATH="C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\.deps;C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\app"
python -m streamlit run app\streamlit_app.py --global.developmentMode false --server.address 127.0.0.1 --server.port 8501
```
UI 显示：
- 计划和图指标
- 过滤器
- 代理跟踪
- 安全决策
- 答案
- 结构化计划表
- 检索的文档
## 运行评估
```powershell
$env:PYTHONPATH="C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\.deps;C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\app"
python evaluation\run_eval.py
```
评估检查：
- 结构化计划搜索返回结果
- 检索找到免赔额文档
- 代理跟踪包括计划搜索和检索代理
- 阻止提示注入
- 阻止私人客户端/策略数据请求
- 图摘要不为空
## 运行 MCP 服务器烟雾测试
```powershell
$env:PYTHONPATH="C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\.deps;C:\Users\ravja\OneDrive\Documents\New project\insurance-copilot-local\app"
python scripts\smoke_mcp.py
```
`mcp_server.py` 暴露的 MCP 工具：
- `search_plans`
- `retrieve_terms`
- `summarize_graph`
- `answer_question`
## Docker
```powershell
docker build -t insurance-copilot .
docker run --rm -p 8501:8501 --env MISTRAL_API_KEY=$env:MISTRAL_API_KEY insurance-copilot
```
## RAG 设计
应用程序故意将事实与解释分开。
结构化事实使用 DuckDB：
- 状态
- 县/服务区域
- 金属级别
- 每月保费
- 免赔额选项
- 自付上限选项
解释使用检索：
- 什么是免赔额
- 什么是保费
- 什么是金属级别
- CMS PUF 文件包含什么
LLM 接收两个来源，并被指示不要发明缺少的计划细节。
## 知识图层
第一个图版本建模：
- 计划 -> 发行人
- 计划 -> 金属级别
- 计划 -> 状态
- 计划 -> 服务区域
- 计划 -> 免赔额选项
- 计划 -> 自付上限选项
图从 `app/knowledge_graph.py` 中的 `plans.csv` 构建。它使用 `networkx`，如果安装了，则使用，如果没有，则使用小型本地图类。
## 当前限制
- 县匹配目前仅支持小型内置县到 FIPS 映射。
- 免赔额和自付值可能因计划变体/CSR 级别而异，因此应用程序显示选项而不是一个保证值。
- 保费使用 40 岁费率作为简单的可比较估计。
- 这不是财务、法律或医疗建议。
- 当前检索语料库很小；应该添加更多官方 CMS 和词汇文档。
- 多代理层是 ADK 风格的，在 Python 中显式。如果提交需要官方 Google ADK 运行时，请添加该包装器作为最终集成层。
## 未来改进
- 添加完整的县名称到 FIPS 查找。
- 添加计划变体和 CSR 级别选择。
- 添加更丰富的官方保险词汇文档。
- 添加评估问题和预期答案。
- 添加数据处理和搜索筛选的自动化测试。
- 如果文档语料库变大，请用持久向量数据库替换本地向量检索。
