企业官网建设流程全解析

1. 从一次"训练到一半就崩"的经历说起

去年帮一个做工业质检的朋友搭模型，数据集是产线上的缺陷图片，大概两万多张，任务本身不复杂——ResNet 做二分类。本地机器只有一张消费级显卡，跑一轮要四十多分钟，调参调到第三轮的时候，训练日志里突然冒出一片nan，loss 直接变成nan，模型权重全废。那会儿我第一反应是学习率太大，调小之后还是nan；又怀疑数据里有脏样本，清洗了一遍，照样nan。折腾到凌晨两点，才意识到问题出在混合精度训练时梯度溢出，而本地环境没有做梯度裁剪和 loss scaling 的兜底。

这件事让我彻底想明白一个道理：模型训练这件事，真正难的不是写那几十行网络定义，而是把训练过程跑稳、跑完、跑出可复现的结果，然后再把它变成一个别人能调用的服务。本地环境能帮你验证想法，但一旦数据量上去、模型变大、需要多人协作，本地那套"手动挡"就撑不住了。

华为云 ModelArts 就是在这个背景下进入我视野的。它本质上是一个覆盖"数据标注—训练—调优—部署—推理"全链路的云端 AI 开发平台，把算力调度、环境依赖、分布式训练、模型托管这些脏活累活都包了。你只需要关心你的数据和你的网络结构，剩下的交给平台。这篇笔记就是把我从零跑通"训练+部署"这条链路的过程完整记下来，包括每一步为什么这么做、哪些参数不能乱填、哪些坑我替你踩过了。

适合谁看？如果你手上有数据、有模型想法，但被本地算力卡住；或者你已经会写 PyTorch 代码，但不知道怎么把它变成一个能对外提供服务的 API；再或者你在准备华为 ICT 大赛云赛道，需要一套可复现的 ModelArts 操作流程——这篇都能直接用。我会尽量把每一步讲到"照着做就能跑通"的程度，同时把背后的逻辑讲清楚，让你换个数据集也能自己迁移。

2. 动手之前，先把 ModelArts 的几个核心概念理清楚

很多人第一次进 ModelArts 控制台会懵，因为左边菜单一大堆：数据管理、开发环境、训练管理、模型管理、部署上线……看起来每个都能干活，但不知道从哪进。我一开始也是这样，点来点去浪费了半天。所以先把这几个概念的关系讲透，后面操作就不会迷路。

2.1 OBS、Notebook、训练作业、模型、在线服务到底是什么关系

用一句话串起来：数据放在 OBS，代码在 Notebook 里写和调，调好了提交成训练作业，训练产出模型，模型部署成在线服务对外提供推理。

• OBS（对象存储服务）：这是整个平台的"硬盘"。你的数据集、训练脚本、训练输出的模型文件，全都存在这里。ModelArts 本身不长期保存你的数据，它只是读写 OBS。所以你得先有一个 OBS 桶，把数据传上去。这一点和本地开发最大的区别是：你不能用本地路径/home/user/data，所有路径都得是obs://你的桶名/...这种形式。

• Notebook（开发环境）：一个在线的 JupyterLab，背后挂着一台带 GPU 的云主机。你可以在这里写代码、跑小规模调试、看数据长什么样。它的价值在于"交互式调试"——你可以一个 cell 一个 cell 地试，确认数据加载没问题、模型 forward 不报错，再提交正式训练。我的习惯是：任何训练脚本，先在 Notebook 上用一小部分数据跑通 1 个 epoch，确认无误再提交训练作业。

• 训练作业（Training Job）：正式的训练任务。你指定算法代码路径、数据路径、输出路径、算力规格，平台帮你起机器、装环境、跑完、存模型、释放机器。它和 Notebook 最大的区别是它是"非交互"的——提交之后你只能看日志，不能中途改代码。所以提交前一定要在 Notebook 里验证充分。

