ClearML 实验管理 — 开源全栈 MLOps 平台：实验追踪 + 数据管理 + 任务调度¶

# 安装 ClearML 客户端
pip install clearml                        # 基础安装
pip install clearml-agent                  # 任务调度 Agent（可选）

# 初始化配置（连接到 ClearML 服务器）
clearml-init                               # 交互式配置向导

# 如果使用免费的公共服务器（app.clear.ml）
# 按提示输入 API 凭证即可

# 本地自部署服务器（使用 Docker Compose）
git clone https://github.com/allegroai/clearml-server.git
cd clearml-server
docker-compose up -d                       # 启动本地服务

# 验证连接
python -c "from clearml import Task; Task.init(project_name='test', task_name='test')"

from clearml import Task, Logger, Dataset   # 三个核心类

# === 实验追踪（最常用）===
# 在训练代码最开头添加这两行，就能自动追踪所有内容
task = Task.init(
    project_name="宏基因组分析",             # 项目名（会自动创建）
    task_name="随机森林-特征选择-v1",        # 实验名
    task_type=Task.TaskTypes.training,      # 任务类型
)

# 记录超参数（支持字典）
task.connect({
    "n_estimators": 100,                    # 随机森林树数量
    "max_depth": 10,
    "learning_rate": 0.01,
})

# 记录指标（实时显示在 Web 界面）
logger = task.get_logger()
for epoch in range(100):
    train_loss = 0.5 - epoch * 0.003       # 示例值
    val_acc = 0.7 + epoch * 0.002

    logger.report_scalar(                   # 记录标量指标
        title="Loss",                       # 图表标题
        series="train_loss",               # 系列名（一张图可以有多个系列）
        value=train_loss,
        iteration=epoch,                    # X 轴（通常是 epoch 或 step）
    )
    logger.report_scalar(
        title="Accuracy",
        series="val_accuracy",
        value=val_acc,
        iteration=epoch,
    )

# 记录混淆矩阵（自动生成热图）
import numpy as np
confusion = np.array([[50, 10], [5, 35]])
logger.report_confusion_matrix(
    "Confusion Matrix", "train",
    matrix=confusion,
    iteration=100,
    xlabels=["健康", "T2D"],               # X 轴标签
    ylabels=["健康", "T2D"],               # Y 轴标签
)

task.close()                               # 关闭任务（标记为完成）

from clearml import Dataset

# === 数据集管理（版本控制数据）===
# 创建新数据集版本
dataset = Dataset.create(
    dataset_name="宏基因组16S数据",         # 数据集名称
    dataset_project="宏基因组分析",          # 所属项目
    dataset_version="1.0",                  # 版本号
)
dataset.add_files("/data/16S_fastq/")      # 添加数据文件（支持目录）
dataset.upload()                            # 上传到 ClearML 服务器
dataset.finalize()                          # 完成版本（之后不能修改）

# 在训练代码中加载数据集（自动缓存）
dataset = Dataset.get(
    dataset_name="宏基因组16S数据",
    dataset_version="1.0",
)
local_path = dataset.get_local_copy()      # 下载到本地并返回路径
print(f"数据集路径：{local_path}")

# === 模型自动记录 ===
from clearml import OutputModel
output_model = OutputModel(task=task, label_enumeration={"健康": 0, "T2D": 1})
output_model.update_weights("model.pkl")   # 上传模型文件
output_model.update_design(config_dict={"model": "RandomForest", "n_estimators": 100})

# 完整的 sklearn 模型训练追踪示例

from clearml import Task, Logger
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score
import numpy as np
import joblib

# 初始化 ClearML 任务（一行代码搞定追踪）
task = Task.init(
    project_name="T2D菌群分类",
    task_name="随机森林_baseline",
)

# 记录超参数（修改这里的值，Web 界面会自动显示）
params = task.connect({
    "n_estimators": 200,
    "max_depth": 15,
    "min_samples_split": 5,
    "random_state": 42,
})

# 加载数据（示例）
X = np.random.randn(100, 50)               # 示例：100个样本，50个特征
y = np.random.randint(0, 2, 100)           # 示例：二分类标签

# 训练模型
rf = RandomForestClassifier(
    n_estimators=params["n_estimators"],   # 使用 ClearML 管理的超参数
    max_depth=params["max_depth"],
    random_state=params["random_state"],
)
rf.fit(X, y)

# 交叉验证评估
cv_scores = cross_val_score(rf, X, y, cv=5, scoring="roc_auc")
logger = task.get_logger()
logger.report_scalar("AUC", "mean", cv_scores.mean(), 0)
logger.report_scalar("AUC", "std", cv_scores.std(), 0)

# 保存并上传模型
joblib.dump(rf, "random_forest.pkl")
task.upload_artifact("random_forest_model", "random_forest.pkl")

print(f"交叉验证 AUC: {cv_scores.mean():.4f} ± {cv_scores.std():.4f}")
task.close()