AItrackwalker/AItrackwalker

Fork 0

Files

T

admin b2150c4b68 本地模型可接入

2026-07-22 10:46:09 +08:00

12 KiB

Raw Permalink Blame History

铁路无人机智能巡检系统实现说明

1. 当前实现范围

本仓库已按《铁路无人机智能巡检系统设计说明书》定义的架构重新实现，主实现不再采用单体 Python 原型，而是采用以下工程结构：

platform/backend：Spring Boot 业务平台。
ai-services/vision-inference：FastAPI 视觉/红外/变化检测服务。
ai-services/pointcloud-analysis：FastAPI 点云/TIF/DEM 形变分析服务。
frontend：Vue3 + TypeScript 前端。
infra：PostGIS、Redis、Kafka、MinIO、Prometheus、各服务 Docker Compose 编排。
docs/IMPLEMENTATION_COMPLIANCE.md：设计说明书到实现的映射关系。
docs/full-chain-visualization-design.md：全链路可视化设计方案。
docs/full-chain-node-visualization-analysis-design.md：全链路节点交互与数据展示设计。

当前 AI 服务保留确定性推理适配器，接口、模型组、返回结构均按真实模型接入方式设计。全链路运行已实现 12 个节点工作台、节点快照、SSE 实时事件、失败重试、实体索引和结果导出。后续接入 YOLO、Mask R-CNN、SAM、ONNX Runtime、TensorRT、Open3D/PCL、GDAL 等模型或算法时，替换对应 FastAPI 服务内的推理适配逻辑即可。

模型管理工作台已完成模型台账、版本与制品、JSON Schema 参数方案、固定回归集、临时样本上传、断点续传、异步测试、多模态结果查看、横向评估、报告导出、反馈回流和发布治理。入口为 /algorithm-assets/models。

2. 目录结构

platform/backend/                 Spring Boot 业务平台
ai-services/vision-inference/      FastAPI 视觉/红外/变化检测服务
ai-services/pointcloud-analysis/   FastAPI 点云/TIF 分析服务
frontend/                          Vue3 + TypeScript 前端
infra/                             Docker Compose 与 Prometheus 配置
scripts/                           启停与冒烟测试脚本
docs/                              实现映射与说明

3. 本地启动完整技术栈

.\scripts\start_stack.ps1

Docker 镜像默认走已验证可用的华为云 SWR Docker Hub 代理 swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io，Python 依赖走阿里 PyPI，Maven 依赖配置华为云、腾讯云、阿里云和 Maven Central 多源兜底，前端依赖走 npmmirror。

访问：

http://localhost:8088

个人 CPU 电脑使用专用配置启动：

.\scripts\start_cpu_stack.cmd

CPU 模式启用 ONNX Runtime CPU、Open3D CPU、单并发、批量 1、模型懒加载和 500,000 点上限。五类模型的制品目录、安装方式、真实推理与基线结果区分见 docs/local-cpu-model-runtime.md。

4. 核心接口

