MMRec 多模态推荐工具箱：数据预处理、特征编码与模型训练实战

简介：MMRec多模态推荐工具箱是一套面向推荐系统开发者和研究人员的完整资源，旨在简化多模态推荐模型的构建与复现。压缩包内共含59个文件，主要由29个Python脚本（负责模型定义、训练与评估）、18个YAML配置（管理实验参数）、4个Jupyter Notebook（覆盖数据切分、特征编码与预处理流程）构成，另有3个Markdown说明文档、PDF报告及图表等辅助材料，整体仅446KB，便于快速部署和二次开发。工具箱集成了协同过滤、矩阵分解以及MTransE、CDAE、MMoE等10余种先进模型，既有经典的SVD、PMF等算法，也有基于神经网络的深度模型，覆盖从传统方法到深度学习的完整技术路线；同时支持Yelp、Amazon等公开数据集，可直接开展基准测试与对比实验。实验模板与分步Notebook使得数据加载、模型训练、结果评估一目了然，并能通过简单API快速导入模型、扩展自定义算法，显著降低多模态推荐的研究门槛。目前已有267人浏览学习，适合需要快速上手多模态推荐研究或进行算法对比实验的中高级开发者。

1. 多模态推荐模型不是把文本和图片拼在一起：MMRec 给出一套可复现范式

做推荐系统的人应该都有这种体会：换一个模型框架，数据处理就得从头再来一遍。多模态推荐更是重灾区，文本、图像、属性特征各自处理完了，到融合阶段才发现 ID 对不上、维度对不齐、负采样口径不一致。我第一次接触 MMRec 这个多模态推荐工具箱时，最大的感受是它终于把"多模态推荐"这件事拆成了标准件——10 多个模型共享同一套数据流水线，从原始评分到交互序列、再到多模态特征编码，每一步都有独立的 Notebook 可以单独检查。它不挑模型，也不绑架你的实验习惯，适合研究人员做基线对比，也适合工程同学在项目里快速验证一个新 idea 值不值得深入。

2. 项目结构与配置体系：从目录布局到跑通第一个模型

2.1 先从目录下手：data 和 preprocessing 为什么拆开

拿到 MMRec 之后，别急着读代码，先花十分钟把目录过一遍。我一般会先在项目根目录跑一条 tree 命令，把结构落下来：

tree -L 2 -I "__pycache__|*.pyc"

这一步不是让你把结构背下来，而是搞清楚一份数据从头到尾要经过哪些处理器。核心目录是src，里面五个子目录分工很明确：configs放实验配置，utils放公共工具，common放跨模型复用的组件，models放各推荐模型实现，data放数据处理逻辑。preprocessing放在src之外，是因为它本身是"一次性加工"——你只需要在换数据集的时候跑一遍，不用跟着每次训练重复执行。

提示：MMRec 把"数据预处理"和"模型训练"拆成两个独立阶段，这是贯穿整个工具箱的设计主线。后面所有 Notebook 和脚本都遵循这条主线。

这样做还有个隐藏好处：你的实验记录里"数据版本"是清晰的。我之前接手过不少推荐项目，翻车现场几乎都发生在读取数据的函数里偷偷改了特征逻辑，结果换了台机器结果对不上。MMRec 这样拆，至少把"数据处理"和"模型训练"的耦合压到了最低。你改模型的时候不需要担心把数据管道改坏，反过来也一样。

images目录里放了两个 logo 文件，那是文档用的，不用管。根目录的README.md写得比较简略，真正的操作说明其实分散在 preprocessing 下的几个 Notebook 里，所以别指望只读 README 就能跑起来，后面的章节我会逐个拆开讲。

2.2 三大配置：数据、模型、训练

再来看configs目录。MMRec 每个模型的配置基本可以拆成三个块：数据块、模型块、训练块。拿一个典型配置举例：

# configs 下实际文件的字段名以仓库为准，这里展示核心结构 data: dataset: "amazon" data_path: "data/amazon/inter" reindex: True model: name: "MTransE" embed_dim: 64 margin: 1.0 feat_hidden: 128 train: batch_size: 1024 epochs: 50 lr: 0.001 eval_epochs: 5

