BeerReviews 推荐系统（Baseline：Item-Item 相似度）

本项目基于 beer_reviews.csv 构建一个可解释的推荐系统：

• 按用户推荐：输入 review_profilename 输出 Top-N 啤酒
• 相似啤酒：输入 beer_beerid 输出相似啤酒
• UserCF + 重排（可选进阶）：UserCF 与 ItemCF 召回候选，再用 MLP 模型筛选 Top-N

环境准备

在 /data/czd/beer 目录下：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

训练（生成 artifacts）

python cli.py train --csv beer_reviews.csv --out artifacts --topk 200

常用可选参数：

• --max-rows 200000：先用小样本跑通
• --min-user-ratings 5 --min-item-ratings 5：过滤稀疏用户/啤酒
• --dedup latest|mean|none：同一用户-啤酒多条记录处理（默认 latest）
• --block-size 256：相似度计算分块大小（越大越快但峰值内存更高）

按用户推荐 Top-N

python cli.py recommend-user --artifacts artifacts --user "stcules" --topn 10

UserCF（相似用户协同过滤）

先训练 user-user 相似度（会生成 Su_user_user_topk.npz）：

python cli.py train-usercf --csv beer_reviews.csv --out artifacts --topk-users 200 --block-size 256

然后用 UserCF 做推荐（用于对比）：

python cli.py recommend-usercf --artifacts artifacts --user "stcules" --topn 10 --topk-users 200

相似啤酒

python cli.py similar-item --artifacts artifacts --beer-id 52159 --topn 10

也支持按名字模糊搜索（可能不唯一）：

python cli.py similar-item --artifacts artifacts --beer-name "Caldera Ginger Beer" --topn 10

Hybrid：ItemCF+UserCF 召回 + MLP 重排（有意思的玩法）

1) 训练重排模型

重排训练使用 显式阈值标签：review_overall>=4 正样本，<=2 负样本，=3 丢弃；负样本优先从召回候选里采（难负样本）。

python cli.py train-rerank --csv beer_reviews.csv --out artifacts --alpha 0.7 --cand-per-source 200 --neg-per-pos 5

会生成 artifacts/rerank_model.pt（PyTorch MLP 重排模型）。

2) Hybrid 推荐（最终 Top-N）

python cli.py recommend-hybrid --artifacts artifacts --user "stcules" --topn 10 --alpha 0.7 --cand-per-source 200

离线评估（可选）

按每个用户最后一条交互做留一法（时间切分），评估 HitRate@K / Recall@K：

python cli.py eval --csv beer_reviews.csv --topk 50 --max-users 20000

提示：

• 全量 beer_reviews.csv 训练会比小样本慢很多，建议先用 --max-rows 跑通流程，再逐步放大。
• 若机器内存紧张，可适当调小 --block-size（更稳，但更慢）。

训练完成后：怎么做一个简单 Demo 验证效果？

我们提供了一个命令行 Demo：demo_cli.py，用于快速试用 ItemCF / UserCF / Hybrid / 相似啤酒。

1. 先看看有哪些用户/啤酒可以测：

python demo_cli.py --artifacts artifacts suggest --users 10 --beers 10

2. 用 ItemCF / UserCF / Hybrid 分别给同一个用户出 Top-N，对比差异：

python demo_cli.py --artifacts artifacts itemcf  --user "stcules" --topn 10
python demo_cli.py --artifacts artifacts usercf  --user "stcules" --topn 10
python demo_cli.py --artifacts artifacts hybrid  --user "stcules" --topn 10 --alpha 0.7

3. 测“相似啤酒”：

python demo_cli.py --artifacts artifacts similar --beer-id 52159 --topn 10

Streamlit Demo（推荐）

训练好 artifacts/ 后，可以启动一个简单的网页 Demo（对比 ItemCF/UserCF/Hybrid，并支持相似啤酒查询）：\n

streamlit run app.py --server.port 8501 --server.address 0.0.0.0

页面左侧可以填 artifacts 目录（默认就是 artifacts）。

Web Demo（FastAPI：带中文名与图片）

1) 资源准备：中文名 + 图片（Wikimedia/Wikipedia）

训练好 artifacts/ 后，先生成资产表（增量可重复执行）：

python -m src.asset_prep --artifacts artifacts --limit 2000 --download-images

说明：

• --download-images 会把图片下载到 artifacts/images/；若不下载，前端会通过 /assets/images/{beer_id} 自动 302 跳转到 image_url。
• 机器翻译默认使用 deep-translator（需要网络）。若环境不允许外网，可先关掉翻译，仅生成图片字段：

python -m src.asset_prep --artifacts artifacts --limit 2000 --translator none --download-images

2) 启动 API + 前端页面（同一个服务）

ARTIFACTS_DIR=artifacts uvicorn api:app --host 0.0.0.0 --port 8000

浏览器打开：http://localhost:8000/

3) 关键接口

• GET /api/health
• GET /api/recommend?user=...&topn=10&algo=itemcf|usercf|hybrid
• GET /api/similar?beer_id=...&topn=10 或 GET /api/similar?q=...&topn=10
• GET /assets/images/{beer_id}：本地图片优先，否则跳转到 Wikipedia 图片

产物说明（artifacts/）

• X_train.npz：用户-物品稀疏评分矩阵（CSR）
• S_item_item_topk.npz：Item-Item 相似度（CSC，保留 Top-K）
• Su_user_user_topk.npz：User-User 相似度（CSC，保留 Top-K）
• id2user.npy：用户ID到用户名
• id2beer.npy：物品ID到 beer_beerid
• item_meta.csv：啤酒元信息（名称/风格/ABV/酒厂等）
• popular.csv：热门榜（用于兜底）
• rerank_model.pt：PyTorch MLP 重排模型（Hybrid 推荐使用）
• beer_assets.csv：演示网站资产表（中文名/图片URL/本地图片路径等）