• 模型（Model）：训练作业跑完会产出一个模型文件（比如model.pt或 SavedModel 目录）。你需要把它"注册"成一个 ModelArts 模型，指定推理用的框架和入口脚本。这一步相当于给模型办了个"身份证"，后面部署要用。

• 在线服务（Online Service）：把注册好的模型部署成一个 RESTful API，别人发 HTTP 请求就能拿到推理结果。这是整条链路的终点，也是模型真正产生价值的地方。

理清这条链路之后，你会发现 ModelArts 的设计逻辑其实很清晰：存储和计算分离，开发和训练分离，训练和部署分离。每一段都可以独立替换、独立调试，这对工程化来说非常重要。

2.2 为什么我不建议一上来就用"自动学习"

ModelArts 有个"自动学习"功能，上传数据、点几下就能出模型，看起来很香。但我实测下来，它适合的是"我完全不懂 AI，就想快速验证一个想法"的场景。一旦你要控制网络结构、要调超参、要做数据增强、要复现论文，自动学习就不够用了。

更重要的是，自动学习帮你屏蔽了细节，但细节恰恰是你最需要理解的部分。比如数据格式要求、标签映射关系、评估指标怎么算——这些在自动学习里是黑盒，但换成正式训练作业，你必须自己写清楚。所以我建议：哪怕你是新手，也直接从 Notebook + 训练作业这条路走，前期多花两小时，后面省两天。

2.3 算力规格怎么选：不是越贵越好

ModelArts 提供从 CPU 到各种 GPU 的规格。选规格的核心原则是看显存，不看算力数字。因为大多数"训练跑不起来"的问题，本质是显存不够（OOM），而不是算力不够。

一个粗略的估算方法：显存占用 ≈ 参数量 × 4 字节 × 4（梯度+优化器状态+激活值）。比如一个 1 亿参数的模型，FP32 训练大概需要 1.6GB 只是存权重，加上梯度和 Adam 优化器状态（每个参数两份动量），实际轻松超过 6GB，再算上 batch 的激活值，8GB 显存跑 batch_size=8 都悬。

所以我的经验是：

提示：训练作业按"运行时长"计费，机器一启动就开始算钱。所以调试阶段尽量用 Notebook 的小规格，确认没问题再提交大规格训练作业。我见过有人用 8 卡 A100 调一个数据加载的 bug，烧掉的钱够买台笔记本了。

3. 数据准备：从本地文件到 OBS 桶的完整搬运

数据是训练的根。这一步做不好，后面全是坑。我踩过最典型的一个坑是：本地用ImageFolder读数据一切正常，传到 OBS 之后训练报"找不到文件"，排查半天发现是路径里有个中文目录名，OBS 对特殊字符的处理和本地不一样。

3.1 数据集该怎么组织目录结构

ModelArts 对数据目录没有强制要求，但你的训练脚本怎么读，决定了你怎么组织。我推荐两种最通用的结构：

分类任务（ImageFolder 风格）：

dataset/ ├── train/ │ ├── cat/ │ │ ├── 001.jpg │ │ └── ... │ └── dog/ │ ├── 001.jpg │ └── ... └── val/ ├── cat/ └── dog/

检测/分割任务（图片+标注分离）：

dataset/ ├── images/ │ ├── 001.jpg │ └── ... ├── annotations/ │ ├── 001.xml │ └── ... └── train.txt # 每行：images/001.jpg annotations/001.xml

关键点：目录名和文件名一律用英文+数字+下划线，不要有空格、中文、特殊符号。这不是 ModelArts 的锅，是跨平台文件系统的通用建议，但云端环境对这个问题更敏感。

3.2 上传到 OBS 的三种方式与选择建议

把数据弄到 OBS，有三条路：

1. 控制台网页上传：适合小数据（几百 MB 以内）。直接拖拽，简单粗暴。但超过 1GB 就非常慢，而且容易断。

2. OBS Browser+ 客户端：适合中等数据（几 GB 到几十 GB）。图形界面，支持断点续传、批量上传。我一般用这个传数据集。

