vent_ai_platform/docs/api.md

API 清单

统一前缀：/api/v1

系统

方法	路径	说明
GET	/system/info	平台、数据库和 Agent 信息
GET	/system/health	业务数据库健康检查
GET	/health	服务级健康检查

驾驶舱与矿井

方法	路径	说明
GET	/dashboard/overview	驾驶舱 KPI 与模块汇总
GET	/mines	矿井列表
POST	/mines	新增矿井
GET	/mines/{id}	矿井详情
GET	/mines/{id}/areas	采区列表
GET	/mines/{id}/work-faces	工作面列表
GET	/mines/{id}/roadways	巷道列表

业务资料

方法	路径	说明
GET	/documents	分页、分类和关键词检索
GET	/documents/categories	分类统计
GET	/documents/templates	按 PDF、Word、Excel 查询抽取模板
POST	/documents	创建资料元数据
POST	/documents/upload	上传资料文件并自动进入解析、抽取工作流
GET	/documents/{id}	资料及结构化字段详情
PATCH	/documents/{id}	更新资料
DELETE	/documents/{id}	删除资料
GET	/documents/{id}/processing	查看 MinerU 解析和模型抽取进度
POST	/documents/{id}/process	重新执行解析和抽取
POST	/documents/{id}/extractions	新增结构化字段

上传表单支持 parse_mode：

值	模式	MinerU API	限制
lightweight	轻量解析	/api/v1/agent/parse/file	10 MB / 20 页
precision	精准解析	/api/v4/file-urls/batch	200 MB / 200 页

数据感知

方法	路径	说明
GET	/monitoring/overview	数据源、传感器、设施和告警汇总
GET	/monitoring/sources	数据源
GET	/monitoring/sensors	传感器
GET	/monitoring/sensors/{id}/readings	最近监测值
POST	/monitoring/readings	写入实时监测值
GET	/monitoring/facilities	通风设施
GET	/monitoring/alarms	告警

工业视频平台

对应页面“工业视频平台”：通道管理、实时视频、分屏预览、状态总览、识别抓拍与智能识别事件。

方法	路径	说明
GET	/video-platform/overview	通道总量、在线/离线/故障、未闭环事件和抓拍总量
GET	/video-platform/modules	风门/局部风机/主风机页签、检索项与记录表头配置
GET	/video-platform/modules/{module}/summary	模块状态总览（正常、离线、故障、预警与今日统计）
GET	/video-platform/channels	通道列表，支持模块、状态和关键字筛选
POST	/video-platform/channels	新增通道
GET	/video-platform/channels/{id}	通道详情
PATCH	/video-platform/channels/{id}	更新通道
DELETE	/video-platform/channels/{id}	删除通道及其抓拍与记录
GET	/video-platform/channels/{id}/stream	视频流，按库中磁盘路径读取，支持 Range 拖动播放
GET	/video-platform/channels/{id}/snapshot	通道最近识别抓拍图（抓图按钮）
GET	/video-platform/snapshots	识别抓拍检索（时间范围、类型、设备、关键字分页）
GET	/video-platform/snapshots/{id}	抓拍详情
GET	/video-platform/snapshots/{id}/image	抓拍原图
GET	/video-platform/snapshots/{id}/thumbnail	抓拍缩略图
GET	/video-platform/events	视频分析事件与实时告警
PATCH	/video-platform/events/{id}	更新事件处理状态
GET	/video-platform/records	通行与操作记录（车辆/人员通行、未关严、人员轨迹、区域统计、设备操作等）

module 取值为 door（风门）、local_fan（局部风机）、main_fan（主风机及配电室）。 视频与图像不写入数据库，表中保存磁盘绝对路径，媒体根目录由 VIDEO_MEDIA_ROOT 指定； /stream 与 /image 按库中路径流式返回文件，支持 Range 断点拖动，文件缺失时返回 404。

知识中心

方法	路径	说明
GET	/knowledge	知识列表
POST	/knowledge	新增知识
POST	/knowledge/search	关键词检索和排序
GET	/knowledge/overview	远端知识库状态、知识条目和分类统计
GET	/knowledge/catalog	远端知识目录，支持分类、标签和关键词筛选
GET	/knowledge/catalog/{note_id}	远端知识条目详情和完整内容
POST	/knowledge/ask	面向页面问答的检索、来源追溯和摘要回答
POST	/knowledge/rag	RAG 问答，检索知识库并调用大模型生成带引用回答
POST	/knowledge/rag/stream	RAG 问答 SSE 流式接口，逐段返回模型生成内容
GET	/knowledge/rag/stream	EventSource 流式接口，参数为 question 和 top_k
WS	/knowledge/rag/ws	WebSocket 流式接口，客户端发送问题，服务端逐帧推送结果
GET	/knowledge/graph	基于知识标签生成风险关联关系图

知识中心通过 KNOWLEDGE_SERVICE_BASE 接入远端 Obsidian Vault 检索服务。 远端未启用向量模型时，后端会自动将 semantic/hybrid 请求降级为 keyword， 并对中文整句自动提取“局部通风机、瓦斯超限、风量”等领域关键词后多路检索。 /knowledge/ask 默认调用 RAG 生成，也可将 generate_answer 设为 false 只返回检索摘要。 /knowledge/rag 始终启用大模型生成。生成阶段会把编号后的检索片段作为上下文， 要求模型只依据资料回答并标注 [1]、[2] 来源编号；模型不可用时自动降级为检索摘要。 寒暄、自我介绍和能力咨询会先经过意图路由，不进入知识检索，直接由大模型简洁回复。

/knowledge/rag/stream 返回 text/event-stream，事件顺序为：

1. meta：问题、检索模式、来源列表和检索耗时。
2. thinking：模型返回的推理过程增量内容。
3. delta：模型正式回答的逐段内容。
4. warning：流式生成异常时的非阻断告警。
5. done：完整回答、最终状态、模型名和生成耗时。

页面优先使用 WebSocket，避免部分浏览器或代理对 SSE 响应进行整体缓冲； WebSocket 不可用时自动回退到 EventSource 或 fetch 流。 前端将 thinking 放入可折叠容器，回答内容按 Markdown 渲染，来源在回答结束后显示。

缺陷诊断

方法	路径	说明
GET	/diagnosis/rules	诊断规则
GET	/diagnosis/tasks	诊断任务
GET	/diagnosis/tasks/{id}	结果和证据链
POST	/diagnosis/run	执行规则诊断

综合评价

方法	路径	说明
GET	/evaluations/indicators	评价指标
POST	/evaluations/indicators	新增指标
GET	/evaluations/runs	评价批次
GET	/evaluations/runs/{id}	评价和指标得分
POST	/evaluations/run	执行综合评价

闭环处置

方法	路径	说明
GET	/work-orders	整改任务
POST	/work-orders	新建任务
GET	/work-orders/{id}	任务详情
PATCH	/work-orders/{id}	更新任务状态
GET	/work-orders/{id}/events	任务轨迹
POST	/work-orders/{id}/events	添加处理事件

DeepAgent

方法	路径	说明
GET	/ai/capabilities	Agent 和工作流状态
POST	/ai/workflows/run	运行诊断、评价、问答或资料分析工作流
POST	/ai/chat?stream=false	知识问答 JSON 响应
POST	/ai/chat?stream=true	知识问答 SSE 响应