CHANGELOG_DEBUG_MODE.md 5.56 KB
Edit Raw Blame History


离线推荐任务 - Debug模式功能更新
更新日期
2025-10-22
更新内容
为所有离线推荐任务添加了debug模式支持，使得所有任务都能够生成明文可读文件，方便查看推荐效果。
修改的文件
1. 脚本文件
✅ 新增debug支持的脚本

scripts/i2i_content_similar.py


添加 --debug 参数支持
添加 --top_n 参数支持
导入 save_readable_index 和 fetch_name_mappings 函数
修改 generate_similarity_index 函数，支持传入 top_n 参数
在debug模式下生成两个可读文件：


output/debug/i2i_content_name_YYYYMMDD_readable.txt
output/debug/i2i_content_pic_YYYYMMDD_readable.txt


scripts/i2i_item_behavior.py


导入 save_readable_index 函数
在debug模式下生成可读文件：


output/debug/i2i_item_behavior_YYYYMMDD_readable.txt


✅ 已有debug支持的脚本（保持不变）
以下脚本已经支持debug模式，无需修改：


scripts/i2i_swing.py ✓
scripts/i2i_session_w2v.py ✓
scripts/i2i_deepwalk.py ✓
scripts/interest_aggregation.py ✓
scripts/tag_category_similar.py ✓ (有自己的实现)

2. 调度脚本
run.sh

更新 Task 4 (内容相似度)，添加 --top_n $TOP_N $DEBUG_MODE 参数
确保所有任务都统一使用 $DEBUG_MODE 变量

3. 文档文件
新增文档

DEBUG_MODE_USAGE.md


完整的debug模式使用说明
包含所有支持debug模式的任务列表
使用方法和示例
性能影响说明
故障排查指南

CHANGELOG_DEBUG_MODE.md (本文件)


记录此次更新的详细内容


功能特性
Debug模式输出格式
所有任务在开启debug模式后，都会在 output/debug/ 目录生成对应的可读文件，格式统一为：
================================================================================
明文索引文件
生成时间: 2025-10-22 14:30:25
描述: i2i:task_name
总索引数: XXXXX
================================================================================

[1] i2i:task_name:item_id (商品名称)
--------------------------------------------------------------------------------
  1. ID:similar_id_1(相似商品1名称) - Score:0.8520
  2. ID:similar_id_2(相似商品2名称) - Score:0.7845
  3. ID:similar_id_3(相似商品3名称) - Score:0.7321
  ...

现在所有任务都支持的可读文件


任务
标准输出文件
可读文件


Swing算法
i2i_swing_YYYYMMDD.txt
debug/i2i_swing_YYYYMMDD_readable.txt


Session W2V
i2i_session_w2v_YYYYMMDD.txt
debug/i2i_session_w2v_YYYYMMDD_readable.txt


DeepWalk
i2i_deepwalk_YYYYMMDD.txt
debug/i2i_deepwalk_YYYYMMDD_readable.txt


内容相似度(名称)
i2i_content_name_YYYYMMDD.txt
debug/i2i_content_name_YYYYMMDD_readable.txt


内容相似度(图片)
i2i_content_pic_YYYYMMDD.txt
debug/i2i_content_pic_YYYYMMDD_readable.txt


Item行为相似度
i2i_item_behavior_YYYYMMDD.txt
debug/i2i_item_behavior_YYYYMMDD_readable.txt


Tag分类相似度
tag_category_similar_YYYYMMDD.txt
debug/tag_category_similar_YYYYMMDD_readable.txt


兴趣聚合(热门)
interest_hot_YYYYMMDD.txt
debug/interest_hot_YYYYMMDD_readable.txt


兴趣聚合(购物车)
interest_cart_YYYYMMDD.txt
debug/interest_cart_YYYYMMDD_readable.txt


兴趣聚合(新品)
interest_new_YYYYMMDD.txt
debug/interest_new_YYYYMMDD_readable.txt


兴趣聚合(全局)
interest_global_YYYYMMDD.txt
debug/interest_global_YYYYMMDD_readable.txt


使用方法
全局开启/关闭debug模式
编辑 run.sh，修改 DEBUG_MODE 变量：
DEBUG_MODE="--debug"  # 开启debug模式
# 或
DEBUG_MODE=""  # 关闭debug模式

单独运行任务
# i2i内容相似度
python3 scripts/i2i_content_similar.py --top_n 50 --debug

# i2i行为相似度
python3 scripts/i2i_item_behavior.py --lookback_days 180 --top_n 50 --debug

验证
所有修改已通过以下验证：


✅ Python语法检查 (python3 -m py_compile)
✅ Linter检查 (无错误)
✅ 代码逻辑审查
✅ 与现有debug模式实现保持一致

向后兼容性

✅ 不传 --debug 参数时，行为与之前完全一致
✅ 标准输出文件格式不变
✅ 所有现有脚本和调度任务继续正常工作

性能影响

不开启debug模式：无性能影响
开启debug模式：任务时间增加约10-20%（主要用于查询商品名称）

后续建议

定期清理 output/debug/ 目录，避免占用过多磁盘空间
在生产环境建议关闭debug模式，仅在需要检查效果时开启
可以考虑添加自动清理脚本，保留最近N天的debug文件

文件清单
修改的文件

scripts/i2i_content_similar.py
scripts/i2i_item_behavior.py
run.sh

新增的文件

DEBUG_MODE_USAGE.md
CHANGELOG_DEBUG_MODE.md

测试建议
运行以下命令测试debug模式是否正常工作：
# 测试i2i_content_similar
cd /home/tw/recommendation/offline_tasks
python3 scripts/i2i_content_similar.py --top_n 10 --debug

# 测试i2i_item_behavior
python3 scripts/i2i_item_behavior.py --lookback_days 30 --top_n 10 --debug

# 检查是否生成了可读文件
ls -lh output/debug/*_readable.txt

总结
此次更新确保了所有离线推荐任务都具有统一的debug模式支持，使得开发和运维人员能够更方便地查看和验证推荐效果，提高了系统的可维护性和可观测性。