Files

T

zhanghongyu_0626 4b8e11c9bd feat(threshold): Implement customer loss threshold configuration and notification system

- Added `ThresholdRepository` for managing customer loss threshold configurations and notifications.
- Introduced `threshold_service` to handle loss threshold alerts based on customer portfolio performance.
- Enhanced `customer_prompts` to include new intent for querying product net values.
- Updated `customer_service` to integrate new threshold alert functionality into existing workflows.
- Implemented `sanitize_postprocess` for improved compliance handling in customer interactions.
- Enhanced course documentation to reflect updates in advisor training modules and interactive elements.

This update significantly improves the customer experience by providing proactive loss threshold notifications and enhancing the overall service framework.

2026-09-10 10:57:40 +08:00

16 KiB

Raw Permalink Blame History

技术栈与版本（已定）

更新日期：2026-09-10
环境：Windows 本机开发 · 内存 15.4 GB（可用约 3.7 GB）
原则：日常开发走 Windows 原生安装；Docker 仅 Redis 单容器 + 答辩/生产备选，不用于日常全栈容器化。

0. 选型背景：我们在解决什么问题

本项目是 四个 Agent 共用一套合规底座 的金融代销演示系统：客户 / 代理人 / 数据分析 / 风控，各自对话与 Tool，但共享 MySQL 画像与审计、Core 只读账、向量知识库与 Redis 会话。

选型时要同时满足：

约束	对技术选型的影响
合规与审计	业务真相在 MySQL + Core；Redis 只是加速副本；审计表只 INSERT
四 Agent 不互调 LLM	需要统一 FastAPI 入口 + LangGraph 编排，而不是四个独立微服务各搞一套
无真实 Core	用 MySQL 模拟 `jinrong_core`，Agent 经 Repository 只读，便于本地灌库演示
本机内存紧（~3.7 GB 可用）	不能日常跑 Docker 全家桶 + Milvus 三容器；向量用 Milvus Lite
团队 Windows 原生开发	MySQL / Neo4j / Ollama 本机安装；减少「先起 5 个容器才能写代码」
敏感文档不出内网	Embedding 本地 Ollama；生成推理可走 DeepSeek API（可脱敏）
答辩要可演示	保留 Docker Compose 切换路径（Milvus Standalone、完整 Redis），与开发 API 一致

决策原则（拍板后不变）： 能本机原生则原生；必须容器化的只选 内存占用小、切换成本低 的组件；前后端分离、API 契约先行；P0 不引入 MinIO / 实时行情 / 多租户。

1. 各组件为什么选它

下面按 「这层干什么 → 为什么用这个」 说明；版本号见 §2 组件一览。

1.1 后端：Python 3.13 + FastAPI

为什么	说明
Agent 与 API 同进程	四个 Agent 的 LangGraph、Tool、Repository 与 REST 路由在同一 FastAPI 进程，调试、断点、pytest 一条线，不必维护 Java + Python 两套
异步 I/O 够用	对话、SSE、MySQL/Redis 并发连接；风控事件线以同步 SQL 为主，FastAPI 足够
类型与生态	Pydantic 校验请求体、settings 管理双库与阈值；与 LangChain / pymilvus 生态衔接成熟
未选 Node/Java 做 Agent 主栈	团队 Python 统一；数据分析 Agent 的 SQL 守卫、风控规则引擎已在 Python 落地

1.2 Agent 编排：LangGraph + langchain-openai（DeepSeek）

为什么	说明
状态图 + Tool 节点	对话 = `tool → llm → guard` 固定链路；风控/客服可插分支而不重写 HTTP
DeepSeek 通过 OpenAI 兼容 API	`langchain-openai` 改 base_url 即可；无 key 时降级明确标注，不 silent 假回复
未选裸 HTTP 调模型	Tool 注册表、免责声明、会话注入需要与 LangGraph 节点绑定；手写状态机维护成本高
未选四 Agent 各一个独立服务	项目规则禁止 Agent 互调 LLM；共用 `chat.py` + `X-Agent-Type` 分流更省内存

1.3 关系库：MySQL 8.0 双库（`jinrong_agent` + `jinrong_core`）

