簡介MMRec 是一套面向推薦系統(tǒng)開發(fā)者與科研人員的多模態(tài)推薦工具箱聚焦文本、圖像等多源特征的融合建模幫助解決單一模態(tài)推薦精度與多樣性不足的問題適合具備一定 Python 與深度學習基礎、希望快速復現(xiàn)與對比前沿算法的中高級學習者。資源包共 59 個文件約 446KB以 29 個 py 腳本承載模型與訓練邏輯18 個 yaml 管理實驗配置4 個 ipynb 提供數(shù)據(jù)預處理與實驗流程模板另有 md 說明、png 示意圖與 pdf 報告目錄按 models、configs、utils、preprocessing 等模塊劃分結構清晰便于按需檢索。目前已有 267 人學習下載。借助內置的協(xié)同過濾、矩陣分解及 MTransE、CDAE、MMoE 等深度模型配合 Yelp、Amazon 等公開數(shù)據(jù)集支持讀者可快速完成數(shù)據(jù)加載、模型訓練與結果評估并基于可擴展接口集成自有算法開展對比實驗降低多模態(tài)推薦系統(tǒng)的研發(fā)門檻。1. 多模態(tài)推薦工具箱10 多個模型塞進一個 Jupyter Notebook 到底怎么跑你手上有一份用戶行為日志里面有商品圖、標題文本、類目 ID還有點擊序列。老板說「做個多模態(tài)推薦試試」。你打開搜索引擎發(fā)現(xiàn)每個模型都有自己的預處理腳本、自己的依賴版本、自己的訓練入口——光是把圖像特征和文本特征對齊到同一個用戶 ID 上就能耗掉兩天。這個工具箱要解決的就是這件事把 10 多個多模態(tài)推薦模型收進一套統(tǒng)一的 Python 工程里用 Jupyter Notebook 做入口數(shù)據(jù)加載、特征拼接、模型切換、指標評估走同一套接口。它適合兩類人一類是想快速對比不同多模態(tài)融合策略的算法工程師另一類是想在本地跑通一個完整推薦 pipeline 再決定要不要上生產的學生或轉行者。不適合指望開箱即用上億級流量的場景——工具箱的定位是實驗臺不是線上服務。下面按「環(huán)境怎么搭 → 數(shù)據(jù)怎么進 → 模型怎么切 → 坑在哪 → 怎么驗證」的順序拆開講。2. 把工具箱跑起來Python 環(huán)境、Jupyter 路徑與依賴安裝2.1 先確認 Python 版本和虛擬環(huán)境別在系統(tǒng)解釋器里裝多模態(tài)推薦工具箱通常依賴 PyTorch、torchvision、transformers、pandas、scikit-learn 這幾類庫。這些庫對 Python 版本有硬性要求常見做法是鎖在 Python 3.8 到 3.10 之間。如果你用的是 Python 3.12部分舊版 torchvision 的 wheel 可能找不到會直接卡在安裝階段。我一般會先建一個獨立虛擬環(huán)境避免和系統(tǒng)里已有的 numpy、cv2 打架。Windows 和 Linux 的命令略有差別# Linux / macOS python3.9 -m venv venv_mmrec source venv_mmrec/bin/activate # Windows PowerShell python -m venv venv_mmrec .\venv_mmrec\Scripts\Activate.ps1激活之后先升級 pip再裝核心依賴。注意 torch 的安裝命令要跟 CUDA 版本匹配如果你沒有 GPU直接用 CPU 版即可pip install --upgrade pip # CPU 版本適合先跑通流程 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install transformers pandas scikit-learn jupyter notebook邏輯說明先建虛擬環(huán)境是為了隔離依賴torch 單獨指定 index-url 是因為默認源里的版本可能和你的 CUDA 不匹配jupyter notebook 放在最后裝避免它提前拉取舊版依賴。參數(shù)上--index-url換成 CUDA 版本時把cpu改成cu118或cu121具體看你的顯卡驅動。提示裝完之后用python -c import torch; print(torch.__version__)確認版本不要等到跑模型時才發(fā)現(xiàn) torch 沒裝上。2.2 Jupyter Notebook 默認保存路徑與工作目錄設置很多人第一次用 Jupyter Notebook會發(fā)現(xiàn)新建的 notebook 保存在一個莫名其妙的目錄里找都找不到。這是因為 Jupyter 默認從啟動時的當前目錄讀取文件。解決辦法有兩個一是在啟動前cd到工具箱所在目錄二是生成配置文件并修改默認路徑。# 生成配置文件如果還沒有 jupyter notebook --generate-config # 查看配置文件位置 jupyter --config-dir打開生成的jupyter_notebook_config.py找到c.NotebookApp.notebook_dir這一行取消注釋并改成你的工具箱根目錄c.NotebookApp.notebook_dir /home/user/mmrec_toolbox邏輯說明改完之后每次啟動 Jupyter 都會直接進入工具箱目錄notebook 里用相對路徑讀數(shù)據(jù)就不會報FileNotFoundError。參數(shù)上Windows 路徑要寫成rD:\mmrec_toolbox這種原始字符串否則反斜杠會被轉義。如果你不想改配置也可以在啟動命令里直接指定jupyter notebook --notebook-dir/home/user/mmrec_toolbox2.3 安裝缺失節(jié)點和常見依賴報錯的處理工具箱里的 notebook 通常會 import 一堆庫跑第一個 cell 就可能報ModuleNotFoundError。常見的有cv2OpenCV、PIL、tqdm、faiss。這些不在核心依賴里需要單獨裝pip install opencv-python pillow tqdm # faiss 用于向量檢索CPU 版即可 pip install faiss-cpu邏輯說明opencv-python提供 cv2用于圖像預處理faiss-cpu用于多模態(tài)特征向量的近鄰檢索如果你只是跑通模型訓練可以先不裝。參數(shù)上faiss-cpu和faiss-gpu不要同時裝會沖突。注意如果報錯信息里出現(xiàn)pip install -u --pre comfyui-m這類提示那是其他項目的依賴和本工具箱無關不要照著裝。3. 數(shù)據(jù)怎么進工具箱多模態(tài)特征對齊與鄰接矩陣構建3.1 多模態(tài)推薦的數(shù)據(jù)長什么樣三張表和一個對齊鍵多模態(tài)推薦的核心難點不是模型結構而是數(shù)據(jù)對齊。典型的數(shù)據(jù)組織方式是三張表用戶-物品交互表、物品圖像特征表、物品文本特征表。三張表通過item_id關聯(lián)。表名關鍵字段說明interactionsuser_id, item_id, rating, timestamp用戶行為日志item_imagesitem_id, image_path, image_feat圖像路徑或預提取特征item_textsitem_id, title, text_feat標題或描述文本特征常見做法是先用預訓練模型把圖像和文本編碼成向量存成.npy或.pkl訓練時直接加載。這樣比每次從原圖跑 CNN 快一個數(shù)量級。如果你手上只有原始圖片和文本工具箱里一般會提供一個preprocess.py或對應的 notebook cell 來做批量編碼。import numpy as np import pandas as pd from PIL import Image import torch from transformers import CLIPProcessor, CLIPModel # 加載 CLIP 做圖文編碼 model CLIPModel.from_pretrained(openai/clip-vit-base-patch32) processor CLIPProcessor.from_pretrained(openai/clip-vit-base-patch32) def encode_image(image_path): image Image.open(image_path).convert(RGB) inputs processor(imagesimage, return_tensorspt) with torch.no_grad(): feat model.get_image_features(**inputs) return feat.squeeze().numpy() def encode_text(text): inputs processor(texttext, return_tensorspt, paddingTrue, truncationTrue) with torch.no_grad(): feat model.get_text_features(**inputs) return feat.squeeze().numpy()邏輯說明CLIP 把圖像和文本映射到同一個向量空間這樣后續(xù)融合時不需要額外做維度對齊。參數(shù)上paddingTrue和truncationTrue是處理變長文本的標配max_length默認 77超過會被截斷。如果你用中文文本建議換成支持中文的 CLIP 變體否則文本特征質量會很差。3.2 構建用戶-物品鄰接矩陣從交互表到稀疏矩陣推薦模型里經常需要鄰接矩陣來表示用戶和物品的連接關系。工具箱里通常用 scipy 的稀疏矩陣來存避免內存爆炸。import scipy.sparse as sp import pandas as pd # 讀取交互表 df pd.read_csv(data/interactions.csv) # 構建用戶和物品的索引映射 user_ids df[user_id].unique() item_ids df[item_id].unique() user_map {uid: i for i, uid in enumerate(user_ids)} item_map {iid: i for i, iid in enumerate(item_ids)} # 構建稀疏鄰接矩陣 rows df[user_id].map(user_map).values cols df[item_id].map(item_map).values data np.ones(len(df)) adj sp.csr_matrix((data, (rows, cols)), shape(len(user_ids), len(item_ids))) print(f鄰接矩陣形狀: {adj.shape}, 非零元素: {adj.nnz})邏輯說明csr_matrix適合按行切片訓練時按用戶取交互記錄效率高。參數(shù)上shape必須顯式指定否則 scipy 會按最大值推斷容易漏掉尾部 ID。如果你的交互表里有重復的 user-item 對data里會出現(xiàn)多個 1建議先去重或改成評分值。提示如果物品數(shù)量超過百萬item_map這種字典會占不少內存可以改用pd.factorize直接生成編碼。3.3 把圖像和文本特征拼到物品側兩種融合時機多模態(tài)融合分早期融合和晚期融合。早期融合是在輸入層就把圖像向量和文本向量拼在一起送進同一個編碼器晚期融合是各自過編碼器最后在打分層相加或拼接。工具箱里一般兩種都提供通過配置項切換。# 早期融合直接拼接 image_feats np.load(data/image_feats.npy) # shape: (n_items, 512) text_feats np.load(data/text_feats.npy) # shape: (n_items, 512) fused_feats np.concatenate([image_feats, text_feats], axis1) # (n_items, 1024) # 晚期融合各自保留訓練時分別過網(wǎng)絡 # 在模型 forward 里處理邏輯說明早期融合實現(xiàn)簡單但要求兩個模態(tài)維度不能差太多否則某一模態(tài)會主導。晚期融合更靈活但參數(shù)量更大。參數(shù)上拼接后的維度是兩者之和后續(xù)全連接層的輸入維度要對應改。4. 模型怎么切10 多個模型的統(tǒng)一接口與訓練入口4.1 工具箱的目錄結構先找到入口 notebook一個典型的多模態(tài)推薦工具箱目錄大致長這樣mmrec_toolbox/ ├── data/ # 數(shù)據(jù)存放 ├── models/ # 各模型實現(xiàn) │ ├── vbpr.py │ ├── mmgcn.py │ ├── lgmrec.py │ └── ... ├── configs/ # 配置文件 ├── notebooks/ # Jupyter 入口 │ ├── 01_quick_start.ipynb │ ├── 02_train_vbpr.ipynb │ └── ... ├── utils/ # 數(shù)據(jù)加載、評估指標 └── requirements.txt先打開notebooks/01_quick_start.ipynb從頭到尾跑一遍。這個 notebook 通常用一份小樣本數(shù)據(jù)幾分鐘內能跑完目的是驗證環(huán)境沒問題。跑通之后再換自己的數(shù)據(jù)。4.2 切換模型改一個配置項而不是改代碼工具箱的價值在于統(tǒng)一接口。常見做法是每個模型都實現(xiàn)fit和predict兩個方法通過配置文件里的model_name切換。# configs/base.yaml model_name: VBPR embedding_dim: 64 lr: 0.001 batch_size: 1024 epochs: 50 modality: [image, text] fusion_type: earlyimport yaml from models import get_model with open(configs/base.yaml) as f: config yaml.safe_load(f) model get_model(config[model_name], config) model.fit(train_loader, val_loader)邏輯說明get_model是一個工廠函數(shù)根據(jù)名字返回對應模型實例。參數(shù)上embedding_dim控制隱向量維度太小欠擬合太大容易過擬合fusion_type決定用早期還是晚期融合。改配置比改代碼安全也方便做消融實驗。4.3 訓練過程中的指標觀察別只看 loss推薦模型的評估指標通常是 RecallK、NDCGK、HitK。工具箱里一般會在每個 epoch 結束后打印驗證集指標。你要關注的是驗證集指標有沒有在漲而不是訓練 loss 有沒有降。from utils.metrics import evaluate for epoch in range(config[epochs]): model.train_one_epoch(train_loader) metrics evaluate(model, val_loader, topk[10, 20, 50]) print(fEpoch {epoch}: Recall10{metrics[recall10]:.4f}, fNDCG10{metrics[ndcg10]:.4f})邏輯說明topk列表決定評估哪些截斷位置一般看 10 和 20 就夠了。參數(shù)上如果 Recall10 一直不漲先檢查數(shù)據(jù)加載有沒有把負樣本采錯再檢查學習率是不是太大。注意多模態(tài)推薦里圖像和文本特征的質量對結果影響很大。如果圖像特征是用隨機初始化的 CNN 提的那還不如不用。5. 避坑與排查多模態(tài)推薦工具箱最常見的 5 個翻車點5.1 現(xiàn)象跑第一個 notebook 就報ModuleNotFoundError: No module named cv2原因工具箱的依賴清單里可能沒寫 opencv-python但圖像預處理 cell 用到了 cv2。解決pip install opencv-python如果還報錯檢查是不是裝到了系統(tǒng) Python 而不是虛擬環(huán)境里。用which python和which pip確認路徑一致。5.2 現(xiàn)象訓練 loss 正常下降但 Recall10 一直是 0.01 左右原因最常見的是負采樣出了問題。多模態(tài)推薦訓練時需要正負樣本對如果負樣本采到了和正樣本同一個物品或者負樣本全是熱門物品模型學不到區(qū)分能力。解決檢查數(shù)據(jù)加載器里的負采樣邏輯確保負樣本從用戶未交互的物品里采并且做 popularity 校正。5.3 現(xiàn)象圖像特征和文本特征拼在一起后模型只學文本那一半原因兩個模態(tài)的數(shù)值范圍差異太大。圖像特征經過 CLIP 歸一化后通常在 -1 到 1 之間文本特征如果沒歸一化可能在 -10 到 10 之間。直接拼接會讓文本主導梯度。解決拼接前對每個模態(tài)做 L2 歸一化或標準化。from sklearn.preprocessing import normalize image_feats normalize(image_feats, norml2) text_feats normalize(text_feats, norml2) fused np.concatenate([image_feats, text_feats], axis1)5.4 現(xiàn)象Jupyter Notebook 跑著跑著內核掛了提示內存不足原因多模態(tài)特征向量占內存很大。假設 10 萬個物品每個物品圖像 512 維 float32文本 512 維光特征就占 100000 × 1024 × 4 字節(jié) ≈ 400MB。如果再加上鄰接矩陣和中間激活很容易超過 8GB。解決用 float16 存特征或者分批加載而不是一次性全讀進內存。5.5 現(xiàn)象換了一個模型配置文件改了但結果沒變原因Jupyter Notebook 里可能緩存了舊的模型實例或舊的配置變量。解決改完配置后重啟內核或者在 notebook 里顯式重新加載配置和模型。不要指望改了 yaml 文件后當前內核里的變量會自動更新。6. 進階驗證用消融實驗判斷多模態(tài)到底有沒有用跑通工具箱之后你最該做的一件事不是換更多模型而是做一組消融實驗確認多模態(tài)特征確實帶來了提升。具體做法是固定模型結構只改輸入模態(tài)只用 ID 特征、只用文本、只用圖像、圖文都用。如果圖文都用比單模態(tài)只高 0.1%那說明你的融合方式可能有問題或者數(shù)據(jù)本身模態(tài)信息就不強。# 消融實驗配置 ablation_configs [ {modality: []}, # 只用 ID {modality: [text]}, # 文本 {modality: [image]}, # 圖像 {modality: [image, text]} # 多模態(tài) ] results {} for cfg in ablation_configs: config.update(cfg) model get_model(config[model_name], config) model.fit(train_loader, val_loader) metrics evaluate(model, test_loader, topk[10, 20]) results[str(cfg[modality])] metrics邏輯說明這組實驗能直接告訴你多模態(tài)信號有沒有被模型用上。參數(shù)上每次只改modality其他超參保持一致否則對比不公平。如果多模態(tài)比單模態(tài)還差優(yōu)先檢查特征對齊和歸一化。另一個驗證技巧是看模型學到的物品向量是否保留了模態(tài)結構。可以用 t-SNE 把物品向量降到二維按類目著色如果同類物品聚在一起說明多模態(tài)特征被有效編碼了。from sklearn.manifold import TSNE import matplotlib.pyplot as plt item_embs model.get_item_embeddings() # (n_items, dim) tsne TSNE(n_components2, random_state42) vis tsne.fit_transform(item_embs) plt.scatter(vis[:, 0], vis[:, 1], ccategories, s1, cmaptab20) plt.savefig(item_emb_tsne.png, dpi150)我自己踩過的坑是一開始只看 Recall 數(shù)字覺得多模態(tài)比單模態(tài)高就行。后來發(fā)現(xiàn)圖像特征其實沒被用上因為歸一化沒做模型直接把圖像分支的權重學成了接近零。做消融實驗和可視化之后才定位到問題。所以別偷懶跑完模型一定回頭看一眼特征到底有沒有生效。希望幫到你。本文還有配套的精品資源點擊獲取