3. obsutil 命令行工具：适合大数据和自动化。支持obsutil cp -r -f local_dir obs://bucket/dataset/这种递归上传，还能写脚本定时同步。数据量超过 50GB 我强烈建议用这个。

注意：上传前先确认 OBS 桶的区域和你的 ModelArts 在同一个区域（比如都在"华北-北京四"）。跨区域读写会产生额外流量费，而且速度慢。这个坑我在第一次用的时候踩过，传了 30GB 数据到错误的区域，白等了两小时。

3.3 数据格式转换：别等到训练时才后悔

如果你的原始数据是 CSV、Excel、或者一堆散乱的图片，在本地就转成训练脚本能直接读的格式，不要指望在云端现转。原因很简单：云端转换要消耗算力时间，而且一旦转换逻辑有 bug，你得重新提交训练作业，成本更高。

我常用的做法是：本地写一个prepare_data.py，把原始数据统一成上面说的目录结构，顺便做几件事——检查图片是否能正常打开（用 PIL 的verify()）、统计类别分布、剔除损坏样本。这个脚本跑完，数据就是"干净"的，传上去直接用。

from PIL import Image import os def check_images(root): bad = [] for dirpath, _, filenames in os.walk(root): for f in filenames: if f.lower().endswith(('.jpg', '.png', '.jpeg')): p = os.path.join(dirpath, f) try: img = Image.open(p) img.verify() # 验证文件完整性 except Exception as e: bad.append((p, str(e))) return bad if __name__ == '__main__': bad_files = check_images('./dataset') print(f'发现 {len(bad_files)} 个损坏文件') for p, err in bad_files: print(p, err)

这个脚本看起来简单，但帮我省过好几次事。有一次数据集里混进了几十张下载不完整的图片，训练时 DataLoader 直接崩，报的错还特别隐晦。提前用这个脚本筛一遍，问题在本地就解决了。

4. 在 Notebook 里把训练脚本调通

Notebook 是整个流程里我最喜欢的部分，因为它把"写代码"和"跑代码"放在同一个界面，改一行跑一行，反馈极快。但要用好它，有几个细节必须注意。

4.1 创建 Notebook 实例时的关键选择

创建 Notebook 时，平台会让你选镜像、规格、存储。我的建议：

• 镜像：选PyTorch或TensorFlow的官方镜像，版本和你本地一致。比如你本地用 PyTorch 2.0，就选对应的镜像，避免 API 不兼容。如果镜像里没有你需要的包，可以在 Notebook 里pip install，但注意Notebook 重启后 pip 装的包会丢，所以正式训练时要在训练作业的启动脚本里重新装。

• 规格：调试阶段选最小的 GPU 规格（比如 T4），够用就行。等代码调通了，正式训练再换大规格。

• 存储：Notebook 自带一块本地盘（比如/home/ma-user/work），但这块盘的数据在实例停止后不保证保留。所以重要代码和数据一定要存到 OBS，或者用平台的"持久化存储"功能。

提示：我习惯在 Notebook 里建一个code/目录放训练脚本，调通后直接把这个目录同步到 OBS，训练作业的代码路径就指向它。这样"调试"和"正式训练"用的是同一份代码，不会出现"本地能跑云端不能跑"的问题。

4.2 数据加载：从 OBS 读还是先拷到本地

这是新手最容易纠结的问题。ModelArts 的 Notebook 可以直接用obs://路径读数据（通过moxing库），但直接读 OBS 的速度远慢于读本地盘。所以我的策略是：

• 小数据（< 5GB）：直接用moxing从 OBS 拷到 Notebook 本地盘，再让 DataLoader 读本地。拷贝一次，后面训练快很多。

• 大数据（> 5GB）：用moxing的流式读取，或者用 ModelArts 的"数据盘"功能挂载。但说实话，大数据集我一般直接提交训练作业，不在 Notebook 里跑全量。

