# 离线索引产出规范
  
  ## 📋 索引任务列表
  
  | 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 |
  |---------|---------|---------|---------|-----------|

  | **i2i_swing_cpp** | `cd offline_tasks/collaboration && bash run.sh` | 每天 | `offline_tasks/collaboration/output/swing_similar.txt` | `item_id \t similar_id1:score1,similar_id2:score2,...` |

  | **i2i_swing** | `python3 scripts/i2i_swing.py` | 每天 | `output/i2i_swing_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
  | **i2i_session_w2v** | `python3 scripts/i2i_session_w2v.py` | 每天 | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
  | **i2i_deepwalk** | `python3 scripts/i2i_deepwalk.py` | 每天 | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
  | **i2i_content** | `python3 scripts/i2i_content_similar.py` | 每周 | `output/i2i_content_hybrid_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
  | **interest_hot** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
  | **interest_cart** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
  | **interest_new** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
  | **interest_global** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
  
  ## 📊 详细格式说明
  
  ### 1. i2i相似度索引
  

  #### 1.1 C++ Swing算法（高性能版本）
  
  **输出格式**
  ```
  item_id \t similar_id1:score1,similar_id2:score2,...
  ```
  
  **示例**
  ```
  3600052	2704531:0.00431593,2503886:0.00431593,3371410:0.00431593,3186572:0.00431593
  2704531	3600052:0.00431593,2503886:0.00863186,3371410:0.00431593
  ```
  
  **字段说明**
  - `item_id`: 商品SKU ID
  - `similar_id`: 相似商品ID
  - `score`: 相似度分数（原始Swing分数，范围不固定）
  
  **特点**
  - ⚡ **高性能**: C++实现，速度比Python快10-100倍
  - 📊 **大规模**: 适合处理10万+商品的相似度计算
  - 🔢 **原始分数**: 输出Swing算法原始分数（未归一化）

  - 📁 **文件位置**: `offline_tasks/collaboration/output/swing_similar.txt`
  - 📝 **可读版本**: `offline_tasks/collaboration/output/swing_similar_readable.txt` (包含商品名称)

  
  #### 1.2 Python算法（标准版本）
  
  **输出格式**

  ```
  item_id \t item_name \t similar_id1:score1,similar_id2:score2,...
  ```
  

  **示例**

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

  **字段说明**

  - `item_id`: 商品SKU ID
  - `item_name`: 商品名称
  - `similar_id`: 相似商品ID
  - `score`: 相似度分数（0-1之间，越大越相似）
  

  **特点**
  - 🐍 **易调试**: Python实现，便于开发和调试
  - 🎯 **功能丰富**: 支持时间衰减、日期维度等高级特性
  - 📊 **归一化**: 相似度分数已归一化到0-1区间
  - 📁 **文件位置**: `offline_tasks/output/i2i_*_YYYYMMDD.txt`
  
  #### 1.3 算法对比
  
  | 算法 | 实现语言 | 性能 | 特点 | 适用场景 |
  |------|---------|------|------|---------|
  | **Swing (C++)** | C++ | ⚡⚡⚡ | 高性能，大规模数据 | 生产环境，海量数据 |
  | **Swing (Python)** | Python | ⚡ | 支持日期维度，时间衰减 | 需要高级特性 |
  | **Session W2V** | Python | ⚡ | 基于会话序列 | 详情页"看了又看" |
  | **DeepWalk** | Python | ⚡ | 基于图结构 | 详情页"相关推荐" |
  | **Content** | Python | ⚡⚡ | 基于商品属性 | 冷启动商品推荐 |
  
  #### 1.4 使用建议
  
  **C++ Swing适用场景**:
  - 商品数量 > 50,000
  - 需要快速计算结果
  - 生产环境部署
  - 计算资源有限
  
  **Python Swing适用场景**:
  - 需要时间衰减功能
  - 需要日期维度分析
  - 开发调试阶段
  - 需要灵活调整参数

  
  ### 2. 兴趣点聚合索引
  
  #### 输出格式
  ```
  dimension_key \t item_id1,item_id2,item_id3,...
  ```
  
  #### 示例
  ```
  platform:pc	12345,67890,11223,44556,22334
  category_level2:200	67890,12345,22334,55667,11223
  platform_category2:pc_200	12345,67890,22334,11223,55667
  supplier:10001	12345,44556,22334,67890,11223
  ```
  
  #### 维度说明
  
  **单维度（7个）**
  - `platform:{platform_id}` - 业务平台（pc, h5, app等）
  - `client_platform:{client}` - 客户端平台（iOS, Android, Web等）
  - `supplier:{supplier_id}` - 供应商
  - `category_level1:{cat_id}` - 一级分类
  - `category_level2:{cat_id}` - 二级分类
  - `category_level3:{cat_id}` - 三级分类
  - `category_level4:{cat_id}` - 四级分类
  
  **组合维度（4个）**
  - `platform_client:{platform}_{client}` - 平台+客户端
  - `platform_category2:{platform}_{cat_id}` - 平台+二级分类
  - `platform_category3:{platform}_{cat_id}` - 平台+三级分类
  - `client_category2:{client}_{cat_id}` - 客户端+二级分类
  
  #### 列表类型说明
  
  | 类型 | 文件名 | 计算逻辑 | 适用场景 |
  |------|--------|---------|---------|
  | **hot** | `interest_aggregation_hot_YYYYMMDD.txt` | 最近N天的高频交互商品 | 首页"热门推荐" |
  | **cart** | `interest_aggregation_cart_YYYYMMDD.txt` | 高加购率商品 | 首页"热门加购" |
  | **new** | `interest_aggregation_new_YYYYMMDD.txt` | 最近上架的新品 | 首页"新品推荐" |
  | **global** | `interest_aggregation_global_YYYYMMDD.txt` | 全局热门商品 | 首页"猜你喜欢" |
  
  ## 🔄 调度建议
  
  ### 每日调度（数据量大，变化快）
  ```bash
  # 每天凌晨3点执行
  0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py --lookback_days 730 --top_n 50
  ```
  
  ### 每周调度（数据量小，变化慢）
  ```bash
  # 每周日凌晨4点执行
  0 4 * * 0 cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_content_similar.py --top_n 50
  ```
  
  ## 📁 文件命名规范
  
  ### 标准格式
  ```
  {algorithm_name}_{date}.txt
  ```
  
  ### 示例
  ```
  i2i_swing_20251016.txt
  i2i_session_w2v_20251016.txt
  interest_aggregation_hot_20251016.txt
  ```
  
  ### Debug文件（开发调试用）
  ```
  output/debug/{algorithm_name}_{date}_readable.txt
  logs/debug/{algorithm_name}_{date}_{time}.log
  ```
  
  ## 📈 数据量估算
  
  | 索引类型 | 索引数量 | 单条大小 | 总大小 | 更新频率 |
  |---------|---------|---------|--------|---------|

  | i2i_swing_cpp | ~50,000 | ~400B | ~20MB | 每天 |

  | i2i_swing | ~50,000 | ~500B | ~25MB | 每天 |
  | i2i_session_w2v | ~50,000 | ~500B | ~25MB | 每天 |
  | i2i_deepwalk | ~50,000 | ~500B | ~25MB | 每天 |
  | i2i_content | ~50,000 | ~500B | ~25MB | 每周 |
  | interest_hot | ~10,000 | ~1KB | ~10MB | 每天 |
  | interest_cart | ~10,000 | ~1KB | ~10MB | 每天 |
  | interest_new | ~5,000 | ~1KB | ~5MB | 每天 |
  | interest_global | ~10,000 | ~1KB | ~10MB | 每天 |

  | **总计** | **~295,000** | - | **~155MB** | - |
  
  **说明**:
  - C++ Swing因为不包含商品名称，单条大小较小
  - 推荐同时使用C++ Swing（生产）和Python Swing（开发）

  
  ## 🎯 质量检查
  
  ### 数据完整性检查
  ```bash
  # 检查文件是否生成
  ls -lh output/*_$(date +%Y%m%d).txt
  
  # 检查行数
  wc -l output/*_$(date +%Y%m%d).txt
  
  # 检查格式
  head -5 output/i2i_swing_$(date +%Y%m%d).txt
  ```
  
  ### 数据质量指标
  
  **i2i索引质量**
  - 覆盖率：有推荐的商品数 / 总商品数 > 80%
  - 推荐数量：每个商品推荐10-50个相似商品
  - 分数范围：相似度分数在0.01-1.0之间
  
  **兴趣聚合质量**
  - 覆盖率：有数据的维度数 / 总维度数 > 60%
  - 推荐数量：每个维度推荐50-1000个商品
  - 商品去重：同一商品在列表中只出现一次
  
  ## 🔍 查询示例
  
  ### 查看特定商品的相似推荐
  ```bash
  # 查看商品12345的相似商品
  grep "^12345\t" output/i2i_swing_20251016.txt
  ```
  
  ### 查看特定维度的热门商品
  ```bash
  # 查看PC平台的热门商品
  grep "^platform:pc\t" output/interest_aggregation_hot_20251016.txt
  ```
  
  ### 统计索引数量
  ```bash
  # 统计各类型索引数量
  for file in output/*_20251016.txt; do
      echo "$file: $(wc -l < $file) 条"
  done
  ```
  
  ## ⚠️ 注意事项
  
  1. **文件编码**: 所有文件使用UTF-8编码
  2. **分隔符**: 使用Tab（\t）分隔字段
  3. **商品ID**: 使用数字类型，不带引号
  4. **分数精度**: 相似度分数保留4位小数
  5. **排序规则**: 相似商品按分数降序排列
  6. **去重**: 确保推荐列表中没有重复商品
  7. **有效性**: 推荐的商品必须是在售状态
  
  ## 🔗 相关文档
  
  - **Redis数据规范**: `REDIS_DATA_SPEC.md`
  - **API接口文档**: `RECOMMENDATION_API.md`
  - **Debug指南**: `DEBUG_GUIDE.md`
  - **配置说明**: `UPDATE_CONFIG_GUIDE.md`