这段配置的核心逻辑不是某个参数的具体数值，而是"模型相关参数必须跟着模型走"。embed_dim和margin是 MTransE 这类翻译嵌入模型特有的超参，你改模型的时候必须把整套模型参数一起换掉，而不是只替换name字段就指望能跑。我在 2.1 里说 data 和 preprocessing 要分开，这里同理——模型配置和训练配置分开，你调学习率的时候就不会误伤模型结构。

按模型分文件的做法还有个明显优点：实验复现成本低。跑之前把configs目录打一个 tar 包，实验结束之后再把结果放进去，就是一份完整的实验记录。我自己的习惯是每个实验单独建一个配置快照目录，跑基线、跑新模型、跑消融实验都用这份快照，防止后改的配置污染之前的结果。不要小看这个习惯，等你要写论文或者向领导汇报对比数据的时候，能省下大量排查时间。

common和utils这两个目录我是放在一起看的。common里通常是跨模型复用的组件，比如批次采样器、评估函数；utils里则是一些更基础的工具函数。你新写模型的时候八成会用到这两个目录里的现成组件，所以先花半小时翻一翻里面有哪些函数，比直接抄别的模型代码来得快。

2.3 数据格式：先把 rating 变成 interaction 再说其他

MMRec 里所有模型不管多模态不多模态，起点都是一份标准的 interaction 数据。原始 rating 文件长这样：user_id, item_id, rating, timestamp，但推荐模型训练时需要的往往是user_id, item_id, time，或者加上行为类型。preprocessing/0rating2inter.ipynb就是干这件事的，把原始打分表过滤、转成统一的交互序列格式。

这一步最常见的问题是：rating 文件里同一对(user, item)出现多次怎么办。常见做法是取时间戳最新的一条，或者按场景取均值。MMRec 的 Notebook 里一般会按排序去重，也就是同一用户对同一物品的多次行为只保留最近一次。我建议你在跑完之后看一眼inter输出文件的行数，如果和原始 rating 差太多，说明去重逻辑或者过滤逻辑比你预期的激进，这时候不要硬着头皮往下走。

另外，inter 文件一般还会有最小交互数过滤，比如把交互次数少于 5 的用户直接删掉。这个阈值直接决定你训练集的数据量。阈值设太高，用户稀疏度上来了但样本数骤减；设太低，冷启动用户过多，模型会学偏。我的做法是先看数据集的交互分布直方图再定阈值，而不是随便填一个数。

2.4 跑通第一个模型的三个信号

配置和数据都准备好了，怎么判断自己已经跑通了？不要只看终端有没有报错，我一般看三个信号：

• 训练 loss 在下降，且不是断崖式下降到 NaN。
• 验证集指标（Recall、NDCG 之类）随 epoch 有规律地波动或上升。
• reports目录里生成了可阅读的评估报告，哪怕是简单表格。

如果三个信号都满足，说明你的环境、数据、配置三者已经对齐。接下来才谈得上调参和换模型。如果你卡在某一步，优先检查src/data里的读取逻辑有没有拿到预期的文件，再看configs里data_path指得对不对。这一步我踩过坑，后面避坑章节会专门讲。

3. 多模态预处理的三个关键 Notebook：划分、重索引与特征编码

3.1 1splitting：按时间划分还是按用户划分

预处理目录里的编号顺序是有讲究的。1splitting.ipynb排在最前面，因为你得先把数据切开，才能谈后面的索引和特征。这个 Notebook 做的事可以理解为：把完整交互序列切分成训练集、验证集、测试集。看似简单，但划分策略直接决定你实验结论的可信度。

最常见的划分方式是按时间切：以某个时间点为界，之前的交互进训练集，之后的进测试集。这种方式模拟的是真实线上场景——用历史预测未来，所以推荐系统论文里用的最多。另一种方式是随机按用户比例切，比如每个用户取 80% 交互做训练，20% 做测试。这种切法能保证测试集里每个用户都有足够行为，适合分析用户级冷启动或者做 user-wise 的实验。

MMRec 的 splitting Notebook 里一般会允许你在两种策略里选，具体取哪种取决于你的业务场景。我的建议是：如果数据集本身带时间戳且时间跨度足够，优先按时间切；如果要做用户分组对比，再考虑比例切。切完之后，训练集、验证集、测试集的用户和物品集合会有差异，后面重索引环节需要格外小心——如果你在切分之前就做了索引，切分后新旧 ID 会打架，这是个非常大的雷区。

