XinheBot v2.1 · 云-端协同多智能体巡检系统 PRD
2026-10-06 · 芯禾XinheBotPRD边缘计算MQTTLangGraph
版本：v2.1-draft（设计稿 · 未落地） 定位：在现有 XinheBot v2 云端多智能体巡检平台基础上，新增端侧轻量化 VLM Agent，形成「端侧实时感知 + 云侧复杂决策」双引擎架构。
背景与目标
现有方案痛点
当前 XinheBot v2 采用纯云端 VLM 识别架构：机器人/无人机拍摄原图 → 上传云端 GPU 服务器 → 云端大模型推理 → 返回告警结果。在野外巡检场景暴露三类核心问题：
- 弱网不可用：山区、厂区地下、密林区域无公网覆盖，原图上传失败，巡检任务中断，异常无法上报。
- 带宽成本高：单张巡检原图 2~5MB，批量巡检每天产生数千张图，4G 流量成本高、上传排队延迟大。
- 实时性不足：原图上传 + 云端推理往返延迟 2~5s，机器人无法当场触发暂停、避障等本地动作。
建设目标
构建 端侧 Agent + 云侧 Agent 双引擎巡检系统：端侧跑轻量化 VLM，本地识别、本地决策、离线缓存；云侧 LangGraph 负责复杂规划、RAG、权限、派单。网络恢复后端侧断点续传告警与证据图。
- 离线可用：断网状态下机器人/无人机继续巡检，告警本地缓存，业务不中断。
- 带宽节省：仅上传缩略图 + 元数据，原图后台补传，目标较纯云端方案降低 ≥70% 流量。
- 低延迟：端侧单帧推理 ≤500ms，高危异常本地即时响应，无需等待云端。
- 架构延续：完全复用现有 XinheBot v2 的 LangGraph 主图、MCP 工具层、告警面板、任务调度，不重写业务。
整体架构
系统分三层：端侧层（设备本地）、云侧层（现有 XinheBot 后端）、前端层（PC + 移动 H5）。端云之间通过 MQTT/HTTPS 弱网自适应通道通信。
┌─────────────────────────────────────────────────────────────┐
│ 端 侧 层（设备本地） │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ 巡检机器人 RK3588 │ │ 无人机机载计算模块 │ │
│ │ ┌──────────────────┐ │ │ ┌──────────────────┐ │ │
│ │ │ 端侧 VLM Agent │ │ │ │ 端侧 VLM Agent │ │ │
│ │ │ 异常识别/本地决策│ │ │ │ 异常识别/航线调整│ │ │
│ │ ├──────────────────┤ │ │ ├──────────────────┤ │ │
│ │ │ SQLite 离线缓存 │ │ │ │ SQLite 离线缓存 │ │ │
│ │ │ 断点续传队列 │ │ │ │ 断点续传队列 │ │ │
│ │ └──────────────────┘ │ │ └──────────────────┘ │ │
│ └──────────┬───────────┘ └──────────┬───────────┘ │
└─────────────┼──────────────────────────┼────────────────────┘
│ MQTT / HTTPS 弱网自适应 │
┌─────────────┼──────────────────────────┼────────────────────┐
│ ▼ ▼ │
│ FastAPI 主后端 (8012) · LangGraph 云侧多智能体主图 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Expert RAG │ Patrol │ Drone │ EdgeAlarmSubgraph(新增) │ │
│ │ 三层记忆 · Reflection · MCP 35工具 · 多租户RBAC │ │
│ └──────────────────────────────────────────────────────┘ │
│ MySQL 8 · PostGIS 16 · Redis · Milvus · MinIO · Mosquitto │
└──────────────────────────────┬─────────────────────────────┘
│
┌──────────────────────────────┴─────────────────────────────┐
│ PC 管理端 (Vue3 + Cesium + Element Plus) · 移动 H5 │
│ 实时告警面板 / 批量视觉工作台 / 任务中心 / 复核派单 │
└─────────────────────────────────────────────────────────────┘设计原则：端侧只做”实时、轻量、离线就能干”的事；云侧只做”重计算、需要大模型、需要跨设备数据”的事。两者职责不重叠、不重复推理。
端云职责边界（核心设计）
| 维度 | 端侧 Agent（设备本地） | 云侧 Agent（LangGraph） |
|---|---|---|
| 模型规模 | 轻量化 VLM（Qwen-VL-2B INT8 量化，RKNN 格式转换） | 云端大模型 Qwen-Plus / 本地 7B，复杂推理与 RAG |
| 核心能力 | 图像异常识别、本地告警标记、简单动作触发（暂停/绕行）、离线缓存 | 复杂任务规划、CAD/OCR 图纸解析、RAG 知识库问答、多租户权限、复核派单、工单联动 |
| 数据范围 | 仅本机巡检画面、本地缓存告警 | 全租户设备、历史数据、知识库、工单、跨设备协同 |
| 网络依赖 | 断网可独立运行，巡检任务不中断 | 需联网访问数据库 / LLM / 向量库 |
| 传输内容 | 缩略图 + 告警元数据；网络恢复后补传原图 | 任务指令、航线、配置、知识库检索结果下发 |
| 硬件载体 | 巡检机器人 RK3588 / Jetson Orin；无人机机载计算模块 | 云端 GPU 服务器 / 现有 FastAPI 部署节点 |
端侧 Agent 模块设计
部署形态
| 设备类型 | 硬件载体 | 模型部署 | 通信通道 |
|---|---|---|---|
| 巡检机器人 | 板载 RK3588 / Jetson Orin NX | Qwen-VL-2B INT8 量化版，RKNN 格式转换，本地推理 | 复用现有 Mosquitto MQTT 遥测通道 |
| 巡检无人机 | 机载计算模块 | 轻量化 YOLO-VLM 异常检测模型 | 4G / 数传电台弱网通道 |
端侧核心功能
- 本地视觉异常识别：实时对巡检画面帧推理，识别人员闯入、垃圾堆积、水体污染、设备跑冒滴漏、管线破损；端侧识别延迟 ≤500ms，命中异常自动抓拍原图 + 生成 bbox 标注框；高危异常（人员闯入）本地立即触发机器人暂停 + 声光提示，不依赖云端。
- 离线缓存队列：端侧本地 SQLite 存储未上传成功的告警记录；单设备缓存上限 2000 条，超出按 FIFO 淘汰最早记录；离线状态下巡检任务正常执行。
- 断点续传同步：网络恢复后按 created_at 时间序自动批量上传；每条告警携带端侧生成的全局唯一 alarm_id（UUID），云端幂等去重；原图分片续传，单张最大 5MB，失败自动重试 3 次指数退避。
- 本地降级策略：VLM 模型加载失败 → 降级为传统 CV 规则检测；本地存储满 → 暂停原图抓拍仅上传元数据；电量 < 20% → 自动缓存剩余任务并上报。
云侧协同模块设计
LangGraph 新增端侧告警协同子图
在现有 MainGraph 总线下新增 EdgeAlarmSubgraph，挂接在 customer 路由之后，处理端侧上送的告警流：
端侧告警上报
│
▼
[去重校验] alarm_id 幂等检查，重复直接 ACK
│
▼
[异常分类] 按 anomaly_type + level 路由
│
▼
[租户校验] tenant_id 行级隔离，跨租户直接 403
│
├──► 正常告警 ──► 合并入告警列表 ──► WebSocket 推送 PC/H5
│
├──► 高危告警 ──► 自动建工单 ──► 派发对应巡检员
│
└──► 重复告警 ──► 合并同点位 5 分钟内同类告警，防告警风暴与现有模块的复用集成
| 现有模块 | 集成方式 |
|---|---|
| 实时告警面板（PC） | 现有 Vue 告警列表自动合并端侧上报 + 云端历史告警；端侧告警新增 source=edge 标签区分来源 |
| 移动 H5 任务中心 | 端侧高危告警实时推送到巡检员 H5”活跃告警”列表；点击告警一键”派人复核” |
| MCP 工具层 | 新增 3 个端侧工具：edge_alarm_list / edge_ack_alarm / edge_sync_status |
| RAG 知识库 | 端侧上报异常时，云侧自动检索对应设备维保知识库，生成故障排查建议随告警推送 |
| 批量视觉识别工作台 | 端侧识别结果与云端批量识别结果共用同一告警表、同一证据图存储 |
数据设计
端侧本地表（SQLite）
| 字段 | 类型 | 说明 |
|---|---|---|
alarm_id | TEXT | 全局唯一 UUID（端侧生成，云端幂等键） |
device_sn | TEXT | 设备序列号 |
anomaly_type | TEXT | 异常类型（intrusion / garbage / water / leak …） |
level | TEXT | 告警级别（alarm / warn / normal） |
lon / lat / alt | REAL | 拍摄位置经纬高 |
thumbnail_path | TEXT | 本地缩略图路径 |
image_path | TEXT | 本地原图路径 |
bbox_json | TEXT | 异常框坐标 JSON |
created_at | TEXT | 拍摄时间（ISO8601） |
sync_status | INTEGER | 0=未同步 / 1=已同步 / 2=同步失败 |
云端扩展字段（现有 alarms 表新增）
| 字段 | 类型 | 说明 |
|---|---|---|
source | VARCHAR(16) | 告警来源：cloud / edge |
bbox_json | JSON | 异常标注框坐标（端侧识别产出） |
synced_at | DATETIME | 端侧同步完成时间 |
sync_delay_sec | INT | 断网延迟上报时长（秒） |
接口设计
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/edge/alarms/report | 端侧批量上报告警元数据（含 alarm_id 幂等键） |
| POST | /api/edge/alarms/{alarm_id}/image | 端侧分片上传告警原图（断点续传） |
| GET | /api/edge/devices/{sn}/sync-status | 查询端侧设备未同步告警数 / 同步进度 |
| POST | /api/edge/alarms/{alarm_id}/ack | 巡检员确认端侧告警 |
| WS | /ws/{tenant}/{user} | 复用现有 WebSocket 推送端侧新告警 |
所有接口强制 JWT + 设备 SN 双鉴权；端侧上报数据自动绑定 tenant_id，服务端二次校验设备归属，杜绝跨租户数据泄露。
降级与异常策略
| 异常场景 | 端侧行为 | 云侧行为 |
|---|---|---|
| VLM 模型加载失败 | 降级为传统 CV 规则检测 | 接收降级标记，告警详情页标注”规则检测” |
| 本地存储满 | 暂停原图抓拍，仅上传告警元数据 | 收到存储满状态，下推清理指令 |
| 电量 < 20% | 自动缓存剩余任务，上报低电量 | 调度器重新分配任务或召回设备 |
| 网络长时间断开 | 持续写入 SQLite，2000 条上限 FIFO 淘汰 | 在设备列表标记”离线缓存中” |
| 重复告警风暴 | 端侧 5 秒内同点位同类告警合并 | 云侧 5 分钟窗口二次合并 |
非功能需求
| 指标 | 目标值 |
|---|---|
| 端侧单帧推理延迟 | ≤500ms |
| 告警上报到前端延迟 | ≤3s |
| 带宽节省比例 | ≥70% |
| 端侧识别准确率 | ≥85% |
| 断网缓存时长 | ≥72 小时 |
| 断点续传告警去重率 | 100% |
说明：本 PRD 为架构设计思路稿，当前阶段无真实端侧硬件与模型部署。端侧 VLM 模型、RKNN 转换、SQLite 缓存、断点续传接口均为规划中的能力，用于面试讲解与后续迭代方向。