卷五：模型移植

阅读时长：30-45 分钟目标：学会将第三方模型转换、上传并接入系统，完成一次“模型移植 + 场景任务接入 + 效果验证”的完整闭环前提：已完成 CosmoEdge 场景任务编排，理解基本的场景任务编排 需要额外环境：一台安装了 Docker 的电脑，用于模型转换

CosmoEdge 场景任务编排 解决的是“怎么组织已有能力”。本卷解决的是“怎么把新的能力带进来”。也就是说：

**CosmoEdge 场景任务编排 **教您编排
CosmoEdge 第三方模型移植 教您引入第三方模型

学完本卷后，您将具备以下能力：

将 ONNX 模型转换为设备可运行的 bmodel
将模型上传到 CosmoEdge
配置模型元数据并验证模型是否可用
将第三方模型接入新的场景任务

本卷学习路径

plain

准备模型
  ↓
Docker 中完成转换
  ↓
上传到系统并补全元数据
  ↓
图片验证
  ↓
接入 场景任务 并做端到端测试

第一章：准备第三方模型

本卷使用一个公开可获取的 VisDrone 检测模型 作为示例。

模型仓库链接

VisDrone-YOLOv8-Models-Upgrade

选择它有三个原因：

公开、可复用，适合教程示例
是标准目标检测任务，容易验证
类别和系统内置场景不同，能证明平台不只支持内置模型

1.1 支持的输入格式

格式	说明
ONNX	推荐，兼容性最好
PyTorch `.pt`	需先自行导出为 ONNX
TensorFlow `.pb`	需先自行导出为 ONNX

建议
首次移植优先选 ONNX。这样能把问题集中在“模型转换和接入”本身，而不是框架导出差异。

1.2 本卷示例文件

请准备一个 ONNX 模型文件，例如：

plain

visdrone_yolov8s.onnx

并放在本地目录中，例如：

plain

/home/user/models/

注意
如果后续您替换成自己的模型，下面命令里的文件名、输入尺寸、输出名都要跟着一起改。

第二章：Docker 环境准备

模型转换需要使用算能官方提供的 Docker 镜像。

2.1 安装 Docker

操作系统	安装方式
Ubuntu / Debian	`sudo apt-get install docker.io`
CentOS	`sudo yum install docker`
Windows	安装Docker Desktop

安装后验证：

bash

docker --version
## 预期输出：Docker version 2x.x.x

将用户USER添加到docker用户组

plain

sudo gpasswd -a USER docker

替换 USER 为自己的普通用户

更新用户组

plain

newgrp docker

2.2 拉取镜像

下载镜像压缩包

plain

wget https://sophon-file.sophon.cn/sophon-prod-s3/drive/24/06/14/12/sophgo-tpuc_dev-v3.2_191a433358ad.tar.gz

导入镜像站点

plain

docker load -i sophgo-tpuc_dev-v3.2_191a433358ad.tar.gz

2.3 常用 Docker 命令速查

命令	作用
`docker images`	查看本地镜像
`docker run -it -v /本地路径:/容器路径 sophgo/tpuc_dev:latest bash`	启动容器并挂载目录
`exit`	退出容器

第三章：模型转换

将 ONNX 模型转换为设备可运行的 bmodel，核心只需要两步：

model_transform
model_deploy

3.1 启动容器

bash

docker run -it -v /home/user/models:/workspace sophgo/tpuc_dev:v3.2 bash

这条命令的作用是：

启动官方转换环境
把本地模型目录挂载到容器内的 /workspace

3.2 安装转换依赖包

bash

pip install tpu_mlir -i https://mirrors.ustc.edu.cn/pypi/simple/

3.3 步骤一：转换为 MLIR

bash

model_transform \
  --model_name visdrone_yolov8s \
  --model_def /workspace/visdrone_yolov8s.onnx \
  --input_shapes [[1,3,640,640]] \
  --pixel_format rgb \
  --output_names output0 \
  --mlir visdrone.mlir

3.4 步骤二：转换为 bmodel

bash

model_deploy \
  --mlir visdrone.mlir \
  --quantize F16 \
  --chip bm1688 \
  --model visdrone_yolov8s_f16.bmodel

转换完成后，/workspace 目录下会生成：

plain

visdrone_yolov8s_f16.bmodel

3.4 这一步最常见的三个注意点

--input_shapes 必须和模型训练/导出时一致
--pixel_format 要和模型训练时预处理一致
--output_names 要和模型导出的实际输出名一致

第四章：上传模型到系统

4.1 进入模型仓库

进入 模型仓库

点击 上传模型

填写模型信息:

字段	示例值	说明
主类型	检测算法
子类型	yolov8_det	上传的模型yolo版本
模型名称	VisDrone 无人机检测	便于识别
上传文件	`visdrone_yolov8s_f16.bmodel`	转换得到的模型文件
归一化	0-1
颜色通道	RGB
类别标签	pedestrian, people, bicycle, car, van, truck, tricycle, awning-tricycle, bus, motor	用于类别显示和映射

点击确定保存该模型

4.2 上传完成后的检查点

上传完成后，确认：

模型出现在模型仓库列表中
状态正常
名称、类型、输入尺寸、标签无明显错误

修改配置尺寸、置信度阈值等基础参数

修改配置类别信息

模型的基础信息一定要准确无误，否则出问题排查难度大

第五章：图片验证模型可用性

在把模型接入场景任务之前，先做一次轻量验证。

5.1 准备测试图片

准备几张与模型场景接近的图片，例如无人机航拍图。

5.2 创建图片验证任务

进入 **场景任务， **新建无人机图片检测任务

创建 **无人机图片检测 **算法编排链路

点击 算法编排 进入编排页面

