簡(jiǎn)介MMRec 是一套面向推薦系統(tǒng)開發(fā)者與科研人員的多模態(tài)推薦工具箱聚焦文本、圖像等多源特征的融合建模幫助解決單一模態(tài)推薦精度與多樣性不足的問題適合具備一定 Python 與深度學(xué)習(xí)基礎(chǔ)、希望快速?gòu)?fù)現(xiàn)與對(duì)比前沿算法的中高級(jí)學(xué)習(xí)者。資源包共 59 個(gè)文件約 446KB以 29 個(gè) py 腳本承載模型與訓(xùn)練邏輯18 個(gè) yaml 管理實(shí)驗(yàn)配置4 個(gè) 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é)果評(píng)估并基于可擴(kuò)展接口集成自有算法開展對(duì)比實(shí)驗(yàn)降低多模態(tài)推薦系統(tǒng)的研發(fā)門檻。1. 多模態(tài)推薦工具箱10 多個(gè)模型塞進(jìn)一個(gè) Jupyter Notebook 到底怎么跑你手上有一份用戶行為日志里面有商品圖、標(biāo)題文本、類目 ID還有點(diǎn)擊序列。老板說「做個(gè)多模態(tài)推薦試試」。你打開搜索引擎發(fā)現(xiàn)每個(gè)模型都有自己的預(yù)處理腳本、自己的依賴版本、自己的訓(xùn)練入口——光是把圖像特征和文本特征對(duì)齊到同一個(gè)用戶 ID 上就能耗掉兩天。這個(gè)工具箱要解決的就是這件事把 10 多個(gè)多模態(tài)推薦模型收進(jìn)一套統(tǒng)一的 Python 工程里用 Jupyter Notebook 做入口數(shù)據(jù)加載、特征拼接、模型切換、指標(biāo)評(píng)估走同一套接口。它適合兩類人一類是想快速對(duì)比不同多模態(tài)融合策略的算法工程師另一類是想在本地跑通一個(gè)完整推薦 pipeline 再?zèng)Q定要不要上生產(chǎn)的學(xué)生或轉(zhuǎn)行者。不適合指望開箱即用上億級(jí)流量的場(chǎng)景——工具箱的定位是實(shí)驗(yàn)臺(tái)不是線上服務(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 這幾類庫。這些庫對(duì) Python 版本有硬性要求常見做法是鎖在 Python 3.8 到 3.10 之間。如果你用的是 Python 3.12部分舊版 torchvision 的 wheel 可能找不到會(huì)直接卡在安裝階段。我一般會(huì)先建一個(gè)獨(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激活之后先升級(jí) 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 版本時(shí)把cpu改成cu118或cu121具體看你的顯卡驅(qū)動(dòng)。提示裝完之后用python -c import torch; print(torch.__version__)確認(rèn)版本不要等到跑模型時(shí)才發(fā)現(xiàn) torch 沒裝上。2.2 Jupyter Notebook 默認(rèn)保存路徑與工作目錄設(shè)置很多人第一次用 Jupyter Notebook會(huì)發(fā)現(xiàn)新建的 notebook 保存在一個(gè)莫名其妙的目錄里找都找不到。這是因?yàn)?Jupyter 默認(rèn)從啟動(dòng)時(shí)的當(dāng)前目錄讀取文件。解決辦法有兩個(gè)一是在啟動(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邏輯說明改完之后每次啟動(dòng) Jupyter 都會(huì)直接進(jìn)入工具箱目錄notebook 里用相對(duì)路徑讀數(shù)據(jù)就不會(huì)報(bào)FileNotFoundError。參數(shù)上Windows 路徑要寫成rD:\mmrec_toolbox這種原始字符串否則反斜杠會(huì)被轉(zhuǎn)義。如果你不想改配置也可以在啟動(dòng)命令里直接指定jupyter notebook --notebook-dir/home/user/mmrec_toolbox2.3 安裝缺失節(jié)點(diǎn)和常見依賴報(bào)錯(cuò)的處理工具箱里的 notebook 通常會(huì) import 一堆庫跑第一個(gè) 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不要同時(shí)裝會(huì)沖突。注意如果報(bào)錯(cuò)信息里出現(xiàn)pip install -u --pre comfyui-m這類提示那是其他項(xiàng)目的依賴和本工具箱無關(guān)不要照著裝。3. 數(shù)據(jù)怎么進(jìn)工具箱多模態(tài)特征對(duì)齊與鄰接矩陣構(gòu)建3.1 多模態(tài)推薦的數(shù)據(jù)長(zhǎng)什么樣三張表和一個(gè)對(duì)齊鍵多模態(tài)推薦的核心難點(diǎn)不是模型結(jié)構(gòu)而是數(shù)據(jù)對(duì)齊。典型的數(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)練時(shí)直接加載。這樣比每次從原圖跑 CNN 快一個(gè)數(shù)量級(jí)。如果你手上只有原始圖片和文本工具箱里一般會(huì)提供一個(gè)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 把圖像和文本映射到同一個(gè)向量空間這樣后續(xù)融合時(shí)不需要額外做維度對(duì)齊。參數(shù)上paddingTrue和truncationTrue是處理變長(zhǎng)文本的標(biāo)配max_length默認(rèn) 77超過會(huì)被截?cái)唷Ｈ绻阌弥形奈谋窘ㄗh換成支持中文的 CLIP 變體否則文本特征質(zhì)量會(huì)很差。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í)按用戶取交互記錄效率高。參數(shù)上shape必須顯式指定否則 scipy 會(huì)按最大值推斷容易漏掉尾部 ID。如果你的交互表里有重復(fù)的 user-item 對(duì)data里會(huì)出現(xiàn)多個(gè) 1建議先去重或改成評(píng)分值。提示如果物品數(shù)量超過百萬item_map這種字典會(huì)占不少內(nèi)存可以改用pd.factorize直接生成編碼。3.3 把圖像和文本特征拼到物品側(cè)兩種融合時(shí)機(jī)多模態(tài)融合分早期融合和晚期融合。早期融合是在輸入層就把圖像向量和文本向量拼在一起送進(jìn)同一個(gè)編碼器晚期融合是各自過編碼器最后在打分層相加或拼接。工具箱里一般兩種都提供通過配置項(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)練時(shí)分別過網(wǎng)絡(luò) # 在模型 forward 里處理邏輯說明早期融合實(shí)現(xiàn)簡(jiǎn)單但要求兩個(gè)模態(tài)維度不能差太多否則某一模態(tài)會(huì)主導(dǎo)。晚期融合更靈活但參數(shù)量更大。參數(shù)上拼接后的維度是兩者之和后續(xù)全連接層的輸入維度要對(duì)應(yīng)改。4. 模型怎么切10 多個(gè)模型的統(tǒng)一接口與訓(xùn)練入口4.1 工具箱的目錄結(jié)構(gòu)先找到入口 notebook一個(gè)典型的多模態(tài)推薦工具箱目錄大致長(zhǎng)這樣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ù)加載、評(píng)估指標(biāo) └── requirements.txt先打開notebooks/01_quick_start.ipynb從頭到尾跑一遍。這個(gè) notebook 通常用一份小樣本數(shù)據(jù)幾分鐘內(nèi)能跑完目的是驗(yàn)證環(huán)境沒問題。跑通之后再換自己的數(shù)據(jù)。4.2 切換模型改一個(gè)配置項(xiàng)而不是改代碼工具箱的價(jià)值在于統(tǒng)一接口。常見做法是每個(gè)模型都實(shí)現(xiàn)fit和predict兩個(gè)方法通過配置文件里的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是一個(gè)工廠函數(shù)根據(jù)名字返回對(duì)應(yīng)模型實(shí)例。參數(shù)上embedding_dim控制隱向量維度太小欠擬合太大容易過擬合fusion_type決定用早期還是晚期融合。改配置比改代碼安全也方便做消融實(shí)驗(yàn)。4.3 訓(xùn)練過程中的指標(biāo)觀察別只看 loss推薦模型的評(píng)估指標(biāo)通常是 RecallK、NDCGK、HitK。工具箱里一般會(huì)在每個(gè) 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列表決定評(píng)估哪些截?cái)辔恢靡话憧?10 和 20 就夠了。參數(shù)上如果 Recall10 一直不漲先檢查數(shù)據(jù)加載有沒有把負(fù)樣本采錯(cuò)再檢查學(xué)習(xí)率是不是太大。注意多模態(tài)推薦里圖像和文本特征的質(zhì)量對(duì)結(jié)果影響很大。如果圖像特征是用隨機(jī)初始化的 CNN 提的那還不如不用。5. 避坑與排查多模態(tài)推薦工具箱最常見的 5 個(gè)翻車點(diǎn)5.1 現(xiàn)象跑第一個(gè) notebook 就報(bào)ModuleNotFoundError: No module named cv2原因工具箱的依賴清單里可能沒寫 opencv-python但圖像預(yù)處理 cell 用到了 cv2。解決pip install opencv-python如果還報(bào)錯(cuò)檢查是不是裝到了系統(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)練時(shí)需要正負(fù)樣本對(duì)如果負(fù)樣本采到了和正樣本同一個(gè)物品或者負(fù)樣本全是熱門物品模型學(xué)不到區(qū)分能力。解決檢查數(shù)據(jù)加載器里的負(fù)采樣邏輯確保負(fù)樣本從用戶未交互的物品里采并且做 popularity 校正。5.3 現(xiàn)象圖像特征和文本特征拼在一起后模型只學(xué)文本那一半原因兩個(gè)模態(tài)的數(shù)值范圍差異太大。圖像特征經(jīng)過 CLIP 歸一化后通常在 -1 到 1 之間文本特征如果沒歸一化可能在 -10 到 10 之間。直接拼接會(huì)讓文本主導(dǎo)梯度。解決拼接前對(duì)每個(gè)模態(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 萬個(gè)物品每個(gè)物品圖像 512 維 float32文本 512 維光特征就占 100000 × 1024 × 4 字節(jié) ≈ 400MB。如果再加上鄰接矩陣和中間激活很容易超過 8GB。解決用 float16 存特征或者分批加載而不是一次性全讀進(jìn)內(nèi)存。5.5 現(xiàn)象換了一個(gè)模型配置文件改了但結(jié)果沒變?cè)騄upyter Notebook 里可能緩存了舊的模型實(shí)例或舊的配置變量。解決改完配置后重啟內(nèi)核或者在 notebook 里顯式重新加載配置和模型。不要指望改了 yaml 文件后當(dāng)前內(nèi)核里的變量會(huì)自動(dòng)更新。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)信號(hào)有沒有被模型用上。參數(shù)上每次只改modality其他超參保持一致否則對(duì)比不公平。如果多模態(tài)比單模態(tài)還差優(yōu)先檢查特征對(duì)齊和歸一化。另一個(gè)驗(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)擊獲取