为什么	说明
双库隔离 L0 与 Agent enrich	`jinrong_core` = 模拟正式账（客户、持仓、流水、产品）；`jinrong_agent` = 会话、审计、预警、L1/L2/L3、AML
Agent 只读 Core	符合「Core 是权威账，Agent 不能改 C1~C5」；真实接入时只换 Core 连接，Agent 库 schema 基本不动
未选 PostgreSQL	团队与本机已标准化 MySQL 8；表设计、种子脚本、Windows 安装路径已打通
未选 SQLite 做生产底座	四 Agent 并发写审计/会话、集成测试要贴近真库；SQLite 仅单测用

1.4 缓存：Redis 8.x（开发推荐 Docker `6380`）

为什么	说明
会话热窗口	`sess:{agent}:{session_id}:msgs`：最近 N 轮对话，TTL 2h；miss 回源 MySQL
画像热读	`profile:l3:{customer_id}` 等 cache-aside；MySQL 为权威
风控辅助	预警 Pub/Sub、去重键、限流计数、JWT jti 吊销
为什么开发改用 Docker Redis（6380）	本机 Windows 自带 Redis 常占 6379 且版本偏旧（RESP3 兼容问题）；Docker `redis:7-alpine` 映射 6380，与 `database.py` RESP2 一致，只启一个容器 ~50MB，不拉垮 3.7GB 内存
未选 Memcached	需要 List、Pub/Sub、TTL 组合；Redis 一条栈覆盖会话+缓存+限流

1.5 图库：Neo4j 5.x（Desktop）

为什么	说明
关系穿透演示	客户—产品—行业—市场多跳查询；为 GraphRAG / 投顾场景预留
非画像主库	完整画像在 MySQL L1/L2/L3；Neo4j 存实体关系，由 `sync_neo4j.py` 从 Core 同步
Desktop 降低运维	开发期不需自建集群；答辩可导出/换 Server
P0 对话未强依赖	选型先占位；不阻塞四 Agent P0 主链路

1.6 向量库：Milvus Lite + pymilvus（1024 维 bge-m3）

为什么	说明
RAG 必需	产品规则、客服 fin_* 库、代理人知识检索；需要向量检索 + 标量过滤（effective_date 等）
Milvus Lite 单文件	免 etcd/minio/milvus 三容器（~3.5GB）；本机 `.milvus/` 或 `data/milvus.db` 即可
与 Standalone 同 API	答辩/生产改 `MILVUS_URI` 切 Standalone，Collection 维度和字段不变
未选 pgvector / 纯 FAISS 文件	多 Collection、标量过滤、与 pymilvus 文档对齐；FAISS 中文路径等坑已在 T-21 踩过
1024 维 bge-m3	中文金融语料表现好；Ollama 本地 embed，文档向量不出内网

1.7 前端：React 19 + Vite 7 + Ant Design 5 + HashRouter

为什么	说明
四角色工作台	登录、侧栏、Dashboard、Chat、表格台账；需要组件库而非脚本式页面
HashRouter	静态部署 / 本地 file 预览友好；后端只提供 API，不要求服务端路由
Vite 开发体验	HMR 快；与 TS strict、Vitest 一套工具链
未选 Streamlit	需求文档或课程示例或出现 Streamlit；本项目统一 React，四 Agent 共用 Layout/API 客户端，桌面端信息密度更高
未选 Vue/Angular	团队既定 React；Ant Design 5 金融后台组件成熟

1.8 LLM 分工：DeepSeek API + Ollama bge-m3

能力	选型	为什么
对话 / 推理 / Tool	DeepSeek API	质量与成本平衡；OpenAI 兼容接入 LangGraph
Embedding	Ollama bge-m3 本地	产品手册、政策 chunk 不出内网；维度 1024 与 Milvus 对齐
未选全本地 LLM	—	本机内存不够跑 7B+ 推理 + Neo4j + MySQL 同时满载；生成走 API 更稳
未选全云端 Embedding	—	合规与演示要求「知识库向量化在内网完成」

1.9 数据分析：sqlglot（SQL AST 白名单）

为什么	说明
NL→SQL 必须防写	分析 Agent 只允许 SELECT；AST 层拦截 DROP/UPDATE/多语句
与只读 DB 账号双保险	即使账号配错，应用层仍拒绝非 SELECT
未选正则黑名单	金融 SQL 嵌套多，正则易漏；sqlglot 解析更可靠

1.10 刻意不选

