tangwang / recommendation

DEBUG_GUIDE.md 9.44 KB

Debug模式使用指南

🐛 Debug功能概述

Debug模式为所有离线任务提供：

  1. 详细的DEBUG级别日志 - 显示数据流向、统计信息、处理进度
  2. 明文索引文件 - ID后面带上对应的名称，方便检查效果
  3. 数据采样展示 - 关键步骤的示例数据
  4. 性能统计 - 每个步骤的耗时和资源使用

🚀 快速开始

1. 运行单个脚本（Debug模式）

cd /home/tw/recommendation/offline_tasks

# Swing算法 - Debug模式
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug

# 兴趣聚合 - Debug模式  
python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug

# 内容相似 - Debug模式
python3 scripts/i2i_content_similar.py --top_n 10 --debug

2. 运行所有任务（Debug模式）

# 使用debug参数运行所有任务
python3 run_all.py --lookback_days 7 --top_n 10 --debug

📊 Debug输出说明

A. 日志输出

Debug模式下，日志会输出到两个地方：

  1. 控制台 - 实时查看进度
  2. Debug日志文件 - 完整保存

日志文件位置：

offline_tasks/logs/debug/i2i_swing_20251016_193000.log
offline_tasks/logs/debug/interest_aggregation_20251016_193500.log
...

B. 日志内容示例

2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数:
2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
2025-10-16 19:30:00 - i2i_swing - DEBUG -   alpha: 0.5
2025-10-16 19:30:00 - i2i_swing - DEBUG -   top_n: 10
2025-10-16 19:30:00 - i2i_swing - DEBUG -   lookback_days: 7
2025-10-16 19:30:00 - i2i_swing - DEBUG -   debug: True
2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================

2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录

2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================
2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息:
2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================
2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234
2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5
2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name']
2025-10-16 19:30:05 - i2i_swing - DEBUG - 
2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型:
2025-10-16 19:30:05 - i2i_swing - DEBUG -   user_id: object
2025-10-16 19:30:05 - i2i_swing - DEBUG -   item_id: int64
2025-10-16 19:30:05 - i2i_swing - DEBUG -   event_type: object
2025-10-16 19:30:05 - i2i_swing - DEBUG -   create_time: datetime64[ns]
2025-10-16 19:30:05 - i2i_swing - DEBUG -   item_name: object

2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布:
2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToCart: 8520 (55.93%)
2025-10-16 19:30:05 - i2i_swing - DEBUG -   contactFactory: 3456 (22.68%)
2025-10-16 19:30:05 - i2i_swing - DEBUG -   purchase: 2134 (14.01%)
2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToPool: 1124 (7.38%)

2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345
2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%)
2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%)
...

C. 明文索引文件

Debug模式下，每个索引文件都会生成对应的明文文件：

原始索引文件 (output/i2i_swing_20251016.txt):

12345   香蕉干   67890:0.8567,11223:0.7234,44556:0.6891
67890   芒果干   12345:0.8567,22334:0.7123,55667:0.6543

明文索引文件 (output/debug/i2i_swing_20251016_readable.txt):

================================================================================
明文索引文件
生成时间: 2025-10-16 19:35:00
描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7)
总索引数: 2345
================================================================================

[1] i2i:swing:12345(香蕉干)
--------------------------------------------------------------------------------
  1. ID:67890(芒果干) - Score:0.8567
  2. ID:11223(菠萝干) - Score:0.7234
  3. ID:44556(苹果干) - Score:0.6891
  4. ID:22334(木瓜干) - Score:0.6234
  5. ID:55667(草莓干) - Score:0.5891

[2] i2i:swing:67890(芒果干)
--------------------------------------------------------------------------------
  1. ID:12345(香蕉干) - Score:0.8567
  2. ID:22334(木瓜干) - Score:0.7123
  3. ID:55667(草莓干) - Score:0.6543
  4. ID:11223(菠萝干) - Score:0.6234
  5. ID:44556(苹果干) - Score:0.5891

...

================================================================================
已输出 50/2345 个索引
================================================================================

📁 文件结构

Debug模式下的文件组织：

