企业官网建设流程全解析

1. 为什么我最终选了 ClearML：受够了“实验记录靠截图”的日子

如果你和我一样，搞过一阵子深度学习训练，大概率经历过这种场景：模型跑了十几个小时，终于出了个不错的精度，结果你只记得“好像是用那个调了学习率之后的版本跑的”，至于数据集是哪个版本、超参数怎么改的、loss曲线长什么样，全凭一张嘴和几张三年前的文件名截图。再惨一点，电脑重启，jupyter notebook 的 cell 顺序乱了，训练日志丢了，那一刻真的想摔键盘。

ClearML 解决的就是这件事。它是一个开源的 MLOps 平台，核心功能一句话就能说清楚：把你训练的代码、环境、超参数、日志、指标曲线、模型文件全部自动记录下来，然后在网页上给你一个可视化的看板，任何时候回来看，都能完整复现“当时到底发生了什么”。更舒服的是，这种记录基本不需要你改代码，只要在原有训练脚本里加两行 import，剩下的全是自动的。

这个“低侵入”的特性，是我选它而不是其他平台的最主要原因。你不需要把整套训练框架迁移过去，不需要重写 dataloader，也不需要非得用它的 Task 类把所有逻辑包起来。ClearML 的设计思路是“监听 + 上报”，你原有的 PyTorch / TensorFlow / scikit-learn 代码该怎么写还怎么写，它通过框架自带的回调机制把日志抓走。

这篇文章我会从一个零基础用户的角度，完整走一遍 ClearML 的安装、环境准备、初始化、跑通第一个实验的全过程。适合的人群很明确：刚接触 MLOps、想给自己的深度学习项目加上实验管理能力、又不想被复杂平台劝退的同学。我会把每一步“为什么要这么做”也讲明白，不只是贴命令。

提示：ClearML 有免费的开源社区版，也有企业版。本文介绍的是开源版 + 免费云端服务的使用方式，这也是绝大多数个人开发者和小团队最合适的起步路径。

2. 安装前的整体设计：先用免费服务，还是自建 Server？

2.1 两种使用模式的区别，先搞清楚再动手

ClearML 的使用模式可以粗分成两类：SaaS 模式和自托管模式。

SaaS 模式就是官方给你提供一个免费的测试服务器（在 app.clear.ml 上注册账号就能拿到），你的训练脚本把日志上报到官方服务器，然后在网页上查看。这种模式最大的好处是零运维，注册即用，适合个人学习和中小型项目的初期阶段。数据隐私方面，如果你只是跑公开数据集、做算法验证，完全没问题；但如果是公司内部数据，就得掂量一下。

自托管模式则是用 Docker 在你自己机器上把 ClearML Server 跑起来，所有数据不出内网。这种模式适合对数据安全有要求、或者需要把实验管理平台做成团队基础设施的场景。自托管需要至少 4GB 内存和 20GB 磁盘，官方推荐配置是 8GB 内存起步，因为要同时跑 Elasticsearch、MongoDB、Redis 和 Web 服务这四个组件。

我的建议很直接：第一次接触，百分之百选 SaaS 模式。先把整个流程跑通，搞清楚 Task、Queue、Artifact 这些概念是怎么回事，再去折腾自托管。不然你还没搞清楚日志上报是怎么回事，就先被 docker-compose 的日志刷屏劝退了，得不偿失。

2.2 本地环境的三个硬性要求

不管选哪种模式，你的本地机器都需要满足三个基本条件：

第一，Python 版本必须是 3.7 以上，建议 3.8 或 3.9。我测试过 3.10 和 3.11 也能正常工作，但官方文档中 3.8 和 3.9 的兼容性验证最充分，如果你机器上正好有 conda，建议直接建一个 Python 3.9 的干净环境。

第二，有 pip 能正常安装包的网络环境。ClearML Python 包本身不大，安装很快，但如果你要用 PyTorch、TensorFlow 这些深度学习框架，网络条件就得跟上，不然光装 torch 就能耗掉你一个下午。

