# 智保通第二阶段后端 本目录是智保通第二阶段“知识服务与数据分析”的统一后端。项目完整继承第一阶段的智能投保、订单、支付、保单、推广归因和后台治理能力，并在同一个 Agent Kernel 上增加 **Agentic RAG、客户长期记忆、多模态材料识别、保单服务和运营趋势分析**。 后端采用 Python 3.12、FastAPI 和 `src/zbt` 可安装包布局，通过 uv 管理依赖和虚拟环境。 ## 1. 第二阶段新增能力 ### H5 客户端 - Agentic RAG 保险咨询：复杂问题拆分、查询改写、多轮检索和证据聚合。 - 有依据时展示知识来源；知识库未明确时拒绝推测。 - 客户长期记忆：保存明确表达的保障偏好，在新会话中召回并支持删除。 - 敏感信息保护：手机号、身份证号、银行卡号等内容禁止写入长期记忆。 - 保单服务：从保障中的保单发起申请，上传图片并使用多模态模型识别材料。 - 服务记录：查看申请状态和运营处理结果。 ### 运营管理端 - 知识中心：`上传/创建 → 索引 → 检索测试 → 发布`。 - 检索测试记录持久化；发布前必须存在有效的检索测试记录。 - 服务申请中心：查看原始材料、识别字段和识别可信度，并进行受理或不受理处理。 - 运营智能体：分析订单量、订单保费、有效保单量和有效保单保费。 - 趋势分析：支持最近 7、30、90 天，并按日期或产品生成图表数据。 - Agent 历史会话和运行记录按用户、人格与权限范围隔离。 ## 2. Agent 技术架构 项目保留“一个内核、两种人格”的设计： - `customer`：客户保障顾问，负责保险咨询、投保引导、知识问答和客户记忆。 - `operation`：运营数据助手，负责业务指标、趋势和推广归因分析。 - Agent Kernel：统一管理 Persona、Skill、Tool 白名单、策略校验、结构化 UI Block、运行事件和异常边界。 主要调用链： ```text HTTP 请求 → AgentThreadService → Agent Kernel → Persona + Skill + Policy → LangChain create_agent → DeepSeek → 受控业务 Tool / 知识检索 Tool → 结构化响应 → MySQL 运行记录 + Redis 热状态 + LangSmith Trace ``` 知识检索链路： ```text 问题拆分与改写 → BGE-M3 向量化 → Milvus 向量召回 + 关键词召回 → BGE Reranker 重排 → 证据聚合与去重 → 带来源回答或拒绝推测 ``` 医疗材料识别通过阿里云百炼兼容接口调用 `qwen3.5-plus`，识别结果作为候选字段保存，不能替代用户确认和运营处理。 ## 3. 目录结构 ```text backend/ ├── src/zbt/ │ ├── api/ # FastAPI 路由、鉴权和响应封装 │ ├── commands/ # 数据、知识库和评测命令 │ ├── core/ # 配置、安全、错误和公共能力 │ ├── domains/ # 投保、Agent、知识、记忆、服务申请等领域 │ ├── harness/ # Agent 内核、Persona、Skill、Policy 和结构协议 │ ├── infrastructure/ # MySQL、Redis、Milvus 和外部模型适配器 │ └── main.py # FastAPI 应用装配入口 ├── migrations/ # Core、Agent、Analytics 三库迁移 ├── evals/ # 真实模型评测数据 ├── tests/ # 自动化测试 ├── var/ # 本地服务材料等运行文件 ├── alembic.ini ├── pyproject.toml └── uv.lock ``` ## 4. 运行环境 需要提前安装并启动： - Python 3.12 - uv - MySQL 8 - Redis - Milvus - Node.js 22 和 pnpm（启动前端时需要） 后端读取 `backend/.env`。主要配置包括： | 配置类别 | 环境变量 | |---|---| | MySQL | `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、三个 `MYSQL_*_DATABASE` | | Redis | `REDIS_URL`、`REDIS_PREFIX` | | Milvus | `MILVUS_URI`、`MILVUS_TOKEN`、`MILVUS_COLLECTION_PREFIX` | | 向量模型 | `BGE_M3_MODEL_PATH`、`BGE_M3_DEVICE`、`BGE_RERANKER_MODEL_PATH`、`BGE_RERANKER_DEVICE` | | 文本模型 | `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL` | | 多模态模型 | `DASHSCOPE_API_KEY`、`DASHSCOPE_BASE_URL`、`DASHSCOPE_VISION_MODEL` | | 可观测性 | `LANGSMITH_TRACING`、`LANGSMITH_API_KEY`、`LANGSMITH_ENDPOINT`、`LANGSMITH_PROJECT` | | 安全配置 | `JWT_ACCESS_SECRET`、`JWT_REFRESH_SECRET`、`FIELD_ENCRYPTION_KEY` | 如尚未创建 `.env`： Windows PowerShell： ```powershell Set-Location backend New-Item -ItemType File -Path .env -ErrorAction SilentlyContinue notepad .env ``` macOS： ```bash cd backend touch .env open -e .env ``` 不要将包含真实数据库密码和模型密钥的 `.env` 提交到 Git。 ## 5. 首次初始化 第二阶段首次运行所需的数据库快照、Milvus 初始化脚本和启动说明统一保存在： [../database/项目启动文档与数据准备.zip](../database/项目启动文档与数据准备.zip) 请将压缩包解压到当前仓库根目录，然后打开相对路径 `../项目启动文档与数据准备/智保通第一、二、三阶段启动指南.md`，按照“第二阶段：知识服务与运营分析”一节执行。该指南及配套脚本会自动定位仓库根目录，不依赖 `harness_zbt` 或其他固定目录名。 压缩包中的第二阶段 `mysql.sql` 只初始化 `insurance_s2_core`、`insurance_s2_agent` 和 `insurance_s2_analytics`，并已包含第一阶段继承数据。不要再使用项目内旧 SQL，也不要额外执行 Alembic、`seed`、`inherit_stage_one` 或 `build_analytics`。 ## 6. 启动项目 ### 6.1 Windows 一次启动 在项目根目录执行： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 ``` 该脚本同时启动 FastAPI、H5 和运营管理后台。 ### 6.2 Windows 分别启动 后端： ```powershell Set-Location backend uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload ``` H5： ```powershell Set-Location frontend pnpm dev:h5 ``` 管理后台： ```powershell Set-Location frontend pnpm dev:admin ``` ### 6.3 macOS / Linux 一次启动 ```bash ./scripts/dev.sh ``` 不要在 `frontend/apps/h5` 或 `frontend/apps/admin` 目录执行 `pnpm dev:h5`、`pnpm dev:admin`；这两个命令属于前端 workspace 根目录。 ### 6.4 运行地址 - H5： - 管理后台： - Swagger： - OpenAPI JSON： - 健康检查： 测试账号： - H5：`18800000001`，验证码 `147258` - 管理员：`admin / zaq1XSW@` - 运营人员：`operator01 / zaq1XSW@` - 审核人员：`reviewer01 / zaq1XSW@` ## 7. 单独启动后端 如果只调试 API，可只运行 FastAPI。 Windows PowerShell： ```powershell Set-Location backend uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload ``` macOS： ```bash cd backend uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload ``` 后端启动时会预加载 BGE-M3 和 BGE Reranker。首次下载或首次载入模型时，终端可能长时间显示 Hugging Face 下载和权重加载信息；出现 `Application startup complete` 后再测试知识问答。 ## 8. 真实模型评测 先启动项目，再在 `backend` 目录执行。 Windows PowerShell： ```powershell uv run python -m zbt.commands.evaluate_agents --suite smoke uv run python -m zbt.commands.evaluate_agents --suite full ``` macOS： ```bash uv run python -m zbt.commands.evaluate_agents --suite smoke uv run python -m zbt.commands.evaluate_agents --suite full ``` 评测会调用真实文本模型、真实业务 Tool 和真实 HTTP 接口。启用 LangSmith 后，可在对应项目中查看运行 Trace 和评测记录。 ## 9. 测试和代码检查 Windows PowerShell（在项目根目录执行）： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1 ``` macOS / Linux（在项目根目录执行）： ```bash ./scripts/test.sh ``` 普通代码检查不会替代真实模型评测。涉及 Agent 决策、知识引用和 Tool 调用顺序的行为，应另外运行第 8 节的评测命令。 ## 10. 数据库迁移命令 当前推荐使用完整 SQL 快照进行首次初始化。只有在开发新的表结构变更时，才需要手动执行 Alembic。 Windows PowerShell 与 macOS 均在 `backend` 目录执行： ```bash uv run alembic -c alembic.ini --name alembic_core upgrade head uv run alembic -c alembic.ini --name alembic_agent upgrade head uv run alembic -c alembic.ini --name alembic_analytics upgrade head ``` 已经发布的迁移文件不要直接修改；表结构发生变化时应创建新的 revision。 ## 11. 构建后端安装包 Windows PowerShell： ```powershell Set-Location backend uv build ``` macOS： ```bash cd backend uv build ``` 构建结果生成在 `backend/dist`，包括 wheel 和源码包。日常开发继续使用 `uv sync --locked` 和 `uv run`，无需手工安装构建产物。 ## 12. 相关文档 - `../README.md`：第二阶段项目总览和快速启动。 - `../docs/第二阶段新增能力与测试.md`：第二阶段新增业务及建议测试场景。 - `../docs/智保通第一、二阶段启动指南.md`：两个阶段的完整启动说明。 项目根目录中的每个 `scripts/*.ps1` 均提供同名 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。