import moxing as mox # 把 OBS 上的数据拷到 Notebook 本地 mox.file.copy_parallel('obs://your-bucket/dataset/', '/home/ma-user/work/dataset/') print('拷贝完成')

copy_parallel比copy快，因为它会并发拷贝。这个函数我几乎每个项目都用，属于必备工具。

4.3 先跑通 1 个 epoch，再谈其他

代码写完之后，不要急着提交训练作业。先在 Notebook 里做三件事：

1. 用 10 张图片跑一遍 forward，确认模型结构没问题、输出维度对。
2. 用完整数据集跑 1 个 epoch，确认数据加载、loss 计算、反向传播、优化器更新都正常。
3. 保存一次模型并重新加载，确认保存和加载的逻辑对得上。

这三步做完，你基本可以放心提交训练作业了。我见过太多人跳过这三步，直接提交训练作业，结果跑了半小时报个"维度不匹配"，白白浪费算力。

4.4 训练脚本里必须写好的几个"接口"

ModelArts 的训练作业对脚本有一些约定，不遵守就会报错。核心是用argparse接收参数，因为平台是通过命令行参数把数据路径、输出路径传给你的。

import argparse import os def parse_args(): parser = argparse.ArgumentParser() parser.add_argument('--data_url', type=str, default='./data', help='训练数据路径') parser.add_argument('--train_url', type=str, default='./output', help='模型输出路径') parser.add_argument('--epochs', type=int, default=10) parser.add_argument('--batch_size', type=int, default=32) parser.add_argument('--lr', type=float, default=1e-3) return parser.parse_args() if __name__ == '__main__': args = parse_args() # 关键：ModelArts 传入的是 OBS 路径，需要先拷到本地 import moxing as mox local_data = '/cache/data' local_output = '/cache/output' os.makedirs(local_data, exist_ok=True) os.makedirs(local_output, exist_ok=True) mox.file.copy_parallel(args.data_url, local_data) # ... 训练逻辑 ... # 训练完把模型拷回 OBS mox.file.copy_parallel(local_output, args.train_url)

这里有个非常重要的细节：ModelArts 训练作业里，--data_url和--train_url传进来的是 OBS 路径，但你的训练代码不能直接读 OBS（速度慢且不稳定），所以要先用moxing拷到本地/cache目录，训练完再拷回去。/cache是训练容器的本地盘，读写快，但作业结束后会清空，所以必须拷回 OBS。

注意：/cache的空间有限，如果数据集特别大，拷贝可能失败。这时候要么申请更大的规格，要么用流式读取。我一般会先估算数据集大小，确保/cache放得下。

5. 提交训练作业：参数怎么填才不报错

Notebook 调通之后，提交训练作业就是"填表单"。但表单里每一项都有讲究，填错了轻则报错，重则跑一半失败。

5.1 训练作业表单逐项拆解

以"常用框架"方式创建训练作业为例，关键字段：

• 算法来源：选"常用框架"，然后选 PyTorch/TensorFlow 等。如果你用的是自定义镜像，选"自定义"。

• 代码目录：指向 OBS 上存放训练脚本的目录，比如obs://your-bucket/code/。注意是目录，不是单个文件。平台会把整个目录拷到容器里。

• 启动文件：代码目录里的入口脚本，比如train.py。这个文件必须存在，否则报错。

• 数据来源：可以配置多个数据通道，每个通道指定一个 OBS 路径和一个挂载名。比如数据通道 1 指向obs://your-bucket/dataset/，挂载名data，那么脚本里--data_url就会收到这个路径。

• 训练输出位置：模型保存到哪个 OBS 路径，比如obs://your-bucket/output/。

• 运行参数：传给脚本的命令行参数，比如--epochs=20 --batch_size=64 --lr=0.001。这里填的参数会覆盖脚本里的 default 值。

• 算力规格：选 GPU 型号和卡数。单卡就选 1，多卡选 2/4/8。

• 作业日志路径：日志存到哪，方便排查。

5.2 超参怎么设：一份能直接抄的起点

