# 铁路无人机智能巡检平台本地 CPU 模型运行说明

## 1. 运行目标

本地 CPU 模式用于个人电脑上的系统开发、单样本测试、接口联调和处理流程验证。运行配置固定为：

| 配置项 | 本地值 |
| --- | --- |
| 运行配置 | `cpu-local` |
| 执行提供程序 | `CPUExecutionProvider` |
| 模型交换格式 | ONNX |
| 计算精度 | FP32 |
| 单次批量 | 1 |
| 最大推理并发 | 1 |
| 最大常驻模型 | 1 |
| 视觉输入尺寸 | 512 或 640 |
| 点云点数上限 | 500,000 |
| 模型加载策略 | 按需加载、LRU 卸载 |

该模式不承担模型训练、多路视频实时处理或生产高并发推理。

## 2. 五类能力

| 模型组 | 本地配置 | 无模型制品时的行为 |
| --- | --- | --- |
| `vision-detector` | PP-YOLOE-SOD-s ONNX | 返回带 `execution_mode=baseline` 的基线结果 |
| `vision-segmenter` | PP-LiteSeg-STDC1 ONNX | 返回带 `execution_mode=baseline` 的基线结果 |
| `change-detector` | BIT-R18 ONNX | 有双时相影像时使用 OpenCV CPU 差分，否则返回基线结果 |
| `pointcloud-analyzer` | Open3D CPU | PLY/PCD/XYZ/PTS 可直接执行几何分析，不需要模型权重 |
| `thermal-analyzer` | PP-YOLOE-s 与 PatchCore ONNX | 使用辐射元数据执行温度规则并返回基线定位结果 |

基线模式只用于业务流程验证，不计作真实模型精度。前端、接口结果和运行快照均显示执行模式和降级原因。

## 3. 一键启动

```powershell
.\scripts\start_cpu_stack.cmd
```

脚本依次执行：

1. 创建五类模型的本地制品目录。
2. 以基础 Compose 和 CPU 覆盖配置构建服务。
3. 启动 PostGIS、Redis、Kafka、MinIO、后端、前端和两个 AI 服务。
4. 等待服务健康并检查 CPU 配置。
5. 验证五个模型组、Open3D 和推理模式标识。

已经完成镜像构建时可以跳过构建：

```powershell
.\scripts\start_cpu_stack.cmd -NoBuild
```

访问地址：

- 平台：<http://localhost:8088>
- 系统运维：<http://localhost:8088/operations>
- 视觉运行状态：<http://localhost:8101/api/v1/runtime>
- 空间运行状态：<http://localhost:8102/api/v1/runtime>

## 4. 制品目录

```text
runtime/models/
├── vision-detector/ppyoloe-sod-s/
│   ├── model.onnx
│   └── labels.txt
├── vision-segmenter/pp-liteseg-stdc1/
│   ├── model.onnx
│   └── labels.txt
├── change-detector/bit-r18/
│   ├── model.onnx
│   └── labels.txt
└── thermal-analyzer/
    ├── ppyoloe-s/
    │   ├── model.onnx
    │   └── labels.txt
    └── patchcore/
        └── model.onnx
```

模型制品目录由 `.gitignore` 中的 `runtime/` 规则保护，不进入 Git。

## 5. 安装模型

将经过铁路数据训练并导出的 ONNX 模型安装到注册表指定位置：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup_cpu_models.ps1 `
  -ModelGroup vision-detector `
  -ModelPath C:\models\rail-ppyoloe-sod-s.onnx `
  -LabelsPath C:\models\rail-labels.txt `
  -Restart
```

支持安装的模型组：

- `vision-detector`
- `vision-segmenter`
- `change-detector`
- `thermal-analyzer`

`labels.txt` 每行一个类别，顺序必须与模型训练和导出时的类别编号完全一致。安装通用公开权重只能验证运行时，不能识别项目定义的铁路缺陷类别。

## 6. 输入契约

### 6.1 图像与红外

支持对象存储地址、HTTP 地址和本地文件地址。模型测试上传的文件通过 MinIO 的 `s3://bucket/object` 地址读取。单个资源默认不得超过 64 MB。

### 6.2 变化检测

当前期影像使用资源的 `storage_url`，基准期影像通过元数据提供：

```json
{
  "baseline_storage_url": "s3://rail-model-tests/baseline/image.jpg"
}
```

两期影像都存在时优先运行 BIT-R18 ONNX；模型未安装时运行 OpenCV 配准和差分流程。

### 6.3 点云分析

支持 PLY、PCD、XYZ、XYZN、XYZRGB 和 PTS。LAS/LAZ 应在预处理阶段转换为 PLY 或 PCD。双时相形变分析同样通过 `baseline_storage_url` 指定基准点云。

只有当前期点云时执行滤波、范围和质量统计；提供基准点云时增加 Point-to-Plane ICP、距离差分、变化点比例和体积近似量计算。

## 7. 状态判定

| `execution_mode` | 含义 |
| --- | --- |
| `onnxruntime-cpu` | 已安装 ONNX 模型并完成真实推理 |
| `open3d-cpu` | 已执行真实点云几何处理 |
| `opencv-cpu` | 已执行真实双时相图像差分基线 |
| `baseline` | 未执行真实模型，结果只用于流程联调 |

模型管理页面中的 `CPU 本地基线` 参数方案使用 FP32、批量 1 和小尺寸输入。系统运维页面显示模型制品、按需加载状态和执行提供程序。

## 8. 验证与停止

运行独立验证：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify_cpu_runtime.ps1
```

停止服务：

```powershell
.\scripts\stop_stack.ps1
```
