企业官网建设流程全解析

AutoGluon MultiModalPredictor 征战 Kaggle Petfinder Pawpularity：从多模态训练到无网 Kernel 部署的完整实战

【免费下载链接】autogluonFast and Accurate ML in 3 Lines of Code项目地址: https://gitcode.com/GitHub_Trending/au/autogluon

本文以 Kaggle 的 Petfinder Pawpularity 竞赛为完整案例，系统讲解如何用 AutoGluon 的MultiModalPredictor完成一次"图像回归 + 无网环境部署"的端到端竞赛实战：从构建预测器、配置训练超参数、5 折交叉验证，到保存 standalone 模型、把 AutoGluon 与依赖打包进 Kaggle Dataset、最终在 Kernel-only 比赛中离线加载模型并生成集成预测。读完本文，你将掌握 MultiModalPredictor 的核心 API 用法、五大类超参数配置的作用，以及一套可复用的"本地训练 → 离线部署 → 竞赛提交"完整方案。

1. 竞赛背景：预测宠物照片的受欢迎程度

Petfinder Pawpularity 是 Kaggle 上的一项图像回归竞赛：给定一张宠物照片，模型需要预测其"受欢迎程度"（Pawpularity 分数，范围 0–100）。数据集中每张图片配有一组二值化元数据（如是否戴帽子、是否模糊、是否有第二只宠物等），评估指标为RMSE（Root Mean Squared Error），分数越低越好。

该案例的典型意义在于：它同时覆盖了多模态学习的两个核心问题——图片特征与表格元数据的自动融合，以及竞赛环境的离线部署（Kaggle Kernel-only 比赛无法访问外网下载预训练权重）。AutoGluon 的MultiModalPredictor正好同时提供了多模态融合能力与 standalone 离线保存机制，因此非常适合作为演示对象。

仓库中与本案例配套的完整代码位于 examples/automm/kaggle_pawpularity，包括训练脚本 kaggle_pawpularity_train.py 与提交脚本 kaggle_pawpularity_submit.py，下文所有代码均可与源码逐行对应。

2. 用 MultiModalPredictor 完成训练

MultiModalPredictor是 AutoGluon 中面向多模态数据的统一预测工具，可以同时处理图像、文本、数值和类别数据。它会自动识别各列的数据类型，并为每种模态挑选合适的预训练深度学习骨干网络（backbone），再通过融合层把各模态的特征拼接起来。使用者只需少量代码即可完成从数据加载到模型训练的整个过程。

2.1 构建 MultiModalPredictor

训练的第一步是实例化预测器，关键参数如下：

