簡介一份基于阿里巴巴展示廣告點擊率數(shù)據(jù)集的 Python 電商廣告推薦系統(tǒng)源碼面向有一定 Python 基礎、希望把推薦算法落地成完整工程的開發(fā)者和學習者。壓縮包共13個文件以12個 Python 腳本為主另有1個 Markdown 說明文檔整體僅21KB代碼按離線召回、在線推薦、特征存儲、品牌與品類打分等模塊組織目錄結構十分清晰便于快速定位學習。目前已有920人學習下載。項目內(nèi)說明文檔對原始樣本與廣告特征的字段做了說明可幫助理解用戶、廣告、品類、品牌等核心數(shù)據(jù)通過源碼可以掌握 ALS 召回模型的落地寫法、CTR 數(shù)據(jù)分析思路以及如何把離線特征寫入 Redis 供線上推薦模塊調(diào)用。對剛入門推薦系統(tǒng)、想復現(xiàn)電商廣告點擊率預估流程的人而言這是一份輕量但完整的實戰(zhàn)范例也適合用作課程設計或面試項目參考。1. Python電商廣告推薦系統(tǒng)源碼先搞清楚這個 zip 里最值錢的部分在哪拿到一個“Python電商廣告推薦系統(tǒng)源碼.zip”最容易犯的錯是一上來就找模型文件然后把 Item2Vec 或雙塔訓練跑通就覺得完事了。真在廣告場景里待過的工程師都清楚這個 zip 里最值錢的部分是那條從廣告日志到召回、精排、出價排序的完整鏈路而不是某一個單獨的模型。用戶點擊一個商品廣告后系統(tǒng)要在幾十毫秒內(nèi)完成候選壓縮、CTR/CVR 預估、和廣告主出價一起排序這一套流程在 Python 里每一步都有對應實現(xiàn)但每一步也都藏著坑。這篇文章就是順著這個 zip 的常見內(nèi)容拆開講先立住廣告推薦的理論前提再落到樣本構造和可抄的訓練代碼最后把最容易翻車的五個問題和上線前的驗證方法講透。適合有點 Python 基礎、手里正好有類似源碼包、想把離線模型做成線上可用方案的從業(yè)者。2. 電商廣告推薦為什么不能照搬內(nèi)容推薦召回、排序和Embedding的分工2.1 廣告推薦為什么不能照搬內(nèi)容推薦三個本質(zhì)差異做過內(nèi)容推薦的人切換到廣告推薦第一個不適應就是用戶意圖短促得多。刷信息流時用戶有的是時間閑逛點不點一個視頻取決于“感不感興趣”但在電商廣告場景里用戶往往帶著明確購買意圖進來搜“藍牙耳機”就是想買耳機搜不到合適的可能十秒后就走了。這意味著廣告推薦要在更短的決策窗口里把“最可能被點擊且廣告主愿意付費”的商品排到前面。第二個差異是參與方的數(shù)量。內(nèi)容推薦只需要對用戶和內(nèi)容兩方建模廣告推薦卻必須把廣告主也拉進目標函數(shù)。同樣是曝光位A 廣告主的出價是 0.5 元一次點擊B 廣告主出價 2 元一次點擊即便系統(tǒng)預測用戶點 B 的概率略低B 也可能因為出價高而贏得這個展位。這就要引入 eCPM 的概念按預估點擊率 pCTR 乘以出價來排序而不是單純按點擊率排序。第三個差異是位置因素遠比內(nèi)容推薦強烈。同一個廣告放在首屏和放在頁面底部點擊率可能差一個量級。如果模型把“位置好”學成了“這個廣告好”那換個展位后預測就完全失真。所以后來成熟的方案都會把位置單列成特征甚至單獨建模這在普通內(nèi)容推薦里很少被提到。2.2 召回層的職責把百萬級候選壓到兩三千廣告系統(tǒng)的候選商品數(shù)量級通常在百萬甚至千萬精排模型不可能對全量商品做預估必須先做召回。召回的職責不是“找最準”而是“別漏掉”——哪怕多花點算力也不能讓用戶真正想點的商品壓根沒進候選集。最常用的三路召回在這個類型的源碼包中幾乎都能看到。第一路是 Item2Vec把用戶點擊序列當作句子、商品當作詞喂給 Word2Vec訓練出商品向量用用戶最近點擊的向量平均去檢索相近商品。第二路是矩陣分解經(jīng)典 ALS 或 BPR把 user-item 交互矩陣分解成低秩向量。第三路是雙塔內(nèi)積召回用戶塔和廣告塔分別輸出向量用內(nèi)積或余弦相似度做近鄰搜索在線用 Faiss 這類向量檢索引擎召回。三路召回往往還要做“多路合并”。我的習慣是每路設定配額比如 Item2Vec 出 30%、ALS 出 30%、雙塔出 40%合并后去掉重復保證候選集的多樣性。只留一路召回是廣告推薦召回階段最常見的貧血方案——模型再準漏掉的那批用戶意圖商品也補不回來。2.3 排序?qū)拥穆氊焢CTR、pCVR 和 eCPM 出價排序召回把候選壓到幾千條后排序?qū)右饤l做精細預估。正統(tǒng)的廣告排序鏈路分三段粗排用輕量模型把幾千條快速降到幾百條精排用完整特征的大模型對幾百條逐條打 pCTR如果廣告主按轉化付費還要再算 pCVR。精排之后不是直接按點擊率降序輸出而是按 eCPM 排序。這里要單獨強調(diào) eCPM 公式因為它是廣告推薦區(qū)別于所有純推薦系統(tǒng)的關鍵點。點擊競價模式下eCPM pCTR × bid轉化競價模式下eCPM pCTR × pCVR × bid。也就是說精排模型輸出的是概率分數(shù)但真正排在前面的是“概率分數(shù)與廣告主出價的乘積”。如果只把 pCTR 排序當成最終排序等于把廣告主維度徹底丟掉了這在商業(yè)化場景里是不可接受的。2.4 為什么 Embedding 在這里是核心從 ID 向量到在線檢索前面提到的三路召回本質(zhì)上都是 Embedding 的產(chǎn)物。Item2Vec 輸出商品向量ALS 輸出用戶向量和商品向量雙塔輸出的一側是用戶向量、另一側是廣告向量。理解了這點就能明白源碼包里為什么往往有一段“訓練向量 建索引 在線檢索”的代碼召回階段根本不跑模型只是用訓練好的向量去查最近鄰。Embedding 的第二個價值是冷啟動。新廣告沒有點擊歷史無法用協(xié)同過濾但它的 ID 向量可以先初始化為同類目商品的向量平均值或者用文本特征映射進向量空間。這樣新廣告即便沒有曝光也能進候選。第三個價值是離線在線一致性向量可以在離線算好在線只做內(nèi)積運算幾十毫秒內(nèi)返回結果。這比在線重算特征然后跑深度模型要快一個數(shù)量級。3. 廣告日志怎么變成訓練樣本清洗、負采樣和時間窗口3.1 先看日志長什么樣EDR 里哪些字段值得進特征拿到源碼包第一件事不是讀模型代碼而是找數(shù)據(jù) schema。廣告系統(tǒng)最常見的數(shù)據(jù)來源是 EDR 日志每條日志記錄一次曝光事件主要字段通常包括 event_time、user_id、ad_id、item_id、position_id廣告位、scene_id場景 ID、is_click是否點擊、is_convert是否轉化即下單或支付以及廣告主側字段 bid_price出價、creative_id素材 ID。是否要保留全部字段進特征取決于業(yè)務。我的經(jīng)驗是user_id、item_id、position_id 這三個 ID 類特征必須保留曝光和轉化標簽必留bid_price 只用于排序階段不進 CTR 模型的預估值——因為出價是廣告主策略和用戶是否點擊沒有因果關系。creative_id 建議單獨建 Embedding因為同一商品用不同創(chuàng)意圖點擊率差異很大。3.2 負采樣比例怎么定曝光未點擊和隨機負樣本要分開廣告點擊率通常在 0.5% 到 2% 之間正樣本極少。如果把所有曝光未點擊都當負樣本正負比可以到 1:100 甚至更夸張模型會被負樣本徹底淹沒。常見的做法是保留全部正樣本對負樣本按比例采樣整體控制在 1:5 到 1:10 之間。但負采樣要區(qū)分兩種來源選了曝光未點擊的樣本和隨機從未曝光商品里抽的樣本。曝光未點擊代表“用戶見過但沒點”是真實的負反饋要多保留隨機負樣本代表“用戶根本沒見到這個商品”是人為制造的負樣本要控制比例。如果隨機負樣本比例過高模型會學偏——它會把“這個商品沒有曝光給用戶”理解成“用戶不喜歡這個商品”線上推出去后點擊率反而下降。3.3 組裝特征寬表小心時間穿越下面這段代碼是這類源碼包里最常見的樣本構造邏輯把曝光日志和用戶歷史行為拼接成一條樣本每行代表一個“用戶-廣告”二元組。import pandas as pd import numpy as np def build_samples(log_df, click_df, neg_sample_ratio8, seed42): # 正樣本所有點擊行為 pos log_df[log_df[is_click] 1].copy() # 曝光未點擊的負樣本 exp_neg log_df[(log_df[is_click] 0)].copy() # 隨機負樣本從未曝光集合里抽 all_items log_df[item_id].unique() rng np.random.default_rng(seed) exposed set(log_df[log_df[is_click] 1][item_id].unique()) random_negs [] for user_id in pos[user_id].unique(): # 每個正樣本用戶補 random_neg 條隨機未曝光商品 candidates [i for i in all_items if i not in exposed] sampled rng.choice(candidates, sizemin(neg_sample_ratio, len(candidates)), replaceFalse) for item_id in sampled: random_negs.append({user_id: user_id, item_id: item_id, label: 0}) rand_neg_df pd.DataFrame(random_negs) # 合并取合理正負比 df pd.concat([pos, exp_neg, rand_neg_df], ignore_indexTrue) df[label] df[is_click].fillna(0).astype(int) # 特征用戶在 7 天內(nèi)對該商品的點擊次數(shù)、對同類目點擊次數(shù) df[user_item_click_7d] df.apply( lambda r: click_df[(click_df[user_id] r[user_id]) (click_df[item_id] r[item_id]) (click_df[event_time] r[event_time]) # 時間窗口 (click_df[event_time] r[event_time] - 7 * 86400) ].shape[0], axis1) return df這段代碼的關鍵在兩處。時間窗口條件event_time r[event_time]是防“未來特征”的第一道防線——構造特征時只能用預測時刻之前發(fā)生的行為不能用之后的信息7 * 86400是 7 天窗口窗口越長特征越平滑但越滯后窗口越短越靈敏但容易稀疏。neg_sample_ratio控制負采樣強度建議從 8 起步調(diào)參時觀察線上點擊率變化不要盲目加大。4. 可以直接抄進源碼里的四段代碼Item2Vec、ALS、LR 和雙塔4.1 Item2Vec 召回20 分鐘跑通的最小代碼Item2Vec 是把用戶的歷史點擊序列當成句子、商品當成詞來訓練。下面這段代碼可以直接跑唯一的前提是sequences已經(jīng)按用戶和時間排好序。from gensim.models import Word2Vec # sequences 形如 [[item_1, item_3, ...], [item_2, item_5, ...]] # 每個元素是一個用戶按時間排序的點擊商品序列 model Word2Vec( sentencessequences, vector_size64, window5, min_count5, sg1, epochs10, workers4, ) model.wv.save(item_vectors.kv)sg1表示用 skip-gram對低頻商品更友好window5意味著序列中前后 5 個商品互相成為訓練對窗口越大越能捕捉“看完這個再看那個”的長距離關系但也更容易引入噪聲min_count5過濾出現(xiàn)次數(shù)少于 5 次的商品避免冷門商品學出不可靠的向量vector_size64是最小可用維度在百萬商品規(guī)模下通常要放到 128 到 256。訓練完檢查一下輸出。打開item_vectors.kv找?guī)讉€商品看看最近鄰是否合理搜“iPhone 充電器”應該返回數(shù)據(jù)線、耳機這類配件如果返回的是完全不相關的類目多半是序列切分有問題——正樣本序列里混入了太多噪聲點擊。4.2 用 implicit 做 ALS 召回三個必須調(diào)的參數(shù)矩陣分解是召回的老牌方法Python 里最省事的庫是 implicit。ALS 不需要卷積或深度網(wǎng)絡但它的參數(shù)直接影響召回質(zhì)量。import implicit from implicit.als import AlternatingLeastSquares from scipy.sparse import coo_matrix # data: 每行是 user_idx, item_idx, weight # weight 用點擊次數(shù)或置信度點擊 1 次記 1購買記 2 mat coo_matrix((data[weight], (data[user_idx], data[item_idx]))) model AlternatingLeastSquares( factors64, regularization0.01, iterations20, random_state42, ) model.fit(mat) # 給 user_idx 召回 20 個商品 ids, scores model.recommend(user_idx, mat[user_idx], N20)三個重點參數(shù)factors是隱向量維度64 起步維度越大表達力越強但過擬合風險越高regularization是正則系數(shù)0.01 是個保守起點如果召回結果過于集中在熱門商品可以調(diào)到 0.1 試iterations是交替最小二乘的迭代輪數(shù)20 輪夠收斂繼續(xù)加大收益很小但耗時翻倍。這個庫有個隱含細節(jié)傳給fit的稀疏矩陣會被當作“置信度矩陣”數(shù)值越大代表交互強度越高而不是簡單二分類。所以構造矩陣時同一個 user-item 對如果發(fā)生過多次點擊weight建議直接累加而不是只記 1 次。4.3 精排 LR廣告位編號和出價特征一起進模型精排階段不一定上來就上深度模型LR 依然是個很能打的基線。它的優(yōu)勢是可解釋、不易過擬合、訓練快適合先跑通全鏈路再替換成大模型。from sklearn.linear_model import LogisticRegression from sklearn.model_selection import train_test_split # X 的列依次是user_emb(64維), item_emb(64維), # position_id, user_ctr_7d, item_ctr_7d, scene_id X_train, X_val, y_train, y_val train_test_split(X, y, test_size0.2, random_state42) lr LogisticRegression( C1.0, class_weightbalanced, solverliblinear, max_iter200, ) lr.fit(X_train, y_train)class_weightbalanced讓 sklearn 自動按類別頻率調(diào)整權重正樣本少時直接在兩三類正負比下訓練模型幾乎不會輸出“點擊”預測balanced 能立刻緩解這個問題C1.0是正則強度的倒數(shù)調(diào)小 C 會讓權重更小、抗過擬合更強調(diào)大 C 則讓模型更激進地擬合訓練集solverliblinear在小批量稀疏特征上收斂快是處理廣告日志這種高維稀疏數(shù)據(jù)最穩(wěn)的選擇。LR 的預測結果需要看分布直方圖。正常情況是大多數(shù)樣本的 pCTR 集中在 0.01 到 0.1只有少量高于 0.3如果預測分數(shù)出現(xiàn)大量接近 0 或接近 1 的情況說明特征里有泄漏或者正負樣本切分有問題。4.4 雙塔的簡化版本內(nèi)積和溫度系數(shù)雙塔結構如今是廣告召回的主流方案因為在線檢索可以把用戶向量和廣告向量分開算好再內(nèi)積。import torch import torch.nn as nn class TwoTower(nn.Module): def __init__(self, n_user, n_item, dim64): super().__init__() self.user_emb nn.Embedding(n_user, dim) self.item_emb nn.Embedding(n_item, dim) self.user_layer nn.Linear(dim, dim) self.item_layer nn.Linear(dim, dim) def forward(self, user_ids, item_ids): u self.user_layer(self.user_emb(user_ids)) v self.item_layer(self.item_emb(item_ids)) return (u * v).sum(dim1) model TwoTower(n_user, n_item, dim64) # 訓練策略正樣本對 label1batch 內(nèi)隨機采其他物品做負樣本 # 損失用 BCEWithLogits輸出 logit 過 sigmoid 即為 pCTRdim64同樣是向量維度self.user_layer和self.item_layer讓兩個塔不是單純的 Embedding 查表而是各學一層非線性變換表達力更強代價是訓練時間變長。用內(nèi)積而不是余弦相似度內(nèi)積保留向量的模長信息更接近點擊率建模的原始需求如果換成余弦要額外加一個溫度系數(shù)否則所有分數(shù)會被壓縮到很窄的區(qū)間難以區(qū)分好壞樣本。雙塔最常見的誤區(qū)是兩個塔的輸入特征不對稱用戶塔只用了 ID廣告塔卻塞了大量文本和價格特征。實踐里要保證兩個塔的特征復雜度大體匹配否則訓練會偏向特征更豐富的那一側。5. 電商廣告推薦的五個翻車現(xiàn)場現(xiàn)象、原因和解決辦法5.1 正樣本比例失衡模型只會對熱門廣告位點頭現(xiàn)象訓練完成后打印預測分布發(fā)現(xiàn)模型對幾乎所有樣本都輸出“不點擊”哪怕在正樣本集合上預測概率也只有 0.1 上下。線上 A/B 一看總體點擊率沒有提升熱門展位反而掉了。原因正負樣本比例 1:100 時LR 或神經(jīng)網(wǎng)絡不設置任何類別權重學到的決策邊界幾乎全是負樣本的形態(tài)。更隱蔽的是模型學到了“position_id 越大越不點擊”的假規(guī)律——因為大展位的曝光量大、負樣本絕對數(shù)量多。解決先給正樣本加權重class_weightbalanced是最快的干預更徹底的辦法是把 position_id 單獨作為偏置項加入模型輸出pCTR sigmoid(user_item_score position_bias)線上排序時把 position_bias 置零讓排序不依賴位置。這個“位置偏置校正”的做法在廣告和搜索領域已經(jīng)是標配源碼包里如果沒實現(xiàn)建議自己補上。5.2 離線 AUC 很漂亮線上點擊率反而崩了現(xiàn)象離線測試 AUC 0.82團隊信心滿滿上了全量第二天看線上點擊率下降 15%。回看數(shù)據(jù)發(fā)現(xiàn)離線評估時窗口混用了未來數(shù)據(jù)。原因特征工程里用了“當天是否下單”“當天是否加購”之類的標簽特征這些信息在訓練時可用的實際預測時刻并不存在是典型的時間穿越。AUC 被這些未來信息抬得虛高線上完全沒有對應特征模型自然失效。解決切數(shù)據(jù)集必須按時間切訓練集和驗證集以某個時間點為界驗證集不能出現(xiàn)任何訓練集時間之后的樣本構造特征時強制要求event_time 預測時刻這樣的窗口約束。我在每次特征上線前都會跑一遍“延遲回放”用幾天前的特征數(shù)據(jù)模擬當天的預測對比預測值和實際值的差距這個驗證方法能抓住大多數(shù)時間穿越問題。5.3 負采樣過度離線 AUC 虛高線上召回質(zhì)量下降現(xiàn)象把負采樣比例調(diào)到 1:50 之后離線 AUC 仍有上漲但線上的點擊率沒有同步提升且廣告主反饋曝光量下降。原因負采樣比例過高模型學會了區(qū)分“真實曝光”和“人為采樣”而不是區(qū)分“用戶喜歡什么”和“用戶不喜歡什么”。離線 AUC 只能說明模型能分開訓練集里的正負樣本但線上曝光分布和訓練分布已經(jīng)不一致。解決把曝光未點擊的負樣本全部保留只對隨機負樣本做采樣且隨機負樣本不超過正樣本的 5 倍。同時要看線上指標離線 AUC 只能用來做模型版本之間的對比不能作為放量依據(jù)。要根治線上線下不一致還要在訓練時對采樣后的樣本做重要性加權。5.4 只看 AUC 不校準eCPM 排序被系統(tǒng)性帶偏現(xiàn)象新模型的 AUC 比舊模型高 0.02替換上線后廣告收入持平點擊率也沒提升。原因AUC 衡量的是“排序能力”不保證模型輸出的概率是真實概率。比如模型對所有樣本的 pCTR 都低估一倍排序順序完全不變AUC 依然很高。但廣告排序用的是 eCPM pCTR × bidpCTR 被系統(tǒng)性低估后低出價的優(yōu)質(zhì)廣告會被錯誤地排到后面收入自然沒變化。解決補做概率校準。把訓練好的模型在時間窗口外的數(shù)據(jù)上預測畫校準曲線看預測概率和實際點擊率是否一致偏差大就用溫度縮放或 Platt Scaling 校正。校準是廣告推薦上線前必須做的步驟很多源碼包里沒有需要自己補。5.5 跑源碼先翻車在環(huán)境Python 版本、NumPy 和內(nèi)存現(xiàn)象import implicit報錯、Word2Vec訓練時內(nèi)存暴漲、NumPy 版本沖突導致 scipy 調(diào)用失敗。這類問題占了拿到新源碼包后 70% 的調(diào)試時間。原因源碼包可能是在 Python 3.8 NumPy 1.x 的環(huán)境下寫的而你本機是 Python 3.11 NumPy 2.ximplicit 這類底層 C 庫依賴版本鎖得比較緊。加上商品向量維度高、日志量大內(nèi)存不夠就會在訓練中途被殺進程。解決先為本項目單獨建一個虛擬環(huán)境不要直接裝進全局裝依賴時優(yōu)先看源碼包里是否帶 requirements.txt 或 environment.yml按鎖定的版本裝。如果 implicit 編譯失敗優(yōu)先處理pip install implicit --no-cache-dir大概率能解決編譯器找不到的問題內(nèi)存爆炸則下調(diào)min_count或vector_size先跑通再逐步加大到生產(chǎn)規(guī)模。6. 上線前拿這三個指標自檢召回覆蓋率、NDCG 和校準曲線6.1 召回覆蓋率看召回是否“只見熱門”離線召回測試不能只看 hit rate還要看覆蓋率——召回結果里究竟覆蓋了多少不同的商品以及新商品有沒有機會進入候選集。如果百萬商品里召回的熱門商品占了九成冷門商品幾乎見不到說明召回模型被“馬太效應”困住了廣告主投放新商品的空間就沒有了。我的習慣是把覆蓋率作為召回階段的第一自檢指標低于 50% 就要調(diào)整負采樣和熱度的平衡。6.2 NDCG廣告列表的質(zhì)量不只是“點沒點”點擊和不點擊是很粗的二分廣告場景里轉化價值不同。用戶點了但沒下單和點了直接支付對廣告主的價值完全不同。NDCG 能處理這種分級轉化算 1 分點擊算 0.5 分單純曝光算 0 分然后按位置折損。上線前我會對比新舊模型在 NDCG5 和 NDCG10 上的差異NDCG 持平而 AUC 提高說明提升在排序而不是在概率預測上。6.3 校準曲線和分數(shù)分布畫兩張圖再做決定校準必須在上線前做下面這段代碼畫出校準曲線直接判斷 pCTR 是否“說真話”。from sklearn.calibration import calibration_curve import matplotlib.pyplot as plt prob_true, prob_pred calibration_curve(y_true, y_score, n_bins10) plt.plot(prob_pred, prob_true, markero) plt.plot([0, 1], [0, 1], r--) plt.xlabel(predicted CTR) plt.ylabel(actual CTR) plt.show()如果點全部落在紅色參考線上方模型在低估點擊率落在下方則高估。排序順序不受影響的“低偏差”可以勉強接受但幅度超過 20% 就嚴重影響 eCPM 排序。我上線前只看兩張圖一張校準曲線一張 pCTR 分布直方圖。分布直方圖能暴露 5.1 節(jié)說的“模型只預測一個常數(shù)”以及 5.2 節(jié)說的“分數(shù)極端化”這兩張圖都正常才敢放小流量 A/B。用這套方法做下來不敢說零踩坑但至少能保證拿到手的源碼包在跑通之后不是“黑匣子”。這幾年做的廣告推薦項目里最深刻的教訓就是模型只是鏈路里最小的一塊召回覆蓋率、位置偏置和概率校準才是真正決定線上效果的三塊基石。希望幫到你。本文還有配套的精品資源點擊獲取