# 离线索引产出规范

## 📋 索引任务列表

| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 |
|---------|---------|---------|---------|-----------|
| **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相似度索引

#### 输出格式
```
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之间，越大越相似）

#### 算法差异
| 算法 | 特点 | 适用场景 |
|------|------|---------|
| **Swing** | 基于用户共同行为，发现购买关联 | 详情页"大家都在看" |
| **Session W2V** | 基于会话序列，捕捉浏览顺序 | 详情页"看了又看" |
| **DeepWalk** | 基于图结构，发现深层关系 | 详情页"相关推荐" |
| **Content** | 基于商品属性，类目相似 | 冷启动商品推荐 |

### 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 | ~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 | 每天 |
| **总计** | **~245,000** | - | **~135MB** | - |

## 🎯 质量检查

### 数据完整性检查
```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`