vent_ai_platform/docs/architecture.md

架构说明

分层边界

API 层

负责 HTTP 参数、状态码、分页和响应模型，不直接编写 SQL，不保存业务状态。所有路由统一挂载在 /api/v1。

服务层

负责业务规则和事务编排：

• diagnosis_service：基于监测、设施和工作面数据执行规则诊断
• evaluation_service：计算五维指标、综合得分和等级
• work_order_service：生成任务编号并记录状态迁移
• knowledge_service：检索和排序知识条目
• knowledge_hub_service：接入远端 Vault 知识检索、目录聚合、问答和风险图谱
• knowledge_hub_service RAG 流程：多路召回 → 去重排序 → 上下文裁剪 → DeepAgent 生成 → 来源编号回传；模型失败时返回抽取式摘要
• 知识中心支持 SSE 流式 RAG，先返回来源元数据，再逐段推送模型 token，最后发送完成事件
• 页面优先通过 WebSocket 接收 RAG token，SSE 与 fetch 作为兼容回退

Repository 层

负责 SQLAlchemy 查询和持久化。未来切换数据源时，API 与服务层不需要修改。

Agent 层

DeepAgent 只增强以下能力：

• 诊断根因和耦合关系解释
• 综合评价解释和优化建议
• 基于检索结果的知识问答
• 业务资料字段分析

数值计算、风险等级和数据库写入由确定性服务完成。模型失败时返回规则引擎结果，不阻断业务。

数据流

数据源 / 业务资料 / 监测数据
        │
        ▼
数据接入与结构化存储
        │
        ├── 知识条目与检索
        ├── 缺陷规则与诊断结果
        ├── 评价指标与评价批次
        └── 告警与整改工单
        │
        ▼
DeepAgent 解释、归纳、问答和建议

并发与一致性

• 普通 CRUD 使用同步 SQLAlchemy Session，FastAPI 在线程池执行同步依赖。
• DeepAgent 工作流使用异步模型调用。
• 诊断和评价的计算结果先落库，再调用模型生成解释。
• 工单状态迁移记录 work_order_events，保留完整轨迹。

生产扩展

• 高频监测数据建议迁移到 TDengine、InfluxDB 或同类时序数据库。
• 文件建议迁移到 MinIO 或对象存储。
• 知识向量迁移到 Milvus、pgvector 或 Elasticsearch。
• 知识中心当前接入远端 Obsidian Vault 检索服务；远端仅负责召回，平台负责分类、 来源追溯、可选生成式回答和页面数据聚合。
• 用户鉴权、RBAC 和矿井级数据隔离需要在上线前补齐。
• 单机部署可直接运行；高并发场景应拆分 API、Agent Worker 和采集服务。