OFFLINE_INDEX_SPEC.md
6.85 KB
离线索引产出规范
📋 索引任务列表
| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 |
|---|---|---|---|---|
| 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 IDitem_name: 商品名称similar_id: 相似商品IDscore: 相似度分数（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 |
全局热门商品 | 首页"猜你喜欢" |
🔄 调度建议
每日调度（数据量大，变化快）
# 每天凌晨3点执行
0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py --lookback_days 730 --top_n 50
每周调度（数据量小，变化慢）
# 每周日凌晨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 | - |
🎯 质量检查
数据完整性检查
# 检查文件是否生成
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个商品
- 商品去重：同一商品在列表中只出现一次
🔍 查询示例
查看特定商品的相似推荐
# 查看商品12345的相似商品
grep "^12345\t" output/i2i_swing_20251016.txt
查看特定维度的热门商品
# 查看PC平台的热门商品
grep "^platform:pc\t" output/interest_aggregation_hot_20251016.txt
统计索引数量
# 统计各类型索引数量
for file in output/*_20251016.txt; do
echo "$file: $(wc -l < $file) 条"
done
⚠️ 注意事项
- 文件编码: 所有文件使用UTF-8编码
- 分隔符: 使用Tab（\t）分隔字段
- 商品ID: 使用数字类型，不带引号
- 分数精度: 相似度分数保留4位小数
- 排序规则: 相似商品按分数降序排列
- 去重: 确保推荐列表中没有重复商品
- 有效性: 推荐的商品必须是在售状态
🔗 相关文档
- Redis数据规范:
REDIS_DATA_SPEC.md - API接口文档:
RECOMMENDATION_API.md - Debug指南:
DEBUG_GUIDE.md - 配置说明:
UPDATE_CONFIG_GUIDE.md