一、前言
在端侧 AI 部署场景中，土星云 SE110S 系列（SE110S-WA32/WB16/WC08）凭借BM1684X 、BM688 、CV186AH 的高算力、低功耗优势，成为工业视觉、边缘计算等场景的优选硬件。但 PyTorch 训练的模型（.pt）无法直接在 TPU 上运行，必须通过PyTorch→ONNX→BModel的标准流程转换为算能专用的 BModel 格式。
本文基于项目sophon-models，手把手带你完成环境搭建、容器化部署、模型转换（Qwen3VL-2B 大模型 + Yolov8s 检测模型双示例）、常见报错解决全流程，帮你快速落地土星云端侧 AI 应用。
二、核心原理：模型转换链路
模型转换核心是通过TPU-MLIR 编译器将通用模型格式编译为 TPU 硬件可执行指令，完整链路如下： PyTorch(.pt) → ONNX → MLIR（中间表示）→ BModel（土星云SE110S-WA32/WB16/WC08专用）。
- ONNX：作为通用中间格式，解决不同训练框架（PyTorch/TensorFlow）的兼容性问题；
- TPU-MLIR：算能自研编译器，基于 MLIR（Multi-Level Intermediate Representation）技术，负责模型优化、算子映射、量化压缩，最终生成 BModel；
- BModel：算能 TPU 专属格式，包含硬件指令、权重、量化参数，可直接在土星云 SE110S-WA32/WB16/WC08 芯片上高效推理。
三、环境准备（Docker 容器化，一键部署）
3.1 硬件与系统要求
- 硬件：x86 主机（内存≥16GB，磁盘≥100GB）；
- 系统：Ubuntu 20.04（推荐，兼容性最佳）；
- 目标芯片：算能 SE110S-WA32/WB16/WC08（ARM 架构）。
3.2 拉取核心代码仓库
创建工作目录，克隆sophon-models及算能官方依赖库（TPU-MLIR、sophon-demo、LLM-TPU）：
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 创建工作目录 mkdir -p Sophon-Models && cd Sophon-Models # 克隆核心仓库（含转换脚本与示例） git clone https://gitee.com/saturn-cloud/sophon-models.git # 克隆算能官方依赖库（必装，模型转换核心工具） git clone https://github.com/sophgo/tpu-mlir.git # 编译器核心 git clone https://github.com/sophgo/sophon-demo.git # 模型示例与工具 git clone https://github.com/sophgo/LLM-TPU.git # 大模型转换工具 |
3.3 加载 Docker 镜像（3 种方式，优先拉取）
算能提供预编译的tpuc_dev镜像（v3.4），内置 TPU-MLIR、Python 依赖、编译工具链，避免环境冲突：
方式 1：直接拉取（推荐，网络正常时）
|------------------------------------------------------------------------------------------------------------|
| # 官方镜像 docker pull sophgo/tpuc_dev:v3.4 # 备用镜像（国内加速） docker pull uhub.service.ucloud.cn/ucas/tpuc_dev:v3.4 |
方式 2：离线加载（拉取失败时）
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 下载镜像压缩包（约10GB，耐心等待） wget https://sophon-assets.sophon.cn/sophon-prod-s3/drive/25/04/15/16/tpuc_dev_v3.4.tar.gz # 加载镜像到本地 Dockerdocker load -i tpuc_dev_v3.4.tar.gz |
3.4 启动容器并编译环境
1. 启动容器（执行脚本，自动映射目录）
|-----------------------------------------------------------------|
| # 进入sophon-models目录，执行启动脚本 cd sophon-modelssh 0_start_docker.sh |
脚本说明：自动将宿主机Sophon-Models目录映射到容器/workspace，容器内直接访问宿主机代码与模型文件。
2. 编译 TPU-MLIR（关键步骤，这一步比较耗时，请耐心等待）
进入容器后，执行编译脚本（必须用./ 执行，不可用 sh）：
|----------------------------|
| # 进入容器后，执行编译 ./1_bianyi.sh |
3. 激活环境变量（每次进入容器需执行）
|--------------------------------------------------------------|
| # 进入tpu-mlir目录，激活环境 cd /workspace/tpu-mlirsource envsetup.sh |
四、实战示例 1：Qwen3VL-2B 大模型转换（多模态）
4.1 模型下载（ModelScope）
在容器内执行，下载 Qwen3VL-2B-Instruct 模型（约 4GB）：
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 安装modelscope（若未安装） pip install modelscope -i https://mirrors.aliyun.com/pypi/simple/ # 下载模型到默认缓存目录 modelscope download --model Qwen/Qwen3-VL-2B-Instruct # 移动模型到工作目录（方便后续调用） mkdir -p /workspace/models/LLMcd /workspace/models/LLMmv /root/.cache/modelscope/hub/models/Qwen/Qwen3-VL-2B-Instruct ./ |
4.2 模型转换（W4BF16 量化，bm1684x）
执行llm_convert.py（LLM-TPU 提供的大模型转换工具）：
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| llm_convert.py \ -m /workspace/models/LLM/Qwen3-VL-2B-Instruct/ \ # 模型路径 -s 2048 \ # 序列长度 --max_input_length 1024 \ # 最大输入长度 --quantize w4bf16 \ # 4位权重量化+BF16激活 -c bm1684x \ # 目标芯片 --out_dir qwen3vl_2b \ # 输出目录 --max_pixels 768,768 # 图像最大分辨率 |
4.3 常见报错解决（KeyError: 'qwen3_vl'）
报错信息：
|--------------------------------|
| plaintext KeyError: 'qwen3_vl' |
原因：
transformers版本过低，不支持 Qwen3VL 模型配置。
解决：
升级transformers与torchvision，重新执行转换命令：
|-------------------------------------------------------------------------------------|
| pip3 install transformers torchvision -U -i https://mirrors.aliyun.com/pypi/simple/ |
五、实战示例 2：Yolov8s 检测模型转换（自定义训练）
5.1 第一步：PyTorch→ONNX（宿主机执行）
先将自定义训练的yolov8s.pt导出为 ONNX 格式（PyTorch 环境）：
|----------------------------------------------------------------------------------------------------------------------------------|
| # 安装ultralytics pip install ultralytics # 导出ONNX（输入尺寸640×640，batch=1） yolo export model=yolov8s.pt format=onnx imgsz=640 batch=1 |
导出成功后，得到yolov8s.onnx，上传到容器/workspace目录。
5.2 第二步：ONNX→MLIR（容器内，model_transform.py）
执行model_transform.py，将 ONNX 转为 MLIR 中间表示，配置预处理参数：
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| model_transform.py \ --model_name yolov8s \ # 模型名称 --model_def /workspace/yolov8s.onnx \ # ONNX路径 --input_shapes \[1,3,640,640] \ # 输入shape（N,C,H,W） --mean 0.0,0.0,0.0 \ # 预处理均值 --scale 0.0039216,0.0039216,0.0039216 \ # 预处理归一化（1/255） --pixel_format rgb \ # 图像格式 --mlir /workspace/yolov8s.mlir # 输出MLIR路径 |
5.3 第三步：MLIR→BModel（容器内，model_deploy.py）
执行model_deploy.py，编译 MLIR 为 BModel，支持 FP16 量化（平衡精度与速度）：
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| model_deploy.py \ --mlir /workspace/yolov8s.mlir \ # MLIR路径 --quantize F16 \ # FP16量化 --processor bm1684x \ # 目标芯片 --model /workspace/yolov8s_fp16.bmodel # 输出BModel路径 |
编译成功后，在/workspace目录生成yolov8s_fp16.bmodel，可直接部署到 SE110S 芯片。
六、模型部署与推理验证
6.1 部署到 SE110S 开发板
- 将生成的 BModel 文件（如yolov8s_fp16.bmodel）上传到开发板；
- 安装算能运行时库（libsophon），配置环境变量；
- 调用sophon-runtime接口加载 BModel，执行推理。
6.2 推理测试（Python 示例）
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| import sophon.sail as sail # 初始化推理引擎 engine = sail.Engine("yolov8s_fp16.bmodel", 0, sail.IOMode.SYSIO) # 加载并预处理图像（resize到640×640，归一化） img = cv2.imread("test.jpg") img = cv2.resize(img, (640, 640)) img = img.astype(np.float32) / 255.0 img = np.transpose(img, (2, 0, 1))np.newaxis, ... # 执行推理 output = engine.process(img) # 后处理（NMS、坐标还原）... |
七、总结与最佳实践
7.1 核心流程回顾
1.环境容器化：用tpuc_dev:v3.4镜像隔离依赖，避免编译报错；
2.代码准备：克隆sophon-models+ 算能官方库，激活 TPU-MLIR 环境；
3.模型转换：
- 大模型：用llm_convert.py，支持 W4/W8 量化；
- 检测 / 分类模型：PyTorch→ONNX→MLIR→BModel，用model_transform.py + model_deploy.py；
4.报错解决：优先升级transformers/torch，核对输入尺寸与预处理参数。
7.2 最佳实践
- 量化选择：大模型优先 W4BF16（显存占用减少 75%），检测模型优先 FP16（速度提升 2 倍，精度损失 < 1%）；
- 输入尺寸：与训练时保持一致（如 Yolov8s 用 640×640），避免推理精度下降；
- 镜像管理：离线保存tpuc_dev_v3.4.tar.gz，避免重复下载。
通过本文流程，可快速将自定义 PyTorch 模型部署到土星云 SE110S 系列芯片，适用于工业检测、智能安防、边缘大模型等场景。