mlr3torch：在R语言中统一深度学习与机器学习工作流

mlr3torchR语言深度学习

于 2026-05-28 03:07:32 修改

·本内容遵循CC 4.0 BY-SA版权协议

1. 项目概述：为什么R语言需要mlr3torch？

在数据科学和机器学习的实践中，R语言因其在统计建模、数据可视化和探索性数据分析方面的卓越表现而备受青睐。然而，当项目需求从传统的广义线性模型、决策树延伸到需要处理图像、文本或复杂序列数据的深度学习领域时，许多R用户会感到一丝“割裂感”。我们常常需要跳出熟悉的tidyverse或mlr3生态，去调用基于Python的keras或tensorflow接口，或者学习一套全新的、专为深度学习设计的R包（如torch或luz）的API。这种上下文切换不仅增加了学习成本，更关键的是，它破坏了机器学习工作流的统一性和可复现性。想象一下，你的特征工程、交叉验证、超参数调优流程在mlr3中已经打磨得十分顺畅，但到了训练神经网络时，却不得不手动编写循环来管理训练集和验证集，手动记录损失曲线，手动实现早停法——这无疑是一种效率的倒退。

mlr3torch的出现，正是为了弥合这一鸿沟。它的核心目标不是再造一个深度学习轮子，而是扮演一个“桥梁”和“集成器”的角色。它将torch（R语言中强大且底层的张量计算与神经网络库）的强大能力，无缝地嵌入到mlr3这一现代、统一、面向对象的机器学习框架之中。这意味着，你现在可以将一个深度神经网络，完全当作mlr3中的一个“学习器”（Learner）来对待。你可以用它和随机森林、XGBoost一起进行基准测试（Benchmarking）；你可以利用mlr3tuning来自动搜索最佳的学习率、隐藏层大小；你可以通过mlr3pipelines将图像增强、特征标准化与神经网络训练连接成一个有向无环图（DAG）。简而言之，mlr3torch让深度学习的实验和管理，变得和其他机器学习模型一样“规范”和“自动化”。

这个框架的价值，尤其体现在需要严谨比较不同模型、进行大规模超参数优化或构建复杂自动化流水线的场景中，例如学术研究、Kaggle竞赛或工业界的模型选型与部署前验证。它降低了在R中进行生产级深度学习开发的门槛，让数据科学家能够更专注于模型架构和业务逻辑，而非繁琐的工程细节。

2. mlr3torch核心架构与设计哲学

2.1 与mlr3生态的深度集成

mlr3torch并非一个孤立的包，它的力量完全来源于与mlr3生态系统的深度集成。理解这一点，是高效使用它的关键。在mlr3中，所有机器学习任务都围绕几个核心抽象展开：任务（Task）、学习器（Learner）、重采样（Resampling） 和基准测试（Benchmark）。

mlr3torch的核心贡献，是提供了一个新的学习器类 LearnerClassifTorch 和 LearnerRegrTorch。这些学习器对象封装了一个torch神经网络模型、其优化器、损失函数以及训练循环。一旦创建，这个学习器对象就与mlr3中任何其他学习器（如classif.rpart决策树）具有完全一致的接口。你可以调用$train()方法在任务上训练它，调用$predict()方法在新数据上进行预测，更重要的是，你可以将它传递给mlr3的所有高阶工作流工具。

例如，进行5折交叉验证，对于纯torch代码，你需要手动分割数据、编写训练循环、管理每折的状态。而在mlr3torch中，这仅仅是两行代码：

library(mlr3)

library(mlr3torch)

# 假设已经有一个分类任务 `task` 和一个mlr3torch学习器 `learner`

resampling = rsmp("cv", folds = 5)

rr = resample(task, learner, resampling)

# rr$aggregate(msr("classif.acc")) 即可得到平均精度

这种设计哲学确保了一致性和可组合性。你的深度学习实验可以轻松地融入现有的、基于mlr3的模型比较和自动化流程中。