添加 **目标检测算法 **

配置 业务逻辑参数

选择原子模型：VisDrone 无人机检测

选择标签：全选

点击 **保存 **将该编排流程保存

5.3 图片分析

选择算法 无人机图片检测

上传图片

点击** 开始分析 **启动测试

5.3 结果分析

结果分析：

图片中的行人、车辆等目标能被检测出来
检测框位置基本合理
类别名称显示正常，不是数字或空白

如果图片验证都不通过，不要急着进入场景任务编排。先回头检查：
模型文件是否上传正确
输入尺寸是否一致
类别标签是否配置完整

第六章：把第三方模型接入场景任务

现在开始把这个模型真正接入业务流程。

场景说明

创建一条新的 无人机目标检测场景任务：

检测画面中的行人和车辆
生成事件
在实时画面上看到框和类别

6.1 创建新算法

进入 **场景任务，新增任务 **

填写基础信息:

任务名称：无人机目标检测
数据源类型：视频分析
任务类型：检测/分析

6.2 搭建最小可用编排链路

按下面顺序添加节点：

plain

视频解码 → 目标检测（第三方模型） → 目标追踪 → 区域告警判断 →  事件上报

点击 算法编排进入编排页面

添加编排逻辑

第一步：添加 视频解码

第二步：添加** 目标检测算法**

第三步：添加目标追踪

第四步：添加区域告警判断

1782289066572

第五步：添加事件上报

配置参数

1782288851103

点击保存保存编排链路

第七章：端到端验证

7.1 创建视频接入

准备一段无人机视角测试视频
进入 **视频接入 **添加视频通道

参数填写：

接入类型：离线视频

通道名称：无人机摄像头

上传视频：无人机.mp4

配置** 服务分配**

点击** 服务分配 **进入配置页面

任务场景选择 无人机目标检测

新增检测区域

配置 运行策略 播放次数为0

点击 **保存 **保存视频接入配置

7.2 观察实时展示

进入 实时展示，视频源选择无人机摄像头

算法叠加设置：无人机目标检测

1782289405892

告警弹窗

1782289340041

检查：

画面中是否有检测框
类别是否显示正确
不同目标是否能持续跟踪

7.3 检查告警记录

进入 事件中心 -> 检测/分析 查看告警事件记录

结果分析：告警事件正常记录，说明该编排链路正常运行

7.4 成功标准

如果以下三项同时成立，就说明这次第三方模型移植已经跑通：

图片测试能正常出结果
场景任务能启动
实时展示和告警记录都能看到效果

附录

A. 常见问题排障

问题	可能原因	解决方法
模型上传后检测无结果	输入尺寸配置错误	检查模型元数据与转换参数是否一致
类别显示成数字	未配置类别标签	在模型仓库补全标签映射
场景任务能启动但无框	缺少 OSD 叠加节点	在末端添加 OSD 叠加
图片测试正常但视频效果差	测试视频分布和训练场景差异大	先用更接近模型场景的视频验证
服务启动失败	节点未正确连线或模型类型不匹配	检查编排结构和模型类型

下一步

学完前五卷后，您已经具备一条完整能力链：

plain

设备上手
  ↓
配置内置场景
  ↓
定义大模型规则
  ↓
编排业务流程
  ↓
移植第三方模型

这意味着您已经可以：

用内置能力快速搭场景
用 VLM / DINO 补足长尾需求
用编排把能力组织成业务流程
把自己的模型真正接入系统

卷五：模型移植 ​

本卷学习路径 ​

第一章：准备第三方模型 ​

1.1 支持的输入格式 ​

1.2 本卷示例文件 ​

第二章：Docker 环境准备 ​

2.1 安装 Docker ​

2.2 拉取镜像 ​

2.3 常用 Docker 命令速查 ​

第三章：模型转换 ​

3.1 启动容器 ​

3.2 安装转换依赖包 ​

3.3 步骤一：转换为 MLIR ​

3.4 步骤二：转换为 bmodel ​

3.4 这一步最常见的三个注意点 ​

第四章：上传模型到系统 ​

4.1 进入模型仓库 ​

4.2 上传完成后的检查点 ​

第五章：图片验证模型可用性 ​

5.1 准备测试图片 ​

5.2 创建图片验证任务 ​

5.3 图片分析 ​

5.3 结果分析 ​

第六章：把第三方模型接入场景任务 ​

场景说明 ​

6.1 创建新算法 ​

6.2 搭建最小可用编排链路 ​

第七章：端到端验证 ​

7.1 创建视频接入 ​

7.2 观察实时展示 ​

7.3 检查告警记录 ​

7.4 成功标准 ​

附录 ​

A. 常见问题排障 ​

下一步 ​

卷五：模型移植

本卷学习路径

第一章：准备第三方模型

1.1 支持的输入格式

1.2 本卷示例文件

第二章：Docker 环境准备

2.1 安装 Docker

2.2 拉取镜像

2.3 常用 Docker 命令速查

第三章：模型转换

3.1 启动容器

3.2 安装转换依赖包

3.3 步骤一：转换为 MLIR

3.4 步骤二：转换为 bmodel

3.4 这一步最常见的三个注意点

第四章：上传模型到系统

4.1 进入模型仓库

4.2 上传完成后的检查点

第五章：图片验证模型可用性

5.1 准备测试图片

5.2 创建图片验证任务

5.3 图片分析

5.3 结果分析

第六章：把第三方模型接入场景任务

场景说明

6.1 创建新算法

6.2 搭建最小可用编排链路

第七章：端到端验证

7.1 创建视频接入

7.2 观察实时展示

7.3 检查告警记录

7.4 成功标准

附录

A. 常见问题排障

下一步