“Python flask 体育商城商品推荐系统”——这个标题既是项目名也是我刚做完的一个周末实战项目的完整写照。先说结论用 Flask 做推荐系统远比想象中轻巧尤其是面对商品数据量不过千、用户行为数据稀疏的校园级或中小型商城场景基于内容的相似度推荐比协同过滤更落地、更容易解释也更适合用来练手和学习。这篇文章会把整个系统的拆解思路、数据库设计、算法实现、Flask 接口封装到本地部署的完整过程全部写出来踩过的坑也一并交代希望能给正在做 Flask 项目或想入门推荐系统的朋友一些实际参考。这个系统能做的事很简单商城里有体育商品球拍、跑鞋、护具这类用户点开一件商品详情页系统根据商品标题、分类、描述等文本信息通过 TF-IDF 加余弦相似度计算自动找出最相似的其他商品推荐给用户。整套东西可以用 SQLite 存储、在本地直接跑起来不需要 GPU、不需要大数据平台几行 Python 就能完成核心推荐逻辑。适合的人群也很明确正在学 Python Web 开发、想给毕设或课程设计加点亮点、或者刚接触推荐算法但不想一上来就啃 Spark 的同学。1. 内容整体设计与思路拆解1.1 为什么选 Flask 而不是 Django很多人一上来就纠结 Flask 还是 Django我个人的判断标准很简单项目规模和数据复杂度。这个体育商城推荐系统核心功能就三块——商品展示、推荐计算、用户点击记录本质上是一个轻量级的中型 Web 应用不会有复杂的权限体系、后台管理、多应用拆分用 Flask 能把每个环节都看得清清楚楚。Flask 的灵活性在于它不是“全家桶”你不需要的项目功能框架不会强行塞给你。比如 Django 自带 ORM、Admin 后台、表单校验这些功能在某些场景是优点但对于一个以推荐算法为核心亮点的项目来说反而容易让初学者迷失在框架本身的机制里。Flask 里你可以自己决定用不用 SQLAlchemy、用哪个扩展做表单验证核心逻辑一目了然出了问题也容易定位。而且 Flask 的调试模式、热加载机制对本地开发非常友好改完代码保存即生效大大加快了迭代速度。当然选择 Flask 也需要自己动手补一些东西——这是它不算缺点的缺点没有自带 Admin 后台、没有集成用户认证但这些对于一个推荐演示系统来说本来就不是刚需。我更看重的是 Flask 的低心智负担和高可控性这让整个项目的主线始终围绕推荐算法而不是框架学习。1.2 推荐方案选型基于内容的相似度推荐推荐系统常见的三大流派基于内容的推荐、协同过滤、混合推荐。在这个项目里我选定基于内容的相似度推荐理由非常实际。协同过滤确实更“智能”它能挖掘用户潜在兴趣但它的前提是要有足够的用户行为数据。比如用户 A 和用户 B 都买过羽毛球拍协同过滤才能把用户 B 买的羽毛球推荐给用户 A。而体育商城在初期往往面临“冷启动”问题——用户行为记录少得可怜协同过滤算出来的结果会非常稀疏甚至无从算起。我这次的项目里用户数据本来就不是重点强行上协同过滤只会让推荐效果看起来像随机推荐。基于内容的推荐就不同了它不依赖用户历史行为只分析商品自身的特征。用户在看某件商品时系统把该商品和其他所有商品做文本相似度对比返回“和当前商品最像的若干商品”。这在商品类目清晰、标题描述规范的情况下效果立竿见影而且对每个用户来说解释成本极低——“您正在看跑鞋所以推荐您看其他跑鞋或相关运动装备”业务上非常通顺也方便做成可解释的推荐理由。1.3 轻量化数据存储的取舍很多初学者容易陷入“必须上 MySQL/PostgreSQL”的思维定势但说到底数据库选型要看数据量级。这个项目商品数据撑死了也就几百上千条用户点击记录也是单机练习级别的数据量SQLite 完全够用而且带来一个极大的好处——零配置、零部署成本。SQLite 是 Python 内置支持的文件型数据库整个数据库就是一个.db文件拷贝即迁移。项目放到任何装有 Python 的机器上都能直接运行不需要额外安装数据库服务这非常契合本地部署的要求。实际用下来SQLite 对几百条数据的查询速度几乎无感加上正确的索引设置完全不影响推荐接口的响应时间。如果你未来想把项目升级成生产环境只需要把 Flask 的数据库连接配置从 SQLite 切换到 MySQL然后用 SQLAlchemy 的 ORM 模型对接即可业务逻辑几乎不用动。所以我不是否定 MySQL而是强调在最合适的阶段用最合适的工具。轻量化数据库让整个项目的上手门槛大幅降低对于教学、演示和中小型商城的初期版本来说SQLite 是最自洽的选择。2. 核心细节解析与实操要点2.1 商品表结构设计商品信息是整个推荐系统的基础表设计直接决定后面算法的输入质量。我设计了以下几个核心字段字段名类型说明idINTEGER 主键商品唯一标识nameVARCHAR(100)商品名称如“李宁羽毛球拍对装”categoryVARCHAR(50)商品分类如“羽毛球/球拍”priceFLOAT商品价格用于展示和后续扩展descriptionTEXT商品详细描述用于相似度计算image_urlVARCHAR(200)商品图片链接用于页面展示tagsVARCHAR(200)商品标签如“入门/耐用/轻量”这里有一个关键设计决策把名称、分类、标签和描述合并成一个文本字段参与相似度计算而不是只算名称相似度。原因很简单很多商品名称高度相似比如“耐克跑鞋”和“耐克运动鞋”只看名称可能算不出差异化但如果把分类“跑步”、描述“缓震透气轻量”这些都纳入文本推荐结果就能捕捉到更深层的语义关联。设计时要注意的另一个点是分类字段要尽量标准化。我一开始图省事用自由文本填分类结果出现了“羽毛球拍”和“羽球拍”两种写法直接导致相似度计算时归类混乱。后来强制规定分类只能从预设列表里选整个推荐质量立刻提升了一个档次。如果你拿到一份分类混乱的数据建议先做一轮简单的聚类清洗把同义分类合并再入库。2.2 用户行为记录如何支撑后续扩展虽然当前版本的核心推荐是内容相似度但我仍然预留了用户行为表这是给未来算法升级留的接口。用户点击记录表user_click_log记录三个信息用户标识、商品ID、点击时间。这个表现阶段可以用来做三件事。第一是统计热门商品作为推荐结果的兜底策略当相似度推荐没有找到足够商品时其余位置用热门商品补足。第二是记录用户的浏览历史在商品详情页展示“最近浏览”提升体验。第三是给将来升级协同过滤积累数据一旦用户行为数据量上来了不需要重新设计表结构直接用现成数据就能跑物品协同过滤算法。我建议在数据访问层写清晰的 DAO 函数比如get_user_click_history(user_id)、get_hot_products(limit)这样后续替换底层存储或增加缓存层时业务层完全不受影响。这算是一个过度设计的反面——它不是过度设计而是低成本高收益的预留设计因为多写一张表的成本极低但未来省掉重构的时间却不少。2.3 准备一份可用的体育商品数据商品数据是推荐系统的“食材”数据质量直接决定推荐口味。我采用手工构造加结构化生成的方式构造了约 100 条体育商品数据覆盖球类、跑步、健身、游泳、户外五个大类每条数据都保证标题含品牌和品类词、描述至少包含两到三个特征词。数据的构造有讲究。比如“尤尼克斯羽毛球拍弓箭系列”这条数据描述写“拍框坚固弹性好适合攻守兼备型选手”这样它和马林羽毛球拍、李宁羽毛球拍之间才会有合理的相似度梯度——同品牌商品相似度最高同品类不同品牌相似度其次跨品类如羽毛球拍和跑步机的相似度则极低这种梯度才是推荐系统能给出“看起来合理”结果的关键。如果你是做毕设或课程设计不要从电商平台爬真实商品数据因为数据量小且字段不规整时清洗成本远高于自己构造。真实数据反而容易因为图片字段缺失、价格格式混乱、描述过于冗长导致各种异常。自己构造数据可以完全控制质量把精力集中在算法和系统设计上。当然如果坚持用真实数据推荐用 Kaggle 上现成的体育商品数据集至少字段已经预处理过。3. 推荐算法核心实现与参数调优3.1 中文文本预处理与分词推荐算法的第一步不是算相似度而是把文本变成计算机能理解的向量。英文文本天然用空格分词但中文不行“羽毛球拍”是一个完整语义单元不能切成“羽毛”“球拍”这种碎片。所以必须先做中文分词。我用的是jieba这个 Python 库它对中文分词的支持和社区活跃度都是目前最好的选择。但直接jieba.cut(text)会分出一大堆无关的停用词比如“的”“了”“和”“非常”这些词在商品描述里出现频率高但对区分商品毫无帮助必须过滤。比较完整的预处理流水线是这样的import jieba STOP_WORDS set([ 的, 了, 是, 和, 与, 或, 很, 非常, 比较, 适合, 一款, 采用, 使用, 设计, 材质, 提供, 以及, 进行, 可以, 具有, 更加, 这款 ]) def preprocess_text(text: str) - str: words jieba.cut(text.lower()) filtered [w.strip() for w in words if w.strip() and w not in STOP_WORDS] return .join(filtered)这一套处理下来“这款羽毛球拍采用碳素材质拍框设计坚固适合攻守兼备型选手”会变成“羽毛球拍 碳素 材质 拍框 设计 坚固 攻守 兼备 型 选手”每个词对后续相似度计算都是有意义的信息。这里强烈建议自定义一个商品领域词典把“羽毛球拍”“篮球鞋”“跑步机”这类词优先识别出来加载方式是jieba.add_word(羽毛球拍)能显著提升分词质量。3.2 TF-IDF 向量化与余弦相似度的原理分词之后需要把文本转成向量。我选择了TF-IDF词频-逆文档频率而不是简单的词袋模型区别在于 TF-IDF 会给每个词赋予权重——某个词在当前商品里出现频率越高越重要但如果它在所有商品里都出现那它的区分度其实很低权重会被降低。用scikit-learn的TfidfVectorizer一步就能完成向量化from sklearn.feature_extraction.text import TfidfVectorizer from sklearn.metrics.pairwise import cosine_similarity import pandas as pd # df 是包含 name/category/description/tags 的商品 DataFrame preprocessed_docs df[combined_text].apply(preprocess_text).tolist() vectorizer TfidfVectorizer() tfidf_matrix vectorizer.fit_transform(preprocessed_docs) # shape: (n_products, n_features) similarity_matrix cosine_similarity(tfidf_matrix)这里的核心概念是余弦相似度它衡量两个向量在方向上的接近程度数值在 0 到 1 之间。你不需要背公式只需要建立直觉两个商品文本向量在多维空间里指向的方向越接近余弦相似度越高。1 表示完全同向0 表示正交即完全无关。我用的cosine_similarity直接遍历所有商品组合时间复杂度是 O(n²)100 条数据完全无压力即使 1000 条商品也能在毫秒级完成。这个方案的优势是不用实时计算我选择在服务启动时先算一遍把相似度矩阵缓存到内存推荐请求进来时直接查表返回这样响应速度极快也避免了每次请求都重新跑算法的浪费。3.3 推荐结果的排序与阈值过滤算完相似度矩阵后还有一个关键细节不能把所有相似商品都推给用户。如果某件商品的相似度最高只有 0.15说明它和其他商品关联度都很弱这时候强行推荐反而影响体验。所以我设置了两个层面的过滤规则。第一层是相似度阈值过滤。我实际调参发现体育商城这种文本特征明显的数据集相似度大于 0.2 才算“沾边”大于 0.5 才是“明显相似”。阈值定太低会出现“看羽毛球拍推篮球鞋”的尴尬定太高则推荐数量不够甚至为空。经过十几轮测试我把阈值设为 0.25结合取 Top N 的策略效果最均衡。第二层是多样性控制。如果只按相似度排序前五个推荐商品可能都是同一个品牌甚至同一款的不同配色这对用户来说信息量很低。我的做法是设置一个max_per_category参数——相似度排名靠前的商品里每个商品分类最多取 2 条。这样既保证推荐相关性又让结果覆盖足够多的品类用户看到推荐列表时的第一反应通常是“这些确实相关而且有几个我没想到的”这正是推荐系统让人惊喜的时刻。def recommend_for_product(product_id: int, top_n: int 6): sim_scores list(enumerate(similarity_matrix[product_id])) sim_scores sorted(sim_scores, keylambda x: x[1], reverseTrue) filtered [] seen_categories set() for candidate_id, score in sim_scores: if candidate_id product_id: continue if score SIMILARITY_THRESHOLD: continue category df.loc[candidate_id, category] if seen_categories.count(category) 2: continue filtered.append((candidate_id, score)) seen_categories.add(category) if len(filtered) top_n: break return filtered3.4 冷启动与兜底策略无论算法多么完善总会有无法给出推荐的情况新入库的商品还没有参与相似度计算或者某件商品文本特征特殊找不到高相似度的邻居。这时候需要兜底策略。我的做法是一个两级的推荐降级链。第一级如果基于内容的推荐结果不足 N 个先用同分类下的热门商品补齐从点击日志里统计一段时间内被点击最多的商品。第二级如果同分类也没有足够商品就返回全站热门商品。这套兜底逻辑在真实业务里非常重要。用户不会理解“这个商品太特殊暂时没有推荐”——他们只会觉得“这个商城系统有问题”。用一个看似不起眼的 fallback 机制把异常场景平滑消化掉这比算法本身更能体现工程经验。实测中加上兜底策略后推荐接口的兜底返回率降为 0任何商品都能稳定给出推荐列表。4. Flask 应用搭建与接口开发全流程4.1 项目目录结构设计与初始化一个清晰的目录结构能让项目后期维护省心太多。我的推荐系统项目目录结构如下sports_mall_recommend/ ├── app.py # Flask 入口路由注册 ├── config.py # 配置项如阈值、路径、常量 ├── models/ │ ├── __init__.py │ ├── database.py # 数据库连接与建表 │ ├── product.py # 商品模型定义 │ └── user_log.py # 用户行为模型定义 ├── recommender/ │ ├── __init__.py │ ├── preprocessing.py # 中文文本预处理 │ ├── similarity.py # TF-IDF 向量化与相似度计算 │ └── engine.py # 推荐引擎入口 ├── static/ │ ├── css/ # 前端样式 │ ├── js/ # 前端逻辑用 fetch 调接口 │ └── images/ # 商品图片占位图 ├── templates/ │ ├── index.html # 商城首页商品列表 │ └── product_detail.html # 商品详情与推荐展示页 ├── data/ │ ├── products.csv # 商品数据源 │ └── mall.db # SQLite 数据库文件 └── requirements.txt这种结构把“数据访问”“算法逻辑”“Web 层”彻底分离开每个模块职责单一。尤其是把推荐算法独立成recommender包之后想换算法比如从 TF-IDF 换成 Word2Vec只需要替换similarity.py内部实现其他文件一行都不用动。4.2 推荐引擎模块的封装推荐引擎是整个系统的核心我把它封装成一个类应用启动时完成加载和预计算class RecommendationEngine: def __init__(self, db_pathdata/mall.db): self.df load_products_from_db(db_path) self.vectorizer TfidfVectorizer() self.documents self.df[combined_text].apply(preprocess_text).tolist() self.tfidf_matrix self.vectorizer.fit_transform(self.documents) self.similarity_matrix cosine_similarity(self.tfidf_matrix) def recommend_by_product(self, product_id, top_n6): # 返回推荐商品列表 ... def recommend_by_text(self, query, top_n6): # 给定搜索词返回匹配商品 ...我额外实现了一个recommend_by_text方法它能把用户搜索关键词比如“碳素羽毛球拍”转成 TF-IDF 向量然后和所有商品向量算相似度返回最匹配的商品。这个功能不止用于搜索还能作为商品推荐的补充入口——用户在首页搜索“跑鞋”系统不仅返回搜索结果还能顺带推荐“同类跑鞋”和其他跑步装备体验上是一个很完整的闭环。封装这个词不是空洞概念。把推荐逻辑封装成类后Flask 路由代码可以非常薄比如from flask import Flask, jsonify, render_template from recommender.engine import RecommendationEngine app Flask(__name__) engine RecommendationEngine() app.route(/api/products/int:pid/recommend) def product_recommend(pid): recommendations engine.recommend_by_product(pid) return jsonify(recommendations)整个路由函数只有几行没有任何算法细节暴露在外。这就是分层的价值路由层只负责 HTTP 协议转换推荐引擎只负责算法计算出了问题直接定位到对应层。4.3 前端页面与交互设计前端我用的是 Flask 自带的 Jinja2 模板加原生 JavaScript 的 fetch 请求完全没有引入前端框架保持项目的轻量属性。商城首页就是一个商品列表每个卡片展示图片、名称、分类、价格。点击“查看推荐”按钮后前端发起 fetch 请求到/api/products/id/recommend拿到推荐数据后动态渲染推荐列表不刷新页面。这套流程虽然简单但完整覆盖了前后端交互的核心链路HTTP 请求、JSON 响应、DOM 动态渲染。商品详情页稍微复杂一点。左侧是商品图片和主要参数右侧是“‘猜你喜欢’推荐区”推荐商品以横向滚动卡片的形式展示。每个推荐卡片附带了推荐理由比如“与当前商品分类相同”或“与当前商品描述相似度较高”这个推荐理由在真实电商平台是常规操作但在课程设计或练习项目里很少有人做做出来会显得完成度特别高。关于图片处理由于是本地项目我用占位图加 CSS 渐变背景的方案不依赖外链资源保证项目离线可用。如果需要在本地部署后给别人演示所有资源都在本地加载速度非常快不会因为外部图片加载失败而出现破图。4.4 本地部署运行与依赖管理本地部署是项目验收的关键环节要做到“拿到代码就能跑”。我先把依赖写进requirements.txtflask2.3.2 flask-sqlalchemy3.0.2 jieba0.42.1 scikit-learn1.3.0 pandas2.0.3版本号全部锁死避免不同环境装到不同大版本导致 API 变化。然后写一个README.md把部署步骤压缩到三条命令pip install -r requirements.txt python app.py 访问 http://127.0.0.1:5000当我把项目移到一个全新的 Python 环境测试时意外发现scikit-learn依赖的scipy在某些旧版本 Linux 上编译比较慢甚至可能编译失败。这就是锁版本之外还需要注意的如果部署环境较旧优先装预编译的 wheel 包不要从源码编译。pip install默认会尝试下载预编译包但如果平台不匹配就可能触发源码编译耗时非常长且容易报错。Flask 的启动配置里我加了一个小技巧app.run(debugTrue, host0.0.0.0, port5000)其中host0.0.0.0表示监听所有网络接口这样如果机器在局域网内手机或另一台电脑也能直接访问系统的推荐页演示时非常方便。调试模式和热加载在我试过的很多版本里表现都不一样建议按固定版本运行遇到不良体验及时查文档。5. 常见问题与排查技巧实录5.1 中文乱码从头到尾贯穿的坑中文乱码是这个项目里最容易遇到也最容易让人放弃的问题我前后踩了三个层面的坑。第一层是数据库层面的连接串和字段编码。SQLite 本身是 UTF-8 存储问题一般不大但要确保代码文件保存为 UTF-8 格式并且连接数据库时不要手动转换编码。第二层是CSV 数据源的编码用 pandas 读取 CSV 时如果文件是 GBK 编码而没指定encodingutf-8读出来全是乱码。第三层也是最容易被忽略的——Flask 返回 JSON 时中文需要设置app.config[JSON_AS_ASCII] False否则 Flask 会把中文自动转成\uXXXX的 Unicode 转义序列。app Flask(__name__) app.config[JSON_AS_ASCII] False这个配置不加浏览器里看到推荐商品名称是\u674e\u5b81而不是“李宁”接口数据本身没错但可读性极差排查起来也容易绕弯路。5.2 依赖版本冲突与 sklearn 安装问题用 scikit-learn 做 TF-IDF 是最省事的方案但安装环节的问题没有一个完整的排查思路的话真的会卡住一晚上。我遇到过最典型的场景是一个干净的 Python 环境里直接pip install scikit-learn结果报错说找不到匹配的版本。严格来说问题根源通常是Python 版本太低。scikit-learn 1.3 以上版本要求 Python 3.8 起步如果你的系统自带的是 Python 3.6pip 就会尝试找旧版本而旧版本又缺少对应系统的预编译包只能从源码编译导致安装失败或耗时极长。排查思路有一个固定的顺序先python --version确认版本再pip list | grep -i scikit看当前环境是否已有包最后选择安装配套版本。在我实际试过很多组合后比较稳妥的方案是在 Python 3.9 或 3.10 环境下使用 scikit-learn 1.2.x 或 1.3.x这两个组合的预编译支持最完善。如果不想用 scikit-learn另一个可行的方案是用纯 Python 自己实现 TF-IDF 计算利用 Python 标准库的collections.Counter和数学函数代码量会增加一些但能完全摆脱 sklearn 的安装依赖。这个方案适合部署环境受限的场景但 scikit-learn 本身性能更好、代码更简洁我依然推荐优先用它。5.3 推荐结果不理想全是热门商品或全是同一商品推荐结果不理想的症状通常分两种一种是推荐列表几乎不变永远推那几个热门商品另一种是推荐结果全是同一品类、甚至同一品牌。第一种情况最可能的原因是文本预处理没有生效导致所有商品向量几乎一样。比如preprocess_text函数被调用了但分词结果没拼接回字符串所有文档变成一长串粘连文本TF-IDF 的区分度就直接丢失了。排查方法是手动调用一次预处理函数观察几个商品的预处理输出是否差异化明显。第二种情况则是分类字段权重太大。如果combined_text里分类对文本向量的贡献远高于名称和描述那么同一分类下的商品在所有商品里排在前面是必然结果。调整方案是给分类文本降低权重比如把分类字段重复次数降低或者在合并文本时不再加入分类字段只靠名称和描述计算相似度再单独用分类做规则过滤。另一种很隐蔽的问题相似度矩阵计算后用错了索引。cosine_similarity返回的矩阵是 N×N但如果你在商品查询时使用的商品 ID 不是矩阵的行索引就会取到完全错误的相似度行。最简单的解决方案是维护一个从商品 ID 到矩阵行索引的映射字典确保取值时对齐。5.4 性能优化思路从内存缓存到服务化虽然 100 条商品数据根本谈不上性能瓶颈但为了让项目有“工程感”我还是做了几个优化这些思路对未来数据量变大时很有参考价值。第一个优化是内存缓存相似度矩阵。推荐引擎启动时预计算所有的相似度运行时直接查内存避免每次请求都重新跑 TF-IDF 和矩阵乘法。这在大数据量场景下尤其重要——实时计算的时间成本会随商品数量呈平方级增长而预计算只需要付出一次性启动成本。第二个优化是商品数据可以增量更新。新商品入库后只对该商品重新计算与其他商品的相似度向量再更新矩阵对应行而不是全量重算。这个优化在多用户后台频繁上架商品时很有效我虽然没有在代码里实现因为项目数据量小没必要但代码结构上已经预留了接口位置。第三个优化方向是把推荐引擎独立成微服务比如用 Flask 编写 API 后部署为单独进程商城主应用通过 HTTP 调用推荐服务。这样商城和推荐系统可以独立扩展推荐服务的负载高时可以单独扩容。但在当前数据规模下这个优化更像是一种架构预演作为了解即可不需要真的实施。6. 写在最后的项目复盘与扩展建议做完这个项目我最大的体会是推荐系统并没有想象中高不可攀一个轻量级的基于内容推荐只要把文本预处理、相似度计算、结果过滤这三个环节做扎实已经能产生相当不错的体验。真正区分工程水平高低的往往不是算法本身而是那些容易被忽视的细节——比如文本分词的停用词表是否完整、相似度阈值是否经过测试、推荐结果是否有兜底策略、返回 JSON 的中文是否没有乱码。如果手头时间和精力允许这个系统还可以往三个方向扩展。第一个方向是加入协同过滤等用户行为数据积累到一定量级后用“买了还买”“看了还看”的逻辑补充基于内容的不足形成混合推荐。第二个方向是让推荐结果带上“理由”告诉用户“因为您浏览的是羽毛球拍分类下的商品所以为您推荐同分类高人气商品”这种可解释性在商业场景里非常加分。第三个方向是把部署方式从本地启动改造成 Docker 容器一行命令启动整个环境彻底消灭“在我电脑上能跑”的问题。项目源码的维护上有一个小建议给关键函数写好模块级 docstring说明输入输出和典型用法。我在写推荐引擎时给每个方法都加了简单注释过了一周再看代码依然能快速回忆起来——这个习惯对个人项目尤其重要因为你的记忆保鲜期远比想象中短。希望这篇文章能帮你少走一些弯路如果你正在做类似的技术选型或已经踩到某个具体的坑照着上面的排查顺序过一遍大概率能找到问题所在。