vent_ai_platform

矿山通防智能管控平台后端

独立于 vent_agent_2.0 的新后端框架，使用：

• FastAPI：HTTP 服务、OpenAPI、依赖注入和 SSE
• SQLAlchemy 2.0：业务数据库 ORM
• Alembic：数据库迁移
• MySQL / SQLite：生产与本地开发双数据库支持
• DeepAgent + LangGraph：智能体、知识问答、诊断解释、评价优化和业务工作流

架构定位

普通业务数据使用 REST API 管理，DeepAgent 不直接负责数据库增删改查。诊断与评价先由确定性规则引擎计算，再由 DeepAgent 补充根因分析、解释和优化建议。未配置模型或未安装 Agent 依赖时，系统自动降级，业务 API 仍然可用。

API 层
  dashboard / documents / monitoring / video-platform / knowledge
  diagnosis / evaluations / work-orders / ai

服务层
  业务规则 / 诊断引擎 / 评价引擎 / 工单状态机 / DeepAgent 工作流

数据层
  SQLAlchemy ORM / Repository / MySQL / SQLite / Alembic

目录

app/
  api/v1/endpoints/    HTTP 接口
  agents/              DeepAgent 运行时、上下文和工作流
  core/                配置、日志、异常和中间件
  db/models/           数据库模型
  db/repositories/     数据访问层
  schemas/             请求与响应模型
  services/            业务服务层
alembic/               数据库迁移
docs/                  架构、数据库和接口文档
scripts/               初始化、种子数据
tests/                 自动化测试

详细设计见 架构说明、数据库设计 和 API 文档。

本地启动

要求 Python 3.12。

cd D:\PycharmProjects\vent_platform_backend
python -m venv .venv
.\.venv\Scripts\python -m pip install -U pip
.\.venv\Scripts\python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python scripts\seed_demo.py
.\.venv\Scripts\python -m uvicorn app.main:app --reload --port 8090

浏览器访问：

• Swagger：http://127.0.0.1:8090/docs
• 健康检查：http://127.0.0.1:8090/health
• API 前缀：http://127.0.0.1:8090/api/v1

默认使用 SQLite。生产环境建议使用 MySQL：

DATABASE_DIALECT=mysql
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=vent_platform

也可以直接启动 MySQL：

docker compose up -d mysql

DeepAgent

在 .env 中配置 OpenAI 兼容模型：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.deepseek.com
DEEPAGENT_MODEL=deepseek-flash

没有配置模型时：

• /api/v1/ai/capabilities 会显示智能体未启用
• 诊断、评价、业务 CRUD 和知识检索仍可运行
• AI 工作流返回规则引擎生成的降级说明

数据库迁移

.\.venv\Scripts\alembic upgrade head
.\.venv\Scripts\alembic revision --autogenerate -m "change description"

初始迁移 0001_initial 创建当前全部表。后续结构变化应生成显式增量迁移。

工业视频平台演示数据

页面“工业视频平台”的后端数据保存在 video_channels、video_snapshots、 video_analysis_events、video_records 四张表中，覆盖风门、局部风机、主风机及配电室三个模块： 通道与设备树、分屏预览、状态总览、识别抓拍、通行与操作记录、视频分析事件。

视频与图像文件不入库，表字段保存磁盘绝对路径，媒体根目录由 VIDEO_MEDIA_ROOT 指定 （默认 D:/workspace/js/gate_analysis_system，即风门/局扇/主扇识别演示系统的公开资源目录）。 接口 /api/v1/video-platform/channels/{id}/stream 按库中路径流式返回视频并支持 Range 拖动， /api/v1/video-platform/snapshots/{id}/image 返回抓拍原图。

已有数据库补种视频平台演示数据（幂等，可重复执行）：

.\.venv\Scripts\python scripts\seed_video_platform.py

测试

.\.venv\Scripts\python -m pytest