# Debug模式使用指南 ## 🐛 Debug功能概述 Debug模式为所有离线任务提供： 1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 3. **数据采样展示** - 关键步骤的示例数据 4. **性能统计** - 每个步骤的耗时和资源使用 ## 🚀 快速开始 ### 1. 运行单个脚本（Debug模式） ```bash 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模式） ```bash # 使用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：调试数据流程 ```bash # 使用小数据量+debug模式快速验证 python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug # 查看日志，检查： # - 数据加载是否正确 # - 行为类型分布是否合理 # - 用户/商品数量是否符合预期 ``` ### 场景2：检查推荐效果 ```bash # 生成明文索引文件 python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug # 打开明文文件查看： cat output/debug/i2i_swing_20251016_readable.txt | less # 检查推荐是否合理，例如： # - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 # - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 ``` ### 场景3：性能调优 ```bash # Debug模式查看各步骤耗时 python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" # 输出示例： # 步骤1耗时: 2.34秒 # 步骤2耗时: 15.67秒 <- 瓶颈在这里 # 步骤3耗时: 1.23秒 # 总耗时: 19.24秒 ``` ### 场景4：参数调整 ```bash # 测试不同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. 开发调试阶段 ```bash # 使用小数据量 + Debug模式 python3 run_all.py --lookback_days 3 --top_n 10 --debug ``` - ✅ 快速验证流程 - ✅ 详细日志便于排错 - ✅ 明文文件检查效果 ### 2. 参数调优阶段 ```bash # 中等数据量 + Debug模式 python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug ``` - ✅ 查看数据分布 - ✅ 评估推荐质量 - ✅ 调整算法参数 ### 3. 生产运行阶段 ```bash # 大数据量 + 正常模式（不加--debug） python3 run_all.py --lookback_days 730 --top_n 50 ``` - ✅ 高效运行 - ✅ 只输出必要日志 - ✅ 节省磁盘空间 ## 🛠️ Debug工具 ### 查看实时日志 ```bash # 实时查看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" ``` ### 统计分析 ```bash # 统计处理的数据量 grep "总行数" logs/debug/*.log # 统计生成的索引数 grep "总索引数" output/debug/*_readable.txt # 查看性能统计 grep "耗时" logs/debug/*.log ``` ### 快速检查 ```bash # 检查前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编码 - 确保查看工具支持中文显示 ## 📖 相关命令 ```bash # 查看帮助 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功能 ```bash # 快速测试 cd /home/tw/recommendation/offline_tasks python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug # 应该看到： # ✓ DEBUG级别日志输出 # ✓ 创建debug日志文件 # ✓ 生成明文索引文件 # ✓ 显示数据统计信息 ``` --- **Debug模式**: 开发和调试的利器 **正常模式**: 生产环境的选择 **灵活切换**: 一个参数的事情