# 离线推荐任务 - Debug模式功能更新

## 更新日期
2025-10-22

## 更新内容

为所有离线推荐任务添加了debug模式支持，使得所有任务都能够生成明文可读文件，方便查看推荐效果。

## 修改的文件

### 1. 脚本文件

#### ✅ 新增debug支持的脚本

1. **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`

2. **scripts/i2i_item_behavior.py**
   - 导入 `save_readable_index` 函数
   - 在debug模式下生成可读文件：
     - `output/debug/i2i_item_behavior_YYYYMMDD_readable.txt`

#### ✅ 已有debug支持的脚本（保持不变）

以下脚本已经支持debug模式，无需修改：

1. **scripts/i2i_swing.py** ✓
2. **scripts/i2i_session_w2v.py** ✓
3. **scripts/i2i_deepwalk.py** ✓
4. **scripts/interest_aggregation.py** ✓
5. **scripts/tag_category_similar.py** ✓ (有自己的实现)

### 2. 调度脚本

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

### 3. 文档文件

#### 新增文档

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

2. **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` 变量：

```bash
DEBUG_MODE="--debug"  # 开启debug模式
# 或
DEBUG_MODE=""  # 关闭debug模式
```

### 单独运行任务

```bash
# 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
```

## 验证

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

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

## 向后兼容性

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

## 性能影响

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

## 后续建议

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

## 文件清单

### 修改的文件
- `scripts/i2i_content_similar.py`
- `scripts/i2i_item_behavior.py`
- `run.sh`

### 新增的文件
- `DEBUG_MODE_USAGE.md`
- `CHANGELOG_DEBUG_MODE.md`

## 测试建议

运行以下命令测试debug模式是否正常工作：

```bash
# 测试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模式支持，使得开发和运维人员能够更方便地查看和验证推荐效果，提高了系统的可维护性和可观测性。