XingHuo/docs/项目框架设计/技术选型和版本/01-技术栈与版本.md

技术栈与版本（已定）

更新日期：2026-09-05
环境：Windows 本机开发 · 内存 15.4 GB（可用约 3.7 GB）
原则：日常开发走 Windows 原生安装；Docker 仅作答辩/生产备选，不用于日常联调。

---

1. 组件一览

组件	版本 / 状态	备注
后端	Python 3.13.14 + FastAPI	系统 Python；Agent 编排 LangGraph 1.2.x + langchain-core / langchain-openai（DeepSeek）/ pymilvus 3.0.1
关系库	MySQL 8.0.46	原生安装，端口 3306 ✓
缓存	Redis 8.10.1	原生安装，路径 F:\Redis\...，端口 6379 ✓
图库	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 未启动；仅答辩/生产备选，非日常开发

---

2. 部署方式：Windows 原生（已定）

2.1 为何不用 Docker 做日常开发

项	说明
本机内存	总计 15.4 GB，可用约 3.7 GB（使用率 ~75%）
Docker 开销	Docker Desktop WSL2 VM 2 GB + Milvus 三容器（etcd / minio / milvus）3.5 GB ≈ 5.5 GB
原生套件占用	MySQL + Redis + Neo4j + Milvus Lite ≈ 1.9 GB

在现有内存下，必须采用 Windows 原生部署，否则 Milvus / Docker 与 IDE、浏览器、Neo4j 同时运行易 OOM。

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

1. MySQL 8.0.46      → :3306
2. Redis 8.10.1      → :6379
3. Neo4j Desktop     → 默认 bolt :7687
4. Ollama + bge-m3   → 本地 embedding
5. FastAPI 后端      → 连接上述服务 + Milvus Lite 文件
6. Vite 前端         → dev server

2.3 生产 / 答辩备选

• 可使用 Docker Compose 拉起完整 Milvus Standalone（etcd + minio + milvus），与开发环境 Milvus Lite 通过同一 pymilvus API 切换 URI。
• 对象存储生产环境可再评估 MinIO / OSS；当前阶段本地目录 + MySQL 元数据即可。

---

3. 连接与配置约定

服务	开发默认	环境变量示例
MySQL	127.0.0.1:3306	MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE=jinrong_agent
Redis	127.0.0.1:6379	REDIS_URL=redis://127.0.0.1:6379/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。

---

4. 向量与 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（代理人）

---

5. 踩坑说明

5.1 Milvus：Lite vs Standalone

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

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

5.2 不用 MinIO

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

5.3 前端栈与需求文档差异

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

5.4 LLM 分工

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

---

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

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

---

7. 版本变更记录

日期	变更
2026-09-05	初版：Windows 原生 + Milvus Lite + 不用 MinIO + React 前端栈