Files

2. 调整字体大小
3. 新增部分功能

2026-06-05 18:00:31 +08:00

18 KiB

Raw Permalink Blame History

AI+合规智能中枢 — 下一步开发与优化路线图（设计文档）

日期：2026-06-05
定位：试点 MVP 走向生产
范围：全景清单 + 异步任务化（设计①）+ 法规感知闭环（设计②）深入方案 + 三阶段实施路线图
作者：AI Regulations Team（brainstorming 产出）

0. 背景与目的

本文档基于对当前仓库前后端真实代码的逐文件探查，结合四份愿景文档（AI_Regulations_Report.pptx、AI_Regulations_Architecture.docx、01_Architecture.html、02_Architecture_Detail.html）与最新开源 AI 技术调研，给出下一步可继续开发与优化的方向清单，并对两个最高价值方向给出可落地的深入设计。

本文档是方向性设计（spec），不是实施计划（plan）。阶段一、阶段二的具体落地由后续 writing-plans 环节拆分为分步计划。

0.1 现状一句话

后端是一套结构清晰的 DDD 风格 FastAPI RAG 系统（上传 → 解析 → 分块 → BGE-M3 嵌入 → Milvus → 混合检索 → 流式问答 + 合规分析），真实可用。但愿景文档中的多个旗舰能力（知识图谱、法规感知闭环、RBAC、EHS、异步化）目前为 mock 或缺失。

1. 现状盘点（基于真实代码）

1.1 已实现且真实可用

文档处理主链路：application/documents/services.py::DocumentCommandService.upload_and_process — 存储 → 解析（阿里云 DocMind / 本地）→ 分块 → BGE-M3 嵌入 → Milvus 入库，含 DocumentProcessingStore 全程状态事件记录。
混合检索：application/knowledge/services.py::KnowledgeRetrievalService — Dense（DenseRetriever）+ BM25（jieba）+ Reciprocal Rank Fusion + 可选 Cross-Encoder 重排。
流式 RAG 问答：application/agent/services.py::AgentConversationService.stream_chat + api/routes/rag.py — 真实检索 + 引文 + 会话历史 + SSE。
合规分析管线：application/compliance/pipeline.py — clause_split → retrieve → gap_check → conclusion，真实 LLM + 真实检索，SSE 流式（api/routes/compliance.py::analyze_stream）。
状态/健康面板：api/routes/status.py + 前端 StatusPage.tsx — Milvus/MinIO/BM25/Reranker/会话实时状态。
存储后端：PostgreSQL / MinIO 适配器齐全；JSON 与 Postgres 双后端可切换。
前端：React 19 + Vite + Tailwind，6 个页面（Overview/Status/Perception/Docs/Compliance/RagChat）。

1.2 愿景已规划但代码缺失或为 mock

能力	愿景出处	代码现状
知识图谱 / Neo4j 多跳推理	架构图 L4/L5、Slide 5	全代码 0 处 neo4j/graph
法规感知自动更新闭环	01_Architecture.html L157-193、Slide 11	`PerceptionService` 喂 `MockEventStore`（20 条死数据）
认证 / RBAC / 审计日志	Slide 12 四角色权限矩阵	全代码 0 处 auth/jwt/rbac；`main.py` CORS=`*`
异步任务 / Worker 集群	架构图"Worker 集群"、Slide 9	`app/workers/` 空目录；处理全同步
EHS 隐患识别（SIF/四维根因）	Slide 7	未实现
多渠道推送（Email/Teams/飞书）	Slide 8	未实现
闭环整改跟踪、可观测性	架构图右栏	缺失

1.3 关键发现

