简介这是一份面向Python初学者与推荐算法入门者的实战项目源码包围绕小说推荐场景提供从数据采集到推荐结果展示的完整实现思路适合课程设计、毕业设计或自学练手使用。压缩包共16个文件约125KB包含4个py脚本、4个csv数据集、4个xml配置、1个txt文本及md说明等分别承担推荐逻辑、爬虫抓取、界面交互与数据存储等职责结构紧凑便于快速理解项目全貌。目前已有362人学习下载说明该案例在同类练手项目中具有一定参考价值。源码附带超详细注释读者可据此梳理协同过滤或相似度推荐的基本流程结合示例数据调试推荐效果并参考界面脚本搭建可视化交互入口从而掌握推荐系统从数据准备到结果输出的关键环节也可在此基础上替换数据集或调整算法参数进行二次开发。1. 小说推荐系统从零落地为什么协同过滤仍是首选基线打开任何一个小说平台书架里躺着几百本“追更中”和“已弃坑”用户真正想找的下一本往往藏在行为数据里。基于 Python 实现的小说推荐系统核心要解决的就是“用户没搜、没点但大概率会喜欢”的预测问题。它适合两类人一类是刚学完 Python 基础语法、想找一个完整项目练手的入门者另一类是想把推荐能力嵌进阅读类产品的后端工程师。这个标题里的“源码超详细注释”意味着交付物是一套可运行、可读、可改的工程代码而不是一段演示脚本。我一般会把这类项目拆成数据层、算法层、服务层三块先跑通 ItemCF 基线再谈向量召回和排序。下面按落地顺序讲清楚每一步怎么做、参数怎么调、哪里容易翻车。2. 数据准备与工程骨架把原始行为日志变成可训练的评分矩阵2.1 小说推荐系统的数据从哪来、长什么样推荐系统的上限由数据决定。小说场景下最核心的三类数据是用户对书籍的显式评分1-5 星、隐式行为阅读时长、章节完成率、加入书架、评论、书籍元信息分类、标签、作者、字数。显式评分稀疏但语义明确隐式行为稠密但需要折算成置信度。常见做法是把“读完一章”记 1 分“加入书架”记 3 分“评分”直接用原始分值再按时间衰减加权。数据文件通常存成 CSV字段包括 user_id、book_id、rating、timestamp元信息单独一张表用 book_id 关联。注意不要用“点击”作为正样本唯一来源小说阅读的点击成本极低误点率很高单靠点击训练出来的模型会把封面好看的书推爆。2.2 用 pandas 构建用户-物品评分矩阵拿到日志后第一步是清洗和透视。下面这段代码把原始行为表聚合成评分矩阵并处理重复行为。import pandas as pd import numpy as np # 读取行为日志假设字段为 user_id, book_id, behavior_type, value, ts logs pd.read_csv(behavior_logs.csv) # 行为权重映射不同行为折算成统一评分 weight_map {read_chapter: 1.0, add_shelf: 3.0, rate: None, comment: 2.0} def to_rating(row): if row[behavior_type] rate: return float(row[value]) # 显式评分直接用 return weight_map.get(row[behavior_type], 0.0) logs[rating] logs.apply(to_rating, axis1) # 同一用户对同一本书多次行为取最大值避免刷行为抬高权重 matrix_df logs.groupby([user_id, book_id], as_indexFalse)[rating].max() # 透视成用户-物品矩阵缺失值填 0 rating_matrix matrix_df.pivot(indexuser_id, columnsbook_id, valuesrating).fillna(0) print(rating_matrix.shape) # 例如 (5000, 12000)逻辑说明weight_map把异构行为统一到同一量纲groupby max是防止同一用户反复“加入书架”把分数堆高。pivot之后矩阵非常稀疏5000 个用户对 12000 本书的评分密度通常不到 2%。参数方面权重值不是固定的阅读类产品可以把“读完”权重调到 2.0 以上时间衰减因子建议按半衰期 30 天计算超过半年的行为乘 0.5 以下。2.3 稀疏矩阵存储与冷启动用户的处理稠密 DataFrame 在用户量上万后会吃光内存生产环境一般转成 scipy 的 CSR 矩阵。同时要预留冷启动策略新用户没有任何行为时走热门榜或分类热度榜兜底等积累到 5 条以上行为再切入个性化召回。from scipy.sparse import csr_matrix sparse_matrix csr_matrix(rating_matrix.values) print(非零元素占比: %.4f % (sparse_matrix.nnz / (sparse_matrix.shape[0] * sparse_matrix.shape[1]))) # 冷启动兜底按书籍平均分和评分人数排序 book_stats matrix_df.groupby(book_id)[rating].agg([mean, count]) hot_books book_stats[book_stats[count] 20].sort_values(mean, ascendingFalse).head(50)这里count 20是热度门槛低于这个数的书均分波动极大不适合直接推给新用户。这个阈值要根据自己平台的书籍总量调整书少就降到 10书多可以提到 50。3. 协同过滤核心实现ItemCF 与 UserCF 的选型与代码落地3.1 为什么小说场景优先选 ItemCFUserCF 找“和你相似的人”ItemCF 找“和你读过的书相似的书”。小说阅读的兴趣漂移比电商慢但品类跨度大一个用户可能同时看玄幻和言情UserCF 的相似用户群会被稀释。ItemCF 的稳定性更好一本书的相似书列表可以离线算好、缓存复用线上只需查表加权。常见做法是用 ItemCF 做召回再用一个轻量排序模型精排。相似度用余弦公式是两本书共同评分用户向量的夹角余弦。3.2 ItemCF 相似度矩阵的完整计算代码from sklearn.metrics.pairwise import cosine_similarity # rating_matrix 是 DataFrame行是用户列是书 item_matrix rating_matrix.T.values # 转置后行是书列是用户 item_sim cosine_similarity(item_matrix) # 形状 (n_books, n_books) # 只保留每本书最相似的 topK其余置零降低存储和噪声 K 20 item_sim_df pd.DataFrame(item_sim, indexrating_matrix.columns, columnsrating_matrix.columns) for book in item_sim_df.index: topk_idx item_sim_df[book].nlargest(K 1).index[1:] # 去掉自身 mask ~item_sim_df.columns.isin(topk_idx) item_sim_df.loc[book, mask] 0.0 print(item_sim_df.iloc[:5, :5])逻辑说明cosine_similarity直接吃 numpy 数组输出对称矩阵。nlargest(K1)取 topK 时多取一个是为了排除自身自身相似度恒为 1。参数 K 是召回多样性和准确率的平衡点K 太小如 5推荐结果同质化严重K 太大如 100会引入弱相关书籍拉低点击率。小说场景我一般从 20 起步A/B 测试时在 15 到 40 之间扫。3.3 基于相似度矩阵生成 TopN 推荐拿到相似度矩阵后对每个用户把他历史评分的书作为“种子”按相似度加权累加候选书的得分。def recommend_for_user(user_id, rating_matrix, item_sim_df, topN10): if user_id not in rating_matrix.index: return [] # 冷启动交给兜底策略 user_ratings rating_matrix.loc[user_id] interacted user_ratings[user_ratings 0].index scores pd.Series(0.0, indexitem_sim_df.columns) for book in interacted: sim_vec item_sim_df[book] scores sim_vec * user_ratings[book] # 评分作为权重 scores scores.drop(interacted, errorsignore) # 过滤已读 return scores.nlargest(topN).index.tolist() print(recommend_for_user(1001, rating_matrix, item_sim_df))逻辑说明scores sim_vec * user_ratings[book]是加权求和用户给过 5 分的书对推荐结果影响更大。drop(interacted)必须做否则会把用户已经读过的书再推一遍这是最常见的翻车点。参数 topN 线上一般取 50 到 200 作为召回集再交给排序层截断到 10 到 20 展示。3.4 评估指标离线 RecallK 与覆盖率怎么算离线评估不能只看准确率否则推荐会收敛到少数热门书。常用组合是 RecallK 加覆盖率。指标含义计算方式小说场景参考值RecallK前 K 个推荐命中测试集的比例命中数 / 测试集总数0.08-0.15Coverage被推荐过的书占总书数比例去重推荐书数 / 总书数0.3 以上Novelty推荐结果的平均冷门程度平均 -log(书籍热度占比)越高越多样计算时按时间切分用前 80% 时间的行为训练后 20% 做测试避免用未来数据预测过去。4. 避坑与排查小说推荐系统落地时最容易翻车的 5 个点4.1 现象推荐结果全是同一本书的不同版本原因数据里同一本书有多个 book_id不同渠道、不同 ISBN相似度计算时把它们当成不同物品互相之间相似度极高导致推荐列表被同一内容占满。解决在数据清洗阶段做书籍去重按书名作者做归一化保留一个主 book_id其余映射过去。4.2 现象离线指标很好线上点击率却很低原因离线评估用了随机切分测试集里混入了训练集同期的行为存在数据泄漏。解决严格按时间切分并且训练集里出现过的用户-书籍对在测试集评估时要排除否则模型只是记住了历史。4.3 现象新用户推荐结果永远是那几本热门书原因冷启动兜底策略只用了全局热度没有做分类多样性。解决热门榜按分类分别取 TopN再轮询展示保证新用户第一屏能看到不同品类。同时记录新用户的首次点击尽快切换到个性化召回。4.4 现象相似度矩阵计算时内存溢出原因书籍数量上万后cosine_similarity输出的是 n×n 稠密矩阵12000 本书就是 1.44 亿个浮点数约 1.1 GB加上中间变量直接爆内存。解决用稀疏矩阵的sklearn.metrics.pairwise.cosine_similarity对 CSR 输入会返回稀疏结果或者分块计算每次只算 1000 本书的相似度。4.5 现象推荐结果更新滞后新书上不了榜原因ItemCF 的相似度矩阵是离线全量计算的新书没有足够行为相似度全是零。解决设置一个“新书探索”通道新书按分类和标签匹配直接插入召回集给固定曝光位积累到 50 条行为后再纳入协同过滤。5. 从离线到线上用 Flask 把推荐结果包成 API 并做缓存5.1 最小可用的推荐服务接口离线算好的相似度矩阵和推荐结果存成 pickle 或 parquet线上服务启动时加载进内存。下面是一个 Flask 接口示例。from flask import Flask, request, jsonify import pickle app Flask(__name__) with open(item_sim.pkl, rb) as f: item_sim_df pickle.load(f) with open(rating_matrix.pkl, rb) as f: rating_matrix pickle.load(f) app.route(/recommend, methods[GET]) def recommend(): user_id int(request.args.get(user_id)) topN int(request.args.get(topN, 10)) books recommend_for_user(user_id, rating_matrix, item_sim_df, topN) return jsonify({user_id: user_id, books: books}) if __name__ __main__: app.run(host0.0.0.0, port5000)逻辑说明pickle.load在服务启动时一次性加载避免每次请求都读磁盘。recommend_for_user是第 3 章定义的函数。参数 topN 通过 query string 传入默认 10。生产环境要把这个接口前面加一层 Redis 缓存key 用rec:{user_id}过期时间设 10 到 30 分钟因为相似度矩阵不是实时更新的。5.2 缓存策略与降级方案推荐接口的响应时间要求通常在 50ms 以内纯 Python 循环计算 topN 在用户行为多的时候会超。常见做法是离线为每个活跃用户预计算好推荐列表存 Redis线上直接读。不活跃用户走实时计算或热门兜底。降级方案要提前写好Redis 挂了就返回热门榜保证接口不 500。import redis, json r redis.Redis(hostlocalhost, port6379, db0) def get_recommend_cached(user_id, topN10): key frec:{user_id} cached r.get(key) if cached: return json.loads(cached)[:topN] books recommend_for_user(user_id, rating_matrix, item_sim_df, topN) r.setex(key, 1800, json.dumps(books)) # 缓存 30 分钟 return bookssetex的 1800 秒是经验值行为更新频繁的平台可以降到 600 秒但会增加计算压力。缓存 key 要加版本号前缀模型更新时整体失效避免新旧结果混用。6. 进阶技巧用矩阵分解补足协同过滤的稀疏短板ItemCF 在行为稀疏时召回质量下降明显这时候可以引入矩阵分解做向量召回。核心思路是把用户-物品评分矩阵分解成两个低秩矩阵用户向量和物品向量的内积逼近原始评分。用surprise库或implicit库都能快速实现下面用surprise做一个 SVD 基线。from surprise import SVD, Dataset, Reader from surprise.model_selection import train_test_split reader Reader(rating_scale(0, 5)) data Dataset.load_from_df(matrix_df[[user_id, book_id, rating]], reader) trainset, testset train_test_split(data, test_size0.2, random_state42) algo SVD(n_factors50, n_epochs20, lr_all0.005, reg_all0.02) algo.fit(trainset) predictions algo.test(testset) # 为指定用户生成推荐 def svd_recommend(user_id, algo, rating_matrix, topN10): interacted rating_matrix.loc[user_id] interacted interacted[interacted 0].index candidates [b for b in rating_matrix.columns if b not in interacted] preds [(b, algo.predict(user_id, b).est) for b in candidates] preds.sort(keylambda x: x[1], reverseTrue) return [b for b, _ in preds[:topN]]参数说明n_factors50是隐向量维度小说场景 30 到 80 都常见维度太高会过拟合n_epochs20是迭代轮数看验证集 RMSE 不再下降就停lr_all0.005是学习率太大震荡、太小收敛慢reg_all0.02是正则化系数防止隐向量数值爆炸。SVD 的输出是评分预测排序时直接用est降序。实际落地时我会把 ItemCF 和 SVD 的召回结果合并去重各取 Top50 组成 100 个候选再用一个简单的 LR 或 GBDT 排序模型融合特征线上 CTR 通常比单路召回高 10% 到 20%。最后说一个我自己的习惯每次改完相似度计算或召回逻辑先跑一遍离线评估脚本把 RecallK、Coverage、Novelty 三个数打出来对比不要凭感觉判断“这次推荐好像更准了”。推荐系统的玄学在于你觉得准的用户不一定点数据说准的才是真的准。希望帮到你。本文还有配套的精品资源点击获取