超参没有万能值，但有一个"不容易出错"的起点。以图像分类为例：

这里重点说batch_size 和 learning_rate 的关系。很多人不知道，batch_size 变大时，learning_rate 通常也要相应变大（线性缩放规则：lr 正比于 batch_size）。比如 batch_size 从 32 加到 256，lr 可以从 1e-3 加到 8e-3。如果你加了 batch_size 但没调 lr，会发现收敛变慢，还以为是模型有问题。

5.3 训练报 nan 的完整排查链路

回到开头那个nan的问题。在 ModelArts 上，nan的排查思路和本地一样，但因为环境是云端，有些信息不好拿。我总结了一套排查顺序：

第一步：确认是不是学习率太大。把 lr 除以 10 再跑，如果nan消失，就是 lr 问题。这是最常见的原因。

第二步：检查数据里有没有异常值。比如图片像素值超出 [0,255]、标签越界、CSV 里有空值。写个脚本统计每个 batch 的输入范围，看有没有 inf 或 nan。

第三步：检查 loss 函数。比如用CrossEntropyLoss时，如果标签是 one-hot 而不是类别索引，会算错。或者用了log(0)这种操作。

第四步：加梯度裁剪。这是最有效的兜底手段：

torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)

在loss.backward()之后、optimizer.step()之前加这一行，能挡住绝大多数梯度爆炸导致的nan。

第五步：检查混合精度。如果用 AMP，确保用了GradScaler：

from torch.cuda.amp import autocast, GradScaler scaler = GradScaler() with autocast(): output = model(input) loss = criterion(output, target) scaler.scale(loss).backward() scaler.unscale_(optimizer) torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0) scaler.step(optimizer) scaler.update()

GradScaler会自动做 loss scaling，防止 FP16 下梯度下溢。少了它，混合精度训练很容易出nan。

提示：ModelArts 的训练日志会实时输出到控制台，也会存到你指定的日志路径。排查nan时，重点看 loss 是在第几个 step 变成nan的，以及那一步的输入数据有没有异常。如果每次都是同一个 step，大概率是数据问题；如果是随机的，大概率是梯度问题。

6. 模型部署：从训练产物到可调用的 API

训练跑完，OBS 的输出目录里会有模型文件。但这时候它还不能对外服务，需要经过"注册模型"和"部署服务"两步。

6.1 推理脚本怎么写：customize_service.py的结构

ModelArts 部署自定义模型时，需要一个推理脚本，通常叫customize_service.py。它的核心是定义一个继承自Model的类，实现_preprocess、_inference、_postprocess三个方法。

from modelarts.model import Model import torch import torch.nn as nn from PIL import Image import numpy as np import io class MyModel(Model): def __init__(self, model_path): super().__init__(model_path) self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') # 加载模型结构 self.model = MyNetwork() # 加载权重 state_dict = torch.load(f'{model_path}/model.pt', map_location=self.device) self.model.load_state_dict(state_dict) self.model.to(self.device) self.model.eval() def _preprocess(self, data): # data 是请求体，通常是图片字节流 images = [] for item in data: img = Image.open(io.BytesIO(item)).convert('RGB') img = img.resize((224, 224)) arr = np.array(img).astype(np.float32) / 255.0 arr = (arr - [0.485, 0.456, 0.406]) / [0.229, 0.224, 0.225] arr = arr.transpose(2, 0, 1) # HWC -> CHW images.append(arr) tensor = torch.from_numpy(np.stack(images)).to(self.device) return tensor def _inference(self, tensor): with torch.no_grad(): output = self.model(tensor) prob = torch.softmax(output, dim=1) return prob.cpu().numpy() def _postprocess(self, prob): # 返回 JSON 可序列化的结果 idx = int(np.argmax(prob, axis=1)[0]) conf = float(np.max(prob, axis=1)[0]) return {'class_id': idx, 'confidence': conf}

几个关键点：