requirements.txt:28 已有 celery>=5.3.0 + redis>=4.5.0，docker-compose.yml 已配 Redis 7，settings.py 已有 redis 配置 —— 异步化是"接线"，不是"从零搭建"。
DocumentProcessingStore 已能记录 run 状态/状态事件 —— 是天然的任务进度表。
PerceptionService.analyze_event 的 LLM 影响分析与 RAG 关联检索是真的 —— 感知闭环缺的只是前半段（采集 → Diff → 入库）。
后端正处于 legacy 迁移期：services/*、workflows/* 为兼容层（见 docs/architecture/backend-project-architecture.md）。

2. 全景机会清单

类型标记：[新能力]=愿景缺口补齐，[加固]=已实现能力优化。价值 ★（1-5），工作量 S/M/L。

P0 — 生产地基（阻断"走向生产"的硬伤）

#	机会点	类型	现状证据	价值	工作量
1	异步任务化（Celery + 已配 Redis）：解析/嵌入/感知/推送下沉 worker	加固	`workers/` 空；`documents.py:34` 上传同步阻塞	★★★★★	L
2	认证 + RBAC + 审计日志，收紧 CORS	新能力	0 处 auth；`main.py` CORS=`*`；Slide 12	★★★★★	M
3	会话 & 任务持久化（内存 → Redis/PG）	加固	`bootstrap.py:254` 内存会话；`compliance.py:25` 内存字典	★★★★	M
4	基础可观测性（Prometheus + 结构化日志 + 追踪）	加固	仅 loguru；架构图右栏全缺	★★★	M

P1 — 高价值能力补齐 + RAG 质量

#	机会点	类型	现状证据	价值	工作量
5	启用并升级 Reranker（`bge-reranker-v2.5-gemma2-lightweight`）	加固	`settings.py:113` 默认关；管线已写好	★★★★	S
6	Agentic 检索（查询改写/意图理解/多路召回）	加固	`agent/services.py` 直接 retrieve，无 rewrite/HyDE	★★★★	M
7	知识图谱 / GraphRAG（Neo4j + LightRAG v1.5）	新能力	0 处 neo4j；LightRAG v1.5 原生支持	★★★★★	L
8	法规感知自动更新闭环（真实采集 + 版本 Diff + 增量重索引）	新能力	`perception/services.py` 用 MockEventStore	★★★★★	L
9	引文置信度评分（Slide 5 承诺"置信度评分+页码溯源"）	加固	`rag.py` sources 无 confidence	★★★	S
10	检索评估 harness（recall@k / faithfulness）	加固	`tests/` 需真实服务，无离线 RAG 评估	★★★	M

P2 — 视野扩展（独立子项目）

#	机会点	类型	价值	工作量
11	EHS 隐患识别（SIF 评分 + 四维根因 + ISO 45001 扫描，Slide 7）	新能力	★★★★	L
12	多渠道推送 + 订阅规则引擎（Email/Teams/飞书，Slide 8）	新能力	★★★	M
13	闭环整改跟踪（任务派发 → 进度 → 验收归档）	新能力	★★★	M
14	企业系统集成（PLM/ERP/OA/MES Webhook）	新能力	★★	L
15	MinerU 3.1 升级（已转 Apache 协议，VLM 解析）作本地兜底	加固	★★	S
16	前端加固（清 mock 数据、补 error/loading 态、KG 可视化、登录态）	加固	★★★	M
17	收口 legacy 迁移（`services/`、`workflows/` 按架构文档归位）	加固	★★	M

3. 深入设计 ① — 异步任务化

3.1 问题

upload_document（api/routes/documents.py:34）在单个 HTTP 请求内同步跑完存储 → 解析（阿里云云端可达 900 秒，settings.py:49）→ 嵌入 → Milvus 入库。大体量 GB 标准必然超时；compliance.py 的 /analyze 为假异步（立即返回 mock）；perception 爬取闭环无执行载体。PPT Slide 9 已将"大文件性能"列为关键挑战，对策正是"流式处理 + 异步队列 + 实时进度"。

3.2 关键前提：基建已就位

requirements.txt:28 已含 celery>=5.3.0 + redis>=4.5.0
docker-compose.yml:46 Redis 7 已配置；settings.py:64 已有 redis 连接配置
PostgresDocumentProcessingStore 已记录 run 状态/状态事件 —— 天然任务进度表
app/workers/ 为空目录（唯一缺口）

3.3 架构（遵循 AGENTS.md 的 `api → application → domain ports → infrastructure`）

api/routes/documents.py  POST /upload
        │ 1. 存二进制 + 建 Document 记录（快，同步）
        │ 2. enqueue task → 立即返回 {doc_id, status:"queued", run_id}
        ▼
infrastructure/tasks/            ← 新增
   celery_app.py                 broker=redis, backend=redis
   document_tasks.py             @task process_document(doc_id) → DocumentCommandService
        │ 复用现有 upload_and_process 的 parse→embed→index 段
        ▼
application/documents/services.py（拆分：store 与 process 解耦）
        │ 每阶段写 DocumentProcessingStore（已存在）→ 进度可查
        ▼
api/routes/documents.py  GET /status/{doc_id}  ← 已存在，读 run 状态即可

3.4 落地步骤（增量、不破坏现有同步路径）

新增 infrastructure/tasks/celery_app.py — Celery 实例，broker/backend 指向已配 Redis。
拆分 upload_and_process → store_document（同步快）+ process_document（可异步），复用现有逻辑，零重写解析/嵌入代码。
新增 document_tasks.py — @celery_app.task 包裹 process_document，失败用 tenacity（已在 deps）重试 + 死信。
改 documents.py 上传 — 默认入队（保留 ?sync=true 同步回退便于演示）；GET /status/{doc_id} 读 DocumentProcessingStore 返回阶段进度。
前端 DocsPage.tsx — 上传后轮询/SSE 进度条（架构图 Worker"心跳/状态上报"已是既定设计）。
dev.sh/dev.bat 加 worker 启动：celery -A app.infrastructure.tasks.celery_app worker。

3.5 工作量与风险

M（中），3-5 天。
最大风险：Celery worker 进程内 PYTHONPATH=backend 与 bootstrap lru_cache 单例需重新初始化 —— 可控，因 bootstrap 已是懒加载。
YAGNI 边界：本期仅异步化"文档处理"一条链；compliance/perception 复用同一 Celery 基建后续接入。

4. 深入设计 ② — 法规感知自动更新闭环

4.1 问题

感知闭环是愿景旗舰能力（01_Architecture.html L157-193、Slide 11）。现状：PerceptionService 喂 MockEventStore（mock_event_store.py:7，20 条手写死数据），list_events/stats 全静态，source_url 真实但从不访问。LLM 影响分析与 RAG 关联检索是真的 —— 闭环缺的是前半段：真实采集 → 变更感知（Diff）→ 入库。

4.2 六步现状对照

步骤	愿景设计	现状	本期目标
① 法规源监控	定时爬国标网/MIIT/UN-ECE/EUR-Lex	❌ 无	✅ 适配器+定时
② 智能变更感知	NLP 比对新旧版本 Diff	❌ 无	✅ 内容指纹+LLM Diff
③ 自动解析入库	MinerU→分块→BGE-M3→Milvus	✅ 已有（复用设计①管线）	✅ 接线
④ 知识图谱更新	Neo4j 关系同步	❌ 无	⏭️ 本期不做（归 GraphRAG 专项）
⑤ 差距分析&推送	AI 比对+按角色推送	🟡 analyze_event 已有分析，无推送	🟡 分析复用，推送下期
⑥ 触发整改闭环	整改任务跟踪	❌ 无	⏭️ 下期

本期聚焦 ①②③，复用设计①异步管线与已有解析/嵌入/检索/分析能力。

4.3 架构（端口与适配器）

domain/perception/ports.py        ← 新增
   RegulationSource (Protocol)    fetch_latest() → list[RawRegulation]
   EventStore (Protocol)          抽象掉 MockEventStore（现有 mock 成为一个实现）
   ChangeDetector (Protocol)      diff(old, new) → ChangeSet

infrastructure/perception/
   sources/                       ← 新增，每法规源一个适配器
     gb_openstd_source.py         国标网 (openstd.samr.gov.cn)
     miit_source.py               工信部
     base_html_source.py          通用 HTML 抓取基类（httpx 已在 deps）
   postgres_event_store.py        ← 替换 MockEventStore（真实持久化）
   content_fingerprint_detector.py  哈希指纹 + LLM 语义 Diff

application/perception/services.py（扩展现有）
   ingest_cycle()                 ← 新增：①抓取 → ②Diff → ③入队解析（设计①的 task）
   （list_events/analyze_event 保持不变，已是真实逻辑）

infrastructure/tasks/perception_tasks.py  ← 复用设计①的 Celery
   @task perception_crawl_cycle()  Celery Beat 定时触发

4.4 关键设计决策

接口契约零改动：PostgresEventStore 输出与 MockEventStore 完全相同的 dict 结构（mock_event_store.py 的 20 字段），故 perception.ts 前端契约、PerceptionPage.tsx、analyze_event 全部不改。Mock 退化为种子数据/演示回退，通过 perception_event_store=mock|postgres 开关切换（对齐现有 document_repository_backend 模式）。
变更感知分两层：廉价层（内容哈希指纹判断"是否变了"）+ 智能层（变了才调 LLM 做"新增/修订/废止条款"结构化 Diff，复用 get_llm_client，prompt 风格照搬 compliance/pipeline.py::_extract_json）。
合规防滥用：尊重 robots.txt + 限速 + tenacity 重试 + 抓取失败不污染已有数据；适配器隔离，单源故障不影响其它。
入库复用设计①：抓到新法规 PDF → 丢进 process_document task → 自动走完解析/嵌入/索引。

4.5 落地步骤

抽 domain/perception/ports.py，让现有 MockEventStore 实现 EventStore 协议（纯重构，行为不变）。
PostgresEventStore + 建表（参照 aliyun_parser/schema.sql 风格）+ 20 条 mock 作 seed。
先做 1 个真实源适配器（建议国标网，结构最稳）跑通 ①→②→③，验证端到端。
content_fingerprint_detector + LLM Diff。
perception_crawl_cycle Celery Beat 定时（每日）；新事件落 PostgresEventStore + 新法规入队解析。
前端 PerceptionPage 加"最近同步时间/本次新增 N 条"（stats 已有结构，加 2 字段）。

4.6 工作量与风险

L（大），5-8 天，依赖设计①先落地（共用 Celery）。
最大风险：外部源站不可控（改版/反爬）。缓解：适配器隔离 + mock 永久保留为回退 + 先攻 1 个源验证（对齐 Slide 13"选取 2-3 个场景 POC 验证"）。
YAGNI 边界：④Neo4j 图谱、⑥整改闭环、多渠道推送本期不做，各自独立子项目。

5. 三阶段实施路线图

5.1 核心主线

项目不缺"能力点"，缺的是让能力点从同步脚本变成可运营的系统。主线是异步化基建：既是文档处理性能解药（设计①），又是感知闭环执行载体（设计②），也是未来 EHS/推送的统一底座。路线图以它为"第 0 块地基"，其余能力挂载其上。

5.2 与 PPT 三阶段映射（Slide 10）

PPT 规划                  代码现状          本路线图补齐
─────────────────────────────────────────────────────
一阶段 知识库+基础问答   ✅ 大体已实现     → 加固 (P0/P1)
二阶段 文档审查+API集成  🟡 审查真/API半   → 异步化+感知闭环
三阶段 EHS+个性化+图谱   ❌ 基本缺失       → 子项目 (P2)

5.3 阶段一 · 生产地基（2-3 周）— "让它扛得住生产"

顺序	事项	依据	估时
1	设计① 异步任务化	celery/redis 已在 deps，workers/ 空	M, 3-5d
2	认证 + RBAC + 审计 + 收紧 CORS	0 处 auth；Slide 12 矩阵	M, 3-5d
3	会话/任务持久化（内存 → Redis/PG）	InMemoryConversationStore 重启即丢	M, 2-3d
4	快赢：启用 Reranker	settings 默认关，管线已写好	S, 0.5d

5.4 阶段二 · 招牌能力（2-3 周）— "让它有亮点"

建议感知闭环优先于图谱（前者复用阶段一异步基建，ROI 更高）。

顺序	事项	依据	估时
5	设计② 法规感知闭环 ①②③	MockEventStore → 真实采集	L, 5-8d
6	Agentic 检索（查询改写/意图理解）	Slide 5"意图理解"，代码是直检索	M, 3-4d
7	引文置信度评分 + 基础可观测性	Slide 5 承诺；架构图右栏全缺	S+M, 3-4d

5.5 阶段三 · 视野扩展（按需，各为独立子项目）— "让它成体系"

每项单独 brainstorm → spec → 实施，本期不细化：

知识图谱 / GraphRAG（Neo4j + LightRAG v1.5，接感知闭环第④步）
EHS 隐患识别（SIF + 四维根因，Slide 7）
多渠道推送 + 订阅规则引擎（Slide 8）→ 闭环整改跟踪（第⑤⑥步）
持续加固：MinerU 3.1 升级、前端清 mock、legacy 收口

5.6 决策建议

强烈建议按阶段顺序：地基 → 招牌 → 扩展。跳过地基直接做招牌，会在生产暴露超时/无鉴权/数据丢失。
阶段一第 4 项（Reranker）可立即做 —— 半天见效，与其它解耦，适合先尝甜头。
阶段二二选一先行：要 demo 冲击力选"感知闭环"；要问答质量选"Agentic 检索"。

6. 最新 AI 技术调研（支撑选型）

技术	版本/状态（2026）	对应机会点
LightRAG	v1.5.0（2026-06），EMNLP 2025；KG-RAG，原生支持 Neo4j + MinerU/Docling，含 Web UI 图谱可视化	#7 知识图谱
MinerU	v3.1.0（2026-04），协议转为 Apache 2.0 基础的开源协议，VLM 解析（MinerU2.5-Pro），109 语言 OCR	#15 本地解析兜底
BGE Reranker	`bge-reranker-v2.5-gemma2-lightweight`（token 压缩 + 分层轻量化，生产推荐）	#5 Reranker 升级
BGE-M3	100+ 语言，8192 上下文，dense+sparse+colbert 统一（现已在用）	现有嵌入
RAGFlow	2026 支持 DeepSeek v4 / MCP / 跨语言查询；agentic RAG 参考实现	#6 Agentic 检索参考

7. 验收与边界

7.1 本文档明确不做（YAGNI）

阶段三所有子项目（图谱、EHS、推送、整改闭环、企业集成）仅列方向，不在本期展开。
移动端适配（AGENTS.md 明确 desktop-first）。
感知闭环的第④⑤⑥步（图谱同步、推送、整改）。

7.2 架构约束（必须遵守）

后端遵循 api → application → domain ports → infrastructure（docs/architecture/backend-project-architecture.md 为权威）。
新业务逻辑不得落入 services/*、workflows/*（legacy 迁移区）。
shared/bootstrap.py 为依赖装配 composition root，新依赖在此接线。
后端注释/docstring 全英文（AGENTS.md 规范）。

7.3 下一步

经用户审阅本 spec 后，对阶段一（异步任务化优先）调用 writing-plans 拆分为分步实施计划。

18 KiB Raw Permalink Blame History Unescape Escape