使用 Kubeflow Trainer v2 训练、微调和部署 YOLOv5
在 Alauda AI Platform 上微调 YOLOv5 目标检测模型,将训练后的模型打包为 Triton Inference Server 模型,并将其发布为在线推理服务。基础模型、数据集和输出模型存储在兼容 S3 的对象存储中。本指南使用 Kubeflow Trainer v2 资源:TrainingRuntime 和 TrainJob。
该示例使用一个 NVIDIA GPU,在 COCO128 示例数据集上微调 YOLOv5n v7.0。所有准备、训练、导出和发布操作都在 Trainer v2 的 node 步骤中执行,因此不需要共享工作区 PVC。
目录
前提条件准备 S3 模型和数据集对象创建 S3 凭证和推理 ServiceAccount构建训练镜像创建 Trainer v2 运行时提交 YOLOv5 微调作业注册 Triton runtime部署并调用推理服务在 Ascend NPU 上部署构建原生 CANN 编译器镜像使用 CANNpyACL 部署已编译的 .om 模型编译并发布离线模型构建 CANN pyACL serving 镜像注册 CANN pyACL runtime 并部署服务已验证的 Ascend 环境(2026-08-11)使用 torch_npu 部署 TorchScript 模型前提条件构建 Ascend serving 镜像注册 Ascend serving runtime创建 Ascend 推理服务前提条件
示例资源使用 Alauda AI Platform 的 NVIDIA 虚拟 GPU 资源键(nvidia.com/gpualloc、nvidia.com/gpucores 和 nvidia.com/gpumem)。如果您的集群分配的是完整 GPU,请在 TrainJob 中将这三个键全部替换为 nvidia.com/gpu: 1。
准备 S3 模型和数据集对象
在兼容 S3 的对象存储中创建以下前缀。训练 Pod 会下载前两个前缀,并将可部署的 Triton 仓库上传到输出前缀。每次训练运行都必须使用新的输出前缀;不要让两个作业写入同一个前缀。
下载 yolov5_s3_transfer.py,安装其依赖项,并设置与训练 Secret 相同的标准 S3 环境变量(AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_S3_ENDPOINT 和 AWS_DEFAULT_REGION)。然后使用随附的 boto3 辅助程序上传源代码树、权重和数据集:
data/coco128.yaml 期望数据集位于相对于 YOLOv5 源代码树的 ../datasets/coco128 路径下。提供的运行时会将数据集下载到该确切路径。对于自定义数据集,请在基础模型前缀中使用一个数据 YAML 文件,其 path 与运行时使用的目录相匹配;或者同时更新运行时和 DATASET_YAML。
基础模型前缀包含训练 Pod 会执行的 Python 代码。请仅从经过审核且固定版本的 YOLOv5 源代码树填充该前缀,并限制对该前缀的写入权限。不要允许不受信任的上传者替换源代码树或预训练权重。
创建 S3 凭证和推理 ServiceAccount
下载 s3-model-storage.yaml。设置命名空间、端点、协议、地域、访问密钥和 Secret 密钥,然后应用该配置:
Secret 的 AWS_S3_ENDPOINT 值包含 http:// 或 https://,供随附的 boto3 辅助程序使用。serving.kserve.io/s3-endpoint 注释必须省略协议,因为 KServe 会从 serving.kserve.io/s3-usehttps 读取协议。TrainJob 会直接引用此 Secret,而 InferenceService 则会通过 yolov5-s3 ServiceAccount 间接引用它。
不要提交已填入内容的 Secret 清单。请使用托管 Secret 工作流或被忽略的本地副本,并在发生安全事件后轮换凭证。将凭证权限限制为仅读取基础模型和数据集前缀,以及仅写入唯一的输出模型前缀。生产环境请使用 s3-usehttps: "1";仅在接受传输风险后,才可对私有测试端点使用 HTTP。
构建训练镜像
基于以下 Containerfile 构建并推送镜像。将下载的 yolov5_s3_transfer.py 保存在 Containerfile 旁边。生产构建前,请将 NVIDIA 基础镜像镜像到经批准的内部镜像仓库,并通过摘要固定版本。必需的 BASE_IMAGE 参数会明确指定此选择。该镜像包含 boto3、YOLOv5 v7.0 的依赖项,以及 YOLOv5 绘制结果图所需的字体文件。生产环境中,请通过经批准的软件包源审核或镜像下载的 Python 依赖项。
例如:
创建 Trainer v2 运行时
下载 yolov5-triton-trainingruntime.yaml,然后在应用前进行以下修改:
- 将
<your-namespace>替换为目标项目命名空间。 - 将
<your-registry>/yolov5-trainer:v7.0替换为已推送的镜像。生产环境中,请使用不可变摘要,而不是可变标签。
应用运行时:
该运行时可重复使用。它会验证必需的输入变量,从 S3 下载模型和数据,运行 train.py,将 best.pt 导出为 TorchScript,并将以下工件布局上传到输出 S3 前缀:
这是 Triton 所需的布局。config.pbtxt 是为示例中的 640 × 640 COCO 模型配置的。如果更改输入图像尺寸或模型输出签名,请在训练前更新运行时中的配置。发布自定义模型前,请使用导出的模型确认输入和输出名称及形状。
设置 OUTPUT_ONNX_URI 后,运行时还会将 model.onnx 写入该独立前缀。它是下文所述原生 CANN 部署路径的输入工件。仅运行 Triton 训练时,请省略该变量。
提交 YOLOv5 微调作业
下载 yolov5-triton-trainjob.yaml。编辑命名空间、三个必需的 S3 URI 以及 TRITON_MODEL_NAME。仅在采用原生 CANN 路径时,才将 OUTPUT_ONNX_URI 设置为第四个 S3 URI。每个输出 URI 都必须是新的前缀。OUTPUT_MODEL_URI 必须与 Triton 推理服务的 storageUri 匹配。然后设置适合你的集群的资源限制和训练参数:
创建并监视作业:
当 TrainJob 成功后,OUTPUT_MODEL_URI 中会包含可部署的 Triton 工件。其日志会报告 S3 下载、训练、TorchScript 导出或 S3 上传过程中出现的故障。
提供的清单有意设计为单节点方案。仅增加 trainer.numNodes 并不会使 YOLOv5 实现分布式训练:运行时命令还必须启动分布式训练进程(例如使用 torchrun),并且每个节点都必须能够访问数据路径。
注册 Triton runtime
如果命名空间尚未提供兼容的 Triton runtime,请下载 triton-servingruntime.yaml。将其命名空间和镜像替换为部署命名空间以及经过批准并按摘要固定的内部镜像,然后应用:
此示例适用于 Triton 25.02、CUDA 12.1 和 triton 模型格式。请更改镜像和加速器标签,使其与集群中可用的镜像和硬件相匹配。部署前,请确保 serving 节点能够拉取所选镜像;使用内部镜像可避免依赖公共 registry 来获取 runtime。有关自定义 serving runtime 的详细说明,请参阅扩展推理 runtime。
部署并调用推理服务
下载 yolov5-triton-inferenceservice.yaml。设置其命名空间和 storageUri,并确保以下所有值都与已完成的训练运行相匹配:
spec.predictor.model.storageUri是OUTPUT_MODEL_URI。metadata.annotations.aml-model-repo是TRITON_MODEL_NAME。- 作业生成的 Triton
config.pbtxt使用相同的TRITON_MODEL_NAME。
然后应用配置并等待服务就绪:
KServe 会在启动 Triton 前从 S3 下载模型,并使用附加到 yolov5-s3 ServiceAccount 的凭证。有关平台 S3 storage-initializer 的行为,请参阅模型存储。
Triton 提供 HTTP v2 API。在集群中的 workbench 或其他 pod 中,使用以下简易客户端发送经过归一化处理的 640 × 640 RGB 图像:
原始输出包含候选框和类别分数。YOLOv5 后处理(包括置信度过滤、非极大值抑制、将边界框缩放回原始图像以及绘制标签)由客户端应用程序执行,不属于本部署流程的内容。
在 Ascend NPU 上部署
上面的 Triton runtime 面向 NVIDIA CUDA,无法为 Ascend NPU 提供服务。本指南提供两条可运行的 NPU 路径:使用 torch_npu 加载导出的 TorchScript 模型的自定义 KServe runtime,以及使用 CANN pyACL 加载经 ATC 编译的 .om 模型的原生 CANN 路径。请根据目标 Ascend 硬件调整镜像、CANN 版本和资源键。
对于原生 CANN 生产实现,请将 Ascend 的 CANN YOLO 模型推理示例作为架构参考。已发布的示例使用 YOLOv7,但其部署流程适用于兼容的 YOLOv5 导出模型:将模型导出为 ONNX,使用 CANN ATC 将其编译为 .om 离线模型,然后通过 CANN pyACL 执行该模型。配套的 CANN 后处理示例演示了 CANN 检测后处理图。
CANN 示例是参考资料,并非此服务的配置清单。特别是,其示例 ATC 命令面向 Ascend 310,因此不要在 910B 部署中照搬其中的 soc_version。请在与目标驱动程序和 910B SKU 兼容的 CANN 环境中构建并验证 .om 文件,并将其存储在单独的不可变 S3 前缀中。CANN 是 toolkit;其当前的 C 和 Python 推理 API 库分别为 acl 和 pyACL。下面可运行的 CANN pyACL 示例实现了与 TorchScript 示例相同的 KServe v2 API。如果转换兼容性或更短的实现路径比原生 CANN 优化更重要,请保留 TorchScript 工件并采用 torch_npu 方法。
构建原生 CANN 编译器镜像
对于 ATC 和 pyACL 路径,请以官方 CANN 910B 开发镜像为基础,而不要使用下文 TorchScript 路径中的 torch_npu serving 镜像。本指南验证过的镜像是 quay.io/ascend/cann:9.0.1-910b-openeuler24.03-py3.11-devel,固定到 sha256:0ff08aa7cbfef37690d2e092aa0dd8fe52add7e50a629f8a0920d3faa0997e06。使用前,请将该摘要对应的镜像推送到构建节点和 serving 节点均可访问的已批准 registry;不要依赖生产 pod 访问公共 registry。
开发镜像包含 atc 和 CANN pyACL Python 绑定,但其内嵌的 CANN Python 环境并未包含 ATC 所需的全部依赖项。请使用以下经过测试的依赖集合构建派生编译器镜像。将软件包安装到 CANN 自己的 site-packages 目录中:如果只将软件包安装到镜像的常规 Python site-packages 目录,内嵌编译器将无法发现它们。
使用经过批准的构建工具构建并推送该派生镜像,例如:
构建前,将 yolov5_s3_transfer.py 保存到此编译器 Containerfile 旁边。针对目标 linux/arm64 平台进行构建,以确保 NumPy、SciPy 和 psutil wheel 与 NPU 节点架构相匹配。编译器镜像仅在构建期间需要访问软件包。在受限网络中,请将匹配的 CPython 3.11 arm64 wheel 放入构建上下文,并使用 --no-index --find-links=<wheelhouse> 安装;不要仅仅为了在启动时安装依赖项,就授予 serving 工作负载广泛的出站访问权限。调用 atc 或导入 acl 之前,先加载 /usr/local/Ascend/ascend-toolkit/set_env.sh。
使用 CANN pyACL 部署已编译的 .om 模型
此路径用于提供针对单个 Ascend SKU 编译的静态批量 FP32 YOLOv5 模型。它使用单独的 S3 前缀,其中必须严格包含以下布局:
请勿将 TorchScript Triton repository、ONNX 源文件或针对其他 soc_version 编译的模型放入此前缀。.om 文件是可执行的 CANN 离线模型,而不是可移植的交换格式。每当目标 Ascend SKU 或不兼容的 CANN/驱动程序栈发生变化时,都应重新编译,并使用新的不可变前缀。
编译并发布离线模型
从上面构建的编译器镜像启动容器。从 OUTPUT_ONNX_URI 下载 model.onnx,然后针对目标 SKU 进行编译。此命令适用于提供的 KServe server 所使用的固定 images:1,3,640,640 FP32 输入;如果模型签名发生变化,必须同时修改 server:
atc 会写入 /work/model.om。boto3 helper 使用与训练工作流相同的 endpoint 和最小权限凭证。输出前缀必须是新的,且只能包含 1/model.om。不要将示例中的 Ascend910B3 值用于其他 SKU。
构建 CANN pyACL serving 镜像
将 yolov5-ascendcl-om.Containerfile 和 yolov5_ascendcl_om_server.py 下载到同一目录中。使用上面的派生 CANN 编译器镜像或等效的 CANN runtime 镜像构建镜像;该镜像必须提供 pyACL Python 绑定,且与目标驱动程序兼容:
server 会初始化一次 CANN pyACL,加载 /mnt/models/1/model.om,验证固定输入形状,并将调用序列化到其 acl context 中。它会公开 KServe v2 健康检查和推理 endpoint,并返回原始 output0 tensor。与 TorchScript 路径一样,YOLO 置信度过滤和非极大值抑制仍由客户端负责。
注册 CANN pyACL runtime 并部署服务
下载 yolov5-ascendcl-om-servingruntime.yaml,将其命名空间设为 InferenceService 命名空间,将镜像替换为你推送的镜像,然后应用:
然后下载 yolov5-ascendcl-om-inferenceservice.yaml。将命名空间和 storageUri 设置为包含 1/model.om 的不可变 S3 前缀,并确保 aml-model-repo 与 KServe v2 模型名称一致:
提供的 InferenceService 使用标准 Huawei device-plugin 资源键 huawei.com/Ascend910: "1" 请求一个完整设备。如果集群使用 HAMI vNPU 切片,请将该限制替换为集群 Ascend 调度配置所需的资源键和内存值。请使用在创建 S3 凭证和推理 ServiceAccount中创建的同一个 S3 ServiceAccount,以便 KServe 下载离线模型。
已验证的 Ascend 环境(2026-08-11)
这是当前开发集群的验证证据,并非通用支持矩阵。使用其他环境前,请验证其驱动程序、runtime 和资源键兼容性是否等效。
训练作业已将 1/model.pt 上传到 OUTPUT_MODEL_URI 下。NPU runtime 直接使用该文件;它不使用 Triton 的 config.pbtxt。
使用 torch_npu 部署 TorchScript 模型
本节余下内容介绍可运行的 TorchScript 路径。此路径保留训练作业创建的模型工件,无需进行 ONNX 或 .om 转换。
前提条件
- 目标节点已安装 Ascend 驱动程序、Kubernetes device plugin 和平台的 Ascend serving 配置。
- 部署命名空间中存在创建 S3 凭证和推理 ServiceAccount中创建的
yolov5-s3ServiceAccount 和 S3 凭证。 - CANN 镜像可以访问主机 CANN 库。其 entrypoint 必须在导入
torch_npu之前加载/usr/local/Ascend/ascend-toolkit/set_env.sh。 - 导出的 TorchScript 模型与 serving 镜像中的 PyTorch/CANN 版本兼容。如果加载失败,请使用匹配的技术栈重新导出模型。
构建 Ascend serving 镜像
将 yolov5-ascend.Containerfile 和 yolov5_ascend_server.py 下载到同一目录中。该镜像扩展了 CANN PyTorch runtime,并为 images 和 output0 提供 KServe v2 健康检查和推理 endpoint。构建时,请提供经过批准并按摘要固定的内部 CANN 基础镜像。
注册 Ascend serving runtime
下载 yolov5-ascend-servingruntime.yaml,将其命名空间设为 InferenceService 命名空间,将镜像替换为你构建的镜像,然后应用:
创建 Ascend 推理服务
下载 yolov5-ascend-inferenceservice.yaml。将命名空间和 storageUri 设置为 TrainJob 写入的 OUTPUT_MODEL_URI。确保 aml-model-repo 与 TRITON_MODEL_NAME 一致,因为自定义 runtime 会将该值用作其 KServe v2 模型名称。
示例会请求一个 HAMI vNPU 切片:
对于标准 Huawei device plugin,请将这两个键替换为 huawei.com/Ascend910: "1"。遵循集群的 Ascend 调度约定,包括所需的 RuntimeClass 或 HAMI scheduler 配置。有关资源键的详细信息,请参阅训练 Runtime 镜像。
应用配置并等待服务就绪:
Ascend 服务使用与 Triton 示例相同的 KServe v2 请求正文;只有服务 URL 不同。在接入生产流量前,请使用示例图像验证服务,因为 operator 覆盖范围和 TorchScript 兼容性取决于所选的 CANN/PyTorch 技术栈。
有关通用模型服务工作流和故障排除,请参阅管理推理服务。