簡介MMRec 是一套面向推薦系統(tǒng)開發(fā)者與科研人員的多模態(tài)推薦工具箱聚焦文本、圖像等多源特征的融合建模幫助解決單一模態(tài)推薦精度與多樣性不足的問題適合具備一定 Python 與深度學(xué)習(xí)基礎(chǔ)、希望快速復(fù)現(xiàn)與對比前沿算法的中高級學(xué)習(xí)者。資源包共 59 個文件約 446KB以 29 個 py 腳本承載模型與訓(xùn)練邏輯18 個 yaml 管理實(shí)驗(yàn)配置4 個 ipynb 提供數(shù)據(jù)預(yù)處理與實(shí)驗(yàn)流程模板另有 md 說明、png 示意圖與 pdf 報(bào)告目錄按 models、configs、utils、preprocessing 等模塊劃分結(jié)構(gòu)清晰便于按需檢索。目前已有 267 人學(xué)習(xí)下載。借助內(nèi)置的協(xié)同過濾、矩陣分解及 MTransE、CDAE、MMoE 等深度模型配合 Yelp、Amazon 等公開數(shù)據(jù)集支持讀者可快速完成數(shù)據(jù)加載、模型訓(xùn)練與結(jié)果評估并基于可擴(kuò)展接口集成自有算法開展對比實(shí)驗(yàn)降低多模態(tài)推薦系統(tǒng)的研發(fā)門檻。1. 多模態(tài)推薦工具箱10 多個模型塞進(jìn)一個 Jupyter Notebook 到底怎么跑你手上有一份用戶行為日志里面有商品圖、標(biāo)題文本、類目 ID還有點(diǎn)擊序列。老板說「做個多模態(tài)推薦試試」。你打開搜索引擎發(fā)現(xiàn)每個模型都有自己的預(yù)處理腳本、自己的依賴版本、自己的訓(xùn)練入口——光是把圖像特征和文本特征對齊到同一個用戶 ID 上就能耗掉兩天。這個工具箱要解決的就是這件事把 10 多個多模態(tài)推薦模型收進(jìn)一套統(tǒng)一的 Python 工程里用 Jupyter Notebook 做入口數(shù)據(jù)加載、特征拼接、模型切換、指標(biāo)評估走同一套接口。它適合兩類人一類是想快速對比不同多模態(tài)融合策略的算法工程師另一類是想在本地跑通一個完整推薦 pipeline 再決定要不要上生產(chǎn)的學(xué)生或轉(zhuǎn)行者。不適合指望開箱即用上億級流量的場景——工具箱的定位是實(shí)驗(yàn)臺不是線上服務(wù)。下面按「環(huán)境怎么搭 → 數(shù)據(jù)怎么進(jìn) → 模型怎么切 → 坑在哪 → 怎么驗(yàn)證」的順序拆開講。2. 把工具箱跑起來Python 環(huán)境、Jupyter 路徑與依賴安裝2.1 先確認(rèn) Python 版本和虛擬環(huán)境別在系統(tǒng)解釋器里裝多模態(tài)推薦工具箱通常依賴 PyTorch、torchvision、transformers、pandas、scikit-learn 這幾類庫。這些庫對 Python 版本有硬性要求常見做法是鎖在 Python 3.8 到 3.10 之間。如果你用的是 Python 3.12部分舊版 torchvision 的 wheel 可能找不到會直接卡在安裝階段。我一般會先建一個獨(dú)立虛擬環(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 單獨(dú)指定 index-url 是因?yàn)槟J(rèn)源里的版本可能和你的 CUDA 不匹配jupyter notebook 放在最后裝避免它提前拉取舊版依賴。參數(shù)上--index-url換成 CUDA 版本時把cpu改成cu118或cu121具體看你的顯卡驅(qū)動。提示裝完之后用python -c import torch; print(torch.__version__)確認(rèn)版本不要等到跑模型時才發(fā)現(xiàn) torch 沒裝上。2.2 Jupyter Notebook 默認(rèn)保存路徑與工作目錄設(shè)置很多人第一次用 Jupyter Notebook會發(fā)現(xiàn)新建的 notebook 保存在一個莫名其妙的目錄里找都找不到。這是因?yàn)?Jupyter 默認(rèn)從啟動時的當(dāng)前目錄讀取文件。解決辦法有兩個一是在啟動前cd到工具箱所在目錄二是生成配置文件并修改默認(rèn)路徑。# 生成配置文件如果還沒有 jupyter notebook --generate-config # 查看配置文件位置 jupyter --config-dir打開生成的jupyter_notebook_config.py找到c.NotebookApp.notebook_dir這一行取消注釋并改成你的工具箱根目錄c.NotebookApp.notebook_dir /home/user/mmrec_toolbox邏輯說明改完之后每次啟動 Jupyter 都會直接進(jìn)入工具箱目錄notebook 里用相對路徑讀數(shù)據(jù)就不會報(bào)FileNotFoundError。參數(shù)上Windows 路徑要寫成rD:\mmrec_toolbox這種原始字符串否則反斜杠會被轉(zhuǎn)義。如果你不想改配置也可以在啟動命令里直接指定jupyter notebook --notebook-dir/home/user/mmrec_toolbox2.3 安裝缺失節(jié)點(diǎn)和常見依賴報(bào)錯的處理工具箱里的 notebook 通常會 import 一堆庫跑第一個 cell 就可能報(bào)ModuleNotFoundError。常見的有cv2OpenCV、PIL、tqdm、faiss。這些不在核心依賴?yán)镄枰獑为?dú)裝pip install opencv-python pillow tqdm # faiss 用于向量檢索CPU 版即可 pip install faiss-cpu邏輯說明opencv-python提供 cv2用于圖像預(yù)處理faiss-cpu用于多模態(tài)特征向量的近鄰檢索如果你只是跑通模型訓(xùn)練可以先不裝。參數(shù)上faiss-cpu和faiss-gpu不要同時裝會沖突。注意如果報(bào)錯信息里出現(xiàn)pip install -u --pre comfyui-m這類提示那是其他項(xiàng)目的依賴和本工具箱無關(guān)不要照著裝。3. 數(shù)據(jù)怎么進(jìn)工具箱多模態(tài)特征對齊與鄰接矩陣構(gòu)建3.1 多模態(tài)推薦的數(shù)據(jù)長什么樣三張表和一個對齊鍵多模態(tài)推薦的核心難點(diǎn)不是模型結(jié)構(gòu)而是數(shù)據(jù)對齊。典型的數(shù)據(jù)組織方式是三張表用戶-物品交互表、物品圖像特征表、物品文本特征表。三張表通過item_id關(guān)聯(lián)。表名關(guān)鍵字段說明interactionsuser_id, item_id, rating, timestamp用戶行為日志item_imagesitem_id, image_path, image_feat圖像路徑或預(yù)提取特征item_textsitem_id, title, text_feat標(biāo)題或描述文本特征常見做法是先用預(yù)訓(xùn)練模型把圖像和文本編碼成向量存成.npy或.pkl訓(xùn)練時直接加載。這樣比每次從原圖跑 CNN 快一個數(shù)量級。如果你手上只有原始圖片和文本工具箱里一般會提供一個preprocess.py或?qū)?yīng)的 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是處理變長文本的標(biāo)配max_length默認(rèn) 77超過會被截?cái)?。如果你用中文文本建議換成支持中文的 CLIP 變體否則文本特征質(zhì)量會很差。3.2 構(gòu)建用戶-物品鄰接矩陣從交互表到稀疏矩陣推薦模型里經(jīng)常需要鄰接矩陣來表示用戶和物品的連接關(guān)系。工具箱里通常用 scipy 的稀疏矩陣來存避免內(nèi)存爆炸。import scipy.sparse as sp import pandas as pd # 讀取交互表 df pd.read_csv(data/interactions.csv) # 構(gòu)建用戶和物品的索引映射 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)} # 構(gòu)建稀疏鄰接矩陣 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適合按行切片訓(xùn)練時按用戶取交互記錄效率高。參數(shù)上shape必須顯式指定否則 scipy 會按最大值推斷容易漏掉尾部 ID。如果你的交互表里有重復(fù)的 user-item 對data里會出現(xiàn)多個 1建議先去重或改成評分值。提示如果物品數(shù)量超過百萬item_map這種字典會占不少內(nèi)存可以改用pd.factorize直接生成編碼。3.3 把圖像和文本特征拼到物品側(cè)兩種融合時機(jī)多模態(tài)融合分早期融合和晚期融合。早期融合是在輸入層就把圖像向量和文本向量拼在一起送進(jìn)同一個編碼器晚期融合是各自過編碼器最后在打分層相加或拼接。工具箱里一般兩種都提供通過配置項(xiàng)切換。# 早期融合直接拼接 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) # 晚期融合各自保留訓(xùn)練時分別過網(wǎng)絡(luò) # 在模型 forward 里處理邏輯說明早期融合實(shí)現(xiàn)簡單但要求兩個模態(tài)維度不能差太多否則某一模態(tài)會主導(dǎo)。晚期融合更靈活但參數(shù)量更大。參數(shù)上拼接后的維度是兩者之和后續(xù)全連接層的輸入維度要對應(yīng)改。4. 模型怎么切10 多個模型的統(tǒng)一接口與訓(xùn)練入口4.1 工具箱的目錄結(jié)構(gòu)先找到入口 notebook一個典型的多模態(tài)推薦工具箱目錄大致長這樣mmrec_toolbox/ ├── data/ # 數(shù)據(jù)存放 ├── models/ # 各模型實(shí)現(xiàn) │ ├── vbpr.py │ ├── mmgcn.py │ ├── lgmrec.py │ └── ... ├── configs/ # 配置文件 ├── notebooks/ # Jupyter 入口 │ ├── 01_quick_start.ipynb │ ├── 02_train_vbpr.ipynb │ └── ... ├── utils/ # 數(shù)據(jù)加載、評估指標(biāo) └── requirements.txt先打開notebooks/01_quick_start.ipynb從頭到尾跑一遍。這個 notebook 通常用一份小樣本數(shù)據(jù)幾分鐘內(nèi)能跑完目的是驗(yàn)證環(huán)境沒問題。跑通之后再換自己的數(shù)據(jù)。4.2 切換模型改一個配置項(xiàng)而不是改代碼工具箱的價(jià)值在于統(tǒng)一接口。常見做法是每個模型都實(shí)現(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ù)名字返回對應(yīng)模型實(shí)例。參數(shù)上embedding_dim控制隱向量維度太小欠擬合太大容易過擬合fusion_type決定用早期還是晚期融合。改配置比改代碼安全也方便做消融實(shí)驗(yàn)。4.3 訓(xùn)練過程中的指標(biāo)觀察別只看 loss推薦模型的評估指標(biāo)通常是 RecallK、NDCGK、HitK。工具箱里一般會在每個 epoch 結(jié)束后打印驗(yàn)證集指標(biāo)。你要關(guān)注的是驗(yàn)證集指標(biāo)有沒有在漲而不是訓(xùn)練 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列表決定評估哪些截?cái)辔恢靡话憧?10 和 20 就夠了。參數(shù)上如果 Recall10 一直不漲先檢查數(shù)據(jù)加載有沒有把負(fù)樣本采錯再檢查學(xué)習(xí)率是不是太大。注意多模態(tài)推薦里圖像和文本特征的質(zhì)量對結(jié)果影響很大。如果圖像特征是用隨機(jī)初始化的 CNN 提的那還不如不用。5. 避坑與排查多模態(tài)推薦工具箱最常見的 5 個翻車點(diǎn)5.1 現(xiàn)象跑第一個 notebook 就報(bào)ModuleNotFoundError: No module named cv2原因工具箱的依賴清單里可能沒寫 opencv-python但圖像預(yù)處理 cell 用到了 cv2。解決pip install opencv-python如果還報(bào)錯檢查是不是裝到了系統(tǒng) Python 而不是虛擬環(huán)境里。用which python和which pip確認(rèn)路徑一致。5.2 現(xiàn)象訓(xùn)練 loss 正常下降但 Recall10 一直是 0.01 左右原因最常見的是負(fù)采樣出了問題。多模態(tài)推薦訓(xùn)練時需要正負(fù)樣本對如果負(fù)樣本采到了和正樣本同一個物品或者負(fù)樣本全是熱門物品模型學(xué)不到區(qū)分能力。解決檢查數(shù)據(jù)加載器里的負(fù)采樣邏輯確保負(fù)樣本從用戶未交互的物品里采并且做 popularity 校正。5.3 現(xiàn)象圖像特征和文本特征拼在一起后模型只學(xué)文本那一半原因兩個模態(tài)的數(shù)值范圍差異太大。圖像特征經(jīng)過 CLIP 歸一化后通常在 -1 到 1 之間文本特征如果沒歸一化可能在 -10 到 10 之間。直接拼接會讓文本主導(dǎo)梯度。解決拼接前對每個模態(tài)做 L2 歸一化或標(biāo)準(zhǔn)化。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 跑著跑著內(nèi)核掛了提示內(nèi)存不足原因多模態(tài)特征向量占內(nèi)存很大。假設(shè) 10 萬個物品每個物品圖像 512 維 float32文本 512 維光特征就占 100000 × 1024 × 4 字節(jié) ≈ 400MB。如果再加上鄰接矩陣和中間激活很容易超過 8GB。解決用 float16 存特征或者分批加載而不是一次性全讀進(jìn)內(nèi)存。5.5 現(xiàn)象換了一個模型配置文件改了但結(jié)果沒變原因Jupyter Notebook 里可能緩存了舊的模型實(shí)例或舊的配置變量。解決改完配置后重啟內(nèi)核或者在 notebook 里顯式重新加載配置和模型。不要指望改了 yaml 文件后當(dāng)前內(nèi)核里的變量會自動更新。6. 進(jìn)階驗(yàn)證用消融實(shí)驗(yàn)判斷多模態(tài)到底有沒有用跑通工具箱之后你最該做的一件事不是換更多模型而是做一組消融實(shí)驗(yàn)確認(rèn)多模態(tài)特征確實(shí)帶來了提升。具體做法是固定模型結(jié)構(gòu)只改輸入模態(tài)只用 ID 特征、只用文本、只用圖像、圖文都用。如果圖文都用比單模態(tài)只高 0.1%那說明你的融合方式可能有問題或者數(shù)據(jù)本身模態(tài)信息就不強(qiáng)。# 消融實(shí)驗(yàn)配置 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邏輯說明這組實(shí)驗(yàn)?zāi)苤苯痈嬖V你多模態(tài)信號有沒有被模型用上。參數(shù)上每次只改modality其他超參保持一致否則對比不公平。如果多模態(tài)比單模態(tài)還差優(yōu)先檢查特征對齊和歸一化。另一個驗(yàn)證技巧是看模型學(xué)到的物品向量是否保留了模態(tài)結(jié)構(gòu)?？梢杂?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)圖像特征其實(shí)沒被用上因?yàn)闅w一化沒做模型直接把圖像分支的權(quán)重學(xué)成了接近零。做消融實(shí)驗(yàn)和可視化之后才定位到問題。所以別偷懶跑完模型一定回頭看一眼特征到底有沒有生效。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取