简介这是一份面向Python学习者的音乐推荐系统完整项目包围绕“跟着迪哥学python”系列配套数据与源代码整理而成适合想掌握推荐算法从数据处理到模型落地完整流程的开发者。项目以Jupyter Notebook和Python脚本为主要载体清晰组织数据清洗、特征工程、推荐引擎构建等关键环节csv数据表与db数据库提供开箱即用的实验数据png图片则直观展示中间过程与结果方便对照检查与调试。压缩包共包含十七个文件以ipynb交互脚本、py功能模块、csv数据表、png图片及db数据库为主整体大小约228.4MB结构紧凑、层次分明便于按需检索。目前已有五千七百五十三人学习使用无论是课程设计、毕业设计还是个人技能进阶都可借助这份资料快速搭建音乐推荐原型并基于已有代码二次开发。1. 一个能落地的音乐推荐系统从播放记录到TopN歌单做推荐系统最让人沮丧的不是算法选型而是拿到一份几十万行的用户播放记录之后不知道这一步该干什么、下一步该做什么。这个项目就是冲着这个问题来的它把一套完整的音乐推荐流程拆成了可运行的Python代码从原始听歌行为出发经过清洗、去噪、构建用户物品矩阵用基于物品的协同过滤计算歌曲相似度最后为每个用户生成TopN推荐歌单并且自带离线评估脚本能直接看到准确率和召回率。对想快速落地的人来说这套代码最大的价值是整条链路是通的。不需要GPU不需要深度学习框架装好pandas和NumPy就能把全部模块跑通。它适合两类人一类是想亲手实现协同过滤而不是只会调接口的Python开发者另一类是课程设计或毕业设计需要一个完整案例的学生。下载解压后按项目里的目录结构把数据和代码对应放好就能一步步把推荐结果跑出来。2. 技术栈与整体架构先搞清楚数据在项目里怎么流动2.1 技术选型为什么是pandasNumPy而不是深度学习框架这个项目没有用TensorFlow或PyTorch那一套原因很务实音乐推荐的协同过滤算法本质上是相似度计算和矩阵运算经典方法在数据量不够大时反而比深度学习稳定而且更容易排查问题。整个项目的数据处理全部基于pandas矩阵运算基于NumPy相似度计算和归一化用了一些scikit-learn的工具函数。这三个库组合起来已经能覆盖从数据清洗到推荐结果的完整链路。不用现成的推荐算法库比如Surprise也是一个刻意的选择。那些库把相似度计算、邻居选择、评分预测全部封装成了黑匣子调两行代码就出结果但对理解原理没有帮助。这个项目把每一步都摊开了写保留了大量中间结果的打印和检查逻辑方便二次开发时按自己的需求改算法。如果后面想换矩阵分解或者引入深度学习只需要替换相似度计算那一个模块其他部分不用动。数据集是公开的音乐行为数据包含三个核心字段用户ID、歌曲ID、播放次数。原始数据是CSV格式大约几十万行模拟了真实的播放日志场景。项目里还附带了一份清洗过的示例数据可以直接用来验证流程不用自己去网上找数据。2.2 目录结构十个文件把推荐流程拆得明明白白项目解压后的目录结构如下模块划分比较清晰每个文件只干一件事music_rec_system/ ├── data/ │ ├── raw/ # 存放原始播放记录 user_behavior.csv │ └── processed/ # 清洗后产出的中间文件 ├── src/ │ ├── data_preprocess.py # 数据清洗去重、过滤异常、归一化 │ ├── build_matrix.py # 构建用户-物品评分矩阵 │ ├── similarity.py # 相似度计算余弦/皮尔逊 │ ├── recommend.py # ItemCF推荐逻辑 │ └── evaluate.py # 离线评估准确率、召回率 ├── config.py # 全局参数配置 ├── run.py # 主入口串联整个流程 └── requirements.txt # 依赖清单src目录下五个Python文件对应推荐系统的五个标准步骤顺序是严格固定的先清洗数据再构建矩阵接着算相似度然后做推荐最后评估。run.py是总入口它做的事情只有一件按照config.py里的配置依次调用这五个模块并把关键指标打印出来。我比较欣赏的是它把config.py单独拎出来而不是把参数散落在各个文件里。推荐邻居数、TopN长度、相似度阈值、播放次数过滤下限全部集中在同一个文件里。改参数的时候不需要去翻算法代码对新手非常友好。2.3 数据流从原始播放日志到推荐结果的完整路径数据在项目里的流动路径是这样的原始播放记录CSV → data_preprocess.py 清洗 → 过滤异常用户和物品播放次数做对数变换 → build_matrix.py 构建用户-物品矩阵 → similarity.py 计算物品间相似度 → recommend.py 为每个用户生成TopN推荐 → evaluate.py 评估并输出指标这个流程里有一个容易被忽略的点清洗之后的数据会落盘到data/processed目录后续步骤直接读取落盘文件。这样做的好处是调试推荐算法的时候不用每次都重新跑一遍清洗省掉了很多重复计算。矩阵构建的环节有一个重要转换。原始数据是长格式一行是一条播放记录推荐算法需要的是宽格式一行是一个用户、一列是一首歌。这个转换用pandas的pivot_table就能完成但后面会提到直接用pivot_table会有一个性能上的坑第3章会展开说。相似度计算是整条链路的中间枢纽。算出来的相似度矩阵规模是物品数乘以物品数如果数据集里有几千首歌这个矩阵就是千万级别的浮点数。项目在计算完成后会把相似度矩阵也落盘保存推荐和评估环节直接加载避免重复计算。这个设计在数据量变大之后会显得很关键因为相似度计算是整个流程里最耗时的一步。3. 数据预处理与特征矩阵构建推荐系统的地基3.1 数据清洗过滤掉那些“听一下就跑”的异常行为原始播放日志里噪声很大不是所有行为都值得进入推荐算法。比如一个用户只听了某首歌一次就再也没听过这种弱信号对相似度计算基本没有贡献反而会引入噪声。项目里设置了一个播放次数过滤阈值把低于阈值的记录直接丢掉。核心代码在data_preprocess.py里import pandas as pd def load_and_filter(raw_path, min_play_count3): # 读取原始播放记录 df pd.read_csv(raw_path, names[user_id, song_id, play_count]) print(f原始记录数: {len(df)}) # 过滤播放次数过低的记录这类记录通常是误触或试听 df df[df[play_count] min_play_count] print(f过滤后记录数: {len(df)}) # 过滤活跃度异常的用户播放总次数少于5次的用户视为噪声用户 user_total df.groupby(user_id)[play_count].sum() valid_users user_total[user_total 5].index df df[df[user_id].isin(valid_users)] # 过滤被播放次数异常高的歌曲通常是数据采集错误 song_total df.groupby(song_id)[play_count].sum() valid_songs song_total[song_total 10000].index df df[df[song_id].isin(valid_songs)] return df参数min_play_count的作用是控制噪声的过滤强度。默认值是3表示一首歌至少被播放3次才算有效行为。如果数据集比较稀疏可以把这个值调低到1或2如果数据很稠密调高到5可以显著减小矩阵规模。过滤完弱行为之后还要处理两类极端情况一类是“僵尸用户”总共只有几次播放记录这类用户的偏好无法统计另一类是“播放异常歌曲”播放次数高得离谱通常是采集端的问题。这两个过滤条件需要根据自己的数据情况调整没有通用标准。3.2 构建用户物品矩阵pivot_table一行代码埋下的坑清洗完数据之后下一步是把长格式数据转成宽格式的用户物品矩阵。项目里用pandas的pivot_table来实现一行代码就能完成import pandas as pd def build_user_item_matrix(df): # 行是用户列是歌曲值是播放次数 matrix df.pivot_table( indexuser_id, columnssong_id, valuesplay_count, fill_value0 ) print(f矩阵形状: {matrix.shape}) return matrix参数fill_value0表示用户没有播放过的歌曲位置填0。这样得到的是一个稠密矩阵几万个用户、几千首歌的时候内存还能承受但如果用户数到十万、歌曲数到几万这个矩阵就会膨胀到几个GB。我在类似项目里的做法是保留原始的长格式数据用scipy.sparse的coo_matrix来构建稀疏矩阵只在需要计算时再把某一行取出来做运算。这样做的好处是内存占用可以降低一到两个数量级缺点是代码会多一点。如果只是想跑通示例数据pivot_table完全够用如果要扩展到自己的大数据集建议直接换成稀疏矩阵。构建完矩阵后建议把矩阵的行和列索引都单独保存一份。因为实际数据里的用户ID和歌曲ID通常不是连续的整数而矩阵运算要求索引对齐。保存一份映射字典后面做推荐结果回查的时候会省很多事。3.3 隐式反馈处理播放次数怎么变成可比较的分数用户听歌数据本质上是隐式反馈播放次数并不直接等价于评分。一个用户每天听某首歌十几次和另一个用户偶尔听一次如果直接用原始次数参与计算播放习惯不同的用户之间会互相干扰。项目里对播放次数做了对数变换把数值压缩到合理的范围import numpy as np def normalize_play_count(matrix): # 对数变换压缩播放次数的量级差异 # 常见做法是 log(1 x)保证0值仍是0 matrix_log np.log1p(matrix) # 按用户行做最大最小值归一化消除用户播放习惯差异 row_max matrix_log.max(axis1).values row_min matrix_log.min(axis1).values normalized (matrix_log - row_min) / (row_max - row_min 1e-6) return normalizednp.log1p是log(1x)的数值稳定版本对于播放次数为0的项变换后仍然为0不影响稀疏结构的判断。按用户行归一化这一步非常重要它相当于把每个用户的播放习惯拉到了同一个尺度上有的用户每首歌都听几十遍有的用户每首歌只听几遍归一化之后比较的是偏好结构而不是绝对次数。常见误用的做法是只做对数变换不按用户归一化或者反过来只按用户归一化不做对数变换。前者的问题在于对数变换后数值仍然受播放次数影响后者的问题在于归一化对离群值敏感极端播放次数会把其他正常值压到接近0。两个步骤配合使用效果会稳定很多。4. 核心推荐算法实现ItemCF从相似度到推荐列表的完整链路4.1 相似度计算余弦相似度和皮尔逊相关系数的取舍物品相似度是整个推荐系统的核心。这个项目实现了两种相似度计算方式通过config.py里的SIMILARITY_METHOD参数切换。余弦相似度是默认选择计算逻辑如下import numpy as np from sklearn.preprocessing import normalize def compute_cosine_similarity(matrix): # matrix: 用户-物品矩阵行是用户列是物品 # 列向量按L2范数归一化然后点积得到余弦相似度 matrix_norm normalize(matrix, norml2, axis0) sim_matrix matrix_norm.T matrix_norm # 把对角线置为0避免物品和自身相似度影响推荐 np.fill_diagonal(sim_matrix, 0) return sim_matrixnormalize函数按列做了L2范数归一化把每一列的用户向量长度统一成1这样列与列之间的点积就是余弦相似度。矩阵乘法用NumPy的dot运算速度很快。对角线置0是为了后续推荐时跳过物品自身。皮尔逊相关系数的实现稍微复杂一些需要对每个物品的评分向量做中心化再计算余弦相似度。效果上皮尔逊相关系数对用户评分尺度的差异鲁棒性更好但计算代价也更高。我在实际项目里的经验是数据稀疏时用余弦相似度更稳定数据稠密时皮尔逊相关系数能挖掘出更细的偏好差异。相似度计算的复杂度是O(n^2 * m)其中n是物品数m是用户数。物品数超过一万之后这个计算会明显变慢。项目里在similarity.py中加了进度打印并且支持把结果落盘就是为了避免在调参时反复重算这一步骤。4.2 基于物品的协同过滤推荐函数逐行拆解相似度矩阵就绪后推荐逻辑相对直接。核心思路是找到用户听过的所有歌曲再找到与这些歌曲相似的其他歌曲按相似度和播放次数加权求和取分数最高的TopN首。推荐函数在recommend.py中def itemcf_recommend(user_item_matrix, item_sim_matrix, user_id, top_n10): # 取当前用户的行向量 user_vec user_item_matrix.loc[user_id] # 找到用户有播放行为的歌曲 interacted_items user_vec[user_vec 0].index.tolist() scores {} for item in interacted_items: # 当前歌曲对用户的权重取对数变换后的播放次数 weight user_vec[item] # 与该歌曲相似的物品列表按相似度降序取前50个 sim_scores item_sim_matrix[item] top_sim sim_scores.sort_values(ascendingFalse).head(50) for candidate, sim in top_sim.items(): if candidate in interacted_items: continue # 累加分数相似度 * 用户的播放权重 scores[candidate] scores.get(candidate, 0) sim * weight # 按分数降序排序取前top_n个 ranked sorted(scores.items(), keylambda x: x[1], reverseTrue)[:top_n] return [song_id for song_id, _ in ranked]这段代码的关键逻辑有三个。第一个是interacted_items的获取它限定了推荐的基础是用户真实发生过的行为没有行为的用户无法使用这个函数所以冷启动问题在后面会单独处理。第二个是top_sim取了前50个相似物品这是一个性能优化避免了遍历整个相似度矩阵的浪费。第三个是候选分数累加方式歌曲的最终分数等于所有用户听过的歌与它的相似度乘以播放权重的和。参数top_n控制推荐列表长度一般取值在5到20之间。邻居数50是经验值数据稀疏时建议调大到100数据稠密时调小到30。这个参数直接影响推荐结果的覆盖率和多样性是调参时最值得实验的一个值。4.3 离线评估用准确率和召回率给推荐质量打分推荐做出来之后怎么知道好不好项目里采用了标准的离线评估方案把数据按时间顺序切分成训练集和测试集训练集用来构建矩阵和计算相似度测试集用来验证推荐结果。评估脚本evaluate.py的核心逻辑如下def evaluate(train_matrix, test_matrix, item_sim_matrix, top_n10): hits 0 total_pred 0 total_test 0 for user_id in test_matrix.index: # 训练集里没有这个用户则跳过冷启动用户 if user_id not in train_matrix.index: continue rec_list itemcf_recommend( train_matrix, item_sim_matrix, user_id, top_n ) # 测试集中用户真实听过的歌曲 test_items set(test_matrix.loc[user_id][test_matrix.loc[user_id] 0].index) hits len(set(rec_list) test_items) total_pred len(rec_list) total_test len(test_items) precision hits / total_pred recall hits / total_test f1 2 * precision * recall / (precision recall 1e-9) return precision, recall, f1准确率衡量的是推荐列表里有多少歌是用户真实听过的召回率衡量的是用户真实听过的歌有多少被推荐出来了。这两个指标在音乐推荐场景下通常此消彼长所以项目还额外计算了F1分数方便横向对比不同参数组合的效果。这里有一个很容易踩的坑evaluate里跳过训练集不存在的用户会让评估结果看起来比实际情况好。因为这些被跳过的用户正是冷启动用户真实线上系统必须处理他们。如果不跳过精确率会被拉低一大截如果跳过指标又失真。项目选择跳过并单独统计数量这个取舍是合理的但阅读评估结果时要清楚指标的适用范围。5. 避坑与常见问题排查数据稀疏、冷启动和性能陷阱5.1 推荐结果全是热门歌曲怎么排查现象跑完推荐后发现TopN列表里永远是那几首最热门的歌不同用户的推荐结果高度雷同。原因这是数据稀疏场景下的马太效应。相似度计算时热门歌曲频繁出现在大量用户的播放列表里计算出来的相似度分数虚高推荐时把其他候选歌曲都挤掉了。解决给热门歌曲加一个惩罚因子在相似度计算时按歌曲的全局热度做降权。常见做法是给相似度乘以一个权重权重和歌曲的流行度成反比比如乘以1 / log(1 歌曲被播放的总次数)。这个惩罚只作用于相似度累加阶段不影响原始播放记录。5.2 相似度矩阵出现全零行或全零列现象打印相似度矩阵时发现某首歌对应的行全部为0导致推荐时永远推荐不出这首歌。原因这首歌在整个数据集中只被一个用户播放过归一化后相似度计算的结果为0或者这首歌的播放次数在预处理阶段被全部过滤掉了。解决在构建相似度矩阵后做一次检查把所有行和为0的物品记录下来。这些物品不适合用协同过滤推荐可以把它们放到热门兜底列表里也可以直接移出候选集。我在项目里会把这类物品单独存成一个文件方便观察数据质量。5.3 用户数多起来之后内存直接爆炸现象几千首歌时程序跑得很流畅数据量扩大到几万首歌后构建用户物品矩阵时直接把内存耗尽。原因pivot_table生成的是稠密矩阵用户数乘以歌曲数的内存开销是O(n*m)的量级。一万用户和两万首歌的矩阵如果每个格子一个float64就是1.6GB内存。解决把稠密矩阵换成scipy.sparse的csr_matrix保存或者在build_matrix.py中改用coo_matrix按坐标构造稀疏矩阵。推荐计算时只需要按行取值csr矩阵的切片操作效率很高。我一般会在config.py里增加一个USE_SPARSE开关数据量小时用pivot_table方便调试数据量大时切到稀疏模式。5.4 新用户进来推荐列表是空的现象某个用户没有任何播放记录调用推荐函数返回空列表。原因ItemCF的推荐逻辑基于用户已有行为计算没有行为就没有相似物品可推荐。解决增加一个热门兜底策略。把所有歌曲按全局播放次数降序排列取前TopN作为冷启动用户的推荐结果。具体做法是在recommend.py中增加一个popualr_fallback函数在itemcf_recommend返回空列表时调用。更精细的做法是结合用户注册时选择的喜欢的歌手或曲风但项目里先做热门兜底已经能满足大多数场景。5.5 离线评估指标虚高怎么切分数据现象随机切分训练测试集后准确率高达40%以上但上线效果明显达不到这个水平。原因随机切分破坏了时间顺序。用户本周听过的歌和上周听过的歌关联性强测试集里包含了和训练集时间相邻的行为评估结果偏离真实场景。解决改为按时间切分。把每首歌的播放记录按时间戳排序取每个用户前80%的行为做训练集后20%的行为做测试集。这样测试集模拟的是“根据过去预测未来”的真实推荐场景评估指标会保守很多但更有参考价值。6. 二次开发改造思路把推荐系统变成可配置的服务6.1 参数化把邻居数、阈值和推荐长度交到配置文件原项目把参数集中在config.py里但参数之间缺少约束。我一般会在二次开发时把配置升级成带校验的版本避免改参数时出现逻辑冲突# config.py 扩展版 SIMILARITY_METHOD cosine # 可选cosine / pearson NEIGHBOR_K 50 # 候选邻居数 TOPN 10 # 推荐列表长度 MIN_PLAY_COUNT 3 # 播放次数过滤阈值 USE_SPARSE False # 是否使用稀疏矩阵 FALLBACK_POPULAR True # 冷启动是否返回热门歌曲 TIME_SPLIT 0.8 # 时间切分的训练集比例 # 参数合法性检查 assert 0 TIME_SPLIT 1, TIME_SPLIT 必须在0到1之间 assert NEIGHBOR_K 0, NEIGHBOR_K 必须大于0参数化改造的核心目的不是让用户随便改而是让每次实验的参数组合可复现。配合评估脚本可以人为地跑几组不同参数做对比实验。我习惯在评估输出里额外打印一份参数摘要把当前参数和对应的准确率、召回率、F1一起写进CSV文件方便后续分析。6.2 混合推荐把热门兜底策略从冷启动扩展到全体用户冷启动的兜底策略可以进一步泛化成混合推荐。思路是给每个用户分配一个“个性化程度”系数行为数据丰富的用户直接走ItemCF结果行为数据稀疏的用户把热门歌曲和个性化结果按比例混合。具体做法是用户播放次数少于10首时推荐列表取30%个性化的结果加70%热门歌曲播放次数超过50首的用户完全使用个性化结果。这个比例可以在config.py里增加两个参数控制。这种分层策略的好处是不会让新用户觉得推荐结果太离谱同时又能保证老用户体验到个性化。它不像深度学习那样需要训练但能解决推荐系统早期的冷启动体验问题。6.3 从离线脚本到Web接口把推荐结果暴露成HTTP服务离线脚本改造到线上服务最简单的做法是用Flask包一个查询接口。核心代码只需要几行from flask import Flask, request, jsonify import build_matrix, similarity, recommend app Flask(__name__) matrix build_matrix.load_matrix() # 启动时加载矩阵 item_sim similarity.load_similarity() # 启动时加载相似度矩阵 app.route(/recommend/user_id) def get_recommend(user_id): rec_list recommend.itemcf_recommend( matrix, item_sim, user_id, top_n10 ) return jsonify({user_id: user_id, songs: rec_list}) if __name__ __main__: app.run(host0.0.0.0, port5000)改造时要注意相似度矩阵和用户矩阵在服务启动时加载到内存请求进来时只做矩阵切片和分数累加单次请求耗时控制在几毫秒到几十毫秒之间。如果用户量特别大可以再加一层缓存把热门用户的推荐结果缓存到内存里。另外线上服务一定要处理冷启动用户。接口收到用户ID后第一步先检查该用户是否在矩阵中如果不在直接返回热门歌曲列表而不是抛异常。我在改造这个项目时曾经因为忽略了这一点导致接口对未登录用户全部返回500错误那次的教训是凡是涉及用户ID的接口一定要先验证数据是否存在。从那以后我每次改完推荐逻辑都强制走一遍离线评估和冷启动用例的回归确认指标没有回退才敢继续往线上走。希望帮到你。本文还有配套的精品资源点击获取