第三，需要一个现代浏览器。ClearML 的 Web UI 对 Chrome 和 Edge 的兼容性最好，Firefox 也行，但某些冷门浏览器上图表渲染偶尔会有小问题。这个不是硬性要求，但能省掉不少排查时间。

2.3 用 conda 还是 venv？我的建议

我知道很多教程默认你用的是 conda，但说实话，对于 ClearML 这种依赖关系相对简单的包，用 Python 自带的 venv 就够了，没必要再装一个 conda。除非你同时还要管理不同版本的 CUDA 环境，那 conda 确实更方便。

我自己的选择是这样的：如果用 GPU 做深度学习，还是 conda 更省心，因为 CUDA 相关的依赖用 conda 装比 pip 稳。但如果只是跑 CPU 小实验、学 ClearML 的功能，直接用 venv 就够了。不管你选哪种，请务必创建一个独立的虚拟环境，不要直接装在系统 Python 里。我之前就干过直接把包往系统 Python 里怼的事，后来环境乱到连pip list都要等三秒，全是泪。

3. 从零安装 ClearML Python 包：保姆级命令实操

3.1 创建虚拟环境并激活

我用 conda 为例，因为这是大多数深度学习玩家的默认选择。先创建一个 Python 3.9 的环境，名字就叫 clearml：

conda create -n clearml python=3.9 -y conda activate clearml

创建好之后，确认一下 Python 版本，顺便看一眼 pip 是不是最新版：

python --version pip install --upgrade pip

注意：如果你用的是 venv，对应的命令是python -m venv clearml_env，然后 Windows 上用clearml_env\Scripts\activate激活，Linux/macOS 上用source clearml_env/bin/activate激活。核心思路一样，只是激活命令有区别。

3.2 安装 ClearML Python 包

这一步很简单，一条命令搞定：

pip install clearml

这个包是整个 ClearML 体系中最核心的客户端组件，它包含了实验管理需要的Task、日志上报用的Logger、数据集管理用的Dataset，以及后面我们会用到的clearml-agent命令行工具。

安装完成后可以验证一下版本号：

clearml --version

如果能看到版本号输出，说明安装成功了。如果提示找不到命令，大概率是虚拟环境没激活，或者你的 Python Scripts 目录没有加入 PATH。

3.3 常见安装报错与处理

我见过最多的安装报错是网络问题导致的超时。解决方法很简单，换成国内镜像源：

pip install clearml -i https://pypi.tuna.tsinghua.edu.cn/simple

如果报的是缺少wheel包之类的构建错误，先用pip install wheel补上，再装 ClearML 基本就顺了。还有一种情况是你机器上已经有一个很老的 clearml 版本，和新的配置文件格式不兼容，这时候先卸载再重新安装：

pip uninstall clearml -y pip install clearml --upgrade

3.4 顺手装一个深度学习框架

如果你只是想先跑通 ClearML 的流程，不一定需要 GPU，装 CPU 版 PyTorch 就够了：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

如果你想用 GPU，那安装方式取决于你的 CUDA 版本。这一步不在本文的核心范围，但后续的示例代码会用到 torch，所以先装上 CPU 版。后面要换 GPU 版再装也不冲突，反正虚拟环境里随便折腾。

4. 连接 ClearML 服务：注册、创建密钥、一键初始化

4.1 注册并创建 API 密钥

如果走 SaaS 模式，先去 app.clear.ml 网站上注册一个账号。注册过程很简单，邮箱验证一下就行。登录之后，点右上角你的头像，进入Settings，再找到Workspace下的API Credentials页面，点Create new credentials按钮。

系统会生成一对密钥：API Access Key和API Secret Key。这两个密钥是成对使用的，作用类似于用户名和密码，你的本地客户端靠它们来向服务器证明身份。

注意：API Secret Key 只有在创建的时候才会完整显示一次，之后就只能看到打码的版本。务必把这一对密钥临时存在记事本里，后面配置要用。丢了的话只能删除重建。