POST /api/v1/inspection/tasks
POST /api/v1/uav/callbacks/mission-status
POST /api/v1/inspection/resources/complete
POST /api/v1/analysis/jobs
POST /api/v1/analysis/jobs/{job_id}/run
GET  /api/v1/alarms
POST /api/v1/workorders/callbacks/status
POST /api/v1/exemptions
GET  /api/v1/models
GET  /api/v1/stats/overview
POST /api/v1/demo/run-full-chain
POST /api/v1/demo/runs
GET  /api/v1/demo/runs/{run_id}
GET  /api/v1/demo/runs/{run_id}/events
GET  /api/v1/demo/runs/{run_id}/events/history
POST /api/v1/demo/runs/{run_id}/cancel
GET  /api/v1/demo/runs/{run_id}/steps/{step_key}
POST /api/v1/demo/runs/{run_id}/steps/{step_key}/retry
GET  /api/v1/demo/runs/{run_id}/entities
GET  /api/v1/demo/runs/{run_id}/export
GET  /api/v1/inspection/resources/{resource_id}/preview
GET  /api/v1/analysis/results/{result_id}/evidence
GET  /api/v1/alarms/{alarm_id}/evidence-chain
POST /api/v1/workorders/{workorder_id}/redispatch
POST /api/v1/workorders/{workorder_id}/review
POST /api/v1/samples/{sample_id}/decision
GET  /api/v1/models/{model_group_id}/versions
GET  /api/v1/models/{model_group_id}/parameter-profiles
POST /api/v1/parameter-profiles/validate
GET  /api/v1/models/{model_group_id}/sample-sets
POST /api/v1/sample-sets/preview
POST /api/v1/test-uploads
POST /api/v1/test-uploads/{session_id}/files
POST /api/v1/test-uploads/{session_id}/chunked-files
PUT  /api/v1/test-uploads/{session_id}/chunked-files/{manifest_id}/parts/{part_index}
POST /api/v1/test-uploads/{session_id}/chunked-files/{manifest_id}/complete
POST /api/v1/model-tests
POST /api/v1/model-tests/{task_id}/validate
POST /api/v1/model-tests/{task_id}/start
GET  /api/v1/model-tests/{task_id}/events
GET  /api/v1/model-tests/{task_id}/results
GET  /api/v1/model-tests/{task_id}/summary
GET  /api/v1/model-tests/{task_id}/report
POST /api/v1/model-test-results/{result_id}/feedback
POST /api/v1/model-releases
POST /api/v1/model-releases/{release_id}/approve
POST /api/v1/model-releases/{release_id}/gray
POST /api/v1/model-releases/{release_id}/promote
POST /api/v1/model-releases/{release_id}/rollback

5. 验证

.\scripts\smoke_test.ps1

冒烟脚本默认通过前端 Nginx 反向代理访问 API，即 http://localhost:8088。脚本会启动新的全链路运行实例，轮询运行快照直到完成，并校验 12 个节点快照、22 条有序事件、实体数量、工单接口与前端入口。如需直连后端，可设置 RAIL_API_BASE_URL=http://localhost:8080。

完整交互回归：

.\scripts\full_chain_interaction_test.ps1

该脚本覆盖资源预览、算法证据、告警证据链、工单改派与复核、样本处置、结果导出、运行取消及从失败节点重试。

离线静态校验：

.\scripts\run_static_checks.ps1

6. 单服务开发命令

# 后端
docker run --rm -v "$PWD\platform\backend:/workspace" -w /workspace swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/maven:3-eclipse-temurin-17 mvn -s maven-settings.xml -B -Ptests test

# 前端
cd frontend
npm install --registry=https://registry.npmmirror.com
npm run build

# 视觉推理服务
cd ai-services/vision-inference
python -m pytest

# 点云分析服务
cd ai-services/pointcloud-analysis
python -m pytest

7. 部署说明

当前部署使用 Docker Compose 拉起完整技术栈。生产环境建议将 Compose 配置迁移到 Kubernetes/K3s，并按设计说明书继续扩展：

Spring Boot 服务横向扩展。
FastAPI 推理服务按模型组独立扩展。
PostgreSQL/PostGIS、Kafka、Redis、MinIO 使用生产级高可用部署。
Prometheus/Grafana 接入告警策略。
AI 模型改为 ONNX Runtime/TensorRT/Triton 推理。
点云分析接入 Open3D/PCL/GDAL 生产处理链。

已在本机生成前端 dist 时，可跳过容器内 npm 安装并使用预构建覆盖配置：

docker compose -f infra/docker-compose.yml -f infra/docker-compose.prebuilt.yml build frontend
docker compose -f infra/docker-compose.yml -f infra/docker-compose.prebuilt.yml up -d

后端镜像构建会执行 JUnit 测试；两个 Python 服务使用多阶段镜像构建，测试阶段执行 pytest，生产层不保留测试依赖。

8. 验证路径

启动完整技术栈。
打开 Web 前端。
点击“启动全链路”。
查看 12 个节点工作台中的任务参数、航线下发、多源接入、预处理流水线、推理过程、规则判定、告警、工单闭环、样本回流和完成汇总。
查看任务、AI 结果、告警、工单、模型版本。
执行 scripts/smoke_test.ps1 与 scripts/full_chain_interaction_test.ps1 验证 API 和节点交互。

9. 多页面导航实现

