|
@@ -0,0 +1,96 @@
|
|
|
|
|
+# 智保通（第二阶段：知识服务与数据分析）
|
|
|
|
|
+
|
|
|
|
|
+第二阶段完整继承智能投保业务，并增加保险知识检索、知识库管理、多模态材料识别和服务申请能力。系统仍由本地 H5 公众号模拟器、运营管理后台和统一 FastAPI 后端组成。
|
|
|
|
|
+
|
|
|
|
|
+## 项目结构
|
|
|
|
|
+
|
|
|
|
|
+```text
|
|
|
|
|
+02-zhibaotong-knowledge-services-analytics/
|
|
|
|
|
+├── backend/ # FastAPI、Agent Harness、业务领域与数据访问
|
|
|
|
|
+├── frontend/
|
|
|
|
|
+│ └── apps/
|
|
|
|
|
+│ ├── h5/ # 本地 H5 公众号模拟器
|
|
|
|
|
+│ └── admin/ # 运营管理后台
|
|
|
|
|
+├── scripts/ # 环境、迁移、种子、启动和质量门禁
|
|
|
|
|
+├── docs/ # 技术边界、测试用例和验证报告
|
|
|
|
|
+└── README.md
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## 核心技术
|
|
|
|
|
+
|
|
|
|
|
+- Agent Harness：一个统一内核，客户顾问与运营助手两种人格。
|
|
|
|
|
+- Agent 运行时：LangChain `create_agent`、DeepSeek、文件化 Prompt/Skill、Tool Registry、Policy Engine、结构化 UI Block/Action。
|
|
|
|
|
+- 可观测性：统一 SSE 运行事件、本地 Run 持久化、Redis 热状态与限流、LangSmith 精确 Trace 深链。
|
|
|
|
|
+- 业务后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic。
|
|
|
|
|
+- 数据：本地 MySQL 8、Redis、Milvus；RabbitMQ 通过 `TaskDispatcher` 抽象保留替换边界。
|
|
|
|
|
+- 知识服务：BGE-M3 向量化、Milvus 检索、关键词与向量混合召回、知识重排。
|
|
|
|
|
+- 多模态：阿里云百炼托管 Qwen3.5-Plus，识别服务申请材料。
|
|
|
|
|
+- 前端：Vue 3、TypeScript、Vite、pnpm workspace。
|
|
|
|
|
+- 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。
|
|
|
|
|
+
|
|
|
|
|
+第二阶段使用独立的 `insurance_s2_*` 数据库，并通过阶段继承脚本延续第一阶段真实业务数据。
|
|
|
|
|
+
|
|
|
|
|
+## 首次初始化
|
|
|
|
|
+
|
|
|
|
|
+先启动本地 MySQL 8 和 Redis，并准备 Python 3.12、uv、Node.js 22、pnpm。
|
|
|
|
|
+
|
|
|
|
|
+项目读取 `backend/.env`。确认其中的 MySQL、Redis、DeepSeek、LangSmith 和本地安全密钥后，先在项目根目录导入第一、二阶段完整 MySQL 快照：
|
|
|
|
|
+
|
|
|
|
|
+```powershell
|
|
|
|
|
+mysql --host=127.0.0.1 --port=3306 --user=root --password --default-character-set=utf8mb4 --execute="source database/zhibaotong-stage1-stage2-mysql.sql"
|
|
|
|
|
+.\scripts\seed-knowledge.ps1
|
|
|
|
|
+
|
|
|
|
|
+Set-Location frontend
|
|
|
|
|
+pnpm install --frozen-lockfile
|
|
|
|
|
+Set-Location ..
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+SQL 快照已包含管理员、角色、产品、业务员、推广码，以及多状态、多时间、
|
|
|
|
|
+多人员归因的订单、支付、保单和 Agent 运行数据。Milvus 向量集合仍通过
|
|
|
|
|
+`seed-knowledge.ps1` 单独初始化。
|
|
|
|
|
+
|
|
|
|
|
+## 启动
|
|
|
|
|
+
|
|
|
|
|
+在项目根目录运行：
|
|
|
|
|
+
|
|
|
|
|
+```powershell
|
|
|
|
|
+.\scripts\dev.ps1
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+- H5：http://127.0.0.1:5173
|
|
|
|
|
+- 管理后台：http://127.0.0.1:5174
|
|
|
|
|
+- API 文档：http://127.0.0.1:8000/docs
|
|
|
|
|
+
|
|
|
|
|
+本地 H5 验证码为 `147258`；初始后台账号为 `admin`，密码为 `zaq1XSW@`。
|
|
|
|
|
+
|
|
|
|
|
+## LangSmith
|
|
|
|
|
+
|
|
|
|
|
+在 `backend/.env` 中配置：
|
|
|
|
|
+
|
|
|
|
|
+```dotenv
|
|
|
|
|
+LANGSMITH_TRACING=true
|
|
|
|
|
+LANGSMITH_API_KEY=你的密钥
|
|
|
|
|
+LANGSMITH_PROJECT=智保通-第二阶段-知识服务与数据分析
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+启动项目后，在 H5 Agent 回复或后台“运营智能体 → 智能体运行中心”中点击“打开 LangSmith”，即可进入该次调用的精确 Trace，而不是只打开 LangSmith 首页。Trace 未完成同步时，刷新运行中心即可重新解析深链。
|
|
|
|
|
+
|
|
|
|
|
+## 真实模型评测
|
|
|
|
|
+
|
|
|
|
|
+先启动整个项目，再在 `backend` 目录执行：
|
|
|
|
|
+
|
|
|
|
|
+```powershell
|
|
|
|
|
+uv run python -m zbt.commands.evaluate_agents --suite smoke
|
|
|
|
|
+uv run python -m zbt.commands.evaluate_agents --suite full
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+两套评测均调用真实 DeepSeek、真实业务工具和真实 HTTP 接口，并检查回答、工具覆盖和 Trace 关联；配置 LangSmith 密钥后，基准样本与自动评分会同步到 LangSmith。
|
|
|
|
|
+
|
|
|
|
|
+## 质量门禁
|
|
|
|
|
+
|
|
|
|
|
+```powershell
|
|
|
|
|
+.\scripts\test.ps1
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+该脚本执行后端测试、Ruff、mypy、前端类型检查与双端生产构建。真实 MySQL/Redis 集成测试以及真实模型评测单独执行，避免普通代码检查意外消耗模型额度。
|
|
|
|
|
+
|
yangxiaolong