不选	为什么
MinIO / OSS（P0）	文档量小，本地 `data/kb/` + MySQL 元数据够用；减依赖
Docker 日常全栈	内存不够；MySQL/Neo4j/Ollama 本机已安装
Streamlit 前端	与 React 工作台重复；不作为交付前端
Agent 互调 / 多 LLM 编排	项目 MEMORY 禁止；跨 Agent 走画像表与预警 API
Milvus Docker 日常	三容器 + Docker Desktop VM 易 OOM；Lite 足够开发

2. 组件一览

组件	版本 / 状态	备注
后端	Python 3.13.14 + FastAPI	系统 Python；Agent 编排 LangGraph 1.2.x + `langchain-core` / `langchain-openai`（DeepSeek）/ `pymilvus` 3.0.1
SQL 安全	`sqlglot`（AST 解析白名单）	数据分析 Agent 只读 SQL 校验；与只读账号双保险（已确认新增）
关系库	MySQL 8.0.46	原生安装，端口 3306 ✓
缓存	Redis 8.x / Docker `redis:7-alpine`	开发推荐 6380（`REDIS_URL`）；本机 Windows Redis 若占 6379 则与之并存 · 见 §3
图库	Neo4j 5.26.19（Enterprise）	Neo4j Desktop 2，已建库 ✓
向量库	Milvus Lite（本地文件模式）	见 §3 踩坑说明；Collection 设计见 03-milvus-collections.md
前端	React 19 + Vite 7 + TS strict + Ant Design 5 + HashRouter + Vitest	沿用既有前端栈；不用需求文档中的 Streamlit
LLM 生成	DeepSeek API	对话 / 推理走云端 API
LLM 向量化	Ollama + bge-m3，1024 维	本地运行；文档向量不出内网
对象存储	不使用 MinIO	文档落本地目录；元数据进 MySQL（可选 P1 索引表）
容器	Docker 29.7.2 Client	Daemon 未启动；仅答辩/生产备选，非日常开发

3. 部署方式：为什么这样部署（已定）

3.1 总体策略：「重服务本机原生 + 轻量容器补缺」

┌─────────────────────────────────────────────────────────┐
│  Windows 本机（日常开发）                                  │
│  MySQL :3306 · Neo4j Desktop · Ollama · FastAPI · Vite   │
│  Milvus Lite 单文件 · 文档目录 data/kb/                    │
├─────────────────────────────────────────────────────────┤
│  唯一日常容器：Docker Redis → 127.0.0.1:6380             │
│  （避开本机 Redis 6379 · 统一 RESP2 · 内存 ~50MB）          │
├─────────────────────────────────────────────────────────┤
│  答辩 / 生产备选：Docker Compose                          │
│  Milvus Standalone（etcd+minio+milvus）· 可换 OSS         │
└─────────────────────────────────────────────────────────┘

部署选择	原因
MySQL 本机安装	双库 + 种子脚本 + pytest 集成测依赖真库；容器化 MySQL 在 3.7GB 可用内存下性价比低
Neo4j Desktop	图形化管理、一键启停；开发不需要 K8s 级 HA
Ollama 本机	Embedding 低延迟、无外网；与 Python 同机调试
Milvus Lite 文件	不启 etcd/minio；向量库与代码同仓库路径可备份
Redis 用 Docker 单容器	本机 Windows Redis 版本/端口冲突；单容器内存小、与 compose 一致，不算「全栈 Docker 开发」
FastAPI + Vite 进程直跑	`uvicorn --reload` + `npm run dev`；改代码即生效
答辩才考虑 Compose 全家桶	演示机内存够时 Milvus Standalone 与 Lite API 相同，切换 URI 即可

3.2 为何不用 Docker 做日常全栈开发

项	说明
本机内存	总计 15.4 GB，可用约 3.7 GB（使用率 ~75%）
Docker 全栈开销	Docker Desktop WSL2 VM ~2 GB + Milvus 三容器 ~3.5 GB ≈ 5.5 GB
原生 + Lite 占用	MySQL + Redis 容器 + Neo4j + Milvus Lite + Ollama ≈ 2 GB 量级

在现有内存下，日常必须避免 Milvus/数据库全容器化，否则与 IDE、浏览器、Neo4j 同时运行易 OOM。

3.3 日常开发启动顺序（建议）

1. MySQL 8.0.46           → :3306
2. Docker Redis           → .\scripts\dev\start-redis.ps1  → :6380
3. Neo4j Desktop          → bolt :7687
4. Ollama + bge-m3        → 本地 embedding
5. FastAPI 后端           → 连接上述 + Milvus Lite 文件
6. Vite 前端              → npm run dev