• _preprocess里的归一化参数必须和训练时一致。训练用 ImageNet 的 mean/std，推理也得用同一套，否则精度会掉。这个坑我踩过，训练时用了自定义归一化，推理时忘了改，结果线上准确率比验证集低 20 个点。

• model.eval()不能忘。它会关掉 dropout 和 batch norm 的训练行为。忘了加，推理结果每次都不一样。

• torch.no_grad()不能忘。省显存、加速推理。

• 返回结果必须是 JSON 可序列化的。numpy 的float32不能直接序列化，要转成 Python 的float。

6.2 注册模型与部署服务的操作顺序

1. 上传推理脚本和模型文件到 OBS。通常放在obs://your-bucket/model/下，包含model.pt和customize_service.py。

2. 在"模型管理"里创建模型。指定模型来源（OBS 路径）、推理框架（选"自定义"）、推理脚本路径。

3. 在"部署上线"里创建在线服务。选择刚注册的模型、算力规格（推理一般 T4 或 CPU 够用）、实例数（1 个起步）。

4. 等待部署完成。状态变成"运行中"就可以调用了。

5. 测试 API。平台会给你一个 HTTPS 地址，用 curl 或 Python requests 发请求。

import requests import base64 url = 'https://your-service-endpoint/v1/infers/xxx' with open('test.jpg', 'rb') as f: img_bytes = f.read() resp = requests.post(url, data=img_bytes, headers={'Content-Type': 'application/octet-stream'}) print(resp.json())

6.3 部署后精度下降的常见原因

模型在验证集上 95%，部署后只有 70%，这种问题很常见。排查方向：

我遇到最多的是预处理不一致。训练时用torchvision.transforms，推理时手写 numpy 归一化，两边参数对不上。解决办法是：把预处理逻辑抽成一个函数，训练和推理共用。这样改一处，两边都生效。

7. 几个让我少走弯路的实操心得

写到这里，核心流程已经讲完了。最后分享几个散落的经验，都是我在实际项目里踩出来的，文档里不会写。

第一，善用"训练作业"的日志和 TensorBoard。ModelArts 支持把 TensorBoard 日志输出到 OBS，然后在 Notebook 里启动 TensorBoard 查看。这比盯着控制台刷日志直观多了。配置方法是在训练脚本里用torch.utils.tensorboard.SummaryWriter，输出路径指向--train_url，训练完在 Notebook 里tensorboard --logdir obs://...就能看。

第二，模型文件不要只存一份。训练作业默认只保存最后一个 epoch 的模型。但实际项目里，你往往需要"验证集上最好的那个"。所以脚本里要自己写"保存最佳模型"的逻辑：

best_acc = 0.0 for epoch in range(epochs): # ... 训练 ... val_acc = evaluate(model, val_loader) if val_acc > best_acc: best_acc = val_acc torch.save(model.state_dict(), f'{local_output}/best_model.pt')

第三，注意 OBS 路径的权限。如果你用的是子账号，确保它对相关 OBS 桶有读写权限。我见过有人训练作业跑完，模型存不进去，报"权限拒绝"，排查半天是 IAM 权限没配好。

第四，部署服务时先小流量测试。在线服务刚上线，不要直接接生产流量。先用几个测试样本验证，确认返回结果正确、延迟可接受，再逐步放量。ModelArts 支持灰度发布，可以配置多个版本按比例分流。

第五，成本控制要上心。训练作业和在线服务都是按需计费。训练完记得手动停止 Notebook 实例，在线服务如果只是测试，用完就删。我给自己定了个规矩：任何云资源，创建时就设个提醒，超过预期时长就检查是否还在跑。这条规矩帮我省过不少冤枉钱。

这套流程我从第一次用到现在，大概跑了十几个项目，从图像分类到文本分类都走过一遍。ModelArts 最大的价值不是它有多"智能"，而是它把工程化的脏活都标准化了——你只要按它的约定组织数据和代码，剩下的它帮你兜底。对于个人开发者和小团队来说，这比自建一套训练集群划算太多。