🐛 Debug功能实现总结

✅ 完成情况

已实现 ✓

1. Debug工具库 (scripts/debug_utils.py) - ✅ 完成

   • 369行完整实现
   • 7个核心函数
   • 支持日志、明文输出、数据统计

2. 配置更新 (config/offline_config.py) - ✅ 完成

   • 新增DEBUG_CONFIG配置段
   • 默认参数配置（DEFAULT_LOOKBACK_DAYS=30）

3. i2i_swing.py - ✅ 完成

   • 完整debug日志
   • 明文索引输出
   • --debug参数支持

4. run_all.py - ✅ 完成

   • 支持--debug参数
   • 自动传递给所有子脚本

5. 文档 - ✅ 完成

   • DEBUG_GUIDE.md (完整使用指南)
   • QUICK_DEBUG_SUMMARY.md (快速总结)
   • UPDATE_CONFIG_GUIDE.md (配置调整指南)

待实现（可选）

其他4个脚本可以按需添加debug支持：

• i2i_session_w2v.py
• i2i_deepwalk.py
  
• i2i_content_similar.py
• interest_aggregation.py

实现模式：与i2i_swing.py相同，只需：

1. 导入debug_utils
2. 添加--debug参数
3. 调用log函数记录关键信息
4. 生成明文文件

🎯 核心功能

1. 详细日志

# 自动记录的信息：
✓ 算法参数（alpha, top_n, lookback_days等）
✓ SQL查询和数据获取（行数、时间范围）
✓ DataFrame详情（列名、类型、缺失值、统计）
✓ 行为类型分布（百分比）
✓ 用户/商品数量统计
✓ 处理进度（每N条/每N个商品）
✓ 中间结果采样（Top3展示）
✓ 每个步骤耗时
✓ 相似度分布统计（min/max/avg）

2. 明文索引

ID全部带名称，格式清晰：

[1] i2i:swing:12345(香蕉干)
--------------------------------------------------------------------------------
  1. ID:67890(芒果干) - Score:0.8567
  2. ID:11223(菠萝干) - Score:0.7234
  3. ID:44556(苹果干) - Score:0.6891

[2] interest:hot:category_level2:200(水果类)
--------------------------------------------------------------------------------
  1. ID:12345(香蕉干)
  2. ID:67890(芒果干)
  3. ID:11223(菠萝干)

3. 名称映射

自动从数据库获取：

• 商品名称 (prd_goods_sku.name)
• 分类名称 (prd_category.name)
• 供应商名称 (sup_supplier.name)
• 平台名称（硬编码映射）

📊 使用示例

基础使用

# 单个脚本debug
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug

# 所有任务debug
python3 run_all.py --lookback_days 7 --top_n 10 --debug

输出位置

offline_tasks/
├── logs/debug/
│   └── i2i_swing_20251016_193000.log    # 详细日志
└── output/debug/
    └── i2i_swing_20251016_readable.txt  # 明文索引

查看输出

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

# 查看明文索引
less output/debug/i2i_swing_*_readable.txt

# 搜索特定商品
grep "香蕉干" output/debug/*_readable.txt -A 5

🔧 技术实现

Debug Logger

from offline_tasks.scripts.debug_utils import setup_debug_logger

# 自动设置：
logger = setup_debug_logger('script_name', debug=True)
# - DEBUG级别
# - 控制台 + 文件双输出
# - 彩色格式化

数据统计

from offline_tasks.scripts.debug_utils import log_dataframe_info

# 自动记录：
log_dataframe_info(logger, df, "数据名称", sample_size=10)
# - 行列数
# - 数据类型
# - 缺失值
# - 采样数据
# - 数值统计

明文输出

from offline_tasks.scripts.debug_utils import (
    save_readable_index, fetch_name_mappings
)

# 获取名称映射
name_mappings = fetch_name_mappings(engine, debug=True)

# 保存明文文件
readable_file = save_readable_index(
    output_file,
    index_data,
    name_mappings,
    description="算法描述"
)

💡 使用建议

开发阶段

# 小数据量 + debug
python3 run_all.py --lookback_days 3 --top_n 10 --debug

✓ 快速验证
✓ 详细排错
✓ 检查效果

调优阶段

# 中等数据量 + debug
python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug

✓ 查看分布
✓ 评估质量
✓ 调整参数

生产阶段

# 大数据量 + 正常模式
python3 run_all.py --lookback_days 730 --top_n 50

✓ 高效运行
✓ 必要日志
✓ 节省空间

📈 性能影响

模式	运行时间	磁盘占用	日志详细度
正常	基准	基准	INFO
Debug	+10-20%	+50MB-500MB	DEBUG

建议：

• 开发/调试：始终使用debug
• 生产环境：关闭debug
• 定期清理：rm -rf logs/debug/* output/debug/*

🎉 主要优势

1. 数据可见 - 看清楚每一步的数据流向
2. 效果可查 - 明文文件直接检查推荐质量
   
3. 性能可测 - 每个步骤的耗时统计
4. 问题可追 - 详细日志快速定位错误
5. 参数可调 - 对比不同参数的效果

📚 相关文档

1. DEBUG_GUIDE.md - 完整使用指南（200+行）
2. QUICK_DEBUG_SUMMARY.md - 快速参考
3. UPDATE_CONFIG_GUIDE.md - 配置调整指南
4. scripts/debug_utils.py - 源代码和注释

✨ 下一步（可选）

如需为其他脚本添加debug支持，参考i2i_swing.py的模式：

# 1. 导入
from offline_tasks.scripts.debug_utils import (
    setup_debug_logger, log_dataframe_info, ...
)

# 2. 添加参数
parser.add_argument('--debug', action='store_true')

# 3. 设置logger
logger = setup_debug_logger('script_name', debug=args.debug)

# 4. 记录信息
log_algorithm_params(logger, params)
log_dataframe_info(logger, df, "名称")

# 5. 生成明文
if args.debug:
    name_mappings = fetch_name_mappings(engine, debug=True)
    save_readable_index(output_file, index_data, name_mappings)

---

状态: ✅ 核心功能已完成
当前: i2i_swing.py + run_all.py完整支持
扩展: 其他脚本可按需添加（模式已建立）