摘要本文围绕一个电商商品混合推荐项目展开重点使用 UCI Machine Learning Repository 的 Online Retail 公开交易数据集。项目把真实发票明细转换为users.csv、products.csv、interactions.csv三张推荐系统核心表再完成隐式反馈建模、用户/商品特征构造、混合推荐训练、Top-N 推荐、评估指标计算、HTML 报告生成和截图展示。本次真实运行保留了 180 个客户、320 个商品、53349 条购买交互。项目按--backend auto选择稳定后端在 Windows 编译版 LightFM 对 WARP/BPR 排序损失不稳定时会自动使用fallback_svd_content即 SVD 协同信号 商品内容特征 热度分数融合。源码仍保留 LightFM 后端如果希望验证编译版 LightFM可使用--backend lightfm --loss logistic。本文所有指标图、推荐列表、报告截图均由本项目代码真实运行生成。关键词推荐系统、LightFM、电商推荐、混合推荐、隐式反馈、UCI Online Retail、Top-N 推荐、Python 项目实战真实数据与业务场景电商推荐系统的核心输入通常不是显式评分而是浏览、收藏、加购、购买等行为。UCI Online Retail 数据集记录了一家英国线上零售商在 2010-12-01 至 2011-12-09 之间的真实交易明细字段包含InvoiceNo、StockCode、Description、Quantity、InvoiceDate、UnitPrice、CustomerID和Country。这些字段非常适合改造成推荐系统中的用户、商品、行为三张表。下面这张真实商品陈列图来自 Wikimedia Commons用来对应电商商品推荐的业务语境真实平台里商品有价格、品类、陈列位置和库存变化推荐系统需要在大量 SKU 中为用户选出更可能购买的候选商品。项目新增了scripts/prepare_uci_online_retail.py用于把 UCI 原始 Excel/zip 文件转换成项目可直接读取的 CSV。转换时保留真实CustomerID和StockCode并派生出推荐模型需要的字段目标文件来源与处理方式作用users.csv由CustomerID聚合得到偏好类目和价格偏好来自历史购买行为构建用户特征products.csv由StockCode、Description、UnitPrice和Country聚合得到构建商品特征interactions.csv每条有效购买记录转换为一次purchase隐式反馈构建用户-商品交互矩阵source_summary.json保存原始行数、保留规模和时间范围方便复现实验本次运行的数据概览如下。可以看到交易在 2011 年下半年逐渐升高商品主要集中在家居装饰、通用礼品、收纳袋盒和厨具餐具等类目价格带也被拆成低价、中价和高价三档。系统流程与模型实现项目流程可以概括为真实交易数据进入数据转换脚本生成用户特征、商品特征和交互行为再进入混合推荐模型输出 Top-N 推荐列表和 HTML 报告。下面这张流程图根据本项目实际流程绘制图中只保留中文模块标签便于直接放进中文博客正文。核心代码入口是main.py。它会加载三张 CSV调用temporal_train_test_split做时间切分然后通过build_recommender选择推荐后端。若当前环境能导入lightfm--backend auto会使用 LightFM若不能导入则自动使用 fallback 后端避免读者在 Windows 编译环境上卡住。python main.py--userCUS_14646 --top-k8--backendautoLightFM 后端的思路是把用户 ID、用户画像、商品 ID、商品画像一起放入矩阵分解模型中。这样模型不仅学习“谁买过什么”还学习“什么样的用户更偏好什么类商品”。对于真实电商数据这种混合建模比单纯协同过滤更适合处理冷启动和长尾商品。fallback 后端不是简单热门榜。它先用 TruncatedSVD 学习用户-商品矩阵中的协同信号再用商品类目、品牌、价格带、标签计算内容相似度最后融合少量热度分数final_score 0.62 * collaborative_score 0.33 * content_score 0.05 * popularity_score这套后端让项目在没有 LightFM 的机器上仍然能跑出真实推荐结果同时保持“行为协同 商品内容”的混合推荐结构。真实运行结果本次运行命令为python main.py--userCUS_14646 --top-k8--backendauto本次验证使用fallback_svd_content稳定后端。训练集包含 51296 条交互测试集覆盖 180 个用户。程序生成了推荐 CSV、评估 JSON、模型文件、结果图和 HTML 报告。目标用户CUS_14646的 Top-8 推荐如下商品名称和 SKU 来自 UCI Online Retail 的真实商品描述item_idtitlecategorypriceprice_bucketscorereasonSKU_22197Popcorn HolderBags_Storage0.85budget0.2792matches Bags_Storage preference; fits budget price preferenceSKU_22379Recycling Bag RetrospotBags_Storage2.10mid0.2655matches Bags_Storage preferenceSKU_23202Jumbo Bag Vintage LeafBags_Storage2.08mid0.2605matches Bags_Storage preferenceSKU_21915Red Harmonica In BoxBags_Storage1.25budget0.2603matches Bags_Storage preference; fits budget price preferenceSKU_21914Blue Harmonica In BoxBags_Storage1.25budget0.2520matches Bags_Storage preference; fits budget price preferenceSKU_84692Box Of 24 Cocktail ParasolsBags_Storage0.42budget0.2429matches Bags_Storage preference; fits budget price preferenceSKU_21889Wooden Box Of DominoesBags_Storage1.25budget0.2416matches Bags_Storage preference; fits budget price preferenceSKU_21232Strawberry Ceramic Trinket BoxBags_Storage1.25budget0.2400matches Bags_Storage preference; fits budget price preference推荐分数图能更直观看出排序差异。前几名都集中在Bags_Storage说明该用户历史行为中收纳袋盒类商品偏好很强模型在过滤已购买商品后继续推荐相近 SKU。评估指标来自时间切分测试每个用户优先留出最近一次“首次购买”的商品作为测试目标训练阶段只使用此时间点之前的历史记录避免把已过滤商品作为不可命中的测试答案。本次结果如下指标结果含义Precision80.0160Top-8 推荐中命中的平均比例Recall8 / HitRate80.1278180 个用户中有 12.78% 的留出商品进入 Top-8MRR80.0535命中商品越靠前该值越高Catalog Coverage0.8250推荐结果覆盖了 82.5% 的商品池需要注意UCI Online Retail 是交易数据不是曝光日志因此离线评估只能验证“历史购买倾向能否被召回”不能等同于线上点击率或转化率。若用于真实业务还需要曝光日志、负采样、A/B 测试和多目标重排。源码结构与复现方法资源包中的源码目录保持教学项目常见结构重点文件如下lightfm_ecommerce_hybrid_recommender/ ├── main.py ├── app.py ├── scripts/ │ └── prepare_uci_online_retail.py ├── src/ │ ├── data_generator.py │ ├── features.py │ ├── recommender.py │ ├── evaluation.py │ ├── visualization.py │ └── report.py ├── demo_data/ │ ├── users.csv │ ├── products.csv │ ├── interactions.csv │ └── source_summary.json ├── outputs/ ├── images/ └── docs/如果只想复现本文结果直接安装最小依赖并运行主程序即可pipinstall-rrequirements.txt python main.py--userCUS_14646 --top-k8--backendauto如果希望重新从 UCI 原始 zip 生成三张 CSV可以运行python scripts/prepare_uci_online_retail.py ^--sourcepath/to/onlineretail.zip ^ --out-dir demo_data ^ --top-users180^ --top-items320^ --min-user-events8如果当前 Python 版本和系统编译环境支持 LightFM可以安装完整后端。Windows 环境建议先用logistic损失验证编译版 LightFM 是否稳定pipinstall-rrequirements-lightfm.txt python main.py--userCUS_14646 --top-k8--backendlightfm--losslogistic运行后重点查看这些输出outputs/recommendations_CUS_14646.csv outputs/evaluation_metrics.json outputs/recommendation_report.html images/results/report_browser_screenshot.png images/results/real_data_overview.png images/results/top_recommendations_user_CUS_14646.png下面这张仪表盘图片也由项目代码生成可作为报告或答辩材料中的结果总览。项目扩展方向这个项目已经完成“真实数据转换、混合推荐训练、指标评估、报告输出”的闭环。如果继续扩展可以从三个方向入手。第一加入更细的行为权重。UCI 数据中主要是购买记录如果换成真实平台日志可以把曝光、点击、收藏、加购、购买、退款拆成不同权重形成更细的隐式反馈强度。第二增加候选召回和重排。当前项目直接对商品池排序适合教学规模真实业务可先用协同过滤、内容相似、热门新品等多路召回再用 LightFM 或学习排序模型重排。第三完善可解释推荐。现在的 reason 字段来自类目和价格带匹配后续可以输出中文理由例如“你近期购买过收纳袋盒类商品”“该商品价格带符合你的历史偏好”“相似客户近期也购买过该 SKU”。总结本项目实现了一个基于真实公开交易数据运行的 LightFM 思路电商混合推荐系统。博客包中的截图、指标图和推荐结果均由本地代码真实生成资源包中也包含数据转换脚本、运行后的 CSV/JSON/HTML 报告和测试文件。对于课程设计、CSDN 项目实战或推荐系统入门来说它的价值不只是“能跑”而是展示了从真实交易明细到 Top-N 商品推荐的完整工程链路。参考资料LightFM GitHubhttps://github.com/lyst/lightfmLightFM Documentationhttps://making.lyst.com/lightfm/docs/UCI Online Retail Datasethttps://archive.ics.uci.edu/dataset/352/online%2BretailWikimedia Commons 图片 https://commons.wikimedia.org/wiki/File:Laptops_in_store_20170514.jpg