3.4 生产 / 答辩备选

Milvus Standalone（Docker Compose）：etcd + minio + milvus，与 Lite 通过 同一 pymilvus API 切换 MILVUS_URI。
Redis：可换云 Redis / 集群；应用只认 REDIS_URL。
对象存储：P0 本地目录；上云再换 OSS 适配层，不改 Agent 业务接口。
DeepSeek：生产可换私有化模型 endpoint，LangGraph 侧仍 OpenAI 兼容协议。

4. 连接与配置约定

服务	开发默认	环境变量示例
MySQL	`127.0.0.1:3306`	`MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_DATABASE=jinrong_agent`
Redis	`127.0.0.1:6380`（Docker 推荐）	`REDIS_URL=redis://127.0.0.1:6380/0`
Neo4j	Desktop 本地	`NEO4J_URI=bolt://localhost:7687`
Milvus Lite	项目内 `.milvus/` 或配置路径	`MILVUS_URI=./data/milvus.db`（Lite 文件 URI 以 pymilvus 文档为准）
Ollama	`http://127.0.0.1:11434`	`OLLAMA_BASE_URL`, `EMBED_MODEL=bge-m3`
DeepSeek	HTTPS API	`DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`

Agent 业务库脚本：01-mysql-共用底座.sql、02-mysql-agent专用.sql。

5. 向量与 RAG 对齐

项	约定
Embedding 模型	Ollama `bge-m3`
向量维度	1024（Milvus Collection `FLOAT_VECTOR(dim=1024)` 必须一致）
Python 客户端	`pymilvus` 3.0.1
开发向量库	Milvus Lite 单文件，免 etcd/minio
共用 Collection	`kb_product_rules`（客户 + 代理人）；`kb_business_ops`（代理人）

6. 踩坑说明

6.1 Milvus：Lite vs Standalone

模式	适用	注意
Milvus Lite（当前）	本机开发、内存受限	与 Standalone 数据不自动互通；迁移需 re-embed + import
Milvus Standalone（Docker）	答辩演示、生产	需额外 ~3.5 GB+ 内存；开发机日常不启

代码层通过 MILVUS_URI / 连接模式开关切换，Collection 字段与 1024 维不变。

6.2 不用 MinIO

原始 PDF/Word 存 本地目录（如 data/kb/）。
Milvus 存 chunk 文本或本地文件相对路径；source_doc_id / source_version 进 MySQL 或 Milvus 标量字段（见 Collection 设计）。
后续若上云，再替换为 OSS 适配层，不改 Agent 业务接口。

6.3 前端栈与需求文档差异

需求/用户故事中可能出现的 Streamlit 不作为本项目前端。
统一：React 19 + Vite 7 + Ant Design 5，四 Agent 可共用组件库与 HashRouter 多入口。

6.4 LLM 分工

能力	选型	数据出境
对话 / 推理 / Tool 编排	DeepSeek API + LangGraph StateGraph	按 API 协议；敏感字段需脱敏
文档 Embedding	Ollama bge-m3 本地	不出内网

6.5 Redis 端口与 RESP 版本

现象	处理
本机 Windows Redis 占 6379	项目 `.env` 用 6380（Docker 映射），两者可并存
客户端 RESP3 与旧 Redis 不兼容	`database.py` 固定 protocol=2（RESP2）
启动	`.\scripts\dev\start-redis.ps1` 或 `docker compose up -d redis`

7. 与项目其他文档的关系

文档	关系
02-JWT-RBAC鉴权手册.md	鉴权与网关（FastAPI 中间件 / SDK）
05-多Agent共用底座清单.md	MySQL / Redis / Milvus / Neo4j 底座
03-milvus-collections.md	向量 Collection 字段
业务场景优先级清单.md	业务 P0 范围

8. 版本变更记录

日期	变更
2026-09-05	初版：Windows 原生 + Milvus Lite + 不用 MinIO + React 前端栈
2026-09	新增 `sqlglot`（数据分析 Agent SQL AST 白名单校验，已确认）
2026-09-10	新增 §0 选型背景、§1 各组件为什么选它、§3 为什么这样部署；Redis 开发口径改为 Docker 6380

16 KiB Raw Permalink Blame History Unescape Escape