predictor = MultiModalPredictor( label="Pawpularity", # 训练数据中的目标列名 problem_type="regression", # 问题类型："multiclass" / "binary" / "regression" eval_metric="rmse", # 评估指标，通常直接对齐竞赛评判标准 path=save_path, # 模型保存路径 verbosity=4, # 控制打印信息的详细程度（0–4） )

各参数含义：

• label：指定训练数据中作为预测目标（标签）的列名，本案例中为"Pawpularity"；
• problem_type：问题类型，可取"multiclass"（多分类）、"binary"（二分类）或"regression"（回归）。本案例为连续值回归；
• eval_metric：模型评估指标，竞赛中通常直接使用官方评估指标，这里为"rmse"；
• path：保存 MultiModalPredictor 模型文件的目录；
• verbosity：控制打印信息的详细程度，4 表示输出最详细日志，便于调试与观察训练过程。

2.2 调用 fit() 训练模型

构建预测器后，调用.fit()即可开始训练：

predictor.fit( train_data=training_df, tuning_data=valid_df, save_path=save_path, hyperparameters={ "model.names": "['timm_image']", "model.timm_image.checkpoint_name": "swin_large_patch4_window7_224", "model.timm_image.train_transforms": "['resize_shorter_side','center_crop','randaug']", "data.categorical.convert_to_text": "False", "env.per_gpu_batch_size": "16", "env.per_gpu_batch_size_evaluation": "32", "env.precision": "32", "optim.lr": "2e-5", "optim.weight_decay": "0", "optim.lr_decay": "1", "optim.max_epochs": "5", "optim.warmup_steps": "0", "optim.loss_func": "bcewithlogitsloss", }, seed=1, )

参数说明：

• train_data：用于训练的数据（DataFrame 或文件路径）；
• tuning_data：用于验证的数据。若为空，AutoGluon 会自动从训练数据中划分出验证集；
• save_path：本次 fit 过程中模型的保存目录；
• hyperparameters：一个字典，用于覆盖默认配置。配置按前缀分为model、data、env、optim（以及proc）五类，点号分层寻址；
• seed：随机种子，保证实验可复现。

hyperparameters 的五大配置域

结合源码理解关键配置项的默认值与作用

在仓库中，上述每个配置域都有对应的默认配置文件，理解默认值有助于判断"该不该覆盖"：

• model.timm_image：timm 图像骨干网络的配置，见 configs/model/default.yaml。默认checkpoint_name为"swin_base_patch4_window7_224"，默认train_transforms为["resize_shorter_side", "center_crop", "trivial_augment"]。本案例改用更大的swin_large_patch4_window7_224，并把数据增强换成更强的randaug（RandAugment），以提升泛化能力。resize_shorter_side表示将图片短边缩放到固定尺寸、center_crop表示中心裁剪，两者配合可把不同长宽比的图片统一为模型输入尺寸；
• model.names：显式指定使用的模型列表。当需要同时建模图像与表格（元数据）并开启融合时，可置为None（由 AutoGluon 自动选择）；当只想用纯图像模型时，置为"['timm_image']"。这一开关正是下文"融合 vs 纯图像"对比实验的关键（见 kaggle_pawpularity_train.py 中的fusion参数逻辑）；
• data.categorical.convert_to_text：是否把类别特征转换为文本描述再送入文本骨干。默认配置见 configs/data/default.yaml，该域还包含minimum_cat_count（最少出现次数，避免把出现过少的类别当作稀有类别）、maximum_num_cat、convert_to_text_template（"direct"/"list"/"text"/"latex"）等细节参数；
• env.per_gpu_batch_size：单 GPU 训练批大小。默认值为 8（见 configs/env/default.yaml），大 batch 有助于稳定训练，但受显存限制；env.per_gpu_batch_size_evaluation为评估（验证/预测）时的批大小，可以设置得比训练更大；
• env.precision：训练精度，默认是"16-mixed"（混合精度）。本案例显式设为"32"（全精度），在推理/提交阶段精度设置需与训练保持一致，避免数值漂移；
• optim.lr：初始学习率，默认1e-4（见 configs/optim/default.yaml）。微调大模型（如 Swin-Large、ViT-Large）时通常降到2e-5～5e-5量级；
• optim.weight_decay：权重衰减，默认0.001，本案例设为0；
• optim.lr_decay：层间学习率衰减系数（layerwise decay）。默认0.9，本案例设为1表示各层学习率一致，不做逐层衰减；
• optim.max_epochs：最大训练轮数，默认20，本案例设为5（大模型在竞赛数据上少量微调即可，避免过拟合）；
• optim.warmup_steps：学习率 warm-up 步数，默认0.1（表示按 epoch 比例），本案例设为0；
• optim.loss_func：损失函数。默认值为"auto"（按问题类型自动选择，回归默认走torch.nn中的对应损失）；本案例指定"bcewithlogitsloss"（BCEWithLogitsLoss）——对 Pawpularity 这类 0–100 离散打分任务，把标签归一化到 0–1 后按二分类损失回归往往效果更好。

在 predictor.py 的fit()源码中可以看到，hyperparameters支持字典、字符串、字符串列表三种写法，例如字符串形式"model.hf_text.checkpoint_name=google/electra-small-discriminator model.timm_image.checkpoint_name=swin_small_patch4_window7_224"，适合在命令行或脚本中直接传参。

2.3 用 5 折交叉验证训练多套模型

竞赛实战中通常不会只训一个模型。仓库配套的训练脚本 kaggle_pawpularity_train.py 展示了完整的 5 折流程：

1. 读取数据并构造图片路径：把train.csv中的Id列重命名为"Image Path"，拼接成train/{Id}.jpg的绝对路径，MultiModalPredictor 会自动识别该列为图像路径；
2. 分层分折：由于 Pawpularity 是连续值，脚本先用pd.cut按目标值分箱（num_bins = ceil(2 * len ** (1/3))），再对分箱结果执行StratifiedKFold(n_splits=5, shuffle=True)，保证每折的标签分布与全量数据一致；
3. 逐折训练：第i折中，其余 4 折作为training_df，第i折作为valid_df，调用predictor.fit(..., save_path=save_path + f"_fold{i}", seed=args.seed)；
4. 逐折验证：用predictor.predict(data=valid_df)得到预测值，与真实标签计算root_mean_squared_error，打印Fold {i} | Score: ...；
5. 逐折保存 standalone 模型：验证通过后调用predictor.save(path=save_standalone_path + f"_fold{i}", standalone=True)，最后汇总打印all-scores与mean_rmse；
6. 释放显存：每折结束后del predictor并调用torch.cuda.empty_cache()，避免多折训练叠加导致 OOM。

脚本把几乎所有超参数（backbone、学习率、批大小、epochs、warmup、loss、折数、种子等）都暴露为命令行参数（argparse），方便批量跑实验、对比不同配置，例如：

python kaggle_pawpularity_train.py \ --data_path ./data/ \ --timm_image_checkpoint_name swin_large_patch4_window7_224 \ --fusion False \ --lr 2e-5 --max_epochs 5 --per_gpu_batch_size 16 --folds 5

其中--fusion参数决定了model.names的取值：融合模式置为None（自动选模型），纯图像模式置为"['timm_image']"，同时保存路径会自动带上fusion或timm_only标识，便于区分实验结果。

3. 保存 Standalone 模型：为离线部署做准备

训练过程中，MultiModalPredictor 会从网络下载预训练权重（例如swin_large_patch4_window7_224对应的 timm 权重）。如果直接保存普通模型，推理时一旦联网失败（或网络被禁用）就无法加载。因此需要在训练后保存"standalone"（独立可离线加载）模型：

predictor.save(path=save_standalone_path, standalone=True)

从 predictor.py 的源码可以看到standalone参数的具体行为：

• standalone=True时，把训练中下载的transformers.CLIPModel、transformers.AutoModel等预训练权重原样保存到os.path.join(path, model_name)，并把配置文件config.yaml中对应的checkpoint_name重置为以local://开头的本地路径。这样加载时模型会直接从本地读取权重，不再访问网络；
• standalone=False时，保存的产物在load()时可能仍需要联网环境处理。

在 kaggle_pawpularity_train.py 中，standalone 路径通过save_path + "_standalone"派生，逐折保存为{save_standalone_path}_fold{i}，即每个 fold 一套独立可离线加载的模型。

4. Kaggle Kernel-only 竞赛的无网部署方案

Kaggle 的代码竞赛（Kernel Competition）在提交阶段无法通过外网获取任何资源——既不能pip installAutoGluon，也不能下载预训练权重。解决这个问题有两个关键点：

1. 通过 Kaggle Dataset 引入 AutoGluon 及其依赖库（解决"库装不上"）；
2. 使用 standalone 模型避免权重下载（解决"模型下不到"）。

4.1 把 AutoGluon 打包为 Kaggle Dataset

• 本地安装 AutoGluon 后，在 Kaggle 上创建一个名为autogluon的新 Dataset；
• 找到本地 AutoGluon 的安装路径，把整个安装目录上传进该 Dataset；
• 在提交 Notebook 中通过下面的代码把 Dataset 路径加入sys.path，即可在不联网的情况下导入 AutoGluon：

import sys sys.path.append("../input/autogluon/")

4.2 手动引入 AutoGluon 的依赖库

AutoGluon 本身还依赖一些 Kaggle 环境未预装的第三方库，需要以同样的方式（打包成 Dataset）引入。当前文档明确列出的依赖库有：

• typish
• timm
• omegaconf
• antlr4
• nlpaug

配套的 kaggle_pawpularity_submit.py 给出了更稳妥的做法：运行一个"获取 standalone"的 Kaggle Notebook（get-autogluon-standalone），它会把所有缺失依赖打包为.whl或.tar.gz文件并收集到autogluon_standalone文件夹中；下载该文件夹的 zip 后作为 Dataset 上传（例如命名为autogluon-standalone-install）。然后在提交 Notebook 中离线安装：

import sys sys.path.append('../input/autogluon-standalone-install/autogluon_standalone/antlr4-python3-runtime-4.8/antlr4-python3-runtime-4.8/src/') !pip install --no-deps --no-index --quiet ../input/autogluon-standalone-install/autogluon_standalone/*.whl --find-links autogluon_standalone

命令中--no-deps --no-index表示不联网解析依赖、不从 PyPI 拉取，只安装本地.whl；第一行sys.path.append是提前把antlr4运行时源码目录加入路径，因为部分场景下 antlr4 依赖以源码形式提供。安装完成后即可正常from autogluon.multimodal import MultiModalPredictor。

5. 在 Kaggle 中加载模型并生成预测

5.1 加载 standalone 模型

把第 3 节保存的 standalone 模型文件夹作为 Dataset 上传到 Kaggle，并挂载为输入数据源，然后加载：

pretrained_model = predictor.load(path=save_standalone_path)

load()是MultiModalPredictor的类方法（见 predictor.py），支持resume=False/True（中断后从last.ckpt恢复）以及verbosity参数。源码同时给出了安全警告：load()内部使用pickle，切勿加载来源不可信的模型文件。

5.2 批量预测与多折平均

加载后直接调用.predict()即可对测试集推理：

test_pred = pretrained_model.predict(test_df)

提交脚本 kaggle_pawpularity_submit.py 展示了完整的多折推理 + 模型集成逻辑：

1. 为每个结果配置（config_6、config_7、config_26等）读取对应的save_path与per_gpu_batch_size_evaluation；
2. 对每个 fold 依次MultiModalPredictor(...)→predictor.load(path=save_standalone_path + f'_fold{fold}/')→ 覆盖推理批大小pretrained_model._config.env.per_gpu_batch_size_evaluation = ...→pretrained_model.predict(test_df)；
3. 同一模型 5 折的预测取平均（np.mean(np.stack(all_preds), axis=0)），得到该模型对测试集的最终预测；
4. 多个模型按权重集成，写入submission.csv：

submission["Pawpularity"] = model_preds[0] * 0.25 + model_preds[1] * 0.5 + model_preds[2] * 0.25 submission.to_csv("submission.csv", index=False)

其中每次推理前后同样执行torch.cuda.empty_cache()释放显存，避免连续加载多个大模型时内存耗尽。

6. 实验结果：融合、数据增强与集成的收益

文档记录了多组实验的完整结果，以下表格列出了各配置在Public Leaderboard（公开榜）与Private Leaderboard（私有榜）上的 RMSE 成绩（数值越小越好），以及对应的 backbone、融合开关、数据增强、优化器参数等完整实验配置：

从表中可以观察到几点规律：

• 融合（Fusion）通常带来更好的成绩：同一 backbone（如swin_large_patch4_window7_224）在开启融合后，本地 CV 从 17.519 提升到 17.485；vit_large_patch16_384融合后的 CV 是 6 组实验中最优的 17.374。这说明把图片特征与表格元数据（二值化标签）融合，确实能提供额外的预测信号；
• 数据增强（randaug）是标配：所有实验都使用randaug，说明对这类真实图片竞赛，强增强是稳定有效的策略；
• 大模型 backbone 占优：成绩靠前的配置集中在vit_large、swin_large、convnext_large这类 large 级别骨干上。

6.1 融合 vs 纯图像（Image-only）的消融对比

为验证融合收益，文档进一步给出了多种 backbone 在"开启融合"与"纯图像"两种模式下的 CV 对比：

整体来看，融合模式在多数 backbone 上优于纯图像模式。值得注意的是，这一结论与单个超参数（如学习率、epochs）的配置耦合——例如上表中convnext_large_384_in22ft1k的 Image-only 配置反而略优，说明融合收益需要通过控制变量的实验来验证。而 MultiModalPredictor 的易用性正在于此：开启或关闭融合只需修改model.names超参数（或fusion命令行开关），完全不需要改动代码，方便大规模消融。

6.2 多模型集成进一步压低 RMSE

把多个 fold 平均后的模型预测再做加权集成，可以进一步压低私有榜分数。文档记录的集成实验结果如下：

可以看到，模型集成把Private Leaderboard 的 RMSE 从单模型最优的约 17.1 进一步压到 16.98 左右，这也是竞赛中稳定提升排名的经典手段。集成在提交脚本中体现为对不同模型的预测向量做加权求和（如0.25 / 0.5 / 0.25的权重分配），完全可以在 Kaggle Notebook 中离线完成。

7. 全流程总结与可复用清单

回顾整个案例，一次完整的"AutoGluon 多模态竞赛"流程可以归纳为六个步骤：

1. 数据准备：构造train.csv/test.csv，把图片Id映射为本地图片路径列，并对连续标签分箱后做StratifiedKFold分层分折；
2. 构建与训练：MultiModalPredictor(label=..., problem_type="regression", eval_metric="rmse", path=..., verbosity=4)，通过hyperparameters覆盖model/data/env/optim四类配置（backbone、增强、批大小、精度、学习率、epochs、损失函数），按 fold 逐折fit()；
3. 逐折验证：用predictor.predict()在验证集上手动计算 RMSE，作为本地模型质量评估；
4. 保存 standalone 模型：predictor.save(path=..., standalone=True)，把下载的预训练权重固化到本地并改写为local://路径，确保离线可用；
5. 无网部署：把 AutoGluon 安装目录与依赖（typish、timm、omegaconf、antlr4、nlpaug）打包为 Kaggle Dataset，通过sys.path.append与pip install --no-deps --no-index离线安装，standalone 模型同样以 Dataset 形式挂载；
6. 推理与集成：predictor.load()逐折加载模型 →.predict()生成测试集预测 → 多折平均 → 多模型加权集成 → 写出submission.csv提交。

这套方案的每一步都在仓库中留有可运行、可对照的代码：训练侧见 kaggle_pawpularity_train.py，提交侧见 kaggle_pawpularity_submit.py，API 行为与默认配置可进一步阅读 predictor.py 及 configs 下的model、data、env、optim默认配置。读者只需把label、数据列与路径替换为自己的竞赛数据，即可将同一套方法复用到其他图像、文本或多模态竞赛中。

【免费下载链接】autogluonFast and Accurate ML in 3 Lines of Code项目地址: https://gitcode.com/GitHub_Trending/au/autogluon