first commit

2026-04-23 09:58:47 +08:00
commit 448e078d99
49 changed files with 5188 additions and 0 deletions
--- a/00_整体部署规划.md
+++ b/00_整体部署规划.md
@@ -0,0 +1,277 @@
+# AI合规智能中枢 — 整体部署规划
+
+> **版本：** 调研版 v1.0 | **日期：** 2026.04 | **团队：** T-Systems AI Regulations Team
+
+---
+
+## 一、项目背景
+
+AI+合规智能中枢面向车企与工厂，是一个全链路合规智能平台。主要解决以下痛点：
+
+| 痛点 | 说明 |
+|------|------|
+| 法规来源复杂 | GB、MIIT、UN-ECE、IATF 16949、ISO 45001 等多源并行 |
+| 更新频率高 | 新能源、数据安全、碳排放法规频繁变动 |
+| 跨语言要求 | 中英德法多语言法规并存 |
+| 文档管理分散 | 内部文档与外部法规割裂，难以统一检索 |
+| 被动识别隐患 | EHS 合规靠人工排查，效率低下 |
+
+**调研目标：** 以最小资源投入（Docker Compose 单机）验证三条核心业务闭环的技术可行性。
+
+---
+
+## 二、部署架构概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         单台服务器                               │
+│  ┌──────────────┐    ┌──────────────────────────────────────┐  │
+│  │  API 网关     │    │           Docker Compose              │  │
+│  │  Nginx :80   │───▶│                                      │  │
+│  └──────────────┘    │  ┌──────────────────────────────┐   │  │
+│                       │  │       业务服务层               │   │  │
+│                       │  │  compliance-backend :8000     │   │  │
+│                       │  │  celery-worker                │   │  │
+│                       │  │  celery-beat                  │   │  │
+│                       │  └──────────┬───────────────────┘   │  │
+│                       │             │                        │  │
+│                       │  ┌──────────▼───────────────────┐   │  │
+│                       │  │        AI 模型层               │   │  │
+│                       │  │  embedding-service :8010      │   │  │
+│                       │  │  mcp-server(MinerU)  :8011    │   │  │
+│                       │  │  LLM → DeepSeek API (云端)   │   │  │
+│                       │  └──────────┬───────────────────┘   │  │
+│                       │             │                        │  │
+│                       │  ┌──────────▼───────────────────┐   │  │
+│                       │  │        数据层                  │   │  │
+│                       │  │  PostgreSQL :5432             │   │  │
+│                       │  │  Redis      :6379             │   │  │
+│                       │  │  Milvus     :19530            │   │  │
+│                       │  │  Neo4j      :7474/:7687       │   │  │
+│                       │  │  MinIO      (Milvus内置)      │   │  │
+│                       │  └──────────────────────────────┘   │  │
+│                       └──────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────▼──────────┐
+                    │   DeepSeek API     │
+                    │   (云端 LLM)       │
+                    └────────────────────┘
+```
+
+---
+
+## 三、原方案 vs 调研方案对比
+
+| 维度 | 原方案（生产级）| 调研方案 | 降级理由 |
+|------|--------------|---------|---------|
+| 编排 | Kubernetes 1.36 + Helm | **Docker Compose** | 无需集群管理，`up -d` 一键启动 |
+| LLM | vLLM + DeepSeek-V3（4×A100）| **DeepSeek/Qwen 云端 API** | 无 GPU 依赖，秒级就绪 |
+| 嵌入模型 | BGE-M3 GPU 服务 | **BGE-M3 CPU 容器** | 调研数据量小，CPU 够用 |
+| Milvus | 分布式集群 + MinIO | **Milvus Standalone**（含内置 MinIO）| 单容器，省去 MinIO 独立部署 |
+| 消息队列 | Kafka 3 节点 | **Redis + Celery**（复用已有 Redis）| 调研无需高吞吐，大幅简化 |
+| 监控 | Prometheus + Grafana + ELK | **仅 Prometheus + Grafana**（可选）| 轻量，后期按需加 |
+| 安全 | JWT + cert-manager + RBAC | **API Key 简单认证** | 调研期无需生产级安全 |
+| CI/CD | GitLab CI 完整流水线 | **无**（手动部署）| 调研期直接 compose up |
+
+---
+
+## 四、硬件最低要求
+
+| 资源 | 最低配置 | 推荐配置 | 说明 |
+|------|---------|---------|------|
+| CPU | 8 核 | 16 核+ | BGE-M3 CPU 模式需要较多核心 |
+| 内存 | 32 GB | 64 GB | Milvus + BGE-M3 + Neo4j 内存消耗较大 |
+| 存储 | 200 GB SSD | 500 GB SSD | 含模型文件（约 5GB）+ 数据 |
+| GPU | **无需** | 1× RTX 3090（24GB）| 有 GPU 可加速嵌入/MinerU |
+| 网络 | 能访问 DeepSeek API | — | LLM 完全在云端 |
+| OS | Ubuntu 22.04 LTS | — | 或 Windows 11 + WSL2 |
+
+**各组件内存估算：**
+
+| 服务 | 内存占用 |
+|------|---------|
+| PostgreSQL | ~1 GB |
+| Redis | ~512 MB |
+| Milvus（含 etcd/minio）| ~4 GB |
+| Neo4j | ~2 GB |
+| BGE-M3（CPU 模式）| ~6 GB |
+| MinerU（CPU 模式）| ~4 GB |
+| compliance-backend | ~1 GB |
+| celery-worker × 1 | ~1 GB |
+| **合计** | **~20 GB** |
+
+---
+
+## 五、五阶段部署步骤（总览）
+
+```
+阶段一：宿主机环境准备
+  └─ 安装 Docker CE / Docker Desktop
+  └─ 配置 nvidia-container-toolkit（有 GPU 时）
+  └─ 创建项目目录，配置 .env
+
+阶段二：基础中间件启动
+  └─ PostgreSQL + Redis（优先启动）
+  └─ etcd + MinIO（Milvus 依赖）
+  └─ Milvus Standalone（向量检索核心）
+  └─ Neo4j Community（知识图谱）
+
+阶段三：AI 模型服务构建与启动
+  └─ 构建 embedding-service（BGE-M3 封装）
+  └─ 构建 mcp-server（MinerU 封装）
+  └─ 预下载模型（BGE-M3 ~2.5GB，MinerU ~2GB）
+
+阶段四：业务微服务启动
+  └─ compliance-backend（FastAPI 主服务）
+  └─ celery-worker（异步任务处理）
+  └─ celery-beat（定时任务调度）
+  └─ nginx（API 网关）
+
+阶段五：验证与闭环测试
+  └─ 健康检查（bash scripts/check_health.sh）
+  └─ 端到端冒烟测试（bash scripts/07_smoke_test.sh）
+  └─ 三条业务闭环验证
+```
+
+---
+
+## 六、三条核心业务闭环
+
+### 闭环①：法规入库 → 检索问答
+
+```
+用户上传 PDF
+    │
+    ▼
+API Gateway（Nginx）
+    │
+    ▼
+kbmp-service（文件接收）
+    │ 异步投递
+    ▼
+Celery Worker
+    │
+    ├─► parse-worker ──► mcp-server（MinerU 解析）
+    │                         │ Markdown + 结构化文本
+    │                         ▼
+    └─► vectorize-worker ──► embedding-service（BGE-M3）
+                                  │ 1024维向量
+                                  ▼
+                             Milvus（向量存储）+ PostgreSQL（元数据）
+
+用户提问
+    │
+    ▼
+BM25 关键词检索 + BGE-M3 向量检索（Milvus hybrid search）
+    │
+    ▼
+Cross-Encoder Reranker（精排 Top-K）
+    │
+    ▼
+DeepSeek API（引文锚定生成）
+    │
+    ▼
+返回答案（含原文引用 + 页码）
+```
+
+### 闭环②：文档上传 → 合规审查
+
+```
+上传供应商/内部文档
+    │
+    ▼
+MinerU 解析 → 条款级分割
+    │
+    ▼
+法规域匹配（vehicle_safety / data_security / ehs）
+    │
+    ▼
+与法规库语义比对（向量相似度 + 关键字匹配）
+    │
+    ▼
+DeepSeek API 风险评分（条款级分析）
+    │
+    ▼
+生成 Markdown 审查报告（风险等级 + 整改建议）
+```
+
+### 闭环③：法规监控 → 变更推送
+
+```
+Celery Beat 定时触发（每天）
+    │
+    ▼
+抓取监控源（国标委 / 工信部 / 应急管理部 / 生环部）
+    │
+    ▼
+内容 Hash 比对（检测变更）
+    │
+    ▼ [有变更]
+NLP Diff 分析（DeepSeek 提取新增/修订/废止条款）
+    │
+    ▼
+增量入库（MinerU 解析 → BGE-M3 → Milvus + PostgreSQL + Neo4j）
+    │
+    ▼
+差距分析（与企业现状比对）
+    │
+    ▼
+推送通知（Email / Webhook / 飞书 / 钉钉）
+    │
+    ▼
+记录变更日志 → 触发整改任务
+```
+
+---
+
+## 七、技术选型决策依据
+
+| 组件 | 选型 | 决策依据 |
+|------|------|---------|
+| 向量数据库 | Milvus 2.4 | 支持 Dense+Sparse 混合检索，BGE-M3 配套，生产可扩展 |
+| 图数据库 | Neo4j 5.x | 法规实体关系建模成熟，APOC 插件丰富，Cypher 查询友好 |
+| 嵌入模型 | BGE-M3 | 中英文双语，支持 dense+sparse+multi-vector，8192 token 上下文 |
+| LLM | DeepSeek API | 推理能力强，成本低（约¥1/百万 tokens），OpenAI 兼容 |
+| 文档解析 | MinerU | GPU 最快 0.21s/页，支持 109 种语言 OCR，布局感知 |
+| 任务队列 | Celery + Redis | 调研阶段够用，比 Kafka 轻量，Redis 可复用 |
+| API 框架 | FastAPI | 异步性能好，OpenAPI 自动生成，Pydantic 数据验证 |
+| 关系数据库 | PostgreSQL + pgvector | 元数据存储 + 备用向量检索，pgvector 镜像开箱即用 |
+
+---
+
+## 八、升级路径（调研 → 生产）
+
+| 维度 | 升级内容 | 触发条件 |
+|------|---------|---------|
+| LLM | API → 本地 vLLM + DeepSeek-V3 | 数据安全要求/API成本超阈值 |
+| Milvus | Standalone → 分布式集群 | 向量数据 > 1000 万条 |
+| 消息队列 | Celery+Redis → Kafka | 并发任务 > 100/分钟 |
+| 编排 | Docker Compose → Kubernetes | 多节点部署/弹性伸缩需求 |
+| 安全 | API Key → JWT + RBAC | 对外提供服务/多租户 |
+| 监控 | Grafana → Grafana + ELK | 日志量大/需要复杂分析 |
+
+---
+
+## 九、文件结构说明
+
+```
+Depolyment/
+├── 00_整体部署规划.md          ← 本文档
+├── 01_技术架构详解.md          ← 六层架构 + 六大微服务详细说明
+├── 02_组件安装指南.md          ← 每个组件的详细安装步骤
+├── 03_业务闭环说明.md          ← 三条闭环的数据流和接口规范
+├── README.md                   ← 快速启动指南
+├── docker-compose.yml          ← 全服务编排
+├── .env.example                ← 环境变量模板
+├── scripts/                    ← 安装与运维脚本（13 个）
+├── services/                   ← 服务源码
+│   ├── embedding/              ← BGE-M3 嵌入服务
+│   ├── mcp-server/             ← MinerU 文档解析服务
+│   └── compliance-backend/     ← 核心业务后端
+├── config/                     ← Nginx、Prometheus 配置
+├── init-sql/                   ← PostgreSQL 初始化 SQL
+├── data/                       ← 运行时数据
+├── logs/                       ← 服务日志
+└── models/                     ← AI 模型缓存
+```