# 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模式**: 开发和调试的利器  
  **正常模式**: 生产环境的选择  
  **灵活切换**: 一个参数的事情