offline_tasks/
├── output/
│   ├── i2i_swing_20251016.txt              # 原始索引文件
│   ├── interest_aggregation_hot_20251016.txt
│   └── debug/                               # Debug明文文件目录
│       ├── i2i_swing_20251016_readable.txt  # 明文索引
│       ├── interest_aggregation_hot_20251016_readable.txt
│       └── ...
└── logs/
    ├── run_all_20251016.log                 # 主日志
    └── debug/                               # Debug详细日志目录
        ├── i2i_swing_20251016_193000.log
        ├── interest_aggregation_20251016_193500.log
        └── ...

🔍 使用场景

场景1：调试数据流程

# 使用小数据量+debug模式快速验证
python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug

# 查看日志，检查：
# - 数据加载是否正确
# - 行为类型分布是否合理
# - 用户/商品数量是否符合预期

场景2：检查推荐效果

# 生成明文索引文件
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug

# 打开明文文件查看：
cat output/debug/i2i_swing_20251016_readable.txt | less

# 检查推荐是否合理，例如：
# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理
# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数

场景3：性能调优

# Debug模式查看各步骤耗时
python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时"

# 输出示例：
# 步骤1耗时: 2.34秒
# 步骤2耗时: 15.67秒  <- 瓶颈在这里
# 步骤3耗时: 1.23秒
# 总耗时: 19.24秒

场景4：参数调整

# 测试不同alpha值的效果
python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1
python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1
python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1

# 对比明文文件，选择最佳参数
diff output/debug/i2i_swing_*_readable.txt

💡 最佳实践

1. 开发调试阶段

# 使用小数据量 + Debug模式
python3 run_all.py --lookback_days 3 --top_n 10 --debug
  • ✅ 快速验证流程
  • ✅ 详细日志便于排错
  • ✅ 明文文件检查效果

2. 参数调优阶段

# 中等数据量 + Debug模式
python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug
  • ✅ 查看数据分布
  • ✅ 评估推荐质量
  • ✅ 调整算法参数

3. 生产运行阶段

# 大数据量 + 正常模式（不加--debug）
python3 run_all.py --lookback_days 730 --top_n 50
  • ✅ 高效运行
  • ✅ 只输出必要日志
  • ✅ 节省磁盘空间

🛠️ Debug工具

查看实时日志

# 实时查看debug日志
tail -f logs/debug/i2i_swing_*.log

# 只看DEBUG级别
tail -f logs/debug/i2i_swing_*.log | grep "DEBUG"

# 只看错误
tail -f logs/debug/i2i_swing_*.log | grep "ERROR"

统计分析

# 统计处理的数据量
grep "总行数" logs/debug/*.log

# 统计生成的索引数
grep "总索引数" output/debug/*_readable.txt

# 查看性能统计
grep "耗时" logs/debug/*.log

快速检查

# 检查前10个推荐
head -50 output/debug/i2i_swing_*_readable.txt

# 搜索特定商品的推荐
grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10

# 统计推荐数量分布
grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l

⚠️ 注意事项

  1. 磁盘空间

    • Debug日志和明文文件会占用较多空间
    • 建议定期清理：rm -rf logs/debug/* output/debug/*

  2. 运行时间

    • Debug模式会增加10-20%的运行时间
    • 生产环境建议关闭debug

  3. 敏感信息

    • 明文文件包含商品名称等信息
    • 注意数据安全和隐私保护

  4. 文件编码

    • 明文文件使用UTF-8编码
    • 确保查看工具支持中文显示

📖 相关命令

# 查看帮助
python3 scripts/i2i_swing.py --help
python3 run_all.py --help

# 验证配置
python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)"

# 测试debug工具
python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')"

✅ 验证Debug功能

# 快速测试
cd /home/tw/recommendation/offline_tasks
python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug

# 应该看到：
# ✓ DEBUG级别日志输出
# ✓ 创建debug日志文件
# ✓ 生成明文索引文件
# ✓ 显示数据统计信息

Debug模式: 开发和调试的利器
正常模式: 生产环境的选择
灵活切换: 一个参数的事情