# 技术栈与版本（已定）

> 更新日期：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](../项目框架设计/表设计/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 日常开发启动顺序（建议）

```text
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](../项目框架设计/表设计/01-mysql-共用底座.sql)、[02-mysql-agent专用.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](./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 范围 |

---

## 7. 版本变更记录

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