这里要补充一下权限的概念。API 密钥本质上是服务器给你发的一张“通行证”，它包含了你的身份信息以及对应的权限范围。在团队场景下，管理员可以给不同成员分配不同权限的密钥，比如只读权限的密钥可以用来查看实验，但不能创建新实验。权限控制是 MLOps 平台在多人协作时非常关键的能力，个人使用阶段可能感受不深，但团队使用时可以避免很多误操作。

4.2 用命令行工具完成初始化

拿到密钥之后，回到终端，输入：

clearml-init

这时候会出现一个交互式的初始化向导，它会要求你粘贴 API Access Key 和 API Secret Key，还会问你要不要设置 Web 服务器地址。如果是 SaaS 模式，直接按回车用默认地址就行。整个过程大概长这样：

ClearML SDK setup process Please create new user credentials... API access key: [你的 Access Key] API secret key: [你的 Secret Key] Web server [https://app.clear.ml]: ...

全部输入完之后，它会生成一个配置文件，存放在你的用户目录下。Windows 路径是C:\Users\你的用户名\clearml.conf，Linux/macOS 路径是~/.clearml.conf。这个文件包含了你的服务器地址和密钥信息，以后所有脚本都会自动读取它，不需要再写死在代码里。

配置完成后，可以跑一个最简单的命令来验证连接是否成功：

clearml-init --check

它会告诉你配置是否有效，也能够正常连接到服务器。到这里，环境部分就全部搞定了。

技巧：如果你是在服务器上配置，而且是非交互式的 SSH 环境，clearml-init的交互式向导可能用不了。这时候可以手动创建~/.clearml.conf文件，按照官方文档的模板把密钥填进去，效果完全一样。

5. 第一个清实验：用三行代码打通全流程

5.1 写一个最小实验脚本

环境都准备好了，现在来跑第一个实验。这个实验不涉及深度学习，就是一个简单的数学计算加日志输出，目的是让你直观地看到 ClearML 到底记录了什么。

新建一个 Python 文件，名字叫first_experiment.py，内容如下：

from clearml import Task # 初始化一个任务，名字叫 "第一个实验" task = Task.init(project_name="My First Project", task_name="Hello ClearML") print("Hello, ClearML!") print("2 + 3 =", 2 + 3) # 上报一个标量指标，方便在网页上看到曲线 logger = task.get_logger() logger.report_scalar("example", "value", value=5, iteration=0) logger.report_scalar("example", "value", value=6, iteration=1)

就这三行核心代码。Task.init干了非常多的事，它会自动检测你当前的 Python 代码、环境依赖、Git 提交信息、命令行参数，把这些信息上传到服务器，然后返回一个 Task 对象。后面我们用logger.report_scalar上报了两个点，这些点会生成图表显示在网页上。

直接运行：

python first_experiment.py

如果一切正常，终端里会出现类似这样的输出：

ClearML Task: created new task id: 8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8

记下这个 task id，它是这个实验的唯一标识。

5.2 在网页上查看你的人生第一个实验

回到 ClearML 的网页界面，左侧菜单点Projects，你应该能看到一个叫My First Project的项目，点进去就能看到这个实验的卡片。

点击卡片进入实验详情页，你会看到非常多的信息。左侧是日志文件，代码里所有print输出都被自动捕获了。右侧是指标曲线，刚才上报的两个点会显示在一个折线图上。下面还有开发者环境信息、Git 提交哈希值、Python 包版本列表。

很多第一次用 ClearML 的人到这里都会有点惊讶：我没写几行代码，它怎么知道这么多？原因在于Task.init在初始化时做了一堆采集工作，它调用了git命令拿到当前仓库的 commit 信息，调用了pip freeze拿到环境依赖列表，还通过 Python 的sys.argv拿到了命令行参数。这些信息对于复现实验至关重要——当你三个月后回看一个实验时，有了环境依赖和代码版本，你才能精确地重建当时的环境。

5.3 关于 “实验” 这个概念，我说点自己的理解

第一次接触 ClearML 时，“Task” 这个概念让我困惑了很久。它和“实验”是什么关系？为什么不用 Experiment 这个名字？我用了一段时间之后概括了一句话：

Task 是实验的一个实例。同一个实验代码，你跑了 10 次不同的超参数组合，就会产生 10 个 Task。它们共享同一个工程和代码，但每个 Task 有自己独立的参数、日志、指标和模型文件。

打个比方：做菜的时候，菜谱就是实验代码，你用不同的火候、盐量做了几盘番茄炒蛋，每一盘就是一个 Task。菜谱本身不记录你这次放了多少盐，但 Task 会记录。这个理解很重要，因为它直接影响你后续怎么组织项目。正确的方式是在代码里用 argparse 接收所有可变参数，然后在 ClearML 的网页界面或者命令行里给每个 Task 指定不同的参数值，让一次代码运行对应一个 Task。

6. 跑一个带模型训练的真实实验：MNIST 手写数字识别

6.1 为什么要用真实训练做演示

很多人学完上一节会觉得“就这”？打印两行字也算实验管理吗？为了消除这种疑惑，我们用一个真实的小型训练任务来演示：在 MNIST 数据集上训练一个简单的神经网络。这个任务非常经典，数据量小，单机 CPU 跑几分钟就能出结果，非常适合做平台功能演练。

这一节的目的是让你看到 ClearML 在真实训练场景中到底帮你自动记录了什么，以及如何手动上报更多自定义信息（比如每个 epoch 准确率、模型文件等）。

6.2 完整代码：训练 + 自动日志 + 模型上传

from clearml import Task import torch import torch.nn as nn import torch.optim as optim from torchvision import datasets, transforms from torch.utils.data import DataLoader # ============ 1. 初始化 ClearML 任务 ============ task = Task.init(project_name="MNIST 实战", task_name="第一个训练任务") # ============ 2. 定义超参数 ============ params = { "epochs": 5, "batch_size": 64, "learning_rate": 0.01, "hidden_size": 128, } # 把超参数记录到 Task 中，网页上可以看到/修改 task.connect(params) # ============ 3. 准备数据 ============ transform = transforms.Compose([ transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,)) ]) train_dataset = datasets.MNIST(root="./data", train=True, download=True, transform=transform) train_loader = DataLoader(train_dataset, batch_size=params["batch_size"], shuffle=True) # ============ 4. 定义模型 ============ class SimpleNet(nn.Module): def __init__(self, hidden_size): super().__init__() self.fc1 = nn.Linear(28 * 28, hidden_size) self.relu = nn.ReLU() self.fc2 = nn.Linear(hidden_size, 10) def forward(self, x): x = x.view(x.size(0), -1) x = self.relu(self.fc1(x)) x = self.fc2(x) return x model = SimpleNet(params["hidden_size"]) criterion = nn.CrossEntropyLoss() optimizer = optim.SGD(model.parameters(), lr=params["learning_rate"]) # ============ 5. 训练循环 ============ logger = task.get_logger() for epoch in range(params["epochs"]): total_loss = 0.0 correct = 0 total = 0 for batch_idx, (data, target) in enumerate(train_loader): optimizer.zero_grad() output = model(data) loss = criterion(output, target) loss.backward() optimizer.step() total_loss += loss.item() _, predicted = torch.max(output.data, 1) total += target.size(0) correct += (predicted == target).sum().item() if batch_idx % 100 == 0: step = epoch * len(train_loader) + batch_idx logger.report_scalar("train", "loss", iteration=step, value=loss.item()) print(f"Epoch {epoch} Batch {batch_idx} Loss {loss.item():.4f}") avg_loss = total_loss / len(train_loader) accuracy = 100.0 * correct / total logger.report_scalar("train", "epoch_loss", iteration=epoch, value=avg_loss) logger.report_scalar("train", "accuracy", iteration=epoch, value=accuracy) print(f"Epoch {epoch} 平均 Loss: {avg_loss:.4f} 准确率: {accuracy:.2f}%") # ============ 6. 保存并上传模型 ============ model_path = "mnist_model.pt" torch.save(model.state_dict(), model_path) task.upload_artifact("mnist_model", artifact_path=model_path) print("训练完成，模型已上传到 ClearML")

这个脚本比较长，但每个部分都很清晰。最关键的是第 2 步和第 6 步：task.connect(params)把超参数同步到了服务器，task.upload_artifact把模型文件传了上去。一个完整实验的核心三要素——参数、指标、产物——这就齐了。

6.3 GPU 版本要改哪些地方

如果要用 GPU 训练，需要改动的地方其实不多。在模型定义之后加一行model = model.cuda()，然后在每个 batch 把数据也搬过去。日志上报部分和模型上传部分不需要任何改动。

device = torch.device("cuda" if torch.cuda.is_available() else "cpu") model = model.to(device) for data, target in train_loader: data, target = data.to(device), target.to(device) # 其余代码不变

ClearML 会自动检测到训练环境中有 GPU，并把 GPU 型号、显存使用率也记录下来。这个信息在后续对比不同硬件上的实验时非常有用。

注意：在真实项目中，模型文件名、数据集路径、超参数这些尽量都用变量而不是硬编码，这样 ClearML 记录的参数列表才完整。比如你改了hidden_size，只要是通过task.connect传入的，在网页上就能看到新值，并且能实现不同参数跑多个实验的组对比。

7. 跑完第一个实验后，你应该去网页上看这几个关键页面

7.1 实验列表与对比视图

训练跑完后，进入项目页面，你会看到一个或多个实验卡片。每个卡片上会显示实验名称、状态、运行时长、创建时间，以及关键的指标摘要（比如准确率）。你可以勾选两个实验，点击Compare按钮，进入对比视图。

对比视图是我个人特别推荐的功能。左右分栏展示两个实验的日志和指标曲线，超参数差异会高亮显示。做实验调参的时候，这个功能能让你快速定位到“这次到底改了什么导致了精度变化”。

7.2 实验详情页的四个核心分区

进入某个实验的详情页，重点看四个地方：

Overview（概览）：展示实验名称、状态、创建时间、运行时长、所属项目等基本信息，以及所有超参数列表。生产环境排查问题时，这个页面是判断“上次上线的是哪个实验”的第一站。

Scalars（指标曲线）：所有通过logger.report_scalar上报的数据都会以曲线图展示，支持多曲线叠加、缩放、导出为 CSV。如果你在训练中上报了 loss 和 accuracy，这里就能清晰地看到训练过程是否收敛、有没有过拟合迹象。

Plots（自定义图表）：可以上报混淆矩阵、PR 曲线、特征分布等复杂图表。对于分类任务，强烈建议每个 epoch 的混淆矩阵都上报一份，排查类别不均衡问题时非常有帮助。

Artifacts（产物）：展示所有通过upload_artifact上传的文件，包括模型权重、预处理后的数据集、评估报告等。每个产物都有版本记录，你可以下载任意历史产物进行回滚。

7.3 用表格对比不同实验的关键指标

当实验多起来之后，列表逐一查看的效率太低，ClearML 支持自定义实验表格。你可以选择要显示的指标列（比如 accuracy、loss、总训练时长），直接做成一个对比表。这个表可以导出为 CSV 分享给同事，非常方便。

我自己实际用得最多的场景是这样的：一个普通项目跑下来，一个月能积累 100 多个实验。如果没有表格对比，想从里面挑出最好的模型基本靠翻记录；有了表格，按 accuracy 排个序，一眼就看到最优的 3 个实验，再点进详情页看它们的超参数差异，效率完全不一样。

8. 常见问题与排查技巧：安装和运行期间的坑

8.1 安装阶段最容易踩的 5 个坑

结合我自己的经历和身边朋友反馈的问题，整理一份高频问题速查表：

8.2 实验运行时的 3 个典型问题

第一个问题：日志上传失败，但本地正常运行。

这通常是网络波动导致的。ClearML 的日志上传是异步的，如果训练中途断网，部分日志可能丢失，但实验本身不会中断。排查方式很简单：检查网络连通性，确认app.clear.ml可以正常访问。如果网络经常波动，建议换自托管模式，数据走内网就稳定得多。

第二个问题：实验其实跑完了，但网页上卡在“运行中”状态。

这是因为进程异常退出时没有主动调task.close()或者用with Task.init() as task的上下文模式。训练处理崩溃或者强杀进程时，客户端来不及上报结束状态。解决方法是：在代码里用 try-finally 包住训练逻辑，finally 里调task.close()，或者直接用上下文管理器写法。这样即使训练报错，Task 也会被标记为失败而不是一直挂起。

第三个问题：训练代码里的torch.compile和 ClearML 有冲突。

某些新版 PyTorch 的torch.compile会改变模型内部的执行流程，极少数情况下会导致 ClearML 无法捕获模型结构。遇到这个问题，先注释掉torch.compile跑一次看看日志是否正常，如果确实是兼容性问题，可以考虑把模型结构记录放在 compile 之前的版本上。

8.3 几个日常使用习惯，能让体验舒服不少

第一，养成给实验起可读名字的习惯。task1、task2这种名字在实验少的时候无所谓，一旦数量上两位数，光看名字根本不知道每个实验做了什么。我现在的做法是：姓名即语义，比如resnet34_lr1e-3_mixup，一眼就知道网络、学习率和数据增强方法。这只是个人习惯，但推荐你也试试。

第二，注意清理不再需要的实验。免费版服务对存储空间有配额限制，动辄几百个实验会让配额消耗得很快。建议模型选了最优之后，就把相关的次优实验归档或删除，保留少量有对比价值的即可。归档不是删除，后续还能恢复。

第三，定期导出关键实验的配置。ClearML 支持把超参数配置导出为 JSON 文件，这是一个很好的备份方式。万一服务器数据出了问题，靠着 JSON 配置也能快速重建实验。

第四，日志文件中注意不要输出敏感信息。训练日志会被完整保存在服务器上，如果你处理的是公司业务数据，涉及用户 ID、手机号之类的敏感信息，请在上报前做脱敏处理。无论用的是 SaaS 还是自托管，这条都是基本素养。

9. 实战心得：从个人使用到团队协作，ClearML 最值钱的能力是什么

用了一段时间 ClearML 之后，我最大的一个感受是：它的价值不在于“记录”，而在于“比较”。

记录只是一个基础能力，真正的效率提升来自“对比不同实验”之后能快速做出判断。手动记录实验时，你需要自己维护一个巨大的表格，每一行是实验编号、修改说明、结果指标。一旦超过二十行，这个表格的维护成本已经高到你会开始偷懒。而 ClearML 的自动记录 + 可视化对比曲线，能让你把精力放在“下一步怎么调参数”上，而不是花时间回忆上次做了什么。

如果你是在团队里使用，ClearML 的价值会更明显。团队成员共享同一个服务之后，每个人跑的实验都在同一个工作区里，谁改了什么、当前最好的模型是哪个、最新的数据集版本是什么，一目了然。这解决了团队协作里非常常见的“你用了哪份数据”这种反复沟通的痛点。

另外说一点很细节但很重要的体会：ClearML 对教育资源、开源项目的支持很友好。个人免费版对非商业用途基本够用，这也意味着学生、独立开发者可以零成本建立起自己的实验管理体系。如果你未来的目标是进入机器学习工程岗位，提前习惯用这类工具组织项目，面试和实际工作时会非常有优势。

最后分享一个我实际开发中的小技巧：不要把 ClearML 当成“最后才接入”的东西。很多人习惯先把模型调通再考虑实验管理，结果到了要记录的时候发现代码已经被改得面目全非。更好的方式是一开始写训练脚本时就把Task.init、task.connect、logger.report_scalar加进去，哪怕早期指标上报得粗糙一点也没关系，至少所有的实验历史从第一天就开始沉淀了。这也意味着，当你某次模型效果突然变好的时候，你永远能找到对应的那次改动，而不是拍着脑袋说“好像是运气好”。