2.2 灵活的三级模型定义体系

为了兼顾易用性和灵活性，mlr3torch提供了三种不同抽象层次的模型定义方式，覆盖了从快速原型到完全自定义的各类需求。

第一级：预定义架构（Pre-defined Architectures） 这是最快捷的方式，适用于标准的全连接网络（MLP）处理表格数据。你无需定义任何网络结构，只需通过LearnerClassifTorch或LearnerRegrTorch的param_set来指定隐藏层的大小、激活函数、丢弃率（Dropout）等超参数。框架内部会根据任务的特征维度自动构建输入层和输出层。这种方式非常适合初学者或当你的首要目标是快速验证深度学习在某个表格数据问题上是否有提升。

第二级：转换现有torch模块（Converting torch Modules） 这是平衡便利与控制的绝佳选择。R的torch包及其高阶接口luz已经提供了丰富的预训练模型（如ResNet、BERT）和模块构建块。mlr3torch允许你直接将一个已经定义好的nn_module（来自torch）或一个luz模型，转换成一个mlr3torch学习器。

library(torch)

library(luz)

# 使用luz定义一个简单的神经网络

net <- nn_module(

initialize = function(input_size, hidden_size, output_size) {

self$fc1 <- nn_linear(input_size, hidden_size)

self$fc2 <- nn_linear(hidden_size, output_size)

self$relu <- nn_relu()

forward = function(x) {

x <- self$fc1(x)

x <- self$relu(x)

x <- self$fc2(x)

}

)

# 使用luz进行模型编译（定义损失函数、优化器等）

model <- net %>%

setup(

loss = nn_cross_entropy_loss(),

optimizer = optim_adam,

metrics = list(luz_metric_accuracy())

) %>%

set_hparams(input_size = 10, hidden_size = 50, output_size = 2)

# 关键一步：将luz模型转换为mlr3torch学习器

learner <- as_learner(model)

这种方式让你可以充分利用torch/luz生态中现有的模型和最佳实践，同时享受mlr3工作流管理带来的便利。

第三级：基于图的自定义架构（Graph-based Custom Architectures） 这是最强大、最灵活的方式，尤其适用于研究新型网络结构或多模态学习。mlr3torch引入了一套基于“图”的领域特定语言（DSL），允许你以声明式的方式构建复杂的网络。你不再需要编写nn_module的initialize和forward方法，而是通过管道操作符（%>>%）将各种“细胞”（Cells，即网络层或操作）连接起来。

library(mlr3torch)

graph <- po("torch_ingress_num") %>>% # 数值型数据输入层

po("nn_linear", out_features = 32) %>>%

po("nn_relu") %>>%

po("nn_dropout", p = 0.3) %>>%

po("nn_linear", out_features = 16) %>>%

po("nn_relu") %>>%

po("nn_linear", out_features = 1) %>>%

po("torch_loss", loss = "mse") # 回归任务使用均方误差损失

learner <- as_learner(graph)

这种图式定义的优势在于：

可视化：mlr3pipelines可以自动将图渲染成结构图，直观展示数据流向。
模块化：每个“细胞”都是独立的、可重用的组件。
易于调试：可以轻松地在图的任意位置插入调试或监控节点。
无缝集成预处理：你可以将数据预处理操作（如标准化、PCA）也作为图的一部分，与神经网络层连接在一起，形成一个端到端的可训练流水线。

实操心得：如何选择模型定义方式？ 我的经验是：从预定义架构开始，快速验证想法。 如果效果尚可但需要微调结构，转向转换torch模块，利用luz的灵活性。当你需要设计包含分支、跳跃连接或多输入/多输出的复杂网络时，基于图的定义是你的不二之选。对于大多数从scikit-learn或tidymodels迁移过来的用户，预定义和转换方式已经能覆盖90%的场景。

3. 核心工作流实战：从数据到评估

3.1 任务创建与数据准备

mlr3torch支持两种主要的数据类型：标准的表格数据（data.frame/data.table）和通用的张量（torch_tensor）。对于表格数据，你需要创建一个Task对象，这与使用其他mlr3学习器完全一致。

library(mlr3)

library(mlr3torch)

library(data.table)

# 示例：使用iris数据集创建一个分类任务

data(iris, package = "datasets")

setDT(iris)

task <- as_task_classif(iris, target = "Species", id = "iris_torch")

对于图像、文本等非表格数据，你需要使用TaskClassifTorch或TaskRegrTorch来创建任务。关键是要提供一个返回(input, target)对的dataset函数。input可以是一个张量，也可以是一个包含多个张量的列表（用于多模态输入）。

# 假设我们有一个图像文件路径列表 `image_paths` 和对应的标签 `labels`

create_dataset <- function(image_paths, labels) {

force(image_paths)

force(labels)

function(i) {

# 这里需要实现图像加载和预处理，例如使用magick或torchvision

img <- torchvision::transform_to_tensor(

magick::image_read(image_paths[i]) %>%

magick::image_resize("224x224!")

)

list(x = img, y = torch_tensor(labels[i], dtype = torch_long()))

}

dataset <- create_dataset(image_paths, labels)

task <- TaskClassifTorch$new(

id = "cats_vs_dogs",

dataset = dataset,

n = length(image_paths) # 必须指定样本数量

)

注意事项：数据加载的性能 在深度学习中，数据加载常常是性能瓶颈。上述示例中，每次索引dataset函数时都从磁盘读取图像并转换，效率极低。在生产环境中，你应该：

使用torch::dataset()创建高效的torch数据集，它支持并行数据加载。

考虑将预处理后的数据缓存到内存或高速磁盘（如SSD）。

利用torchvision提供的标准数据集加载器（如image_folder_dataset）。

3.2 学习器配置与超参数调优

创建学习器后，最重要的步骤就是配置其超参数。mlr3torch学习器的超参数集合（$param_set）包含了网络结构、优化器、学习率调度器等所有可调选项。

# 创建一个基于预定义MLP的分类学习器

learner <- lrn("classif.mlp_torch",

# 网络结构参数

layers = 2, # 2个隐藏层

hidden_dim = c(128, 64), # 各层神经元数

activation = "relu",

dropout = 0.2,

# 优化器参数

optimizer = "adam",

lr = 0.001,

# 训练参数

batch_size = 32,

epochs = 50,

device = "cpu" # 或 "cuda"

)

# 查看所有可调参数

learner$param_set

真正的威力在于与mlr3tuning的集成。你可以像调优随机森林的mtry一样，调优神经网络的学习率、层数、神经元数量。

library(mlr3tuning)

library(paradox)

# 1. 定义搜索空间

search_space = ps(

layers = p_int(lower = 1, upper = 3),

hidden_dim = p_fct(levels = c("64", "128,64", "256,128,64")), # 以字符串形式定义复杂结构

lr = p_dbl(lower = 1e-4, upper = 1e-2, logscale = TRUE),

dropout = p_dbl(lower = 0, upper = 0.5)

)

# 2. 选择调优器（例如随机搜索）

tuner = tnr("random_search", batch_size = 20) # 评估20组配置

# 3. 定义重采样策略（例如3折交叉验证）和性能度量

resampling_inner = rsmp("cv", folds = 3)

measure = msr("classif.ce") # 分类错误率

# 4. 创建自动调优器（AutoTuner）

at = AutoTuner$new(

learner = learner,

resampling = resampling_inner,

measure = measure,

search_space = search_space,

tuner = tuner,

terminator = trm("evals", n_evals = 20) # 总共评估20次

)

# 5. 在外层重采样上评估这个自动调优流程

resampling_outer = rsmp("cv", folds = 5)

rr = resample(task, at, resampling_outer)

print(rr$aggregate(msr("classif.ce")))

这个过程自动化了最耗时的部分：寻找一组在验证集上表现良好的超参数。mlr3tuning支持贝叶斯优化（通过mlr3mbo）、网格搜索等多种高级策略。

3.3 训练、预测与回调函数

配置好学习器后，训练和预测是直截了当的：

# 划分训练集和测试集（例如80/20分割）

split = partition(task, ratio = 0.8)

# 在训练集上训练模型

learner$train(task, row_ids = split$train)

# 在测试集上进行预测

prediction = learner$predict(task, row_ids = split$test)

# 查看预测性能

prediction$score(msr("classif.acc"))

mlr3torch通过回调函数（Callbacks） 机制，提供了对训练过程的精细控制。回调函数是在训练循环的特定时间点（如每个epoch开始/结束时、每个batch后）执行的函数，常用于实现早停（Early Stopping）、学习率调度、模型检查点（Checkpointing）和日志记录。

# 创建一个带有早停和模型检查点的学习器

learner_with_callbacks <- lrn("classif.mlp_torch",

epochs = 100,

callbacks = list(

# 早停回调：如果验证损失在10个epoch内没有改善，则停止训练

callback_early_stopping = list(

monitor = "valid_loss",

patience = 10,

mode = "min"

# 模型检查点回调：保存验证损失最低的模型

callback_model_checkpoint = list(

monitor = "valid_loss",

mode = "min",

filepath = "best_model.pt"

# 学习率调度回调：每20个epoch将学习率乘以0.1

callback_reduce_lr_on_plateau = list(

monitor = "valid_loss",

factor = 0.1,

patience = 5,

mode = "min"

)

实操心得：有效使用回调函数

早停是必须的：深度学习模型很容易过拟合。设置一个基于验证集性能的早停回调，可以自动找到最佳的训练轮数，避免浪费计算资源。

善用模型检查点：对于训练时间很长的模型，检查点回调可以保存训练过程中的最佳模型，防止因程序意外中断而前功尽弃。

学习率调度：像reduce_lr_on_plateau或cosine annealing这样的调度器，能帮助模型在训练后期更精细地收敛到局部最优点，通常能带来小幅但稳定的性能提升。

自定义回调：你可以通过继承TorchCallback类来创建自定义回调，用于记录自定义指标、可视化中间激活、或实现复杂的训练逻辑（如对抗训练）。

3.4 与mlr3pipelines构建端到端流水线

mlr3pipelines是mlr3生态中用于构建机器学习流水线的包。mlr3torch与其集成，意味着你可以将数据预处理、特征工程、数据增强和神经网络训练组合成一个单一的可训练对象。

library(mlr3pipelines)

# 构建一个包含特征缩放、PCA降维和神经网络分类的流水线

graph <- po("scale") %>>% # 特征标准化

po("pca", rank. = 10) %>>% # PCA降维至10维

po("learner", learner = lrn("classif.mlp_torch", layers = 1, hidden_dim = 50))

# 将图转换为一个“图学习器”，它可以像普通学习器一样被训练和评估

graph_learner <- as_learner(graph)

# 现在，graph_learner可以在任何Task上训练，它会自动按顺序执行缩放、PCA和神经网络

对于图像任务，流水线的威力更加明显：

# 一个图像分类流水线示例

graph_img <- po("torch_ingress_image", channels = 3, height = 224, width = 224) %>>%

# 数据增强：随机水平翻转和颜色抖动

po("torch_augment_random_horizontal_flip", p = 0.5) %>>%

po("torch_augment_color_jitter", brightness = 0.2, contrast = 0.2) %>>%

# 加载预训练的ResNet并替换分类头

po("torch_pretrained", model_name = "resnet18", freeze_body = TRUE) %>>%

po("nn_linear", out_features = 10) %>>% # 假设是10分类任务

po("torch_loss", loss = "cross_entropy")

graph_learner_img <- as_learner(graph_img)

这种声明式的流水线构建方式，极大地提升了代码的可读性和可维护性，并且确保了从原始数据到最终预测的整个流程是可复现的。

4. 高级应用与性能考量

4.1 应用案例深度解析

案例一：表格数据的神经架构搜索（NAS） 在输入材料提到的第一个案例中，mlr3torch被用于一个表格回归问题的简单神经架构搜索。其核心思路是利用mlr3tuning的自动化能力，不仅搜索学习率、丢弃率等超参数，还将网络层数、每层神经元数也作为搜索空间的一部分。通过定义如 hidden_dim = p_fct(levels = c("64", "128,64", "256,128,64")) 这样的参数，可以探索不同深度和宽度的网络结构。结合贝叶斯优化（tnr("mbo")），可以在有限的评估次数内，智能地探索巨大的架构空间，找到适合特定数据集的高性能网络，这是手动调参难以做到的。

案例二：预训练模型微调（Fine-tuning） 第二个案例展示了如何微调一个预训练的ResNet-18模型进行猫狗分类。mlr3torch通过po("torch_pretrained")管道操作符简化了这一过程。关键步骤和技巧包括：

冻结骨干网络：设置freeze_body = TRUE，在初始训练阶段只训练新添加的分类头，防止预训练好的特征提取器被破坏。
渐进式解冻：在分类头训练几轮后，可以解冻骨干网络的最后几层进行微调。这可以通过自定义回调或分阶段训练来实现。
差分学习率：对骨干网络和分类头使用不同的学习率（骨干网络的学习率通常更小）。这需要更精细的优化器配置，可能涉及自定义优化器组。

案例三：多模态学习 第三个案例演示了如何为多模态问题（例如，同时处理图像和文本）创建神经网络架构。这正是基于图的定义方式大放异彩的地方。你可以创建多个输入入口（po("torch_ingress_image") 和 po("torch_ingress_num")），让不同模态的数据通过各自的特征提取子网络（例如，图像用CNN，文本用LSTM），然后在某个中间层将提取的特征拼接（po("torch_cat")或po("torch_op", "torch_cat")）起来，输入到后续的共同决策层。mlr3pipelines的图语言使得这种复杂架构的定义变得清晰且模块化。

4.2 性能开销与最佳实践

根据原论文的基准测试，mlr3torch相比纯torch实现，会产生一定的运行时开销，但这在大多数情况下是合理的，是为获得统一的、功能丰富的工作流管理所付出的必要代价。这些开销主要来自mlr3框架本身的管理、日志记录、回调函数调度以及为了通用性而进行的额外数据封装。

为了最大化性能，可以遵循以下最佳实践：

批量数据加载：确保你的TaskTorch或数据集能高效地提供批量数据。使用torch原生的dataset和dataloader是基础。
设备管理：明确设置device = "cuda"以利用GPU加速。确保你的CUDA、torch和LibTorch版本兼容。
简化回调：在追求极致训练速度时，评估是否所有回调都是必需的。例如，在超参数搜索的初期，可以禁用模型检查点或减少日志频率。
向量化操作：在自定义网络层或回调中，尽量使用torch的向量化操作，避免在R层面使用循环。
基准测试：对于关键的性能路径，使用microbenchmark包进行小范围基准测试，识别瓶颈。

4.3 常见问题与排查技巧实录

在实际使用mlr3torch时，你可能会遇到一些典型问题。以下是一个速查表：

问题现象	可能原因	排查与解决思路
训练时损失为NaN或无限大	学习率过高；数据未标准化/归一化；网络层输出值域爆炸（如未使用激活函数）。	1. 将学习率降低一个数量级（如从0.01调到0.001）再试。 2. 检查输入数据，确保数值特征已经标准化（均值0，方差1）。对于图像数据，检查像素值是否被正确缩放到[0,1]或[-1,1]。 3. 在网络中添加批归一化层（`po("nn_batch_norm1d")`）有助于稳定训练。
GPU内存溢出（CUDA out of memory）	批次大小（batch_size）过大；模型参数量过大；梯度累积导致内存占用高。	1. 减小`batch_size`。 2. 使用更小的模型或减少隐藏层维度。 3. 检查是否有不必要的张量被长期保存在内存中（例如在回调中）。 4. 对于`torch`，可以使用`torch::cuda_empty_cache()`尝试清理缓存，但这通常是治标不治本。
预测速度非常慢	可能错误地在CPU上进行预测，而模型是在GPU上训练的；批次大小设置为1。	1. 确保预测时学习器的`device`参数与训练时一致，或者使用`learner$predict_newdata(newdata, device = "cuda")`明确指定设备。 2. 在预测时，如果数据量很大，确保是以批次方式进行的。`mlr3torch`内部会处理，但需检查自定义数据加载逻辑。
超参数调优过程卡住或无进展	搜索空间定义不合理（如学习率范围太大）；评估的配置点太少；早停过于激进。	1. 使用对数尺度（`logscale = TRUE`）搜索学习率等参数，范围如`[1e-5, 1e-1]`。 2. 增加随机搜索的迭代次数（`n_evals`）或尝试贝叶斯优化。 3. 调大早停回调的`patience`参数，给模型更多“热身”时间。
无法复现相同结果	未设置随机种子；使用了非确定性的GPU操作；数据加载顺序随机。	1. 在脚本开头使用`set.seed()`设置R的随机种子，并使用`torch::torch_manual_seed()`设置`torch`的种子。 2. 对于GPU，设置`torch::cuda_deterministic()`可以增加确定性，但可能会降低性能。 3. 确保数据加载器（如果自定义）是确定性的，例如关闭`shuffle`或固定随机种子。
与`mlr3pipelines`集成时报错	管道中操作符的数据类型不匹配；`Task`的类型不正确。	1. 仔细检查管道图：每个操作符的输出类型必须与下一个操作符的输入类型兼容。例如，`po("scale")`输出的是`data.table`，不能直接输入给`po("torch_ingress_num")`，后者需要数值矩阵或张量。通常需要在中间插入`po("as_matrix")`或特定的`ingress`操作符。 2. 确保创建了正确类型的`Task`（如`TaskClassifTorch`用于图像）。

独家避坑技巧：调试图式网络 当使用基于图的定义方式构建复杂网络时，如果出现维度不匹配或运行错误，调试可能比较困难。一个非常实用的技巧是使用graph$plot()将计算图可视化出来，检查数据在各节点间的形状（Shape）变化。此外，可以逐段训练图的一部分来隔离问题。例如，先只训练到某个中间层，确保数据能正确流到那里，然后再逐步添加后续层。

5. 扩展与未来展望

mlr3torch的设计强调了可扩展性。你可以通过继承LearnerTorch基类来创建支持新任务类型（如生存分析、多标签分类）的学习器。也可以通过自定义TorchCallback来实现独特的训练逻辑，例如课程学习（Curriculum Learning）、对抗样本训练等。

社区和包作者未来的开发方向可能会集中在：

支持更多任务类型：如文中提到的生存分析、序列预测（时间序列）、图神经网络（GNN）任务。
集成更多预训练模型和架构：随着torchvision和torchaudio等R包的发展，集成更多现成的SOTA模型。
性能优化：进一步减少框架开销，特别是对于小批量和小模型场景。
部署工具链：提供更便捷的模型导出（例如到ONNX格式）和部署选项，打通从实验到生产的最后一公里。

从我个人的使用体验来看，mlr3torch成功地将R语言深度学习的体验从“脚本堆砌”提升到了“工程化工作流”的层面。它可能不是执行单个神经网络训练最快的工具，但它绝对是管理数十个深度学习实验、进行严谨的模型比较和构建可复现流水线的最佳选择之一。对于已经熟悉mlr3生态的团队和个人，引入mlr3torch能显著提升深度学习项目的开发效率和结果可靠性。它的学习曲线主要在于理解mlr3的核心概念和torch的基本张量操作，一旦掌握，你将获得一个极其强大且统一的机器学习武器库。