3.2 2reindex-feat：重索引的 ID 对齐问题

2reindex-feat.ipynb这个名字里有两个关键词：reindex和feat。重索引的核心目标只有一个——让所有用户、物品、特征都使用连续的整数 ID，且保证全流程映射一致。

我举个例子你就懂坑在哪了。假设原始数据里用户 ID 是字符串"u_1024"，物品 ID 是"book_42"，这两个 ID 本来互不相干。如果不做统一重索引，模型 embedding 查表的时候就得用字符串哈希，一是不连续导致表很大，二是哈希碰撞直接静默出错。重索引就是给每个用户和每个物品分配一个从 0 开始的连续编号，同时生成一份映射表：

# 重索引伪代码：把字符串 ID 映射为连续整数 user_map = {} item_map = {} next_uid = 0 next_iid = 0 for user_id, item_id in interactions: if user_id not in user_map: user_map[user_id] = next_uid next_uid += 1 if item_id not in item_map: item_map[item_id] = next_iid next_iid += 1

这段代码的逻辑就是从 0 开始递增分配 ID，一个字符串用户 ID 只对应一个整数。user_map和item_map两个字典务必保留好，后续所有特征文件、预测结果都要靠这两个映射传回原始 ID，否则你输出一个整数列表谁也看不懂。

这里最容易翻车的点是特征文件的对齐。图像特征、文本特征通常以原始 ID 或文件名作为主键，重索引之后你必须把特征文件的主键也统一成新的整数 ID。如果特征文件里用的还是旧 ID，模型读到特征之后就是错位匹配——用户 A 的特征跑到用户 B 头上去了。验证方法很简单：训练结束后抽几个样本，把预测结果映射回原始 ID，人工核对一下是不是合理的推荐结果。

3.3 3feat-encoder：多模态特征编码的对齐逻辑

到了3feat-encoder.ipynb，就进入多模态推荐最核心的部分——特征编码。这一步把原始图像像素、文本词序列等非结构化数据，转换成模型可以直接消费的稠密向量。常见做法是用预训练模型抽取特征，图像用 CNN 或 ViT 的倒数第二层输出，文本用 BERT 的[CLS]向量，得到一个固定维度的特征向量。

MMRec 的特征编码 Notebook 里一般会规定每个模态的输出维度。比如图像特征切成 512 维，文本特征切成 512 维，属性特征继续拼在后面。这个维度不需要你自己拍脑袋定，编码脚本里通常写好了默认值，你只需要保证所有模态编码完之后的拼接维度与模型输入层一致就行。

这里还有个细节容易被忽略：模态缺失问题。现实场景里，并不是每个物品都有图像或文本描述。如果你的数据里有 10% 的物品没有图像特征，编码阶段怎么办？常规做法是生成一个全零向量或者可学习的占位向量。如果处理不当，训练时会出现 NaN，因为 gradient 传到一个全零的 embedding 上有时会产生异常值。我的做法是：先用一个二进制 mask 标记哪些样本有真实特征，模型 forward 的时候对缺失模态单独处理，而不是简单粗暴地填零。

做完3feat-encoder，你的数据流水线就完整了。从原始 rating 到 interaction，再到划分、重索引、特征编码，每一步产物都是下一阶段的输入。这章结束之后，你的preprocessing目录下应该有一份inter文件、一份feat文件、一份重索引映射表。

4. 模型训练与结果输出：从 train.py 到评估报告

4.1 训练入口：main.py 到 train.py 的调用链

预处理跑完之后才轮到模型训练。MMRec 的训练入口在src/main.py，它做的事情本质上可以压缩成三步：加载配置、实例化模型、调train.py跑训练循环。你直接用命令行开启训练就可以了：

python src/main.py --config configs/mtranse.yaml

运行之后，main.py会读取配置里的model.name字段，然后去models目录找到对应的模型类，传入数据路径和训练参数开始训练。如果你只改了配置没改代码，训练流程本身的代码路径是不需要动的。

这里我要强调一个经验：第一次跑的时候，建议不要直接上完整数据集。我一般先在配置里把epochs调小到 5、batch_size调大到 2048，确认代码链路没问题，再恢复正常参数。这个"冒烟测试"习惯能帮你把环境问题和模型问题分开排查，不然第一次训练崩了你都分不清是配置写错还是环境缺库。

