xinghuo/group_xinghuo_jinrong
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
973bf1b8343f8f5872c1ac79666c31ad29f0ab61
group_xinghuo_jinrong/docs/项目框架设计/技术选型和版本/01-技术栈与版本.md
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

288 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 技术栈与版本（已定）
> 更新日期：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](../项目框架设计/表设计/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 总体策略：「重服务本机原生 + 轻量容器补缺」
```text
┌─────────────────────────────────────────────────────────┐
│ 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 日常开发启动顺序（建议）
```text
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](../项目框架设计/表设计/01-mysql-共用底座.sql)、[02-mysql-agent专用.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](./02-JWT-RBAC鉴权手册.md) | 鉴权与网关（FastAPI 中间件 / SDK） |
| [05-多Agent共用底座清单.md](../项目框架设计/表设计/05-多Agent共用底座清单.md) | MySQL / Redis / Milvus / Neo4j 底座 |
| [03-milvus-collections.md](../项目框架设计/表设计/03-milvus-collections.md) | 向量 Collection 字段 |
| [业务场景优先级清单.md](../需求拆解/业务场景优先级清单.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** |
Reference in New Issue View Git Blame Copy Permalink