前端已按业务域拆分为固定左侧导航和独立路由页面：

页面	路由	主要能力
工作总览	`/overview`	核心指标、重点待办、健康状态和快捷入口
GIS 态势	`/gis`	线路、规则区域、航线、告警点位和实体联动
全链路运行	`/runs`	12 节点工作台、运行记录、异常恢复和历史回放
巡检任务	`/tasks`	任务创建、航线下发、取消和任务详情
数据资源	`/resources`	资源库、接入监控、预处理、质量和预览
智能分析	`/analysis`	分析任务、AI 结果、规则判定和失败恢复
告警中心	`/alarms`	证据链、确认、抑制、恢复和工单关联
工单中心	`/workorders`	表格、泳道、地图、改派、复核和退回
样本与模型	`/algorithm-assets`	样本决策、标注队列、数据集和模型版本
系统运维	`/operations`	服务健康、接口集成、平台事件和系统配置

前端页面使用路由级懒加载。告警、工单、分析结果和样本等高数据量列表使用分页，详情通过抽屉或独立实体路由加载。桌面端使用固定左侧导航，窄屏改为导航抽屉。

页面和接口验收：

.\scripts\navigation_pages_test.ps1

该脚本检查 10 个页面路由、11 组页面数据接口、任务创建与航线状态、任务取消及告警确认操作。

10. 模型管理工作台

页面	路由参数	能力
模型列表	`/algorithm-assets/models`	模型类型、输入模态、生产/候选版本、服务状态和测试统计
能力概览	`?panel=overview`	生产基线、适用场景、版本关系和近期活动
版本与制品	`?panel=versions`	制品哈希、运行约束、契约和校验报告
运行配置	`?panel=runtime`	本地/服务器端点、版本绑定、资源参数、健康检查和原子切换
参数方案	`?panel=parameters`	动态表单、跨字段校验、不可变修订、比较与启停
测试工作台	`?panel=test`	快速测试、批量回归、版本对比、参数对比、样本库与本地上传
评估记录	`?panel=evaluations`	指标比较、结果明细、运行事件和 Markdown 报告
发布记录	`?panel=releases`	申请、审批、灰度、生产切换、回滚和审计

大于 8 MB 的本地样本自动使用幂等分片上传，每片最多重试 3 次；服务端按清单验证分片数量与总大小，合并后计算 SHA-256，再写入 MinIO。上传会话默认保留 7 天，未被测试任务引用的过期对象由定时任务清理。

测试编排使用独立异步执行器和 SSE 事件流，固化模型制品、参数修订、输入校验和与运行环境。视觉检测、分割、红外、变化检测和点云结果使用专用查看器；三维点云基于 Three.js，可切换距离、高程和强度着色。

运行配置将模型版本绑定到实际推理端点，并管理运行引擎、执行提供程序、设备、精度、副本、并发、超时和降级策略。切换前会校验端点健康、运行档案、注册版本和制品状态，切换与回退写入审计记录。服务器部署提供 CUDA/ONNX Runtime GPU 镜像、版本化模型注册表和独立 Compose 覆盖配置，详见 docs/model-runtime-configuration-and-deployment.md。

11. 本次验证记录

Spring Boot：6 个 JUnit 测试全部通过。
视觉推理服务：4 个 FastAPI 契约与运行时测试全部通过。
点云分析服务：4 个 FastAPI 契约与运行时测试全部通过。
Vue3：vue-tsc --noEmit 与 Vite 生产构建通过。
分片上传：8 MB + 1 MB 两分片合并成功，下载对象为 9,437,184 字节，SHA-256 已生成。
测试任务：浏览器选样后完成 8 个可视化执行步骤，结果、汇总指标和验收结论可查询。
点云画布：WebGL 画布为 916 × 537，截图抽样区域包含 2000 余种颜色，确认场景正常渲染。
响应式：390 × 844 下模型列表与结果查看器无页面级横向溢出。
运行配置：完成创建、健康检查、动态切换、切回和删除验收；本地环境能够阻止误切 server-gpu 档案。
部署：PostGIS、Redis、Kafka、MinIO、后端、前端和两个 AI 服务均处于运行或健康状态。

12 KiB Raw Permalink Blame History Unescape Escape