train.py内部其实没什么玄学，就是标准的训练循环：前向传播、算 loss、反向传播、更新参数。但如果你打开train.py想改训练逻辑，要注意它同时负责验证和 checkpoint 保存。保存逻辑一般是按验证集指标来的，比如每隔eval_epochs个 epoch 评估一次，指标变好才保存一次模型。这意味着你训练完看到的"最佳模型"未必是最后一个 epoch 的模型，所以评估时要用保存下来的 checkpoint，不要直接用当前权重。

4.2 各类模型的配置差别：从协同过滤到多模态深度模型

MMRec 的核心价值在于同一个框架里塞了 10 多个模型。我从实现上把它们归成三类，配置差异主要在这三类之间，类别内部基本共用一套训练逻辑。

第一类是传统协同过滤和矩阵分解，比如基于用户的协同过滤、基于物品的协同过滤、SVD 类模型。这类模型没有复杂的特征融合逻辑，输入只有 user 和 item 两个 ID，配置里通常只需要embed_dim一个关键参数。它们适合做基线，跑得快，几分钟就能出结果。复杂度不在模型本身，而在负采样——你没有负样本标签，得从没交互过的物品里采样一批当负样本，采样比例直接决定模型表现。

第二类是深度协同过滤模型，比如 CDAE 这类去噪自编码器。它们开始引入辅助信息，但要小心别和标准的自编码器搞混。CDAE 是在用户交互序列上加噪声再重构，意在捕捉交互的隐式信号。这类的配置里会多出noise_ratio之类的参数，用来控制加噪强度。

第三类才是真正的多模态模型，比如 MTransE、MMoE。它们把物品的图像特征、文本特征拼进来，通过翻译嵌入或门控机制做融合。MTransE 的思路是把用户和物品映射到同一嵌入空间，再通过模态特征进行 "翻译"；MMoE 则用多个专家网络处理不同模态，然后用门控网络做加权融合。这类模型的配置里会出现feat_hidden、margin、num_experts、gate_hidden等参数：

# MMoE 风格配置片段：门控网络的专家数量 model: name: "MMoE" embed_dim: 64 num_experts: 8 expert_hidden: [128, 64] gate_hidden: [32] feat_dim: 1024

num_experts是 MMoE 的关键参数，控制模态门控路由的专家数量。设太少了每个专家要承担过多模态依赖，设太多又容易过拟合。我一般先从 8 开始，效果不理想再往 16 调。这个参数直接决定显存占用，后面避坑章节会提到。

下面用一张表总结这三类模型的选型参考：

4.3 评估指标与报告导出：reports 目录里到底有什么

训练结束之后，结果会落到reports目录。MMRec 在顶层报告里用 PDF 汇总实验结论，src里也有对应的评估脚本。你真正要关心的评估指标一般就那几个：Recall@K、NDCG@K、Precision@K。多模态推荐论文里最常用的是 Recall@20 和 NDCG@20，因为这两个指标能反映"排序质量"和"召回覆盖面"。

评估报告的思路是把你预测的 Top-K 物品和测试集里的真实交互做对比。这里有一个关键细节必须提醒你：评估时的负样本集合怎么定义。有的实现是在全量物品里排序，有的实现是随机采样 999 个物品当负样本再排序。这两种做法算出来的指标数值没有可比性。你在对比 MMRec 内部模型之间的指标没问题，但如果要和你自己之前的结果比，必须先对齐负采样口径，不然数字看起来天差地别。

reports目录里那份MMRec-reports.pdf是作者跑完所有模型后的汇总结果，你可以拿它当参照系。不过我的建议是不要盲目相信 PDF 里的绝对数值，因为你用的数据集划分方式、特征编码版本可能与作者不完全一致。正确用法是：先复现 PDF 里的某个模型结果，对上了，再以此为准跑其他模型对比。

5. 实战避坑：MMRec 跑多模态数据时的四个高频翻车点

5.1 维度不匹配：forward 进去的向量形状对不上

现象：训练刚开始，torch或者numpy直接抛维度错误，常见报错是shape mismatch或者mat1 and mat2 shapes cannot be multiplied。

原因：八成出在特征拼接这一步。文本特征编码出来是[batch_size, 512]，图像特征编码出来是[batch_size, 768]，你在配置里写feat_dim=1024，但实际拼接后是 1280。等于告诉模型输入是 1024 维，实际喂进去 1280 维，第一层线性层就崩了。

