模型导出

这个功能解决什么问题

训练得到的 .pt 文件是 PyTorch 原生格式，只能在装了 PyTorch 和 Ultralytics 的环境里跑。要把模型部署到生产推理服务、边缘设备、专用加速芯片上，需要先把它转成对应的推理格式。

模型导出就是干这件事。每次导出生成一个 ModelArtifact，挂在原版本下面，原始 .pt 不变。检测页、主动学习、批量标注这些消费方按需选择不同 Artifact，互不影响。

支持的导出格式

字段	类型	必填	默认值	说明
ONNX	格式	可选	通用	开放神经网络交换格式，跨框架通用。CPU / GPU / 部分加速器都能跑，是默认推荐格式。
TensorRT	格式	可选	NVIDIA 专用	NVIDIA 针对自家 GPU 优化的推理引擎，延迟最低、吞吐最高。仅限 NVIDIA GPU 环境。
NPU	格式	可选	昇腾专用	华为昇腾 NPU 推理格式，适配 Ascend 系列芯片。仅在配置了 CANN 工具链的环境可用。

关键导出行为

detect 模型默认导出 raw 布局（nms=False）

检测（detect）任务导出 ONNX 时，默认关闭模型内置的 NMS（非极大值抑制），输出形状是 (1, 4+类别数, 锚点数) 的 raw 张量。这样保留每个候选框的原始置信度，便于主动学习做 margin 采样（按 top-1 与 top-2 置信度之差挑边界样本）。

如果只是想做常规推理，平台后端在推理时会对 raw 输出做 class-aware NMS，结果跟带 NMS 的版本一致，不用额外配置。

segment 模型也支持 ONNX 导出

实例分割模型同样可以导出 ONNX，导出后的 Artifact 可以用于检测页测试和主动学习评分。Pose 和 OBB 任务目前不自动导出 ONNX，仍走 .pt 推理路径。

旧制品不会自动迁移

新导出规则只对本次导出生效。之前已经导出过、metadata 里 nms=True 或缺失的旧 ONNX 制品，仍按旧的 end-to-end 路径推理，margin 采样不可用。如果需要 margin 采样，请重新导出一次。

导出入口

图1：模型详情页的「制品导出」子 Tab

1. 进入模型详情页

   在模型管理列表里点开目标模型，进入版本中心化布局。

2. 选择目标版本

   用头部的版本下拉选择器，切到要导出的那个 Version。

3. 切到「制品导出」子 Tab

   子 Tab 标签在页面中部，切过去后会看到该版本下已有的 Artifact 列表（通常至少有一个 .pt）。

4. 发起导出

   点页面右上角的「导出」按钮，选目标格式（ONNX / TensorRT / NPU）。导出在后台跑，完成后列表里多出一条新 Artifact，状态显示为 ready 就能用。

5. 在消费方选用

   导出后的 Artifact 会自动进入模型选择器的候选列表。在检测页、主动学习评分、批量标注 AI 流程里，按项目和任务类型筛选就能看到。

上传外部 .pt 文件

除了从训练任务导出，还可以直接上传外部训练好的 .pt 权重：

上传 = 立即发布

在模型管理列表点「上传模型」，选择 .pt 文件并填写架构信息。上传完成后系统直接创建一个 Model + 一个 ready 状态的 Version + 一个 .pt Artifact，没有 draft 阶段，立即可用于检测和推理。

架构信息会从当前项目的 project_type 继承，不需要手动选算法类型。

上传前确认架构匹配

上传的 .pt 文件必须与项目任务类型一致（检测项目上传检测权重、分割项目上传分割权重）。架构不匹配会导致推理时形状错误，平台不会在上传阶段做权重内容校验。

导出后的 Artifact 用途

导出完成后，新 Artifact 会自动出现在以下消费方：

• 检测页：模型选择器里按 is_default=True 过滤，发布版本的 Artifact 默认可选。
• 主动学习评分：detect 和 segment 任务的 ONNX 兄弟制品会被优先用于 margin 采样，找不到 ONNX 时回退 .pt。
• 批量标注 AI 流程：标注步骤只接受 .pt Artifact，ONNX 会在该路径被拒绝。如果只有 ONNX 制品，需要同时保留 .pt 用于标注。
• 交互式检测页 draft 测试：允许测试 source="draft_test" 和 source="active_learning" 来源的 Artifact，但自动化消费方（DetectionTask、BatchAnnotationJob）会拒绝这两种来源。

is_default 的作用域

ModelArtifact.is_default 是版本内字段，作用域为单个 model_version_id。一个 Version 下可以有多个 default Artifact（比如 .pt 和 ONNX 都是 default），不同 Version 各自维护自己的 default 列表，互不影响。

字段说明

字段	类型	必填	默认值	说明
format	枚举	必填	—	制品格式：pt / onnx / tensorrt / npu。决定推理路由和后端选择。
nms	布尔	可选	detect 默认 False	仅 detect ONNX 制品有意义。True = end-to-end 带 NMS，False = raw 布局支持 margin 采样。
source	枚举	必填	—	制品来源：training（训练自动导出）/ upload（手动上传）/ draft_test（draft 测试）/ active_learning（AL 内部）。
status	枚举	必填	—	制品状态：ready / archived。归档后不进入选择器。
is_default	布尔	可选	False	版本内是否为默认制品。检测页选择器只返回 is_default=True 的制品。

常见问题

导出失败怎么办

常见原因：版本状态不是 ready（比如还在训练中或已归档）、当前环境缺少目标格式的工具链（TensorRT 需要 CUDA 环境、NPU 需要 CANN）。失败信息会写在 Artifact 的状态详情里，可以先排查环境依赖再重试。

导出后能改格式吗

不能。每个 Artifact 的格式在创建时固定。如果需要另一种格式，重新发起一次导出，会在同一 Version 下新增一条 Artifact，旧的保留。

归档 Version 后 Artifact 还能用吗

归档 Version 只把状态置为 archived，文件不删，但 Artifact 不会出现在选择器里。运行中的检测任务如果还引用着这个 Artifact，会继续工作到任务结束，新建任务时就不能再选了。

什么时候需要 TensorRT 或 NPU

追求最低延迟的 NVIDIA GPU 推理选 TensorRT，部署到昇腾芯片选 NPU。其他场景用 ONNX 就够了，跨平台兼容性最好，性能也接近原生。如果不确定，先导出 ONNX 跑通流程，再按需补 TensorRT 或 NPU。