解决：训练前先写一行脚本打印拼接后的特征维度，确认与你配置里的feat_dim一致。我一般会在train.py的第一次迭代时加断言检查：

assert fused_feat.size(-1) == model.feat_dim, \ f"feature dim mismatch: {fused_feat.size(-1)} vs {model.feat_dim}"

5.2 预训练特征和重索引 ID 对不上

现象：loss 能下降，但验证集指标一直很低，甚至不如随机猜测，检查数据时发现推荐出的物品完全是乱的。

原因：3feat-encoder输出的特征文件还是用原始 ID 作行索引，而2reindex-feat已经把所有交互数据的主键换成了新整数 ID。模型拿新 ID 查特征表，查到的都是错位的那些行。这类问题不会报错，属于"静默错位"，是最阴险的坑。

解决：编码特征之后，写一个脚本从特征文件里随机抽几行，和映射表做交叉验证，确认两边 ID 对应关系一致了再开训练。不要嫌这一步麻烦，它值得在每次换数据集时重跑一遍。

5.3 GPU 显存溢出：batch_size 调小了还在崩

现象：报错CUDA out of memory，把batch_size从 1024 调到 256 还是崩，甚至换了更小的模型也崩。

原因：多模态模型吃的显存大头往往不是 batch 数据，而是特征矩阵和门控网络的中间变量，尤其是图像特征拼接后直接参与矩阵乘法时。另一个常见原因是 PyTorch 缓存分配器没及时释放之前的一次性大张量，比如验证阶段构建了全量物品的 embedding 矩阵。

解决：不要只调 batch_size，优先查这几项——特征矩阵是否做了类型转换（比如 float64 占双倍显存）、验证阶段是否一次性加载了全量物品、torch.no_grad()是否包住了验证循环。如果还崩，就把embed_dim从 64 降到 32 试试，确认是显存问题还是模型实现问题。

5.4 复现 PDF 报告失败：指标数值对不上

现象：你按configs里某个模型跑完，指标和顶层 PDF 报告里的数字差不少，低了 5 个点甚至更多。

原因：最可能的原因是负采样口径不一致。PDF 报告里的评估可能是全量物品排序，而你的配置默认是采样排序；或者反过来。另一个原因是数据划分方式不同，比如作者按时间切而你按用户比例切，测试集合本身就不一样。还有可能是特征编码版本不同，比如作者用了 1024 维的图像特征，你的编码脚本输出 512 维。

解决：先检查划分策略，再检查评估代码里的负采样数量，最后看特征维度。把这三点对齐之后，理论上指标能落到 PDF 报告附近。如果还差很远，再考虑是不是数据过滤阈值不同，MIN 交互数这种细节也会影响结果。

6. 扩展自己的模型：从 config 注册到三步验证

MMRec 的价值不只在于现成模型，更在于它的结构方便你把自己设计的模型插进去。我的做法是三个步骤：

第一步，在src/models目录下新建一个文件，仿照现有模型的接口写一个类。关键点是类名、forward的输入输出结构要和现有模型保持一致。具体说，forward要接收用户 ID、物品 ID 和特征张量，返回预测分数。

第二步，在configs目录下建一份配置文件，把name改成你的类名，把所需参数都填上。然后打开main.py或者模型注册入口，把新类挂上去。其实这一步就是一次性注册：

# 模型注册入口片段：新增一行即可 MODEL_REGISTRY = { "MTransE": MTransE, "MMoE": MMoE, "CDAE": CDAE, "MyModel": MyModel, # 新注册的模型 }

第三步，跑通之后做三步验证。先用小数据集冒烟测试，确认 loss 能正常下降；再取几十个样本做手工推理，确认预测结果在合理范围；最后和已有的最弱基线比指标，确认新模型不是无效劳动。这个流程我已经固化成习惯了，因为吃过亏——有一次新模型在训练集上指标很好，但一换数据分布就崩，后来发现是在测试阶段偷偷用了未来信息。

从那以后，我每次新增模型都会强制走一遍"冒烟测试 + 手工核对 + 基线对比"三连验证，确保新代码不只是能跑，而是真的在生产环境里站得住。希望帮到你，这套模式不只是 MMRec 能用，结构清晰的开源实现都值得试。

本文还有配套的精品资源，点击获取