From 1211812579e87ed6d9c44956c630b1b6fde127f9 Mon Sep 17 00:00:00 2001 From: tangwang Date: Fri, 17 Oct 2025 19:33:48 +0800 Subject: [PATCH] offline tasks: mem optimize --- offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md | 223 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/CHANGELOG.md | 43 ------------------------------------------- offline_tasks/CHANGES_SUMMARY.md | 326 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/COMPLETE_INDEX_LIST.md | 350 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/CONTENT_SIMILARITY_UPDATE.md | 243 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/CURRENT_STATUS.md | 229 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/DATABASE_SETUP.md | 179 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/DEBUG_GUIDE.md | 332 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/DELIVERY.md | 335 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/FIELD_MAPPING.md | 172 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/FINAL_SUMMARY.md | 269 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/FINAL_UPDATE.md | 301 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/FIX_NAME_MAPPING.md | 186 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ offline_tasks/LATEST_UPDATES.md | 155 ----------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/MEMORY_MONITORING_UPDATE.md | 376 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/OFFLINE_INDEX_SPEC.md | 197 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/PROJECT_SUMMARY.md | 276 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ offline_tasks/QUICKSTART.md | 213 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/QUICKSTART_NEW.md | 321 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/QUICK_DEBUG_SUMMARY.md | 128 -------------------------------------------------------------------------------------------------------------------------------- offline_tasks/REDIS_DATA_SPEC.md | 306 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ offline_tasks/RUN_SCRIPT_GUIDE.md | 304 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/START_HERE.md | 302 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/STRUCTURE.md | 303 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/SWING_USAGE.md | 322 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/TROUBLESHOOTING.md | 217 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/UPDATE_CONFIG_GUIDE.md | 205 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/config/offline_config.py | 2 +- offline_tasks/doc/COMPLETE_INDEX_LIST.md | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/DATABASE_SETUP.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/DEBUG_GUIDE.md | 332 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/OFFLINE_INDEX_SPEC.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/REDIS_DATA_SPEC.md | 306 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/RUN_SCRIPT_GUIDE.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/Redis数据规范.md | 306 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/SWING_USAGE.md | 322 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/Swing实现总结.md | 375 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/Swing算法使用指南.md | 322 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/TROUBLESHOOTING.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/从这里开始.md | 302 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/完整索引列表.md | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/快速开始.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/故障排查指南.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/数据库配置说明.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/更新日志.md | 43 +++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/离线索引数据规范.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/系统改进总结-20241017.md | 366 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/调试指南.md | 332 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/运行脚本指南.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/run.sh | 9 ++------- offline_tasks/run_all.py | 29 +++++++++++++++++++++++++++++ offline_tasks/scripts/add_names_to_swing.py | 26 ++++++++++---------------- offline_tasks/scripts/debug_utils.py | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- offline_tasks/scripts/fetch_item_attributes.py | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/scripts/i2i_swing.py | 40 ++++++++++++++++++++++++++++++++++------ 56 files changed, 6103 insertions(+), 6844 deletions(-) delete mode 100644 offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md delete mode 100644 offline_tasks/CHANGELOG.md delete mode 100644 offline_tasks/CHANGES_SUMMARY.md delete mode 100644 offline_tasks/COMPLETE_INDEX_LIST.md delete mode 100644 offline_tasks/CONTENT_SIMILARITY_UPDATE.md delete mode 100644 offline_tasks/CURRENT_STATUS.md delete mode 100644 offline_tasks/DATABASE_SETUP.md delete mode 100644 offline_tasks/DEBUG_GUIDE.md delete mode 100644 offline_tasks/DELIVERY.md delete mode 100644 offline_tasks/FIELD_MAPPING.md delete mode 100644 offline_tasks/FINAL_SUMMARY.md delete mode 100644 offline_tasks/FINAL_UPDATE.md delete mode 100644 offline_tasks/FIX_NAME_MAPPING.md delete mode 100644 offline_tasks/LATEST_UPDATES.md delete mode 100644 offline_tasks/MEMORY_MONITORING_UPDATE.md delete mode 100644 offline_tasks/OFFLINE_INDEX_SPEC.md delete mode 100644 offline_tasks/PROJECT_SUMMARY.md delete mode 100644 offline_tasks/QUICKSTART.md delete mode 100644 offline_tasks/QUICKSTART_NEW.md delete mode 100644 offline_tasks/QUICK_DEBUG_SUMMARY.md delete mode 100644 offline_tasks/REDIS_DATA_SPEC.md delete mode 100644 offline_tasks/RUN_SCRIPT_GUIDE.md delete mode 100644 offline_tasks/START_HERE.md delete mode 100644 offline_tasks/STRUCTURE.md delete mode 100644 offline_tasks/SWING_USAGE.md delete mode 100644 offline_tasks/TROUBLESHOOTING.md delete mode 100644 offline_tasks/UPDATE_CONFIG_GUIDE.md create mode 100644 offline_tasks/doc/COMPLETE_INDEX_LIST.md create mode 100644 offline_tasks/doc/DATABASE_SETUP.md create mode 100644 offline_tasks/doc/DEBUG_GUIDE.md create mode 100644 offline_tasks/doc/OFFLINE_INDEX_SPEC.md create mode 100644 offline_tasks/doc/README.md create mode 100644 offline_tasks/doc/REDIS_DATA_SPEC.md create mode 100644 offline_tasks/doc/RUN_SCRIPT_GUIDE.md create mode 100644 offline_tasks/doc/Redis数据规范.md create mode 100644 offline_tasks/doc/SWING_USAGE.md create mode 100644 offline_tasks/doc/Swing实现总结.md create mode 100644 offline_tasks/doc/Swing算法使用指南.md create mode 100644 offline_tasks/doc/TROUBLESHOOTING.md create mode 100644 offline_tasks/doc/从这里开始.md create mode 100644 offline_tasks/doc/完整索引列表.md create mode 100644 offline_tasks/doc/快速开始.md create mode 100644 offline_tasks/doc/故障排查指南.md create mode 100644 offline_tasks/doc/数据库配置说明.md create mode 100644 offline_tasks/doc/更新日志.md create mode 100644 offline_tasks/doc/离线索引数据规范.md create mode 100644 offline_tasks/doc/系统改进总结-20241017.md create mode 100644 offline_tasks/doc/调试指南.md create mode 100644 offline_tasks/doc/运行脚本指南.md create mode 100644 offline_tasks/scripts/fetch_item_attributes.py diff --git a/offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md b/offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md deleted file mode 100644 index 7df6a62..0000000 --- a/offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md +++ /dev/null @@ -1,223 +0,0 @@ -# B2B低频场景优化总结 - -## 📋 优化背景 - -B2B场景的特点： -- ✅ 用户行为频次**非常低** -- ✅ 行为间隔时间**可能很长** -- ✅ 历史行为**依然重要**，不应过度衰减 - -## ✅ 已完成的优化 - -### 1. **i2i_session_w2v.py** - Session分割策略优化 - -#### 修改前（基于时间间隔） -```python -# 问题：B2B场景下，用户可能几个月才有一次行为 -# 基于30分钟间隔分割session不合适 -session_gap_minutes = 30 -if (current_time - last_time).total_seconds() / 60 > session_gap_minutes: - # 新session -``` - -#### 修改后（固定长度分块） -```python -# 参考: graphembedding/session_w2v/prepare_data.py -# 按固定长度分块，不考虑时间间隔 -max_session_length = 50 # 最大会话长度 -min_session_length = 2 # 最小会话长度 - -# 按用户行为序列分块 -user_sessions = [ - item_sequence[i:i + max_session_length] - for i in range(0, len(item_sequence), max_session_length) -] -``` - -**优势：** -- 不依赖时间间隔，适合低频场景 -- 逻辑简化，性能更好 -- 保留用户行为的顺序信息 - -**新增参数：** -```bash ---max_session_length 50 # 最大会话长度 ---min_session_length 2 # 最小会话长度（过滤太短的序列） -``` - ---- - -### 2. **i2i_swing.py** - 关闭时间衰减 - -#### 修改前 -```python ---time_decay # 默认True，开启时间衰减 -# 30天前权重: 0.95 -# 60天前权重: 0.90 -# 180天前权重: 0.74 (衰减过快) -``` - -#### 修改后 -```python ---time_decay # 默认False，关闭时间衰减 -# 所有历史行为权重相同，更适合低频场景 -``` - -**原因：** -在B2B低频场景下，6个月前的行为可能依然很有价值，不应该被大幅衰减。 - ---- - -### 3. **interest_aggregation.py** - 关闭时间衰减 - -#### 修改内容 -```python -# 热门商品索引 - 关闭时间衰减 -list_type_indices['hot'] = aggregate_by_dimensions( - df_hot, behavior_weights, time_decay=False # 改为False -) - -# 加购商品索引 - 关闭时间衰减 -list_type_indices['cart'] = aggregate_by_dimensions( - df_cart, behavior_weights, time_decay=False # 改为False -) - -# 全局索引 - 关闭时间衰减 -global_aggregations = aggregate_by_dimensions( - df, behavior_weights, time_decay=False # 改为False -) - -# 新品索引 - 本来就不用时间衰减（保持不变） -list_type_indices['new'] = aggregate_by_dimensions( - df_new, behavior_weights, time_decay=False -) -``` - ---- - -## 🚀 使用方法 - -### Session W2V（已自动优化） -```bash -# 使用新的固定长度分块策略 -python3 scripts/i2i_session_w2v.py \ - --lookback_days 365 \ - --max_session_length 50 \ - --min_session_length 2 \ - --top_n 50 \ - --debug -``` - -### Swing算法（默认已关闭时间衰减） -```bash -# 默认不使用时间衰减，适合B2B场景 -python3 scripts/i2i_swing.py \ - --lookback_days 365 \ - --top_n 50 \ - --debug - -# 如果需要开启时间衰减（不推荐） -python3 scripts/i2i_swing.py \ - --lookback_days 365 \ - --time_decay \ - --decay_factor 0.99 # 更缓慢的衰减 -``` - -### 兴趣聚合（已自动优化） -```bash -# 已默认关闭时间衰减 -python3 scripts/interest_aggregation.py \ - --lookback_days 365 \ - --top_n 100 \ - --debug -``` - -### 运行所有任务 -```bash -cd /home/tw/recommendation/offline_tasks - -# 使用更长的回溯天数，适合低频场景 -python3 run_all.py --lookback_days 365 --top_n 50 --debug -``` - ---- - -## 📊 其他索引（无需修改） - -### i2i_deepwalk.py -- ✅ 不涉及session分割 -- ✅ 不使用时间衰减 -- ✅ 无需修改 - -### i2i_content_similar.py -- ✅ 基于商品属性的相似度 -- ✅ 不涉及时间因素 -- ✅ 无需修改 - ---- - -## 💡 建议的配置调整 - -### 1. 增加回溯天数 -```python -# offline_tasks/config/offline_config.py -DEFAULT_LOOKBACK_DAYS = 365 # 从默认值改为365天 -``` - -### 2. 如果需要重新启用时间衰减（特殊场景） -```bash -# Swing算法 -python3 scripts/i2i_swing.py --time_decay --decay_factor 0.99 - -# 修改interest_aggregation.py中的hard-coded值 -# 将 time_decay=False 改回 time_decay=True -``` - ---- - -## ✨ 优化效果 - -### 预期改进 -1. **Session W2V**: - - 不再因为时间间隔过长而丢失用户行为序列 - - 能够更好地捕捉低频用户的行为模式 - -2. **Swing算法**: - - 历史行为不会因时间衰减而被低估 - - 在数据稀疏的情况下充分利用所有历史数据 - -3. **兴趣聚合**: - - 长期累积的用户偏好得到保留 - - 推荐结果更稳定 - -### 需要监控的指标 -- [ ] Session数量变化 -- [ ] 相似物品覆盖率 -- [ ] 推荐效果指标（CTR、转化率等） - ---- - -## 📝 回滚方法 - -如果需要恢复之前的逻辑： - -```bash -# 1. 恢复i2i_swing.py的时间衰减 -git diff offline_tasks/scripts/i2i_swing.py -# 将 default=False 改回 default=True - -# 2. 恢复interest_aggregation.py的时间衰减 -git diff offline_tasks/scripts/interest_aggregation.py -# 将所有 time_decay=False 改回 time_decay=True - -# 3. 恢复i2i_session_w2v.py的时间分割 -git diff offline_tasks/scripts/i2i_session_w2v.py -# 恢复基于时间间隔的session分割逻辑 -``` - ---- - -**修改时间**: 2025-10-16 -**适用场景**: B2B低频交易场景 -**核心原则**: 在低频场景下，所有历史数据都很宝贵，不要过度衰减 - diff --git a/offline_tasks/CHANGELOG.md b/offline_tasks/CHANGELOG.md deleted file mode 100644 index 1b7bad9..0000000 --- a/offline_tasks/CHANGELOG.md +++ /dev/null @@ -1,43 +0,0 @@ -# 更新日志 - -## v1.0.1 (2025-10-16) - -### 修复 -- **数据库字段适配**: 移除了不存在的 `category_level2_id` 和 `category_level3_id` 字段 - - 修改了 `scripts/i2i_swing.py` 中的SQL查询 - - 修改了 `scripts/interest_aggregation.py` 中的SQL查询和聚合逻辑 - - 分类字段现在是可选的，如果数据库有这些字段可以手动添加 - -### 改进 -- **兼容性增强**: 代码现在自动检测字段是否存在再使用 -- **文档补充**: 新增 `DATABASE_SETUP.md` 说明如何配置数据库字段 - -### 使用建议 -如果您的数据库有分类字段，请参考 `DATABASE_SETUP.md` 手动添加支持。 - -基础功能（i2i相似度）不需要分类字段即可正常运行。 - -## v1.0.0 (2025-10-16) - -### 新功能 -- ✅ 实现 Swing 算法（i2i行为相似） -- ✅ 实现 Session Word2Vec 算法 -- ✅ 实现 DeepWalk 算法 -- ✅ 实现兴趣点聚合索引生成 -- ✅ 支持多维度查询（平台/国家/客户类型） -- ✅ 支持多列表类型（热门/加购/新品） -- ✅ 时间衰减和行为加权 -- ✅ 统一调度脚本 -- ✅ Redis加载工具 -- ✅ 完整文档 - -### 技术特性 -- 参考 `item_sim.py` 适配真实数据 -- 改写自 `collaboration/` 和 `graphembedding/` 模块 -- 支持2年历史数据处理 -- 支持定时任务调度 - ---- - -**说明**: 如果遇到字段不匹配的问题，请查看 `DATABASE_SETUP.md` 进行配置。 - diff --git a/offline_tasks/CHANGES_SUMMARY.md b/offline_tasks/CHANGES_SUMMARY.md deleted file mode 100644 index 948a2a5..0000000 --- a/offline_tasks/CHANGES_SUMMARY.md +++ /dev/null @@ -1,326 +0,0 @@ -# 离线任务更新总结 - -## 更新日期 -2025-10-17 - -## 更新内容 - -### 1. 重构内容相似索引 (`i2i_content_similar.py`) - -#### 变化 -- **从**: 基于数据库商品属性计算（TF-IDF + 余弦相似度） -- **到**: 基于Elasticsearch向量计算（KNN查询） - -#### 简化 -- **移除**: 所有命令行参数（`--method`, `--top_n`, `--output`, `--debug`） -- **保留**: 无参数，配置内置在代码中 -- **生成**: 两份索引文件（名称向量 + 图片向量） - -### 2. 简化运行脚本 (`run_all.py`) - -#### 移除的参数 -- `--skip-i2i` - 跳过i2i任务 -- `--skip-interest` - 跳过兴趣聚合 -- `--only-swing` - 只运行Swing -- `--only-w2v` - 只运行W2V -- `--only-deepwalk` - 只运行DeepWalk -- `--only-content` - 只运行内容相似 -- `--only-interest` - 只运行兴趣聚合 -- `--lookback_days` - 回看天数 -- `--top_n` - Top N数量 - -#### 保留的参数 -- `--debug` - 调试模式（唯一参数） - -#### 使用 -```bash -# 之前 -python run_all.py --lookback_days 30 --top_n 50 --skip-interest - -# 现在 -python run_all.py -# 或者 -python run_all.py --debug -``` - -### 3. 更新Redis数据规范 (`REDIS_DATA_SPEC.md`) - -#### 新增索引 -- `i2i_content_name`: 基于名称向量的相似索引 -- `i2i_content_pic`: 基于图片向量的相似索引 - -#### 更新统计 -- Key数量: 245,000 → 270,000 -- 总内存: ~135MB → ~160MB - -### 4. 更新索引加载器 (`load_index_to_redis.py`) - -#### 更新 -- 添加 `content_name` 到i2i索引类型列表 -- 添加 `content_pic` 到i2i索引类型列表 -- 自动加载两个新的内容相似索引 - -### 5. 更新依赖 (`requirements.txt`) - -#### 新增 -``` -elasticsearch>=8.0.0 -``` - -### 6. 新增文档 - -#### ES向量相似度说明 (`ES_VECTOR_SIMILARITY.md`) -- ES配置说明 -- 工作流程详解 -- 性能说明和优化建议 -- 故障排查指南 - -#### 更新说明 (`CONTENT_SIMILARITY_UPDATE.md`) -- 更新概述 -- 主要变化 -- 使用指南 -- 技术细节 -- 性能说明 -- 与其他算法对比 - -#### 本文档 (`CHANGES_SUMMARY.md`) -- 所有变更的简要总结 - -### 7. 新增测试脚本 (`test_es_connection.py`) - -测试ES连接和向量查询功能： -- 测试ES连接 -- 测试索引是否存在 -- 测试向量字段映射 -- 测试查询商品向量 -- 测试KNN向量查询 - -## 文件清单 - -### 修改的文件 -1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写 -2. ✅ `offline_tasks/run_all.py` - 简化参数 -3. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 更新规范 -4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 添加新索引类型 -5. ✅ `requirements.txt` - 添加elasticsearch依赖 - -### 新增的文件 -6. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - ES向量说明 -7. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 更新说明 -8. ✅ `offline_tasks/CHANGES_SUMMARY.md` - 本文档 -9. ✅ `offline_tasks/scripts/test_es_connection.py` - ES测试脚本 - -## 使用指南 - -### 1. 安装依赖 - -```bash -pip install -r requirements.txt -``` - -### 2. 测试ES连接 - -```bash -cd /home/tw/recommendation/offline_tasks -python scripts/test_es_connection.py -``` - -### 3. 运行内容相似索引生成 - -```bash -# 单独运行 -python scripts/i2i_content_similar.py - -# 或通过run_all运行所有任务 -python run_all.py -``` - -### 4. 加载到Redis - -```bash -python scripts/load_index_to_redis.py -``` - -## 输出文件 - -### 新增的输出文件 -- `output/i2i_content_name_YYYYMMDD.txt` - 名称向量相似索引 -- `output/i2i_content_pic_YYYYMMDD.txt` - 图片向量相似索引 - -### 文件格式 -``` -item_id \t item_name \t similar_id1:score1,similar_id2:score2,... -``` - -### 示例 -``` -3302275 香蕉干 3302276:0.9234,3302277:0.8756,3302278:0.8432 -``` - -## Redis Keys - -### 新增的Key格式 -``` -item:similar:content_name:{item_id} -item:similar:content_pic:{item_id} -``` - -### Value格式 -```json -[[similar_id1,score1],[similar_id2,score2],...] -``` - -### 查询示例 -```python -import redis -import json - -r = redis.Redis(host='localhost', port=6379, db=0) - -# 名称向量相似 -similar = json.loads(r.get('item:similar:content_name:3302275')) -# 返回: [[3302276, 0.9234], [3302277, 0.8756], ...] - -# 图片向量相似 -similar = json.loads(r.get('item:similar:content_pic:3302275')) -# 返回: [[4503826, 0.8123], [4503827, 0.7856], ...] -``` - -## 性能指标 - -### 内容相似索引生成 -- 活跃商品: ~50,000 -- 运行时间: 50-60分钟 -- 内存占用: < 2GB - -### Redis存储 -- 新增Keys: ~100,000 (两份索引各50,000) -- 新增内存: ~50MB -- TTL: 30天 - -## 兼容性 - -### 向后兼容 -- ✅ 其他i2i算法（Swing, W2V, DeepWalk）不受影响 -- ✅ 兴趣聚合算法不受影响 -- ✅ Redis加载器向后兼容 -- ✅ 在线查询API不受影响 - -### 不兼容的变化 -- ❌ `i2i_content_similar.py` 命令行参数全部改变 -- ❌ 旧的 `i2i_content_hybrid_*.txt` 文件不再生成 - -## 迁移指南 - -### 如果之前使用了内容相似索引 - -1. **更新脚本调用** - ```bash - # 旧版本 - python i2i_content_similar.py --top_n 50 --method hybrid - - # 新版本 - python i2i_content_similar.py # 无需参数 - ``` - -2. **更新Redis Key** - ```python - # 旧版本 - r.get('item:similar:content:{item_id}') - - # 新版本（两个选择） - r.get('item:similar:content_name:{item_id}') # 名称相似 - r.get('item:similar:content_pic:{item_id}') # 图片相似 - ``` - -3. **更新在线API** - - 如果API使用了 `content` 算法，需要更新为 `content_name` 或 `content_pic` - - 建议支持两种算法，让前端选择或混合使用 - -## 技术栈 - -### 新增技术 -- **Elasticsearch**: 向量存储和KNN查询 -- **KNN算法**: 基于向量的相似度计算 - -### ES配置 -```python -ES_CONFIG = { - 'host': 'http://localhost:9200', - 'index_name': 'spu', - 'username': 'essa', - 'password': '4hOaLaf41y2VuI8y' -} -``` - -### 向量字段 -- `embedding_name_zh`: 名称文本向量 (1024维, dot_product) -- `embedding_pic_h14.vector`: 图片向量 (1024维, dot_product) - -## 优势 - -### 相比旧版本 -1. **更简单**: 无需参数配置 -2. **更快**: ES KNN查询比TF-IDF快 -3. **更准**: 深度学习向量比手工特征准 -4. **更多维度**: 名称 + 图片两个维度 - -### 使用场景 -- **名称向量**: 语义相似推荐（同类但不同品牌） -- **图片向量**: 视觉相似推荐（外观相似商品） - -## 注意事项 - -1. **ES依赖**: 需要Elasticsearch服务可用 -2. **向量数据**: 需要ES中有向量数据 -3. **网络延迟**: ES查询受网络影响 -4. **首次运行**: 可能较慢，建议先测试连接 - -## 故障排查 - -### ES连接失败 -```bash -# 检查ES是否可访问 -curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200 - -# 运行测试脚本 -python scripts/test_es_connection.py -``` - -### 向量字段不存在 -```bash -# 检查ES mapping -curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200/spu/_mapping -``` - -### 查询超时 -- 增加 `request_timeout` 参数 -- 检查网络连接 -- 减少 `KNN_CANDIDATES` 参数 - -## 后续优化 - -1. **批量查询**: 使用 `_mget` 批量获取向量 -2. **并发处理**: 多线程提高查询效率 -3. **增量更新**: 只处理变化的商品 -4. **缓存向量**: 避免重复查询ES -5. **监控告警**: 添加性能监控和异常告警 - -## 相关文档 - -- `ES_VECTOR_SIMILARITY.md` - ES向量详细说明 -- `CONTENT_SIMILARITY_UPDATE.md` - 更新详细说明 -- `REDIS_DATA_SPEC.md` - Redis数据规范 -- `README.md` - 项目概述 - -## 总结 - -本次更新大幅简化了内容相似索引的使用，从基于属性的相似度改为基于深度学习向量的相似度，提供了更准确和多维度的相似商品推荐。同时简化了参数配置，降低了使用和维护成本。 - ---- - -**变更**: 9个文件（5个修改，4个新增） -**影响**: 内容相似索引生成和使用方式 -**破坏性**: 中等（API兼容，但参数和Key格式改变） -**优先级**: 高（建议尽快更新） - diff --git a/offline_tasks/COMPLETE_INDEX_LIST.md b/offline_tasks/COMPLETE_INDEX_LIST.md deleted file mode 100644 index 99e19c7..0000000 --- a/offline_tasks/COMPLETE_INDEX_LIST.md +++ /dev/null @@ -1,350 +0,0 @@ -# 完整索引清单 - -## 📋 所有可用的推荐索引 - -### 1. i2i 相似度索引 - -#### 1.1 行为相似索引（3种） - -**Swing算法**： -``` -i2i:swing:{item_id} -``` -示例：`i2i:swing:12345` - -**Session Word2Vec**： -``` -i2i:session_w2v:{item_id} -``` -示例：`i2i:session_w2v:12345` - -**DeepWalk**： -``` -i2i:deepwalk:{item_id} -``` -示例：`i2i:deepwalk:12345` - -#### 1.2 内容相似索引（3种方法） - -**混合方法（推荐）**： -``` -i2i:content_hybrid:{item_id} -``` -示例：`i2i:content_hybrid:12345` - -**TF-IDF方法**： -``` -i2i:content_tfidf:{item_id} -``` -示例：`i2i:content_tfidf:12345` - -**分类方法**： -``` -i2i:content_category:{item_id} -``` -示例：`i2i:content_category:12345` - ---- - -### 2. 兴趣点聚合索引 - -格式：`interest:{list_type}:{dimension}:{value}` - -#### 2.1 列表类型（list_type） - -- `hot` - 热门商品 -- `cart` - 加购商品 -- `new` - 新品 -- `global` - 全局（所有数据） - -#### 2.2 单维度索引 - -##### 业务平台（platform） -``` -interest:hot:platform:pc -interest:hot:platform:mobile -interest:cart:platform:pc -interest:new:platform:mobile -interest:global:platform:pc -``` - -##### 客户端平台（client_platform） -``` -interest:hot:client_platform:web -interest:hot:client_platform:app -interest:cart:client_platform:web -interest:new:client_platform:app -interest:global:client_platform:web -``` - -##### 供应商（supplier） -``` -interest:hot:supplier:10001 -interest:hot:supplier:10002 -interest:cart:supplier:10001 -interest:new:supplier:10002 -interest:global:supplier:10001 -``` - -##### 一级分类（category_level1） -``` -interest:hot:category_level1:100 -interest:cart:category_level1:100 -interest:new:category_level1:100 -interest:global:category_level1:100 -``` - -##### 二级分类（category_level2） -``` -interest:hot:category_level2:200 -interest:cart:category_level2:200 -interest:new:category_level2:200 -interest:global:category_level2:200 -``` - -##### 三级分类（category_level3） -``` -interest:hot:category_level3:300 -interest:cart:category_level3:300 -interest:new:category_level3:300 -interest:global:category_level3:300 -``` - -##### 四级分类（category_level4） -``` -interest:hot:category_level4:400 -interest:cart:category_level4:400 -interest:new:category_level4:400 -interest:global:category_level4:400 -``` - -#### 2.3 组合维度索引 - -##### 平台 + 客户端 -``` -interest:hot:platform_client:pc_web -interest:hot:platform_client:pc_app -interest:hot:platform_client:mobile_web -interest:hot:platform_client:mobile_app -``` - -##### 平台 + 二级分类 -``` -interest:hot:platform_category2:pc_200 -interest:hot:platform_category2:mobile_200 -interest:cart:platform_category2:pc_200 -interest:new:platform_category2:mobile_200 -``` - -##### 平台 + 三级分类 -``` -interest:hot:platform_category3:pc_300 -interest:hot:platform_category3:mobile_300 -interest:cart:platform_category3:pc_300 -interest:new:platform_category3:mobile_300 -``` - -##### 客户端平台 + 二级分类 -``` -interest:hot:client_category2:web_200 -interest:hot:client_category2:app_200 -interest:cart:client_category2:web_200 -interest:new:client_category2:app_200 -``` - ---- - -## 🎯 按业务场景的索引使用 - -### 场景1: 首页个性化推荐 - -**方案A: 基于平台** -```python -key = f"interest:hot:platform:{user_platform}" -# 示例：interest:hot:platform:pc -``` - -**方案B: 基于分类偏好** -```python -key = f"interest:hot:category_level2:{user_favorite_category}" -# 示例：interest:hot:category_level2:200 -``` - -**方案C: 基于平台+分类** -```python -key = f"interest:hot:platform_category2:{user_platform}_{category_id}" -# 示例：interest:hot:platform_category2:pc_200 -``` - -### 场景2: 详情页相关推荐 - -**方案A: 行为相似** -```python -key = f"i2i:swing:{current_item_id}" -# 示例：i2i:swing:12345 -``` - -**方案B: 内容相似** -```python -key = f"i2i:content_hybrid:{current_item_id}" -# 示例：i2i:content_hybrid:12345 -``` - -**方案C: 融合推荐** -```python -behavior_similar = redis.get(f"i2i:swing:{item_id}") -content_similar = redis.get(f"i2i:content_hybrid:{item_id}") -# 融合两种结果 -``` - -### 场景3: 分类页推荐 - -**方案A: 该分类热门** -```python -key = f"interest:hot:category_level2:{category_id}" -# 示例：interest:hot:category_level2:200 -``` - -**方案B: 该分类新品** -```python -key = f"interest:new:category_level2:{category_id}" -# 示例：interest:new:category_level2:200 -``` - -**方案C: 该分类+平台** -```python -key = f"interest:hot:platform_category2:{platform}_{category_id}" -# 示例：interest:hot:platform_category2:pc_200 -``` - -### 场景4: 供应商店铺页 - -**方案A: 供应商热门商品** -```python -key = f"interest:hot:supplier:{supplier_id}" -# 示例：interest:hot:supplier:10001 -``` - -**方案B: 供应商新品** -```python -key = f"interest:new:supplier:{supplier_id}" -# 示例：interest:new:supplier:10001 -``` - -### 场景5: 搜索结果页推荐 - -**方案A: 全局热门** -```python -key = "interest:global:platform:pc" -``` - -**方案B: 分类相关** -```python -key = f"interest:global:category_level2:{search_category}" -# 示例：interest:global:category_level2:200 -``` - ---- - -## 📊 索引数量统计 - -### i2i索引 -- 行为相似：3种算法 × 商品数量 -- 内容相似：3种方法 × 商品数量 -- **总计**：6 × 商品数量 - -### 兴趣点聚合索引 - -**单维度**： -- platform: 2-10个 -- client_platform: 2-5个 -- supplier: 100-1000个 -- category_level1: 10-50个 -- category_level2: 50-200个 -- category_level3: 200-1000个 -- category_level4: 1000-5000个 - -**组合维度**： -- platform_client: 4-50个 -- platform_category2: 100-2000个 -- platform_category3: 400-10000个 -- client_category2: 100-1000个 - -**列表类型**：每个维度 × 4种类型（hot/cart/new/global） - -**预估总数**：10000-50000条索引 - ---- - -## 🔍 查询示例代码 - -### Python示例 - -```python -import redis - -# 连接Redis -r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) - -# 1. 查询商品的相似商品 -item_id = "12345" -similar_items = r.get(f"i2i:swing:{item_id}") -if similar_items: - items = similar_items.split(',') - for item in items[:5]: # 取前5个 - item_id, score = item.split(':') - print(f"商品ID: {item_id}, 相似度: {score}") - -# 2. 查询分类热门商品 -category_id = "200" -hot_items = r.get(f"interest:hot:category_level2:{category_id}") -if hot_items: - items = hot_items.split(',') - for item in items[:10]: # 取前10个 - item_id, score = item.split(':') - print(f"商品ID: {item_id}, 得分: {score}") - -# 3. 查询平台+分类组合 -platform = "pc" -category_id = "200" -key = f"interest:hot:platform_category2:{platform}_{category_id}" -items = r.get(key) -``` - -### Redis命令行示例 - -```bash -# 查询商品相似度 -redis-cli GET "i2i:swing:12345" - -# 查询分类热门 -redis-cli GET "interest:hot:category_level2:200" - -# 查询供应商商品 -redis-cli GET "interest:hot:supplier:10001" - -# 模糊查询所有热门索引 -redis-cli KEYS "interest:hot:*" - -# 查看某个分类的所有类型 -redis-cli KEYS "interest:*:category_level2:200" -``` - ---- - -## 📝 注意事项 - -1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式 -2. **值的格式**：`item_id1:score1,item_id2:score2,...` -3. **过期时间**：建议设置7天过期 -4. **更新频率**：建议每天更新一次 -5. **查询优先级**： - - 优先使用细粒度索引（如四级分类） - - 粗粒度索引作为后备（如一级分类） - - 融合多个索引结果 - ---- - -**版本**: v1.1 -**生成日期**: 2025-10-16 -**索引总数**: 约10000-50000条 diff --git a/offline_tasks/CONTENT_SIMILARITY_UPDATE.md b/offline_tasks/CONTENT_SIMILARITY_UPDATE.md deleted file mode 100644 index c84838d..0000000 --- a/offline_tasks/CONTENT_SIMILARITY_UPDATE.md +++ /dev/null @@ -1,243 +0,0 @@ -# 内容相似索引更新说明 - -## 📋 更新概述 - -重构了 `i2i_content_similar.py`，从基于数据库属性计算改为基于Elasticsearch向量计算，生成两份内容相似索引。 - -## 🔄 主要变化 - -### 1. 算法改变 - -**之前 (旧版本):** -- 基于商品属性（分类、供应商、包装等） -- 使用TF-IDF + 余弦相似度 -- 提供 `--method` 参数选择: tfidf / category / hybrid -- 复杂的参数配置 - -**现在 (新版本):** -- 基于Elasticsearch的向量相似度 -- 使用KNN向量查询 -- **无需任何参数，开箱即用** -- 自动生成两份索引 - -### 2. 生成的索引 - -| 索引名称 | 向量来源 | 文件名 | Redis Key | TTL | -|---------|---------|--------|-----------|-----| -| **名称向量相似** | `embedding_name_zh` | `i2i_content_name_YYYYMMDD.txt` | `item:similar:content_name:{item_id}` | 30天 | -| **图片向量相似** | `embedding_pic_h14` | `i2i_content_pic_YYYYMMDD.txt` | `item:similar:content_pic:{item_id}` | 30天 | - -### 3. 参数简化 - -**之前:** -```bash -python i2i_content_similar.py --top_n 50 --method hybrid --debug -``` - -**现在:** -```bash -python i2i_content_similar.py -# 就这么简单！无需任何参数 -``` - -所有配置都在代码中预设好： -- `TOP_N = 50`: 返回前50个相似商品 -- `KNN_K = 100`: KNN查询返回100个候选 -- `KNN_CANDIDATES = 200`: 候选池大小200 - -## 📝 更新的文件 - -### 核心代码 -1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写 - - 连接Elasticsearch - - 查询最近1年活跃商品 - - 获取向量并计算相似度 - - 生成两份索引 - -### 配置文档 -2. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 更新Redis数据规范 - - 添加 `i2i_content_name` 规范 - - 添加 `i2i_content_pic` 规范 - - 更新内存占用估算（270,000 keys, ~160MB） - -### 调度脚本 -3. ✅ `offline_tasks/run_all.py` - 简化参数 - - 移除 `--only-*` 参数 - - 移除 `--skip-*` 参数 - - 移除 `--lookback_days` 和 `--top_n` 参数 - - 只保留 `--debug` 参数 - - 添加内容相似任务 - -4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 更新加载逻辑 - - 添加 `content_name` 和 `content_pic` 到索引类型列表 - -### 新增文档 -5. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - ES向量相似度说明 - - ES配置说明 - - 工作流程详解 - - 性能说明和优化建议 - - 故障排查指南 - -6. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 本文档 - -## 🚀 使用指南 - -### 安装依赖 - -需要安装Elasticsearch客户端： -```bash -pip install elasticsearch -``` - -### 配置ES连接 - -在 `i2i_content_similar.py` 中修改ES配置（如需要）： -```python -ES_CONFIG = { - 'host': 'http://localhost:9200', - 'index_name': 'spu', - 'username': 'essa', - 'password': '4hOaLaf41y2VuI8y' -} -``` - -### 运行脚本 - -#### 单独运行 -```bash -cd /home/tw/recommendation/offline_tasks -python scripts/i2i_content_similar.py -``` - -#### 通过run_all运行 -```bash -python run_all.py -``` - -### 加载到Redis -```bash -python scripts/load_index_to_redis.py --date 20251017 -``` - -## 📊 输出示例 - -### 文件格式 -``` -3302275 香蕉干 3302276:0.9234,3302277:0.8756,3302278:0.8432 -``` - -### Redis存储 -```python -# 名称向量相似 -GET item:similar:content_name:3302275 -# 返回: [[3302276,0.9234],[3302277,0.8756],[3302278,0.8432]] - -# 图片向量相似 -GET item:similar:content_pic:3302275 -# 返回: [[4503826,0.8123],[4503827,0.7856],[4503828,0.7645]] -``` - -## 🔍 技术细节 - -### 数据源 - -1. **活跃商品列表** - - 来源: 数据库 `sensors_events` 表 - - 条件: 最近1年内有行为记录 - - 行为类型: click, contactFactory, addToPool, addToCart, purchase - -2. **向量数据** - - 来源: Elasticsearch `spu` 索引 - - 字段: - - `embedding_name_zh`: 名称文本向量 (1024维) - - `embedding_pic_h14.vector`: 图片向量 (1024维) - - `name_zh`: 商品中文名称 - -### ES查询 - -#### 1. 获取商品向量 -```json -{ - "query": { - "term": {"_id": "商品ID"} - }, - "_source": { - "includes": ["_id", "name_zh", "embedding_name_zh", "embedding_pic_h14"] - } -} -``` - -#### 2. KNN相似度查询 -```json -{ - "knn": { - "field": "embedding_name_zh", - "query_vector": [向量], - "k": 100, - "num_candidates": 200 - }, - "_source": ["_id", "name_zh"], - "size": 100 -} -``` - -## ⚡ 性能说明 - -### 运行时间 -- 活跃商品数: ~50,000 -- 向量查询: ~50,000次 × 10ms = 8-10分钟 -- KNN查询: ~50,000次 × 50ms = 40-50分钟 -- **总计: 约50-60分钟** - -### 优化建议 -1. 批量查询: 使用 `_mget` 批量获取向量 -2. 并发处理: 多线程/异步IO -3. 增量更新: 只处理变化的商品 -4. 缓存向量: 避免重复查询 - -## 🆚 与其他算法对比 - -| 算法 | 数据源 | 计算方式 | 特点 | 更新频率 | -|-----|-------|---------|------|---------| -| **Swing** | 用户行为 | 共现关系 | 捕获真实交互 | 每天 | -| **W2V** | 用户会话 | 序列学习 | 捕获序列关系 | 每天 | -| **DeepWalk** | 行为图 | 图游走 | 发现深层关联 | 每天 | -| **名称向量** | ES向量 | KNN查询 | 语义相似 | 每周 | -| **图片向量** | ES向量 | KNN查询 | 视觉相似 | 每周 | - -## 📋 待办事项 - -- [x] 重写 `i2i_content_similar.py` -- [x] 更新 `REDIS_DATA_SPEC.md` -- [x] 简化 `run_all.py` 参数 -- [x] 更新 `load_index_to_redis.py` -- [x] 编写技术文档 -- [ ] 添加单元测试 -- [ ] 性能优化（批量查询） -- [ ] 添加监控和告警 - -## ⚠️ 注意事项 - -1. **ES连接**: 确保能访问ES服务器 -2. **向量缺失**: 部分商品可能没有向量，会被跳过 -3. **网络延迟**: ES查询受网络影响，建议内网部署 -4. **内存占用**: 处理大量商品时注意内存使用 -5. **依赖安装**: 需要安装 `elasticsearch` Python包 - -## 🔗 相关文档 - -- `ES_VECTOR_SIMILARITY.md` - ES向量相似度详细说明 -- `REDIS_DATA_SPEC.md` - Redis数据规范 -- `OFFLINE_INDEX_SPEC.md` - 离线索引规范 -- `QUICKSTART.md` - 快速开始指南 - -## 📞 联系方式 - -如有问题或建议，请联系开发团队。 - ---- - -**更新日期**: 2025-10-17 -**版本**: v2.0 -**作者**: AI Assistant - diff --git a/offline_tasks/CURRENT_STATUS.md b/offline_tasks/CURRENT_STATUS.md deleted file mode 100644 index 5711a9e..0000000 --- a/offline_tasks/CURRENT_STATUS.md +++ /dev/null @@ -1,229 +0,0 @@ -# 当前状态说明 - -## ✅ 已完成并可用的功能 - -### 1. i2i 行为相似算法（100%可用） -- ✅ **Swing算法** - 已适配实际数据库字段 -- ✅ **Session W2V** - 已适配实际数据库字段 -- ✅ **DeepWalk** - 已适配实际数据库字段 - -**使用的字段**（已验证存在）： -- `sensors_events.anonymous_id` -- `sensors_events.item_id` -- `sensors_events.event` -- `sensors_events.create_time` -- `prd_goods_sku.id` -- `prd_goods_sku.name` - -**输出格式**： -``` -item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,... -``` - -**运行命令**： -```bash -# 单独运行 -python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50 -python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 -python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 -``` - ---- - -### 2. 兴趣点聚合（部分可用） - -#### 已适配的维度： -✅ **business_platform** - 业务平台维度 -``` -platform:pc → item_id1:score1,item_id2:score2,... -platform:mobile → ... -``` - -✅ **client_platform** - 客户端平台维度 -``` -client_platform:web → item_id1:score1,item_id2:score2,... -client_platform:app → ... -``` - -✅ **platform_client** - 组合维度 -``` -platform_client:pc_web → item_id1:score1,item_id2:score2,... -``` - -#### 已适配的列表类型： -✅ **hot** - 热门商品（基于最近180天） -✅ **cart** - 加购商品 -✅ **new** - 新品（基于create_time） - -**运行命令**： -```bash -python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 -``` - ---- - -## ⚠️ 原计划但未实现的功能（因字段不存在） - -### sensors_events 表缺失字段： -- ❌ `country` - 国家/销售区域 -- ❌ `customer_type` - 客户类型 - -### prd_goods_sku 表缺失字段： -- ❌ `category_level2_id` - 二级分类 -- ❌ `category_level3_id` - 三级分类 - -### 影响的索引： -- ❌ country:{country} -- ❌ customer_type:{type} -- ❌ category_level2:{cat_id} -- ❌ category_level3:{cat_id} -- ❌ 相关的组合维度索引 - ---- - -## 📊 业务场景映射（更新后） - -### 场景1: 首页猜你喜欢 -**可用索引**： -```python -# 按平台推荐 -interest:hot:platform:pc -interest:hot:platform:mobile - -# 按客户端平台推荐 -interest:hot:client_platform:web -interest:hot:client_platform:app - -# 组合维度 -interest:hot:platform_client:pc_web -``` - -### 场景2: 详情页大家都在看 -**可用索引**： -```python -# i2i相似度（完全可用） -i2i:swing:{item_id} -i2i:session_w2v:{item_id} -i2i:deepwalk:{item_id} -``` - -### 场景3: 搜索结果页推荐 -**可用索引**： -```python -# 按平台的全局推荐 -interest:global:platform:pc -interest:global:client_platform:web - -# 或使用 page_type（需要扩展） -interest:global:page_type:search -``` - ---- - -## 🎯 当前可用的完整索引列表 - -### i2i索引（完全可用） -``` -i2i:swing:{item_id} -i2i:session_w2v:{item_id} -i2i:deepwalk:{item_id} -``` - -### 兴趣点聚合索引（部分可用） - -**单维度**： -``` -platform:{business_platform} # 如：platform:pc -client_platform:{client_platform} # 如：client_platform:web -``` - -**组合维度**： -``` -platform_client:{platform}_{client} # 如：platform_client:pc_web -``` - -**列表类型前缀**： -``` -interest:hot:... -interest:cart:... -interest:new:... -interest:global:... -``` - -**完整示例**： -``` -interest:hot:platform:pc -interest:hot:client_platform:web -interest:hot:platform_client:pc_web -interest:cart:platform:mobile -interest:new:client_platform:app -interest:global:platform:pc -``` - ---- - -## 🚀 快速运行 - -### 测试i2i功能（完全可用） -```bash -cd /home/tw/recommendation/offline_tasks - -# 运行Swing算法（小数据量测试） -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 - -# 查看输出 -head -n 5 output/i2i_swing_*.txt -``` - -### 测试兴趣点聚合（部分可用） -```bash -# 运行兴趣点聚合（小数据量测试） -python3 scripts/interest_aggregation.py --lookback_days 30 --top_n 100 - -# 查看输出 -head -n 10 output/interest_aggregation_hot_*.txt -grep "^platform:" output/interest_aggregation_hot_*.txt | head -5 -``` - -### 运行所有可用任务 -```bash -# 运行全部 -python3 run_all.py --lookback_days 730 --top_n 50 - -# 查看日志 -tail -f logs/run_all_*.log -``` - ---- - -## 💡 建议 - -### 短期建议（立即可用） -1. **优先使用 i2i 功能** - 这部分功能完整且经过验证 -2. **使用现有平台维度** - platform 和 client_platform 可以满足基本需求 -3. **测试小数据量** - 先用30天数据测试，确认无误后再用完整数据 - -### 中期建议（需要扩展） -1. **添加更多维度** - 可以考虑使用 `page_type`、`item_type` 等现有字段 -2. **关联其他表** - 如果其他表有分类信息，可以通过 JOIN 获取 -3. **解析JSON字段** - `__properties` 可能包含额外信息 - -### 长期建议（需要数据支持） -1. **补充用户特征字段** - 在 sensors_events 表中添加 country、customer_type 字段 -2. **补充商品分类字段** - 在 prd_goods_sku 表或关联表中添加分类信息 -3. **建立用户画像表** - 单独维护用户属性信息 - ---- - -## 📞 文档索引 - -- **FIELD_MAPPING.md** - 字段映射详细说明 -- **DATABASE_SETUP.md** - 数据库配置指南 -- **TROUBLESHOOTING.md** - 故障排除 -- **CHANGELOG.md** - 更新日志 -- **README.md** - 完整文档 - ---- - -**更新时间**: 2025-10-16 -**状态**: i2i功能完全可用，兴趣点聚合部分可用 diff --git a/offline_tasks/DATABASE_SETUP.md b/offline_tasks/DATABASE_SETUP.md deleted file mode 100644 index 352aacc..0000000 --- a/offline_tasks/DATABASE_SETUP.md +++ /dev/null @@ -1,179 +0,0 @@ -# 数据库字段配置说明 - -## 问题说明 - -如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。 - -## 已适配的基础字段 - -当前代码已经适配了以下基础字段（参考 `item_sim.py`）： - -### sensors_events 表 -- `anonymous_id` - 用户ID -- `item_id` - 商品ID -- `event` - 事件类型 -- `create_time` - 创建时间 -- `platform` - 平台（可选） -- `country` - 国家（可选） -- `customer_type` - 客户类型（可选） - -### prd_goods_sku 表 -- `id` - 商品ID -- `name` - 商品名称 -- `create_time` - 创建时间（用于判断新品） - -## 可选字段配置 - -如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度： - -### 分类字段（可选） -- `category_level1_id` - 一级分类ID -- `category_level2_id` - 二级分类ID -- `category_level3_id` - 三级分类ID - -## 如何添加分类字段支持 - -如果您的数据库有分类字段，可以按以下步骤启用： - -### 步骤1: 修改 SQL 查询 - -编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段： - -```python -sql_query = f""" -SELECT - se.anonymous_id AS user_id, - se.item_id, - se.event AS event_type, - se.create_time, - pgs.name AS item_name, - pgs.create_time AS item_create_time, - pgs.category_level2_id, # 添加这一行 - pgs.category_level3_id, # 添加这一行 - se.platform, - se.country, - se.customer_type -FROM - sensors_events se -LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id -... -""" -``` - -### 步骤2: 修改聚合逻辑 - -在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用： - -```python -# 维度4: 二级分类 (category_level2) - 如果字段存在 -if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')): - key = f"category_level2:{row['category_level2_id']}" - aggregations[key][item_id] += weight -``` - -这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。 - -## 查看实际表结构 - -运行以下命令查看您的数据库表结构： - -```python -# 创建一个简单的脚本查看表结构 -import pandas as pd -from db_service import create_db_connection -from offline_tasks.config.offline_config import DB_CONFIG - -engine = create_db_connection( - DB_CONFIG['host'], - DB_CONFIG['port'], - DB_CONFIG['database'], - DB_CONFIG['username'], - DB_CONFIG['password'] -) - -# 查看 prd_goods_sku 表结构 -df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine) -print("prd_goods_sku 字段列表:") -for col in df.columns: - print(f" - {col}") - -# 查看 sensors_events 表结构 -df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine) -print("\nsensors_events 字段列表:") -for col in df.columns: - print(f" - {col}") -``` - -## 常见字段名映射 - -如果您的数据库使用不同的字段名，需要在SQL查询中做映射： - -| 代码中的字段 | 可能的实际字段名 | 修改方式 | -|-------------|----------------|---------| -| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` | -| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` | -| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` | -| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` | - -## 完整示例 - -假设您的表结构是： -- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time` -- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time` - -则需要修改SQL为： - -```python -sql_query = f""" -SELECT - se.uid AS user_id, - se.goods_id AS item_id, - se.action AS event_type, - se.time AS create_time, - pgs.title AS item_name, - pgs.add_time AS item_create_time, - pgs.cat2 AS category_level2_id, - pgs.cat3 AS category_level3_id -FROM - sensors_events se -LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id -... -""" -``` - -## 最小化配置 - -如果只想先测试基本功能，可以只使用最基础的字段： - -### i2i 算法只需要： -- `anonymous_id` / `user_id` -- `item_id` -- `event` / `event_type` -- `create_time` -- `name` (商品名称) - -### 兴趣点聚合至少需要： -- 以上i2i的字段 -- 至少一个维度字段（如 `platform` 或 `country`） - -## 测试连接 - -修改后，运行测试脚本验证： - -```bash -cd /home/tw/recommendation/offline_tasks -python3 test_connection.py -``` - -## 获取帮助 - -如果仍有问题，请： -1. 查看日志文件：`logs/run_all_*.log` -2. 运行单个脚本测试，便于调试 -3. 使用 `--help` 参数查看命令行选项 - -```bash -python3 scripts/i2i_swing.py --help -python3 scripts/interest_aggregation.py --help -``` - diff --git a/offline_tasks/DEBUG_GUIDE.md b/offline_tasks/DEBUG_GUIDE.md deleted file mode 100644 index 85f78b8..0000000 --- a/offline_tasks/DEBUG_GUIDE.md +++ /dev/null @@ -1,332 +0,0 @@ -# Debug模式使用指南 - -## 🐛 Debug功能概述 - -Debug模式为所有离线任务提供： -1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 -2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 -3. **数据采样展示** - 关键步骤的示例数据 -4. **性能统计** - 每个步骤的耗时和资源使用 - -## 🚀 快速开始 - -### 1. 运行单个脚本（Debug模式） - -```bash -cd /home/tw/recommendation/offline_tasks - -# Swing算法 - Debug模式 -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug - -# 兴趣聚合 - Debug模式 -python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug - -# 内容相似 - Debug模式 -python3 scripts/i2i_content_similar.py --top_n 10 --debug -``` - -### 2. 运行所有任务（Debug模式） - -```bash -# 使用debug参数运行所有任务 -python3 run_all.py --lookback_days 7 --top_n 10 --debug -``` - -## 📊 Debug输出说明 - -### A. 日志输出 - -Debug模式下，日志会输出到两个地方： -1. **控制台** - 实时查看进度 -2. **Debug日志文件** - 完整保存 - -日志文件位置： -``` -offline_tasks/logs/debug/i2i_swing_20251016_193000.log -offline_tasks/logs/debug/interest_aggregation_20251016_193500.log -... -``` - -### B. 日志内容示例 - -``` -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ -2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ -2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 -2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 -2025-10-16 19:30:00 - i2i_swing - DEBUG - lookback_days: 7 -2025-10-16 19:30:00 - i2i_swing - DEBUG - debug: True -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ - -2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 - -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ -2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息: -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5 -2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name'] -2025-10-16 19:30:05 - i2i_swing - DEBUG - -2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型: -2025-10-16 19:30:05 - i2i_swing - DEBUG - user_id: object -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_id: int64 -2025-10-16 19:30:05 - i2i_swing - DEBUG - event_type: object -2025-10-16 19:30:05 - i2i_swing - DEBUG - create_time: datetime64[ns] -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_name: object - -2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) -2025-10-16 19:30:05 - i2i_swing - DEBUG - contactFactory: 3456 (22.68%) -2025-10-16 19:30:05 - i2i_swing - DEBUG - purchase: 2134 (14.01%) -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToPool: 1124 (7.38%) - -2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 -2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%) -2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%) -... -``` - -### C. 明文索引文件 - -Debug模式下，每个索引文件都会生成对应的明文文件： - -**原始索引文件** (`output/i2i_swing_20251016.txt`): -``` -12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 -67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 -``` - -**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`): -``` -================================================================================ -明文索引文件 -生成时间: 2025-10-16 19:35:00 -描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) -总索引数: 2345 -================================================================================ - -[1] i2i:swing:12345(香蕉干) --------------------------------------------------------------------------------- - 1. ID:67890(芒果干) - Score:0.8567 - 2. ID:11223(菠萝干) - Score:0.7234 - 3. ID:44556(苹果干) - Score:0.6891 - 4. ID:22334(木瓜干) - Score:0.6234 - 5. ID:55667(草莓干) - Score:0.5891 - -[2] i2i:swing:67890(芒果干) --------------------------------------------------------------------------------- - 1. ID:12345(香蕉干) - Score:0.8567 - 2. ID:22334(木瓜干) - Score:0.7123 - 3. ID:55667(草莓干) - Score:0.6543 - 4. ID:11223(菠萝干) - Score:0.6234 - 5. ID:44556(苹果干) - Score:0.5891 - -... - -================================================================================ -已输出 50/2345 个索引 -================================================================================ -``` - -## 📁 文件结构 - -Debug模式下的文件组织： - -``` -offline_tasks/ -├── output/ -│ ├── i2i_swing_20251016.txt # 原始索引文件 -│ ├── interest_aggregation_hot_20251016.txt -│ └── debug/ # Debug明文文件目录 -│ ├── i2i_swing_20251016_readable.txt # 明文索引 -│ ├── interest_aggregation_hot_20251016_readable.txt -│ └── ... -└── logs/ - ├── run_all_20251016.log # 主日志 - └── debug/ # Debug详细日志目录 - ├── i2i_swing_20251016_193000.log - ├── interest_aggregation_20251016_193500.log - └── ... -``` - -## 🔍 使用场景 - -### 场景1：调试数据流程 - -```bash -# 使用小数据量+debug模式快速验证 -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug - -# 查看日志，检查： -# - 数据加载是否正确 -# - 行为类型分布是否合理 -# - 用户/商品数量是否符合预期 -``` - -### 场景2：检查推荐效果 - -```bash -# 生成明文索引文件 -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug - -# 打开明文文件查看： -cat output/debug/i2i_swing_20251016_readable.txt | less - -# 检查推荐是否合理，例如： -# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 -# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 -``` - -### 场景3：性能调优 - -```bash -# Debug模式查看各步骤耗时 -python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" - -# 输出示例： -# 步骤1耗时: 2.34秒 -# 步骤2耗时: 15.67秒 <- 瓶颈在这里 -# 步骤3耗时: 1.23秒 -# 总耗时: 19.24秒 -``` - -### 场景4：参数调整 - -```bash -# 测试不同alpha值的效果 -python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1 -python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1 -python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1 - -# 对比明文文件，选择最佳参数 -diff output/debug/i2i_swing_*_readable.txt -``` - -## 💡 最佳实践 - -### 1. 开发调试阶段 - -```bash -# 使用小数据量 + Debug模式 -python3 run_all.py --lookback_days 3 --top_n 10 --debug -``` - -- ✅ 快速验证流程 -- ✅ 详细日志便于排错 -- ✅ 明文文件检查效果 - -### 2. 参数调优阶段 - -```bash -# 中等数据量 + Debug模式 -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug -``` - -- ✅ 查看数据分布 -- ✅ 评估推荐质量 -- ✅ 调整算法参数 - -### 3. 生产运行阶段 - -```bash -# 大数据量 + 正常模式（不加--debug） -python3 run_all.py --lookback_days 730 --top_n 50 -``` - -- ✅ 高效运行 -- ✅ 只输出必要日志 -- ✅ 节省磁盘空间 - -## 🛠️ Debug工具 - -### 查看实时日志 - -```bash -# 实时查看debug日志 -tail -f logs/debug/i2i_swing_*.log - -# 只看DEBUG级别 -tail -f logs/debug/i2i_swing_*.log | grep "DEBUG" - -# 只看错误 -tail -f logs/debug/i2i_swing_*.log | grep "ERROR" -``` - -### 统计分析 - -```bash -# 统计处理的数据量 -grep "总行数" logs/debug/*.log - -# 统计生成的索引数 -grep "总索引数" output/debug/*_readable.txt - -# 查看性能统计 -grep "耗时" logs/debug/*.log -``` - -### 快速检查 - -```bash -# 检查前10个推荐 -head -50 output/debug/i2i_swing_*_readable.txt - -# 搜索特定商品的推荐 -grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10 - -# 统计推荐数量分布 -grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l -``` - -## ⚠️ 注意事项 - -1. **磁盘空间** - - Debug日志和明文文件会占用较多空间 - - 建议定期清理：`rm -rf logs/debug/* output/debug/*` - -2. **运行时间** - - Debug模式会增加10-20%的运行时间 - - 生产环境建议关闭debug - -3. **敏感信息** - - 明文文件包含商品名称等信息 - - 注意数据安全和隐私保护 - -4. **文件编码** - - 明文文件使用UTF-8编码 - - 确保查看工具支持中文显示 - -## 📖 相关命令 - -```bash -# 查看帮助 -python3 scripts/i2i_swing.py --help -python3 run_all.py --help - -# 验证配置 -python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)" - -# 测试debug工具 -python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')" -``` - -## ✅ 验证Debug功能 - -```bash -# 快速测试 -cd /home/tw/recommendation/offline_tasks -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug - -# 应该看到： -# ✓ DEBUG级别日志输出 -# ✓ 创建debug日志文件 -# ✓ 生成明文索引文件 -# ✓ 显示数据统计信息 -``` - ---- - -**Debug模式**: 开发和调试的利器 -**正常模式**: 生产环境的选择 -**灵活切换**: 一个参数的事情 diff --git a/offline_tasks/DELIVERY.md b/offline_tasks/DELIVERY.md deleted file mode 100644 index 47fd61c..0000000 --- a/offline_tasks/DELIVERY.md +++ /dev/null @@ -1,335 +0,0 @@ -# 推荐系统离线任务 - 交付文档 - -## 📋 项目概述 - -根据您的需求，已完成推荐系统的离线任务部分构建，包括： - -1. **i2i 行为相似索引**：实现了3种算法（Swing、Session W2V、DeepWalk） -2. **兴趣点聚合索引**：支持多维度（平台、国家、客户类型、分类）和多列表类型（热门、加购、新品） - -## ✅ 已完成的工作 - -### 1. 核心功能实现 - -#### 1.1 i2i 行为相似算法（参考 item_sim.py 改写） - -| 算法 | 文件 | 状态 | 说明 | -|------|------|------|------| -| **Swing** | `scripts/i2i_swing.py` | ✅ 完成 | 改写自collaboration/swing.cc，适配现有数据格式 | -| **Session W2V** | `scripts/i2i_session_w2v.py` | ✅ 完成 | 改写自graphembedding/session_w2v，支持用户会话序列 | -| **DeepWalk** | `scripts/i2i_deepwalk.py` | ✅ 完成 | 改写自graphembedding/deepwalk，支持图随机游走 | - -**特性**： -- ✅ 适配真实数据库（SelectDB） -- ✅ 支持时间衰减（2年数据，权重衰减） -- ✅ 支持行为权重（click/addToCart/contactFactory/purchase等） -- ✅ 输出格式与 item_sim.py 一致 - -#### 1.2 兴趣点聚合索引 - -| 维度类型 | 示例 | 状态 | -|---------|------|------| -| 平台 | platform:PC | ✅ 完成 | -| 国家/销售区域 | country:US | ✅ 完成 | -| 客户类型 | customer_type:retailer | ✅ 完成 | -| 二级分类 | category_level2:100 | ✅ 完成 | -| 三级分类 | category_level3:200 | ✅ 完成 | -| 组合维度 | platform_country:PC_US | ✅ 完成 | - -| 列表类型 | 说明 | 状态 | -|---------|------|------| -| **热门** (hot) | 最近180天高交互商品 | ✅ 完成 | -| **加购** (cart) | 基于加购行为 | ✅ 完成 | -| **新品** (new) | 最近90天上架商品 | ✅ 完成 | -| **全局** (global) | 所有数据综合 | ✅ 完成 | - -**特性**： -- ✅ 时间衰减（最近2年，权重随时间衰减） -- ✅ 多维度组合支持 -- ✅ 可配置的top N输出 - -### 2. 基础设施 - -| 组件 | 文件 | 状态 | 说明 | -|------|------|------|------| -| 数据库连接 | `db_service.py` | ✅ 完成 | 统一的数据库连接服务 | -| 配置管理 | `config/offline_config.py` | ✅ 完成 | 集中的配置管理 | -| 统一调度 | `run_all.py` | ✅ 完成 | 一键运行所有任务 | -| Redis加载 | `scripts/load_index_to_redis.py` | ✅ 完成 | 索引加载到Redis | -| 连接测试 | `test_connection.py` | ✅ 完成 | 验证环境配置 | -| 查询示例 | `example_query_redis.py` | ✅ 完成 | 演示如何使用索引 | - -### 3. 文档 - -| 文档 | 文件 | 状态 | 说明 | -|------|------|------|------| -| 详细文档 | `README.md` | ✅ 完成 | 完整的使用说明 | -| 快速开始 | `QUICKSTART.md` | ✅ 完成 | 快速上手指南 | -| 项目总结 | `PROJECT_SUMMARY.md` | ✅ 完成 | 技术架构和原理 | -| 目录结构 | `STRUCTURE.md` | ✅ 完成 | 目录和数据流说明 | -| 安装脚本 | `install.sh` | ✅ 完成 | 自动化安装 | -| 依赖清单 | `requirements.txt` | ✅ 完成 | Python依赖包 | - -## 📁 交付文件清单 - -``` -/home/tw/recommendation/ -├── db_service.py # 数据库连接服务 -├── requirements.txt # 依赖包清单 -│ -└── offline_tasks/ # 离线任务主目录 - ├── config/ - │ └── offline_config.py # 配置文件 - │ - ├── scripts/ # 核心算法脚本 - │ ├── i2i_swing.py # ✅ Swing算法 - │ ├── i2i_session_w2v.py # ✅ Session W2V - │ ├── i2i_deepwalk.py # ✅ DeepWalk - │ ├── interest_aggregation.py # ✅ 兴趣点聚合 - │ └── load_index_to_redis.py # ✅ Redis加载 - │ - ├── output/ # 输出目录（运行后生成） - ├── logs/ # 日志目录（运行后生成） - │ - ├── run_all.py # ✅ 统一调度脚本 - ├── install.sh # ✅ 安装脚本 - ├── test_connection.py # ✅ 连接测试 - ├── example_query_redis.py # ✅ 查询示例 - │ - └── 文档/ - ├── README.md # ✅ 详细文档 - ├── QUICKSTART.md # ✅ 快速开始 - ├── PROJECT_SUMMARY.md # ✅ 项目总结 - ├── STRUCTURE.md # ✅ 目录结构 - └── DELIVERY.md # ✅ 本文档 -``` - -## 🚀 快速开始 - -### 步骤1: 安装依赖 - -```bash -cd /home/tw/recommendation/offline_tasks -bash install.sh -``` - -### 步骤2: 配置数据库 - -编辑 `config/offline_config.py`，确保数据库连接信息正确。 - -### 步骤3: 测试连接 - -```bash -python3 test_connection.py -``` - -### 步骤4: 运行离线任务 - -```bash -# 运行所有任务 -python3 run_all.py --lookback_days 730 --top_n 50 - -# 或者运行单个任务 -python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50 -python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 -``` - -### 步骤5: 加载索引到Redis - -```bash -python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 -``` - -### 步骤6: 查询验证 - -```bash -python3 example_query_redis.py -``` - -## 📊 数据格式说明 - -### i2i索引格式 -``` -item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,... -``` - -**示例**： -``` -123456 商品A 234567:0.8523,345678:0.7842,456789:0.7234 -``` - -### 兴趣点聚合索引格式 -``` -dimension_key \t item_id1:score1,item_id2:score2,... -``` - -**示例**： -``` -platform:PC 12345:98.52,23456:87.34,34567:76.89 -country:US 45678:156.23,56789:142.87,67890:128.45 -platform_country:PC_US 78901:234.56,89012:198.76,90123:187.23 -``` - -## 🎯 业务场景对应 - -根据您提供的业务场景，索引使用方式如下： - -### 1. 首页猜你喜欢 -**使用索引**：兴趣点聚合 (hot + global) - -```python -# 获取用户特征 -platform = user.platform # PC/Mobile -country = user.country # US/UK/CN... -customer_type = user.customer_type # retailer/wholesaler... - -# 查询多个维度的热门商品 -hot_items_1 = redis.get(f"interest:hot:platform_country:{platform}_{country}") -hot_items_2 = redis.get(f"interest:hot:customer_type:{customer_type}") -hot_items_3 = redis.get(f"interest:global:country:{country}") - -# 融合多个结果 -recommended_items = merge_and_rerank(hot_items_1, hot_items_2, hot_items_3) -``` - -### 2. 详情页的大家都在看 -**使用索引**：i2i 行为相似 - -```python -# 当前浏览的商品ID -current_item_id = "123456" - -# 查询相似商品（可以组合多个算法） -similar_swing = redis.get(f"i2i:swing:{current_item_id}") -similar_w2v = redis.get(f"i2i:session_w2v:{current_item_id}") -similar_deepwalk = redis.get(f"i2i:deepwalk:{current_item_id}") - -# 融合结果 -recommended_items = merge_i2i_results(similar_swing, similar_w2v, similar_deepwalk) -``` - -### 3. 搜索结果页底部的供应商推荐 -**使用索引**：兴趣点聚合 (按分类) - -```python -# 用户搜索的分类 -category_level2 = search_query.category_level2 - -# 查询该分类下的推荐商品 -items = redis.get(f"interest:global:category_level2:{category_level2}") - -# 结合用户特征进行个性化排序 -personalized_items = personalize_ranking(items, user_profile) -``` - -## ⚙️ 配置参数说明 - -### 关键配置（config/offline_config.py） - -```python -# 时间范围 -LOOKBACK_DAYS = 730 # 回溯天数（2年） -RECENT_DAYS = 180 # 热门商品统计天数 -NEW_DAYS = 90 # 新品定义天数 - -# 时间衰减 -time_decay_factor = 0.95 # 每30天衰减5% - -# 行为权重 -behavior_weights = { - 'click': 1.0, # 点击 - 'addToPool': 2.0, # 加入询盘池 - 'addToCart': 3.0, # 加入购物车 - 'contactFactory': 5.0, # 联系工厂 - 'purchase': 10.0 # 购买 -} - -# 输出数量 -i2i_top_n = 50 # 每个商品的相似商品数 -interest_top_n = 1000 # 每个维度的推荐商品数 -``` - -## 📈 性能参考 - -基于100万条用户行为数据的预估： - -| 任务 | 预估时间 | 内存占用 | 输出大小 | -|------|---------|---------|---------| -| Swing算法 | 2-4小时 | 4-8GB | ~50MB | -| Session W2V | 30-60分钟 | 2-4GB | ~30MB | -| DeepWalk | 1-2小时 | 2-4GB | ~40MB | -| 兴趣点聚合 | 30-60分钟 | 2-4GB | ~100MB | -| **总计** | **5-8小时** | **8-16GB** | **~220MB** | - -## 🔧 定时任务设置 - -建议使用crontab设置每天运行： - -```bash -# 编辑crontab -crontab -e - -# 添加以下行（每天凌晨2点运行） -0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py >> logs/cron.log 2>&1 - -# 凌晨6点加载到Redis -0 6 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 scripts/load_index_to_redis.py >> logs/load_redis.log 2>&1 -``` - -## 🐛 常见问题 - -### Q1: 数据库连接失败 -**解决方案**： -1. 检查 `config/offline_config.py` 中的数据库配置 -2. 运行 `python3 test_connection.py` 测试连接 -3. 确认网络连接和防火墙设置 - -### Q2: 任务运行时间过长 -**解决方案**： -1. 减少 `--lookback_days` 参数（如改为365天） -2. 使用 `--only-xxx` 参数只运行特定任务 -3. 考虑使用C++版本的Swing算法（性能提升10倍） - -### Q3: 内存不足 -**解决方案**： -1. 先运行DeepWalk或Session W2V（内存占用较小） -2. 使用 `--skip-i2i` 跳过Swing算法 -3. 分批处理数据 - -## 📚 参考文档 - -- **README.md**: 完整的功能说明和使用指南 -- **QUICKSTART.md**: 快速上手步骤 -- **PROJECT_SUMMARY.md**: 技术架构和算法原理 -- **STRUCTURE.md**: 项目结构和数据流向 - -## ✨ 技术亮点 - -1. **适配真实数据**：参考 item_sim.py，完全适配现有数据库结构 -2. **多算法支持**：实现了3种主流i2i算法，可以融合使用 -3. **多维度聚合**：支持单维度和组合维度，灵活满足不同场景 -4. **时间衰减**：考虑时间因素，近期行为权重更高 -5. **行为加权**：不同行为类型赋予不同权重，购买权重最高 -6. **统一调度**：一键运行所有任务，自动化程度高 -7. **配置灵活**：所有参数可配置，便于调优 -8. **文档完善**：提供了完整的使用文档和示例代码 - -## 🎉 交付状态 - -**状态**: ✅ 已完成 - -所有功能已实现并测试通过，可以直接使用。建议先在测试环境运行验证，确认无误后再部署到生产环境。 - -## 📞 后续支持 - -如有问题，请查看： -1. 日志文件：`logs/` 目录下的日志 -2. 文档：各个 `.md` 文档 -3. 示例代码：`example_query_redis.py` - ---- - -**交付日期**: 2025-10-16 -**版本**: v1.0 -**状态**: 已完成 ✅ - diff --git a/offline_tasks/FIELD_MAPPING.md b/offline_tasks/FIELD_MAPPING.md deleted file mode 100644 index fc4176c..0000000 --- a/offline_tasks/FIELD_MAPPING.md +++ /dev/null @@ -1,172 +0,0 @@ -# 数据库字段映射说明 - -## 实际表结构 - -根据检查结果，实际的表结构如下： - -### sensors_events 表（用户行为事件表） - -| 代码中使用的字段 | 实际字段名 | 说明 | -|----------------|-----------|------| -| `user_id` | `anonymous_id` | 匿名用户ID | -| `item_id` | `item_id` | 商品ID | -| `event_type` | `event` | 事件类型 | -| `create_time` | `create_time` | 创建时间 | -| `platform` | `business_platform` | 业务平台 | -| `client_platform` | `client_platform` | 客户端平台 | - -**不存在的字段**： -- ❌ `country` - 国家字段（原计划支持，但表中不存在） -- ❌ `customer_type` - 客户类型字段（原计划支持，但表中不存在） - -**其他可用字段**： -- `ip` - IP地址 -- `item_type` - 商品类型 -- `location_src` - 位置来源 -- `search_content` - 搜索内容 -- `page_type` - 页面类型 -- `session_id` - 会话ID - -### prd_goods_sku 表（商品SKU表） - -| 代码中使用的字段 | 实际字段名 | 说明 | -|----------------|-----------|------| -| `item_id` | `id` | 商品ID | -| `item_name` | `name` | 商品名称 | -| `item_create_time` | `create_time` | 商品创建时间 | - -**不存在的字段**： -- ❌ `category_level2_id` - 二级分类ID -- ❌ `category_level3_id` - 三级分类ID - -**其他可用字段**： -- `goods_id` - 关联商品主表ID -- `buyer_id` - 买家ID -- `factory_no` - 工厂编号 -- `package_type_name` - 包装类型名称 -- `on_sell_time` - 上架时间 -- `price_base` - 基础价格 - -## 当前支持的维度 - -基于实际表结构，当前代码支持以下维度： - -### 单维度 -1. ✅ `platform` - 业务平台（business_platform） -2. ✅ `client_platform` - 客户端平台 -3. ❌ `country` - 国家（字段不存在） -4. ❌ `customer_type` - 客户类型（字段不存在） -5. ❌ `category_level2` - 二级分类（字段不存在） -6. ❌ `category_level3` - 三级分类（字段不存在） - -### 组合维度 -1. ✅ `platform_client` - 业务平台 + 客户端平台 - -### 列表类型 -1. ✅ `hot` - 热门商品 -2. ✅ `cart` - 加购商品 -3. ✅ `new` - 新品 - -## 如何扩展更多维度 - -### 方案1: 使用现有字段 - -可以考虑使用表中已有的其他字段来扩展维度： - -```python -# 在 interest_aggregation.py 的 SQL 查询中添加 -sql_query = f""" -SELECT - ... - se.page_type, # 页面类型 - se.item_type, # 商品类型 - pgs.package_type_name, # 包装类型 - ... -""" - -# 在聚合函数中添加新维度 -if pd.notna(row.get('page_type')): - key = f"page_type:{row['page_type']}" - aggregations[key][item_id] += weight - -if pd.notna(row.get('item_type')): - key = f"item_type:{row['item_type']}" - aggregations[key][item_id] += weight -``` - -### 方案2: 关联其他表获取分类信息 - -如果分类信息在其他表中，可以通过 JOIN 获取： - -```python -sql_query = f""" -SELECT - se.anonymous_id AS user_id, - se.item_id, - ... - gc.category_level2_id, - gc.category_level3_id -FROM - sensors_events se -LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id -LEFT JOIN goods_category gc ON pgs.goods_id = gc.goods_id # 假设有这个表 -... -""" -``` - -### 方案3: 从 JSON 字段提取 - -如果 `__properties` 字段包含额外信息，可以解析JSON： - -```python -# 在查询中 -sql_query = f""" -SELECT - ... - se.__properties as properties_json -... -""" - -# 在处理时 -import json -props = json.loads(row.get('properties_json', '{}')) -if 'country' in props: - key = f"country:{props['country']}" - aggregations[key][item_id] += weight -``` - -## 推荐的实际使用维度 - -基于现有字段，建议使用以下维度组合： - -1. **业务平台维度** - `platform:{business_platform}` - - 示例：platform:pc, platform:mobile - -2. **客户端平台维度** - `client_platform:{client_platform}` - - 示例：client_platform:web, client_platform:app - -3. **页面类型维度** - `page_type:{page_type}` （需添加） - - 示例：page_type:detail, page_type:list - -4. **商品类型维度** - `item_type:{item_type}` （需添加） - - 示例：item_type:normal, item_type:special - -## 更新后的输出示例 - -``` -# 实际可用的索引键 -platform:pc → 12345:98.5,23456:87.3,... -platform:mobile → 34567:76.2,45678:65.1,... -client_platform:web → 56789:54.3,67890:43.2,... -client_platform:app → 78901:32.1,89012:21.0,... -platform_client:pc_web → 90123:123.4,01234:112.3,... -``` - -## 总结 - -1. **已实现**: 基于 `business_platform` 和 `client_platform` 的索引 -2. **未实现**: country、customer_type、分类相关索引（因字段不存在） -3. **可扩展**: page_type、item_type 等其他维度 - -如需支持更多维度，请参考上述方案进行扩展。 - diff --git a/offline_tasks/FINAL_SUMMARY.md b/offline_tasks/FINAL_SUMMARY.md deleted file mode 100644 index 03b0b8f..0000000 --- a/offline_tasks/FINAL_SUMMARY.md +++ /dev/null @@ -1,269 +0,0 @@ -# 内容相似索引重构 - 最终总结 - -## ✅ 已完成的工作 - -### 1. 核心功能实现 - -#### 重写 `i2i_content_similar.py` -- ✅ 从数据库属性计算 → ES向量计算 -- ✅ 生成两份索引：名称向量 + 图片向量 -- ✅ 移除所有命令行参数，配置内置 -- ✅ **加入 `on_sell_days_boost` 提权** ⭐新增 - - 取值范围：0.9~1.1 - - 自动应用到所有相似度分数 - - 异常值保护，默认1.0 - -#### 提权逻辑 -```python -# KNN查询获取基础分数 -base_score = knn_result['_score'] - -# 获取上架天数提权值 -boost = knn_result['_source']['on_sell_days_boost'] # 0.9~1.1 - -# 应用提权 -final_score = base_score * boost -``` - -### 2. 简化运行脚本 - -#### `run_all.py` 参数简化 -- ❌ 移除：`--skip-i2i`, `--skip-interest`, `--only-*`, `--lookback_days`, `--top_n` -- ✅ 保留：`--debug` (唯一参数) -- ✅ 添加：内容相似任务 - -#### 使用方式 -```bash -# 之前（复杂） -python run_all.py --lookback_days 30 --top_n 50 --skip-interest --only-content - -# 现在（简单） -python run_all.py -``` - -### 3. 更新配置和文档 - -#### 修改的文件 -1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写，加入提权 -2. ✅ `offline_tasks/run_all.py` - 简化参数 -3. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 新增2个索引规范 -4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 支持新索引 -5. ✅ `requirements.txt` - 添加elasticsearch依赖 - -#### 新增的文件 -6. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - 技术文档 -7. ✅ `offline_tasks/scripts/test_es_connection.py` - 测试工具 -8. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 更新说明 -9. ✅ `offline_tasks/CHANGES_SUMMARY.md` - 变更总结 -10. ✅ `offline_tasks/QUICKSTART_NEW.md` - 快速开始 -11. ✅ `offline_tasks/FINAL_SUMMARY.md` - 本文档 - -### 4. 测试工具增强 - -#### `test_es_connection.py` 功能 -- ✅ 测试ES连接 -- ✅ 测试索引存在 -- ✅ 测试字段映射（包含 `on_sell_days_boost`） -- ✅ 测试向量查询 -- ✅ 测试KNN查询 -- ✅ **显示提权计算过程** ⭐新增 - ``` - 基础分数: 0.8523, 提权: 1.05, 最终分数: 0.8949 - ``` - -## 📊 生成的索引 - -### 索引文件 -| 文件名 | 向量类型 | Redis Key | 提权 | TTL | -|-------|---------|-----------|------|-----| -| `i2i_content_name_YYYYMMDD.txt` | 名称向量 | `item:similar:content_name:{id}` | ✅ | 30天 | -| `i2i_content_pic_YYYYMMDD.txt` | 图片向量 | `item:similar:content_pic:{id}` | ✅ | 30天 | - -### 文件格式 -``` -item_id \t item_name \t similar_id1:boosted_score1,similar_id2:boosted_score2,... -``` - -### 示例（分数已包含提权） -``` -3302275 香蕉干 3302276:0.9686,3302277:0.9182,3302278:0.8849 - ↑ 已应用on_sell_days_boost提权 -``` - -## 🔍 技术细节 - -### ES查询字段 -```python -_source = [ - "_id", # 商品ID - "name_zh", # 中文名称 - "on_sell_days_boost" # 提权值 ⭐ -] -``` - -### 提权处理 -```python -# 1. 获取提权值 -boost = hit['_source'].get('on_sell_days_boost', 1.0) - -# 2. 范围验证（0.9~1.1） -if boost is None or boost < 0.9 or boost > 1.1: - boost = 1.0 # 异常值使用默认值 - -# 3. 应用提权 -final_score = base_score * boost -``` - -### 提权说明 -- **> 1.0**: 提权（新品、热门商品） -- **= 1.0**: 不提权（正常商品） -- **< 1.0**: 降权（长尾商品） - -## 🚀 使用指南 - -### 1. 安装依赖 -```bash -pip install -r requirements.txt -# 新增: elasticsearch>=8.0.0 -``` - -### 2. 测试ES连接（含提权测试） -```bash -python scripts/test_es_connection.py -``` - -输出示例： -``` -✓ 找到商品 3302275 - 名称: 香蕉干 - 上架天数提权: 1.05 - -✓ 名称向量KNN查询成功 - 1. ID: 3302276, 名称: 香蕉片 - 基础分数: 0.9220, 提权: 1.05, 最终分数: 0.9681 - 2. ID: 3302277, 名称: 芒果干 - 基础分数: 0.8746, 提权: 1.05, 最终分数: 0.9183 -``` - -### 3. 运行生成 -```bash -# 单独运行 -python scripts/i2i_content_similar.py - -# 或全部运行 -python run_all.py -``` - -### 4. 加载到Redis -```bash -python scripts/load_index_to_redis.py -``` - -### 5. 查询使用 -```python -import redis -import json - -r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) - -# 获取名称向量相似（分数已含提权） -similar = json.loads(r.get('item:similar:content_name:3302275')) -# 返回: [[3302276, 0.9686], [3302277, 0.9182], ...] -# ↑ 分数已应用on_sell_days_boost - -# 获取图片向量相似（分数已含提权） -similar = json.loads(r.get('item:similar:content_pic:3302275')) -# 返回: [[4503826, 0.8523], [4503827, 0.8245], ...] -# ↑ 分数已应用on_sell_days_boost -``` - -## 🎯 核心改进 - -### 1. 简化使用 -- **无参数**: `i2i_content_similar.py` 无需任何参数 -- **无选择**: `run_all.py` 自动运行所有任务 -- **易维护**: 配置集中在代码中 - -### 2. 更强大 -- **深度学习**: 基于ES向量，比TF-IDF更准确 -- **多维度**: 名称 + 图片两个维度 -- **智能提权**: 自动应用上架天数提权 ⭐ -- **更快**: ES KNN查询性能优秀 - -### 3. 提权优势 -- **动态调整**: 根据商品上架天数动态提权 -- **平滑过渡**: 0.9~1.1小范围提权，避免剧烈变化 -- **异常保护**: 自动处理缺失或异常值 -- **透明计算**: 测试工具显示提权过程 - -## 📈 性能指标 - -| 指标 | 值 | -|-----|---| -| 活跃商品数 | ~50,000 | -| 运行时间 | 50-60分钟 | -| Redis Keys | +100,000 | -| Redis内存 | +50MB | -| 提权开销 | 可忽略（简单乘法） | - -## ⚠️ 重要说明 - -### 提权应用 -- ✅ 所有相似度分数都已应用提权 -- ✅ 输出文件中的分数是最终分数 -- ✅ Redis中存储的分数是最终分数 -- ✅ 无需在应用层再次应用提权 - -### 向后兼容 -- ✅ 其他i2i算法不受影响 -- ✅ Redis加载器向后兼容 -- ❌ 命令行参数全部改变 -- ❌ Redis Key格式改变 - -### 迁移建议 -1. 更新API调用，使用新的Redis Key -2. 无需修改分数处理逻辑（已含提权） -3. 建议同时支持两种向量算法 - -## 📚 文档导航 - -| 文档 | 说明 | -|------|------| -| `QUICKSTART_NEW.md` | 5分钟快速开始 | -| `ES_VECTOR_SIMILARITY.md` | ES向量技术详解 | -| `CONTENT_SIMILARITY_UPDATE.md` | 完整更新说明 | -| `CHANGES_SUMMARY.md` | 所有变更总结 | -| `FINAL_SUMMARY.md` | 本文档 | - -## 🎉 总结 - -本次重构实现了三大目标： - -1. **简化使用** ✅ - - 移除复杂参数 - - 一键运行所有任务 - -2. **提升能力** ✅ - - 深度学习向量 - - 多维度相似度 - - 智能上架天数提权 ⭐ - -3. **易于维护** ✅ - - 代码清晰简洁 - - 文档完整详细 - - 测试工具完善 - -### 关键特性 - -- **🚀 无参数运行**: `python scripts/i2i_content_similar.py` -- **🎯 智能提权**: 自动应用 `on_sell_days_boost` (0.9~1.1) -- **🔍 双向量**: 名称语义 + 图片视觉 -- **📊 高性能**: ES KNN查询快速准确 -- **🛡️ 异常保护**: 提权值验证和默认值处理 - ---- - -**重构完成时间**: 2025-10-17 -**影响范围**: 内容相似索引生成和使用 -**状态**: ✅ 已完成，可投入使用 - diff --git a/offline_tasks/FINAL_UPDATE.md b/offline_tasks/FINAL_UPDATE.md deleted file mode 100644 index cdc33f1..0000000 --- a/offline_tasks/FINAL_UPDATE.md +++ /dev/null @@ -1,301 +0,0 @@ -# 最终更新说明 - -## 📅 更新日期：2025-10-16 - -## ✅ 已完成的功能（完整版） - -### 1. i2i 相似度索引（4种算法） - -#### 1.1 行为相似（3种） -基于用户行为计算商品相似度： - -| 算法 | 文件 | 特点 | 状态 | -|------|------|------|------| -| **Swing** | `i2i_swing.py` | 基于用户共同行为，效果最好 | ✅ 已完成 | -| **Session W2V** | `i2i_session_w2v.py` | 基于会话序列，捕获序列关系 | ✅ 已完成 | -| **DeepWalk** | `i2i_deepwalk.py` | 基于图游走，发现深层关系 | ✅ 已完成 | - -#### 1.2 内容相似（新增） -基于商品属性计算商品相似度： - -| 算法 | 文件 | 特点 | 状态 | -|------|------|------|------| -| **Content-based** | `i2i_content_similar.py` | 基于分类、供应商、属性等 | ✅ 新增完成 | - -**支持的方法**： -- `tfidf` - 基于TF-IDF的文本相似度 -- `category` - 基于分类的相似度 -- `hybrid` - 混合方法（推荐） - -**使用的特征**： -- 商品分类（一级到四级） -- 供应商信息 -- 包装类型和包装方式 -- 商品名称关键词 - -**运行命令**： -```bash -# 使用混合方法（推荐） -python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid - -# 只使用TF-IDF -python3 scripts/i2i_content_similar.py --top_n 50 --method tfidf - -# 只使用分类 -python3 scripts/i2i_content_similar.py --top_n 50 --method category -``` - ---- - -### 2. 兴趣点聚合索引（已完善） - -#### 支持的维度（从2个扩展到7个） - -**单维度**： -1. ✅ `platform` - 业务平台 -2. ✅ `client_platform` - 客户端平台 -3. ✅ `supplier` - 供应商 -4. ✅ `category_level1` - 一级分类 -5. ✅ `category_level2` - 二级分类 -6. ✅ `category_level3` - 三级分类 -7. ✅ `category_level4` - 四级分类 - -**组合维度**： -1. ✅ `platform_client` - 业务平台 + 客户端平台 -2. ✅ `platform_category2` - 平台 + 二级分类 -3. ✅ `platform_category3` - 平台 + 三级分类 -4. ✅ `client_category2` - 客户端平台 + 二级分类 - -**列表类型**： -1. ✅ `hot` - 热门商品 -2. ✅ `cart` - 加购商品 -3. ✅ `new` - 新品 - ---- - -## 🎯 完整的索引输出 - -### i2i索引（4种） -``` -# 行为相似 -i2i:swing:{item_id} -i2i:session_w2v:{item_id} -i2i:deepwalk:{item_id} - -# 内容相似（新增） -i2i:content_hybrid:{item_id} -i2i:content_tfidf:{item_id} -i2i:content_category:{item_id} -``` - -### 兴趣点聚合索引（大幅扩展） - -**单维度示例**： -``` -interest:hot:platform:pc -interest:hot:client_platform:web -interest:hot:supplier:10001 -interest:hot:category_level1:100 -interest:hot:category_level2:200 -interest:hot:category_level3:300 -interest:hot:category_level4:400 -``` - -**组合维度示例**： -``` -interest:hot:platform_client:pc_web -interest:hot:platform_category2:pc_200 -interest:hot:platform_category3:mobile_300 -interest:hot:client_category2:web_200 -``` - -**列表类型示例**： -``` -interest:hot:category_level2:200 -interest:cart:category_level3:300 -interest:new:supplier:10001 -interest:global:platform_category2:pc_200 -``` - ---- - -## 📊 业务场景应用（更新） - -### 场景1: 首页猜你喜欢 -```python -# 1. 基于平台推荐 -items_1 = redis.get("interest:hot:platform:pc") - -# 2. 基于用户常购分类推荐 -items_2 = redis.get("interest:hot:category_level2:200") - -# 3. 基于平台+分类组合 -items_3 = redis.get("interest:hot:platform_category2:pc_200") - -# 融合多个维度 -recommended = merge_and_personalize(items_1, items_2, items_3) -``` - -### 场景2: 详情页大家都在看 -```python -item_id = "12345" - -# 1. 行为相似（用户行为） -similar_behavior = redis.get(f"i2i:swing:{item_id}") - -# 2. 内容相似（商品属性） -similar_content = redis.get(f"i2i:content_hybrid:{item_id}") - -# 3. 融合推荐 -recommended = merge_i2i(similar_behavior, similar_content, weight1=0.6, weight2=0.4) -``` - -### 场景3: 分类页推荐 -```python -category_id = "200" - -# 1. 该分类的热门商品 -hot_items = redis.get(f"interest:hot:category_level2:{category_id}") - -# 2. 该分类的新品 -new_items = redis.get(f"interest:new:category_level2:{category_id}") - -# 3. 组合展示 -display(hot_items, new_items) -``` - -### 场景4: 供应商页推荐 -```python -supplier_id = "10001" - -# 该供应商的热门商品 -hot_items = redis.get(f"interest:hot:supplier:{supplier_id}") -``` - ---- - -## 🚀 运行所有任务 - -```bash -cd /home/tw/recommendation/offline_tasks - -# 运行全部任务（包括新增的内容相似） -python3 run_all.py --lookback_days 730 --top_n 50 - -# 只运行内容相似 -python3 run_all.py --only-content --top_n 50 - -# 跳过内容相似，只运行其他 -python3 run_all.py --skip-content --lookback_days 730 --top_n 50 -``` - ---- - -## 📈 性能参考（更新） - -| 任务 | 数据依赖 | 预估时间 | 内存占用 | -|------|---------|---------|---------| -| Swing | 用户行为（730天） | 2-4小时 | 4-8GB | -| Session W2V | 用户行为（730天） | 30-60分钟 | 2-4GB | -| DeepWalk | 用户行为（730天） | 1-2小时 | 2-4GB | -| **Content-based** | **商品属性（全量）** | **10-30分钟** | **2-4GB** | -| 兴趣点聚合 | 用户行为（730天） | 30-60分钟 | 2-4GB | - -**总计**：约6-10小时 - ---- - -## 📝 数据表依赖关系 - -### i2i 行为相似 -- `sensors_events` - 用户行为事件 -- `prd_goods_sku` - 商品SKU信息 - -### i2i 内容相似（新增） -- `prd_goods_sku` - 商品SKU信息 -- `prd_goods` - 商品主表 -- `sup_supplier` - 供应商信息 -- `prd_category` - 分类信息（层级结构） -- `prd_goods_sku_attribute` - 商品属性 -- `prd_option` - 属性选项 -- `prd_attribute` - 属性定义 - -### 兴趣点聚合（已完善） -- `sensors_events` - 用户行为事件 -- `prd_goods_sku` - 商品SKU信息 -- `prd_goods` - 商品主表 -- `prd_category` - 分类信息（新增） - ---- - -## 🔄 与原有代码的对比 - -### 原计划维度（文档中） -- ❌ 国家/销售区域（字段不存在） -- ❌ 客户类型（字段不存在） -- ⚠️ 二级分类（原以为不存在，现已支持） -- ⚠️ 三级分类（原以为不存在，现已支持） - -### 实际实现维度（完善后） -- ✅ 业务平台 -- ✅ 客户端平台 -- ✅ 供应商（新增） -- ✅ 一级分类（新增） -- ✅ 二级分类（新增支持） -- ✅ 三级分类（新增支持） -- ✅ 四级分类（新增） - ---- - -## 💡 优势总结 - -### 1. 内容相似的优势 -- ✅ **冷启动友好**：新商品立即可用 -- ✅ **不依赖行为数据**：商品上架即可生成相似推荐 -- ✅ **可解释性强**：基于分类、属性等明确特征 -- ✅ **计算快速**：只需要商品属性数据 - -### 2. 多维度聚合的优势 -- ✅ **分类粒度丰富**：支持4级分类 -- ✅ **供应商维度**：支持供应商页推荐 -- ✅ **组合查询**：支持平台+分类等组合维度 -- ✅ **灵活性高**：可根据需要查询不同粒度 - -### 3. 算法融合的优势 -- ✅ **行为 + 内容**：可以融合4种i2i算法 -- ✅ **短期 + 长期**：热门、新品等不同时效性 -- ✅ **粗粒度 + 细粒度**：一级到四级分类 - ---- - -## 🎉 完成状态 - -**✅ 全部完成！** - -1. ✅ i2i 行为相似（3种算法） -2. ✅ i2i 内容相似（1种算法，3种方法） -3. ✅ 兴趣点聚合（7个单维度 + 4个组合维度 + 3种列表类型） -4. ✅ 统一调度脚本 -5. ✅ Redis加载工具 -6. ✅ 完整文档 - ---- - -## 📚 相关文档 - -- **CURRENT_STATUS.md** - 当前功能状态 -- **FIELD_MAPPING.md** - 字段映射说明 -- **DATABASE_SETUP.md** - 数据库配置 -- **TROUBLESHOOTING.md** - 故障排除 -- **README.md** - 完整文档 - ---- - -**更新版本**: v1.1 -**更新日期**: 2025-10-16 -**主要变化**: -- 新增内容相似算法 -- 完善分类维度支持（1-4级） -- 新增供应商维度 -- 扩展组合维度查询 - diff --git a/offline_tasks/FIX_NAME_MAPPING.md b/offline_tasks/FIX_NAME_MAPPING.md deleted file mode 100644 index a5e8f0c..0000000 --- a/offline_tasks/FIX_NAME_MAPPING.md +++ /dev/null @@ -1,186 +0,0 @@ -# 商品名称映射问题修复 - -## 问题描述 - -在Debug模式生成的明文文件中，商品名称显示为"Unknown"： - -``` -[7] i2i:swing:3667845 --------------------------------------------------------------------------------- - 1. ID:3588590(Unknown) - Score:0.2857 - 2. ID:3623446(Unknown) - Score:... -``` - -## 根本原因 - -数据类型不匹配导致名称映射失败： - -1. **fetch_name_mappings()** 从数据库获取的映射，key是**字符串类型**： - ```python - mappings['item'] = dict(zip(df['id'].astype(str), df['name'])) - # 结果: {'12345': '香蕉干', '67890': '芒果干', ...} - ``` - -2. **item_name_map** 从DataFrame创建的映射，key是**整数类型**： - ```python - item_name_map = dict(zip(df['item_id'].unique(), ...)) - # 结果: {12345: '香蕉干', 67890: '芒果干', ...} - ``` - -3. **更新操作失败**： - ```python - name_mappings['item'].update(item_name_map) - # int类型的key和str类型的key不匹配，实际上没有更新成功 - ``` - -4. **查询时找不到**： - ```python - name = name_mappings.get('item', {}).get(str(item_id), 'Unknown') - # 将int的item_id转为str查询，但dict中只有int类型的key，所以返回'Unknown' - ``` - -## 修复方案 - -### 方法1：统一转为字符串（已采用） - -```python -# 修改前 -item_name_map = dict(zip(df['item_id'].unique(), df.groupby('item_id')['item_name'].first())) - -# 修改后（key转为字符串） -item_name_map = dict(zip(df['item_id'].unique().astype(str), df.groupby('item_id')['item_name'].first())) -``` - -### 方法2：update时转换（备选） - -```python -# 转换key类型后再更新 -name_mappings['item'].update({str(k): v for k, v in item_name_map.items()}) -``` - -## 验证修复 - -修复后运行debug模式： - -```bash -cd /home/tw/recommendation/offline_tasks -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug -``` - -检查明文文件： - -```bash -more output/debug/i2i_swing_*_readable.txt -``` - -应该看到： - -``` -[7] i2i:swing:3667845(商品名称) --------------------------------------------------------------------------------- - 1. ID:3588590(香蕉干) - Score:0.2857 - 2. ID:3623446(芒果干) - Score:0.2143 -``` - -## 数据库字段确认 - -正确的查询关系： - -```sql -SELECT - pgs.id as 'sku_id', - pgs.name as '商品名称', - ss.name as '供应商名称', - pc_1.name as '一级类目', - pc_2.name as '二级类目' -FROM prd_goods_sku pgs -LEFT JOIN sup_supplier ss ON pgs.supplier_id = ss.id -LEFT JOIN prd_category pc_1 ON ... -``` - -## 其他脚本 - -这个问题也可能存在于其他脚本，需要同样修复： -- ✅ i2i_swing.py (已修复) -- ⚠️ i2i_session_w2v.py (如果有debug功能需要检查) -- ⚠️ i2i_deepwalk.py (如果有debug功能需要检查) -- ⚠️ i2i_content_similar.py (如果有debug功能需要检查) -- ⚠️ interest_aggregation.py (如果有debug功能需要检查) - -## 预防措施 - -为避免类似问题，建议： - -1. **统一数据类型约定**： - - 所有ID映射的key统一使用字符串类型 - - 在debug_utils.py中明确文档说明 - -2. **添加类型检查**： - ```python - def safe_update_mapping(target_dict, source_dict): - """安全更新映射，自动转换key类型""" - for k, v in source_dict.items(): - target_dict[str(k)] = v - ``` - -3. **添加调试日志**： - ```python - if debug: - logger.debug(f"更新前: {len(name_mappings['item'])} 个名称") - name_mappings['item'].update(item_name_map) - logger.debug(f"更新后: {len(name_mappings['item'])} 个名称") - ``` - ---- - -**状态**: ✅ 已修复 -**影响范围**: i2i_swing.py -**修复时间**: 2025-10-16 - -## 补充修复 - 主输出文件 - -问题同样存在于主输出文件中： - -``` -1070176 Unknown 2786217:0.4000 -2786217 Unknown 1070176:0.4000 -``` - -### 原因 - -主输出代码中使用整数item_id作为key查询： - -```python -for item_id, sims in result.items(): - item_name = item_name_map.get(item_id, 'Unknown') # item_id是int，但map的key是str -``` - -### 修复 - -统一转换为字符串： - -```python -for item_id, sims in result.items(): - item_name = item_name_map.get(str(item_id), 'Unknown') # 转换为字符串查询 -``` - -### 验证 - -```bash -# 重新运行 -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 - -# 检查输出 -more output/i2i_swing_20251016.txt -``` - -应该看到： -``` -1070176 商品名称A 2786217:0.4000 -2786217 商品名称B 1070176:0.4000 -``` - ---- - -**更新时间**: 2025-10-16 20:30 -**状态**: ✅ 完全修复 diff --git a/offline_tasks/LATEST_UPDATES.md b/offline_tasks/LATEST_UPDATES.md deleted file mode 100644 index 74bc04b..0000000 --- a/offline_tasks/LATEST_UPDATES.md +++ /dev/null @@ -1,155 +0,0 @@ -# 最新更新 (2025-10-17) - -## 🎉 本次更新内容 - -### 1. ✅ ES向量相似度 + on_sell_days_boost提权 - -#### 功能 -- 基于Elasticsearch向量计算相似度（名称向量 + 图片向量） -- 自动应用 `on_sell_days_boost` 提权（0.9~1.1） -- 无需任何命令行参数，开箱即用 - -#### 使用 -```bash -python scripts/i2i_content_similar.py -``` - -### 2. ✅ 代码规范：统一使用 logger - -#### 变更 -- 移除所有 `print` 语句 -- 统一使用 `logger` 记录日志 -- 更好的日志级别控制 - -### 3. ✅ run.sh 内存监控 - -#### 功能 -- **25GB警告**: 打印警告日志，继续运行 -- **30GB终止**: 强制kill进程，防止OOM -- **每10秒检查**: 实时监控内存使用 -- **详细日志**: `logs/memory_monitor.log` - -#### 使用 -```bash -./run.sh -``` - -## 📋 快速开始 - -### 1. 测试ES连接和向量 -```bash -python scripts/test_es_connection.py -``` - -### 2. 测试内存监控 -```bash -./test_memory_monitor.sh -``` - -### 3. 运行所有任务（含监控） -```bash -./run.sh -``` - -### 4. 查看监控日志 -```bash -tail -f logs/memory_monitor.log -``` - -## 📊 生成的索引 - -| 索引文件 | Redis Key | 提权 | TTL | -|---------|-----------|------|-----| -| `i2i_content_name_YYYYMMDD.txt` | `item:similar:content_name:{id}` | ✅ | 30天 | -| `i2i_content_pic_YYYYMMDD.txt` | `item:similar:content_pic:{id}` | ✅ | 30天 | - -## 📚 文档 - -| 文档 | 说明 | -|------|------| -| `QUICKSTART_NEW.md` | 5分钟快速开始 | -| `ES_VECTOR_SIMILARITY.md` | ES向量技术详解 | -| `RUN_SCRIPT_GUIDE.md` | 运行脚本使用指南 | -| `MEMORY_MONITORING_UPDATE.md` | 内存监控详细说明 | -| `FINAL_SUMMARY.md` | 完整更新总结 | - -## 🔍 关键特性 - -### ES向量相似度 -```python -# 自动应用提权 -base_score = knn_result['_score'] -boost = knn_result['on_sell_days_boost'] # 0.9~1.1 -final_score = base_score * boost -``` - -### 内存监控 -```bash -# 自动监控每个任务 -python3 run_all.py & -PID=$! -check_memory $PID & # 后台监控 - -# 日志输出 -[2025-10-17 15:20:15] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB) -[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB, 强制终止 -``` - -## ⚠️ 重要说明 - -### 向量相似度 -- ✅ 分数已包含 `on_sell_days_boost` 提权 -- ✅ 输出到文件和Redis的都是最终分数 -- ✅ 应用层无需再次应用提权 - -### 内存监控 -- ⚠️ 默认阈值：25GB警告，30GB终止 -- ⚠️ 可在 `run.sh` 中修改阈值 -- ⚠️ 监控日志保存在 `logs/memory_monitor.log` - -### run_all.py 简化 -- ❌ 移除了所有 `--only-*`, `--skip-*` 参数 -- ✅ 只保留 `--debug` 参数 -- ✅ 配置集中在 `offline_config.py` - -## 🚀 一键运行 - -```bash -# 完整流程（含内存监控） -cd /home/tw/recommendation/offline_tasks -./run.sh - -# 输出: -# ====================================================================== -# 开始运行离线任务 - 2025-10-17 14:00:00 -# 内存监控: 警告阈值=25GB, 强制终止阈值=30GB -# ====================================================================== -# -# >>> 步骤1: 调试模式运行（小数据量） -# ✓ 调试模式完成 -# -# >>> 步骤2: 生产模式运行（大数据量） -# ✓ 生产模式完成 -# -# >>> 步骤3: 加载到Redis -# ✓ Redis加载完成 -# -# ====================================================================== -# 所有任务完成 - 2025-10-17 16:30:00 -# ====================================================================== -``` - -## 🎯 核心改进 - -1. **更智能**: ES向量 + 上架天数提权 -2. **更简单**: 无需参数，一键运行 -3. **更安全**: 内存监控保护系统 -4. **更规范**: 统一使用logger -5. **更完整**: 详细文档和测试工具 - ---- - -**更新日期**: 2025-10-17 -**版本**: v2.1 -**状态**: ✅ 已完成，可投入使用 - diff --git a/offline_tasks/MEMORY_MONITORING_UPDATE.md b/offline_tasks/MEMORY_MONITORING_UPDATE.md deleted file mode 100644 index 22d3772..0000000 --- a/offline_tasks/MEMORY_MONITORING_UPDATE.md +++ /dev/null @@ -1,376 +0,0 @@ -# 内存监控功能更新 - -## 更新日期 -2025-10-17 - -## 更新内容 - -### 1. ✅ 代码规范：移除 print，统一使用 logger - -#### 检查结果 -- ✅ `i2i_content_similar.py` - 已全部使用 logger -- ✅ `test_es_connection.py` - print用于测试工具输出（符合预期） -- ✅ 所有核心代码已使用 logger - -### 2. ✅ run.sh 添加内存监控功能 - -#### 核心功能 - -**内存监控函数**: -```bash -check_memory() { - local pid=$1 - local threshold_warn=25 # 25GB警告阈值 - local threshold_kill=30 # 30GB强制kill阈值 - - while kill -0 $pid 2>/dev/null; do - 获取进程内存使用（MB） - 转换为GB - - if 内存 >= 30GB: - 打印错误日志到终端和文件 - 强制kill进程 - break - elif 内存 >= 25GB: - 打印警告日志到终端和文件 - - sleep 10秒检查一次 - done -} -``` - -#### 监控特性 - -| 特性 | 说明 | -|------|------| -| **警告阈值** | 25GB - 打印警告但继续运行 | -| **终止阈值** | 30GB - 强制kill进程 | -| **检查频率** | 每10秒检查一次 | -| **日志输出** | 终端 + `logs/memory_monitor.log` | -| **自动清理** | 任务完成后自动终止监控 | - -#### 日志格式 - -**警告日志**: -``` -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 -``` - -**强制终止日志**: -``` -[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 -``` - -### 3. ✅ 增强的运行流程 - -#### 更新后的执行流程 - -```bash -#!/bin/bash - -1. 定义内存监控函数 -2. 清理旧进程和输出 -3. 创建logs目录 -4. 显示开始信息（包含监控阈值） - -# 调试模式 -5. 启动调试任务（后台） -6. 启动内存监控（后台） -7. 等待任务完成 -8. 终止监控进程 -9. 检查退出码 - -# 生产模式 -10. 启动生产任务（后台） -11. 启动内存监控（后台） -12. 等待任务完成 -13. 终止监控进程 -14. 检查退出码 - -# 加载Redis -15. 加载索引到Redis -16. 检查退出码 - -17. 显示完成信息 -``` - -### 4. ✅ 新增文件 - -| 文件 | 说明 | -|------|------| -| `run.sh` | 更新：添加内存监控 | -| `RUN_SCRIPT_GUIDE.md` | 新增：运行脚本使用指南 | -| `test_memory_monitor.sh` | 新增：内存监控测试脚本 | -| `MEMORY_MONITORING_UPDATE.md` | 新增：本文档 | - -## 使用指南 - -### 基本使用 - -```bash -# 1. 运行脚本（自动监控内存） -cd /home/tw/recommendation/offline_tasks -./run.sh - -# 2. 查看监控日志 -tail -f logs/memory_monitor.log - -# 3. 查看系统内存 -free -h -``` - -### 测试监控功能 - -```bash -# 运行测试脚本 -./test_memory_monitor.sh -``` - -### 自定义阈值 - -编辑 `run.sh` 第8-9行： -```bash -local threshold_warn=25 # 修改警告阈值 -local threshold_kill=30 # 修改强制kill阈值 -``` - -## 技术细节 - -### 内存获取 - -```bash -# 获取进程内存（RSS，单位KB） -ps -p $pid -o rss= - -# 转换为MB -mem_mb=$(ps -p $pid -o rss= | awk '{print int($1/1024)}') - -# 转换为GB -mem_gb=$(echo "scale=2; $mem_mb/1024" | bc) -``` - -### 进程检查 - -```bash -# 检查进程是否存在 -kill -0 $pid 2>/dev/null - -# 返回值: -# 0 - 进程存在 -# 非0 - 进程不存在 -``` - -### 强制终止 - -```bash -# 发送SIGKILL信号 -kill -9 $pid - -# 特点: -# - 立即终止，不可捕获 -# - 不执行清理代码 -# - 确保进程被终止 -``` - -## 输出示例 - -### 正常运行（内存未超限） - -``` -====================================================================== -开始运行离线任务 - 2025-10-17 14:00:00 -内存监控: 警告阈值=25GB, 强制终止阈值=30GB -====================================================================== - ->>> 步骤1: 调试模式运行（小数据量） -调试任务 PID: 12345 -✓ 调试模式完成 - ->>> 步骤2: 生产模式运行（大数据量） -生产任务 PID: 12346 -✓ 生产模式完成 - ->>> 步骤3: 加载到Redis -✓ Redis加载完成 - -====================================================================== -所有任务完成 - 2025-10-17 16:30:00 -====================================================================== -``` - -### 内存警告（25GB-30GB） - -``` ->>> 步骤2: 生产模式运行（大数据量） -生产任务 PID: 12346 -[2025-10-17 15:20:15] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 -[2025-10-17 15:22:30] ⚠️ 内存警告！当前使用: 27.80GB (>= 25GB), PID=12346 -[2025-10-17 15:24:45] ⚠️ 内存警告！当前使用: 28.95GB (>= 25GB), PID=12346 -✓ 生产模式完成 -``` - -### 内存超限（>=30GB） - -``` ->>> 步骤2: 生产模式运行（大数据量） -生产任务 PID: 12346 -[2025-10-17 15:20:15] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 -[2025-10-17 15:22:30] ⚠️ 内存警告！当前使用: 28.80GB (>= 25GB), PID=12346 -[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12346 -✗ 生产模式失败，退出码: 137 -``` - -## 监控日志示例 - -`logs/memory_monitor.log`: -``` -[2025-10-17 15:20:15] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 -[2025-10-17 15:22:30] ⚠️ 内存警告！当前使用: 28.80GB (>= 25GB), PID=12346 -[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12346 -``` - -## 故障处理 - -### 内存持续增长 - -**现象**: 警告日志频繁出现，内存持续增长 - -**原因**: -- 数据量过大 -- 内存泄漏 -- 批处理大小不合理 - -**解决方案**: -1. 减小批处理大小 -2. 增加垃圾回收频率 -3. 优化算法减少内存占用 -4. 考虑分批运行 - -### 进程被误杀 - -**现象**: 任务未完成就被终止 - -**原因**: -- 阈值设置过低 -- 系统其他进程占用内存 - -**解决方案**: -1. 提高阈值（修改 run.sh） -2. 优化代码减少内存使用 -3. 关闭不必要的系统进程 - -### 监控不生效 - -**检查清单**: -- [ ] `bc` 命令是否安装：`which bc` -- [ ] 脚本是否有执行权限：`ls -l run.sh` -- [ ] logs目录是否存在：`ls -ld logs/` -- [ ] 进程是否在后台运行：`ps aux | grep run_all` - -## 性能影响 - -### 监控开销 - -| 项目 | 影响 | -|------|------| -| CPU | < 0.1% (每10秒运行一次ps命令) | -| 内存 | < 10MB (监控脚本本身) | -| 磁盘I/O | 极小 (仅写日志) | - -### 建议 - -- ✅ 检查频率10秒合理，不建议小于5秒 -- ✅ 警告阈值25GB为系统总内存的合理比例 -- ✅ 终止阈值30GB留有5GB缓冲空间 -- ⚠️ 根据实际情况调整阈值 - -## 最佳实践 - -### 1. 定期查看日志 -```bash -# 每天检查 -cat logs/memory_monitor.log - -# 统计警告次数 -grep "⚠️" logs/memory_monitor.log | wc -l - -# 统计终止次数 -grep "❌" logs/memory_monitor.log | wc -l -``` - -### 2. 设置定时任务 -```bash -# 每周一凌晨2点运行 -0 2 * * 1 /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 -``` - -### 3. 配置告警 -```bash -# 在 run.sh 末尾添加 -if grep -q "❌" logs/memory_monitor.log; then - echo "内存超限告警" | mail -s "[告警] 离线任务内存超限" admin@example.com -fi -``` - -### 4. 监控系统资源 -```bash -# 安装监控工具 -apt install htop sysstat - -# 实时监控 -htop -p $(pgrep -f run_all.py) - -# 查看历史 -sar -r 1 10 # 内存使用情况 -``` - -## 对比 - -### 更新前 -```bash -# 无内存监控 -python3 run_all.py --lookback_days 730 --top_n 50 - -# 问题: -# - 内存可能无限增长 -# - OOM导致系统崩溃 -# - 无法及时发现问题 -``` - -### 更新后 -```bash -# 自动内存监控 -./run.sh - -# 优势: -# ✅ 25GB警告提醒 -# ✅ 30GB自动终止 -# ✅ 详细日志记录 -# ✅ 保护系统稳定 -``` - -## 总结 - -本次更新实现了： - -1. ✅ **代码规范化**: 统一使用logger，移除print -2. ✅ **内存监控**: 25GB警告，30GB强制终止 -3. ✅ **自动化运行**: 集成监控到运行流程 -4. ✅ **日志记录**: 详细的监控日志 -5. ✅ **测试工具**: 提供测试脚本验证功能 -6. ✅ **完整文档**: 使用指南和故障处理 - -### 核心价值 - -- 🛡️ **保护系统**: 防止内存溢出导致系统崩溃 -- 📊 **实时监控**: 每10秒检查一次内存使用 -- 🔔 **及时告警**: 25GB警告，30GB终止 -- 📝 **日志完整**: 所有监控事件都有记录 -- 🔧 **易于调整**: 阈值和频率可轻松修改 - ---- - -**更新完成时间**: 2025-10-17 -**状态**: ✅ 已完成，可投入使用 -**建议**: 先在测试环境验证后再用于生产 - diff --git a/offline_tasks/OFFLINE_INDEX_SPEC.md b/offline_tasks/OFFLINE_INDEX_SPEC.md deleted file mode 100644 index ba5be7d..0000000 --- a/offline_tasks/OFFLINE_INDEX_SPEC.md +++ /dev/null @@ -1,197 +0,0 @@ -# 离线索引产出规范 - -## 📋 索引任务列表 - -| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 | -|---------|---------|---------|---------|-----------| -| **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` diff --git a/offline_tasks/PROJECT_SUMMARY.md b/offline_tasks/PROJECT_SUMMARY.md deleted file mode 100644 index 2e32439..0000000 --- a/offline_tasks/PROJECT_SUMMARY.md +++ /dev/null @@ -1,276 +0,0 @@ -# 推荐系统离线任务 - 项目总结 - -## 项目概述 - -本项目实现了一个完整的推荐系统离线任务框架，用于生成各种推荐索引。主要包括两大模块： - -1. **i2i 行为相似索引**：基于用户行为计算物品之间的相似度 -2. **兴趣点聚合索引**：按多维度聚合用户行为，生成不同场景的推荐列表 - -## 技术架构 - -### 数据来源 -- 数据库：SelectDB（兼容MySQL协议） -- 主要表： - - `sensors_events`：用户行为事件表 - - `prd_goods_sku`：商品SKU表 - -### 算法实现 - -#### 1. i2i 行为相似算法 - -| 算法 | 原理 | 优势 | 适用场景 | -|------|------|------|---------| -| **Swing** | 基于用户共同行为的物品相似度，考虑用户重叠度 | 效果好，能发现深层关系 | 详情页推荐、相关商品 | -| **Session W2V** | 基于用户会话序列训练Word2Vec | 能捕获序列关系 | 下一个可能感兴趣的商品 | -| **DeepWalk** | 基于图随机游走训练Word2Vec | 能发现图结构特征 | 发现潜在关联商品 | - -#### 2. 兴趣点聚合 - -**维度分类：** - -- **单维度**： - - 平台（PC/Mobile/App） - - 国家/销售区域 - - 客户类型（零售商/批发商等） - - 二级分类 - - 三级分类 - -- **组合维度**： - - 平台 + 国家 - - 平台 + 客户类型 - - 国家 + 客户类型 - - 平台 + 国家 + 客户类型 - -**列表类型：** - -- **hot（热门）**：基于最近180天的高交互商品 -- **cart（加购）**：基于加购行为的高频商品 -- **new（新品）**：基于商品创建时间的新品 -- **global（全局）**：基于所有数据的综合排序 - -## 核心特性 - -### 1. 时间衰减 -- 使用指数衰减模型，越近期的行为权重越高 -- 衰减因子：0.95（每30天衰减一次） -- 公式：`weight = decay_factor ^ (days / 30)` - -### 2. 行为权重 -不同行为类型赋予不同权重： - -| 行为类型 | 权重 | 说明 | -|---------|------|------| -| click | 1.0 | 点击 | -| addToPool | 2.0 | 加入询盘池 | -| addToCart | 3.0 | 加入购物车 | -| contactFactory | 5.0 | 联系工厂 | -| purchase | 10.0 | 购买 | - -### 3. 可配置参数 -所有参数集中在 `config/offline_config.py`，便于调整优化。 - -## 文件清单 - -### 核心代码 - -``` -/home/tw/recommendation/ -├── db_service.py # 数据库连接服务 -├── requirements.txt # Python依赖包 -└── offline_tasks/ - ├── config/ - │ └── offline_config.py # 配置文件 - ├── scripts/ - │ ├── i2i_swing.py # Swing算法 - │ ├── i2i_session_w2v.py # Session W2V算法 - │ ├── i2i_deepwalk.py # DeepWalk算法 - │ ├── interest_aggregation.py # 兴趣点聚合 - │ └── load_index_to_redis.py # 加载索引到Redis - ├── run_all.py # 统一调度脚本 - ├── test_connection.py # 连接测试脚本 - ├── example_query_redis.py # Redis查询示例 - ├── README.md # 详细文档 - ├── QUICKSTART.md # 快速启动指南 - └── PROJECT_SUMMARY.md # 本文档 -``` - -### 输出目录 - -``` -offline_tasks/ -├── output/ # 索引输出目录 -│ ├── i2i_swing_YYYYMMDD.txt -│ ├── i2i_session_w2v_YYYYMMDD.txt -│ ├── i2i_deepwalk_YYYYMMDD.txt -│ ├── session_w2v_model_YYYYMMDD.model # W2V模型 -│ ├── deepwalk_model_YYYYMMDD.model # DeepWalk模型 -│ ├── item_graph_YYYYMMDD.txt # 物品图结构 -│ ├── interest_aggregation_hot_YYYYMMDD.txt -│ ├── interest_aggregation_cart_YYYYMMDD.txt -│ ├── interest_aggregation_new_YYYYMMDD.txt -│ └── interest_aggregation_global_YYYYMMDD.txt -└── logs/ # 日志目录 - ├── run_all_YYYYMMDD.log - └── ... -``` - -## 使用流程 - -### 1. 环境准备 -```bash -pip install -r requirements.txt -``` - -### 2. 测试连接 -```bash -cd offline_tasks -python test_connection.py -``` - -### 3. 运行离线任务 -```bash -python run_all.py --lookback_days 730 --top_n 50 -``` - -### 4. 加载索引到Redis -```bash -python scripts/load_index_to_redis.py --expire-days 7 -``` - -### 5. 查询示例 -```bash -python example_query_redis.py -``` - -## 数据格式 - -### i2i索引格式 -``` -item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,... -``` - -示例： -``` -123456 \t 商品A \t 234567:0.8523,345678:0.7842,456789:0.7234 -``` - -### 兴趣点聚合索引格式 -``` -dimension_key \t item_id1:score1,item_id2:score2,... -``` - -示例： -``` -platform:PC \t 12345:98.52,23456:87.34,34567:76.89 -country:US \t 45678:156.23,56789:142.87,67890:128.45 -platform_country:PC_US \t 78901:234.56,89012:198.76,90123:187.23 -``` - -## 在线推荐场景 - -### 场景1：详情页 - 大家都在看 -``` -用户浏览商品ID: 123456 -查询: i2i:swing:123456 -返回: 该商品的相似商品列表 -``` - -### 场景2：首页 - 猜你喜欢 -``` -用户特征: PC端, 美国, 零售商 -组合查询: -1. interest:hot:platform_country:PC_US -2. interest:cart:customer_type:retailer -3. 结合用户历史行为的i2i -``` - -### 场景3：搜索结果页 - 供应商推荐 -``` -用户搜索: 二级分类100 -查询: interest:global:category_level2:100 -返回: 该分类下的热门商品 -``` - -## 性能指标 - -### 数据量参考（730天数据） -- 用户行为记录：约100万-1000万条 -- 商品数量：约10万-50万个 -- 生成索引：约5万-20万条 - -### 运行时间（参考值） -- Swing算法：2-4小时 -- Session W2V：30-60分钟 -- DeepWalk：1-2小时 -- 兴趣点聚合：30-60分钟 -- 总计：约5-8小时 - -### 资源占用 -- CPU：8-16核 -- 内存：8-16GB -- 磁盘：输出文件约500MB-2GB - -## 优化建议 - -### 1. 算法层面 -- **Swing算法**：可以使用C++版本（已有实现），性能提升10倍 -- **并行化**：将不同算法分配到不同机器并行运行 -- **增量更新**：对于变化不大的索引，考虑增量更新 - -### 2. 工程层面 -- **分布式计算**：使用Spark/Flink处理大规模数据 -- **缓存中间结果**：避免重复计算 -- **数据采样**：调试阶段使用采样数据 - -### 3. 业务层面 -- **A/B测试**：对比不同算法的效果 -- **融合策略**：组合多个算法的结果 -- **实时更新**：结合实时计算补充离线索引 - -## 后续扩展 - -### 1. 新增算法 -- ItemCF（物品协同过滤） -- Node2Vec（带权重的图游走） -- Graph Neural Network（图神经网络） - -### 2. 新增维度 -- 价格区间 -- 品牌 -- 标签组合 -- 用户画像更多维度 - -### 3. 实时化 -- 实时更新热门商品 -- 实时更新新品列表 -- 实时i2i相似度计算 - -### 4. 个性化 -- 结合用户画像的个性化排序 -- 多目标优化（点击率、转化率、GMV） -- 强化学习排序 - -## 维护说明 - -### 定期检查 -- 每周检查日志，确保任务正常运行 -- 每月检查索引质量，调整参数 -- 每季度评估算法效果，优化策略 - -### 监控指标 -- 任务执行成功率 -- 索引生成数量 -- Redis命中率 -- 推荐点击率/转化率 - -## 联系方式 - -如有问题或建议，请联系推荐系统团队。 - ---- - -**文档版本**: v1.0 -**最后更新**: 2025-10-16 -**作者**: 推荐系统团队 - diff --git a/offline_tasks/QUICKSTART.md b/offline_tasks/QUICKSTART.md deleted file mode 100644 index 65be781..0000000 --- a/offline_tasks/QUICKSTART.md +++ /dev/null @@ -1,213 +0,0 @@ -# 离线任务快速启动指南 - -## 一、环境准备 - -### 1. 安装依赖 - -```bash -cd /home/tw/recommendation -pip install -r requirements.txt -``` - -### 2. 配置数据库和Redis - -编辑配置文件 `offline_tasks/config/offline_config.py`，确保数据库和Redis连接信息正确： - -```python -# 数据库配置 -DB_CONFIG = { - 'host': 'your_db_host', - 'port': '9030', - 'database': 'datacenter', - 'username': 'readonly', - 'password': 'your_password' -} - -# Redis配置 -REDIS_CONFIG = { - 'host': 'your_redis_host', - 'port': 6379, - 'db': 0, - 'password': None -} -``` - -## 二、运行离线任务 - -### 方式1：运行所有任务（推荐） - -```bash -cd /home/tw/recommendation/offline_tasks -python run_all.py --lookback_days 730 --top_n 50 -``` - -这将依次运行： -1. Swing算法（i2i相似度） -2. Session Word2Vec（i2i相似度） -3. DeepWalk算法（i2i相似度） -4. 兴趣点聚合（多维度商品索引） - -### 方式2：运行单个任务 - -#### 运行Swing算法 - -```bash -cd /home/tw/recommendation/offline_tasks -python scripts/i2i_swing.py --lookback_days 730 --top_n 50 --time_decay -``` - -#### 运行Session Word2Vec - -```bash -python scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model -``` - -#### 运行DeepWalk - -```bash -python scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph -``` - -#### 运行兴趣点聚合 - -```bash -python scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 -``` - -## 三、将索引加载到Redis - -任务运行完成后，将生成的索引加载到Redis： - -```bash -cd /home/tw/recommendation/offline_tasks -python scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 --expire-days 7 -``` - -参数说明： -- `--redis-host`: Redis服务器地址 -- `--redis-port`: Redis端口 -- `--redis-db`: Redis数据库编号（默认0） -- `--expire-days`: 索引过期天数（默认7天） - -## 四、查看输出结果 - -所有输出文件都在 `offline_tasks/output/` 目录下： - -```bash -cd /home/tw/recommendation/offline_tasks/output -ls -lh -``` - -输出文件示例： -``` -i2i_swing_20251016.txt -i2i_session_w2v_20251016.txt -i2i_deepwalk_20251016.txt -interest_aggregation_hot_20251016.txt -interest_aggregation_cart_20251016.txt -interest_aggregation_new_20251016.txt -interest_aggregation_global_20251016.txt -``` - -## 五、查看日志 - -所有运行日志都在 `offline_tasks/logs/` 目录下： - -```bash -cd /home/tw/recommendation/offline_tasks/logs -tail -f run_all_20251016.log -``` - -## 六、设置定时任务 - -### 使用crontab设置每天运行 - -```bash -# 编辑crontab -crontab -e - -# 添加以下行（每天凌晨2点运行） -0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py --lookback_days 730 --top_n 50 >> /home/tw/recommendation/offline_tasks/logs/cron.log 2>&1 -``` - -### 运行后自动加载到Redis - -可以在crontab中添加索引加载任务： - -```bash -# 凌晨6点加载索引到Redis（假设离线任务在4小时内完成） -0 6 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 scripts/load_index_to_redis.py >> /home/tw/recommendation/offline_tasks/logs/load_redis.log 2>&1 -``` - -## 七、验证结果 - -### 查看文件内容 - -```bash -# 查看i2i相似度 -head -n 5 output/i2i_swing_20251016.txt - -# 查看兴趣点聚合 -head -n 5 output/interest_aggregation_hot_20251016.txt -``` - -### 从Redis查询 - -```bash -# 使用redis-cli -redis-cli - -# 查看i2i相似度 -GET i2i:swing:123456 - -# 查看兴趣点索引 -GET interest:hot:platform:PC -GET interest:global:country:US -``` - -## 八、常见问题 - -### Q1: 任务运行时间太长怎么办？ - -A: 可以尝试： -1. 减少 `--lookback_days` 参数（如改为365天） -2. 减少 `--top_n` 参数（如改为20） -3. 在更强大的机器上运行 -4. 考虑分布式运行不同算法 - -### Q2: 内存不足怎么办？ - -A: -1. Swing算法特别消耗内存，可以先跳过：`python run_all.py --skip-i2i` -2. 只运行DeepWalk或Session W2V -3. 对数据进行采样 - -### Q3: 数据库连接超时怎么办？ - -A: -1. 检查数据库配置是否正确 -2. 检查网络连接 -3. 增加SQL查询的超时时间 -4. 分批查询数据 - -### Q4: 如何只更新特定维度的索引？ - -A: 修改 `interest_aggregation.py` 脚本，注释掉不需要的维度计算代码。 - -## 九、性能参考 - -在标准配置（730天数据，top_n=50）下的预估运行时间： - -| 任务 | 数据量 | 预估时间 | 内存占用 | -|------|--------|---------|---------| -| Swing | 100万条行为 | 2-4小时 | 4-8GB | -| Session W2V | 100万条行为 | 30-60分钟 | 2-4GB | -| DeepWalk | 100万条行为 | 1-2小时 | 2-4GB | -| 兴趣点聚合 | 100万条行为 | 30-60分钟 | 2-4GB | - -实际时间会因数据量和机器配置而异。 - -## 十、联系与支持 - -如有问题，请查看日志文件或联系开发团队。 - diff --git a/offline_tasks/QUICKSTART_NEW.md b/offline_tasks/QUICKSTART_NEW.md deleted file mode 100644 index 27fa92b..0000000 --- a/offline_tasks/QUICKSTART_NEW.md +++ /dev/null @@ -1,321 +0,0 @@ -# 快速开始 - 新版本 - -## 🚀 5分钟快速上手 - -### 1. 安装依赖 - -```bash -cd /home/tw/recommendation -pip install -r requirements.txt -``` - -**新增依赖**: `elasticsearch>=8.0.0` - -### 2. 测试ES连接 - -```bash -cd offline_tasks -python scripts/test_es_connection.py -``` - -如果看到 ✓ 表示测试通过。 - -### 3. 运行所有任务 - -```bash -python run_all.py -``` - -就这么简单！不需要任何参数。 - -### 4. 加载到Redis - -```bash -python scripts/load_index_to_redis.py -``` - -## 📋 运行单个任务 - -### i2i相似索引 - -```bash -# Swing算法 -python scripts/i2i_swing.py --lookback_days 30 --top_n 50 --time_decay - -# Session W2V -python scripts/i2i_session_w2v.py --lookback_days 30 --top_n 50 --save_model - -# DeepWalk -python scripts/i2i_deepwalk.py --lookback_days 30 --top_n 50 --save_model - -# 内容相似（ES向量）- 无需参数！ -python scripts/i2i_content_similar.py -``` - -### 兴趣聚合 - -```bash -python scripts/interest_aggregation.py --lookback_days 30 --top_n 1000 -``` - -## 🎯 主要变化 - -### 简化！简化！简化！ - -#### 之前 (v1.0) -```bash -python run_all.py \ - --lookback_days 30 \ - --top_n 50 \ - --skip-interest \ - --only-content \ - --debug -``` - -#### 现在 (v2.0) -```bash -python run_all.py -# 或 -python run_all.py --debug # 启用debug模式 -``` - -### 内容相似索引 - -#### 之前 -- 1个索引: `i2i_content_hybrid_*.txt` -- 基于: 商品属性（分类、供应商等） -- 参数: `--method hybrid --top_n 50` - -#### 现在 -- **2个索引**: - - `i2i_content_name_*.txt` (名称向量) - - `i2i_content_pic_*.txt` (图片向量) -- 基于: Elasticsearch深度学习向量 -- 参数: **无需参数！** - -## 📊 输出文件 - -### 文件位置 -``` -offline_tasks/output/ -├── i2i_swing_20251017.txt # Swing相似索引 -├── i2i_session_w2v_20251017.txt # Session W2V相似索引 -├── i2i_deepwalk_20251017.txt # DeepWalk相似索引 -├── i2i_content_name_20251017.txt # 名称向量相似索引 ⭐新 -├── i2i_content_pic_20251017.txt # 图片向量相似索引 ⭐新 -├── interest_aggregation_hot_20251017.txt # 热门商品 -├── interest_aggregation_cart_20251017.txt # 加购商品 -├── interest_aggregation_new_20251017.txt # 新品 -└── interest_aggregation_global_20251017.txt # 全局热门 -``` - -### 文件格式 -``` -item_id \t item_name \t similar_id1:score1,similar_id2:score2,... -``` - -## 🔍 查询示例 - -### Python查询 - -```python -import redis -import json - -# 连接Redis -r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) - -# 1. 获取Swing相似商品 -similar = json.loads(r.get('item:similar:swing:123456')) -# 返回: [[234567, 0.8523], [345678, 0.7842], ...] - -# 2. 获取名称向量相似商品 ⭐新 -similar = json.loads(r.get('item:similar:content_name:123456')) -# 返回: [[234567, 0.9234], [345678, 0.8756], ...] - -# 3. 获取图片向量相似商品 ⭐新 -similar = json.loads(r.get('item:similar:content_pic:123456')) -# 返回: [[567890, 0.8123], [678901, 0.7856], ...] - -# 4. 获取热门商品 -hot_items = json.loads(r.get('interest:hot:platform:PC')) -# 返回: [123456, 234567, 345678, ...] -``` - -### Redis CLI查询 - -```bash -# 连接Redis -redis-cli - -# 查看Swing相似商品 -GET item:similar:swing:123456 - -# 查看名称向量相似商品 ⭐新 -GET item:similar:content_name:123456 - -# 查看图片向量相似商品 ⭐新 -GET item:similar:content_pic:123456 - -# 查看热门商品 -GET interest:hot:platform:PC -``` - -## ⚙️ 配置说明 - -### ES配置 (i2i_content_similar.py) - -```python -ES_CONFIG = { - 'host': 'http://localhost:9200', - 'index_name': 'spu', - 'username': 'essa', - 'password': '4hOaLaf41y2VuI8y' -} -``` - -### 算法参数 (i2i_content_similar.py) - -```python -TOP_N = 50 # 每个商品返回50个相似商品 -KNN_K = 100 # KNN查询返回100个候选 -KNN_CANDIDATES = 200 # 候选池大小200 -``` - -### 全局配置 (offline_config.py) - -```python -DEFAULT_LOOKBACK_DAYS = 30 # 回看天数 -DEFAULT_I2I_TOP_N = 50 # i2i Top N -DEFAULT_INTEREST_TOP_N = 1000 # 兴趣聚合 Top N -``` - -## 🔧 故障排查 - -### ES连接失败 - -```bash -# 1. 检查ES是否运行 -curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200 - -# 2. 运行测试脚本 -python scripts/test_es_connection.py - -# 3. 检查配置 -# 编辑 scripts/i2i_content_similar.py 中的 ES_CONFIG -``` - -### 商品ID不存在 - -测试脚本默认使用 `item_id = "3302275"`，如果不存在： - -```python -# 编辑 test_es_connection.py -test_item_id = "你的商品ID" -``` - -### Redis连接失败 - -```bash -# 检查Redis配置 -cat offline_tasks/config/offline_config.py | grep REDIS - -# 测试Redis连接 -redis-cli ping -``` - -### 文件不存在 - -```bash -# 检查output目录 -ls -lh offline_tasks/output/ - -# 查看最新生成的文件 -ls -lht offline_tasks/output/ | head -10 -``` - -## 📚 详细文档 - -- **ES向量相似度**: `scripts/ES_VECTOR_SIMILARITY.md` -- **更新说明**: `CONTENT_SIMILARITY_UPDATE.md` -- **变更总结**: `CHANGES_SUMMARY.md` -- **Redis规范**: `REDIS_DATA_SPEC.md` - -## 🎓 学习路径 - -### 新用户 -1. 阅读本文档 ✓ -2. 运行 `test_es_connection.py` -3. 运行 `run_all.py` -4. 查看 `output/` 目录 -5. 加载到Redis并查询 - -### 进阶使用 -1. 阅读 `ES_VECTOR_SIMILARITY.md` -2. 了解向量相似度原理 -3. 优化ES查询性能 -4. 自定义算法参数 - -### 开发者 -1. 阅读 `CONTENT_SIMILARITY_UPDATE.md` -2. 了解技术架构 -3. 阅读源代码注释 -4. 贡献代码改进 - -## 🚨 注意事项 - -### ⚠️ 破坏性变化 - -1. **i2i_content_similar.py 参数全部改变** - - 旧: `--method`, `--top_n`, `--debug` - - 新: 无参数 - -2. **Redis Key格式改变** - - 旧: `item:similar:content:{item_id}` - - 新: `item:similar:content_name:{item_id}` 和 `item:similar:content_pic:{item_id}` - -3. **输出文件改变** - - 旧: `i2i_content_hybrid_*.txt` - - 新: `i2i_content_name_*.txt` 和 `i2i_content_pic_*.txt` - -### ✅ 向后兼容 - -- Swing、W2V、DeepWalk 算法不受影响 -- 兴趣聚合不受影响 -- Redis加载器向后兼容 -- 其他i2i索引继续工作 - -## 💡 最佳实践 - -### 运行频率 -- **行为相似** (Swing, W2V, DeepWalk): 每天 -- **内容相似** (名称向量, 图片向量): 每周 -- **兴趣聚合**: 每天 - -### Redis TTL -- **行为相似**: 7天 -- **内容相似**: 30天 -- **兴趣聚合**: 3-7天 - -### 性能优化 -1. 使用 `--debug` 模式调试 -2. 先用小数据集测试 -3. 定期清理过期数据 -4. 监控ES查询性能 - -## 🎉 总结 - -新版本大幅简化了使用，主要改进： - -1. ✅ **无需参数**: `run_all.py` 和 `i2i_content_similar.py` 无需参数 -2. ✅ **更强大**: 基于深度学习向量，更准确 -3. ✅ **多维度**: 名称 + 图片两个维度 -4. ✅ **更快**: ES KNN查询性能优秀 -5. ✅ **易维护**: 代码简洁，配置清晰 - -开始使用新版本，享受更简单、更强大的推荐系统！ - ---- - -**问题反馈**: 如有问题请查看详细文档或联系开发团队 - diff --git a/offline_tasks/QUICK_DEBUG_SUMMARY.md b/offline_tasks/QUICK_DEBUG_SUMMARY.md deleted file mode 100644 index f0dab48..0000000 --- a/offline_tasks/QUICK_DEBUG_SUMMARY.md +++ /dev/null @@ -1,128 +0,0 @@ -# Debug功能快速总结 - -## ✅ 已完成的工作 - -### 1. 核心组件 - -| 组件 | 状态 | 说明 | -|------|------|------| -| `debug_utils.py` | ✅ | Debug工具库（369行） | -| `offline_config.py` | ✅ | 新增DEBUG_CONFIG | -| `i2i_swing.py` | ✅ | 完整debug支持 | -| `run_all.py` | ✅ | 支持--debug参数传递 | - -### 2. Debug功能特性 - -#### A. 详细日志输出 -```python -# 自动记录： -- 算法参数 -- 数据统计（行数、列数、类型、缺失值） -- 处理进度（每N条显示） -- 每个步骤的耗时 -- 数据分布（行为类型、用户数、商品数） -- 中间结果采样 -``` - -#### B. 明文索引文件 -``` -原始: 12345\t香蕉干\t67890:0.8567,11223:0.7234 -明文: [1] i2i:swing:12345(香蕉干) - 1. ID:67890(芒果干) - Score:0.8567 - 2. ID:11223(菠萝干) - Score:0.7234 -``` - -#### C. 日志文件 -``` -offline_tasks/logs/debug/i2i_swing_20251016_193000.log -offline_tasks/output/debug/i2i_swing_20251016_readable.txt -``` - -## 🚀 使用方法 - -### 单个脚本 -```bash -# i2i_swing.py 已支持debug -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug -``` - -### 所有任务 -```bash -# run_all.py 已支持debug参数传递 -python3 run_all.py --lookback_days 7 --top_n 10 --debug -``` - -## 📊 输出示例 - -### 控制台输出 -``` -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ -2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: -2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 -2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 -2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 -2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) -2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 -``` - -### 明文文件示例 -``` -================================================================================ -明文索引文件 -生成时间: 2025-10-16 19:35:00 -描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) -总索引数: 2345 -================================================================================ - -[1] i2i:swing:12345(香蕉干) --------------------------------------------------------------------------------- - 1. ID:67890(芒果干) - Score:0.8567 - 2. ID:11223(菠萝干) - Score:0.7234 - 3. ID:44556(苹果干) - Score:0.6891 -``` - -## 🔧 Debug工具函数 - -| 函数 | 功能 | -|------|------| -| `setup_debug_logger()` | 设置debug日志 | -| `log_dataframe_info()` | 记录DataFrame详情 | -| `log_dict_stats()` | 记录字典统计 | -| `save_readable_index()` | 保存明文索引 | -| `fetch_name_mappings()` | 获取ID到名称映射 | -| `log_algorithm_params()` | 记录算法参数 | -| `log_processing_step()` | 记录处理步骤 | - -## 📝 待完成 - -需要为以下脚本添加debug支持（使用相同模式）： -- [ ] i2i_session_w2v.py -- [ ] i2i_deepwalk.py -- [ ] i2i_content_similar.py -- [ ] interest_aggregation.py - -## 💡 快速测试 - -```bash -# 1. 测试debug工具 -cd /home/tw/recommendation/offline_tasks -python3 -c "from scripts.debug_utils import *; print('✓ Debug utils OK')" - -# 2. 测试i2i_swing debug模式 -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug - -# 3. 查看输出 -ls -lh logs/debug/ -ls -lh output/debug/ -``` - -## 📖 完整文档 - -详细使用指南：`DEBUG_GUIDE.md` - ---- - -**状态**: 🚧 进行中 (i2i_swing.py完成，其他脚本待更新) -**下一步**: 批量更新其他4个脚本的debug支持 diff --git a/offline_tasks/REDIS_DATA_SPEC.md b/offline_tasks/REDIS_DATA_SPEC.md deleted file mode 100644 index 2777b71..0000000 --- a/offline_tasks/REDIS_DATA_SPEC.md +++ /dev/null @@ -1,306 +0,0 @@ -# Redis数据灌入规范 - -## 📋 数据灌入概述 - -将离线生成的推荐索引加载到Redis，供在线系统实时查询使用。 - -## 🔑 Redis Key规范 - -### 通用规则 -``` -{namespace}:{function}:{algorithm}:{identifier} -``` - -- `namespace`: 业务命名空间（item, user, interest等） -- `function`: 功能类型（similar, feature, hot等） -- `algorithm`: 算法名称（swing, w2v, deepwalk等） -- `identifier`: 具体标识（item_id, dimension_key等） - -## 📊 数据灌入规范表 - -| 模块名称 | 源数据地址 | 格式描述 | RedisKey模板 | RedisValue格式 | TTL | -|---------|-----------|---------|-------------|---------------|-----| -| **i2i_swing** | `output/i2i_swing_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:swing:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | -| **i2i_session_w2v** | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:w2v:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | -| **i2i_deepwalk** | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:deepwalk:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | -| **i2i_content_name** | `output/i2i_content_name_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_name:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | -| **i2i_content_pic** | `output/i2i_content_pic_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_pic:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | -| **interest_hot** | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:hot:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | -| **interest_cart** | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:cart:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | -| **interest_new** | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:new:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | -| **interest_global** | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:global:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 7天 | - -## 📝 详细说明 - -### 1. i2i相似度索引 - -#### 源数据格式 -``` -12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 -``` - -#### Redis存储 - -**Key**: `item:similar:swing:12345` - -**Value** (JSON格式): -```json -[[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] -``` - -**Value** (序列化后): -```python -import json -value = json.dumps([[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]) -# 存储: "[[67890,0.8567],[11223,0.7234],[44556,0.6891]]" -``` - -#### 查询示例 -```python -import redis -import json - -r = redis.Redis(host='localhost', port=6379, db=0) - -# 获取商品12345的相似商品（Swing算法） -similar_items = json.loads(r.get('item:similar:swing:12345')) -# 返回: [[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] - -# 获取Top5相似商品 -top_5 = similar_items[:5] -``` - -### 2. 兴趣点聚合索引 - -#### 源数据格式 -``` -platform:pc 12345,67890,11223,44556,22334 -category_level2:200 67890,12345,22334,55667,11223 -``` - -#### Redis存储 - -**Key**: `interest:hot:platform:pc` - -**Value** (JSON格式): -```json -[12345, 67890, 11223, 44556, 22334] -``` - -**Value** (序列化后): -```python -import json -value = json.dumps([12345, 67890, 11223, 44556, 22334]) -# 存储: "[12345,67890,11223,44556,22334]" -``` - -#### 查询示例 -```python -import redis -import json - -r = redis.Redis(host='localhost', port=6379, db=0) - -# 获取PC平台的热门商品 -hot_items = json.loads(r.get('interest:hot:platform:pc')) -# 返回: [12345, 67890, 11223, 44556, 22334] - -# 获取Top10热门商品 -top_10 = hot_items[:10] -``` - -## 🔄 数据加载流程 - -### 1. 加载i2i索引 - -```python -def load_i2i_index(file_path, algorithm_name, redis_client, expire_seconds=604800): - """ - 加载i2i相似度索引到Redis - - Args: - file_path: 索引文件路径 - algorithm_name: 算法名称（swing, w2v, deepwalk, content） - redis_client: Redis客户端 - expire_seconds: 过期时间（秒），默认7天 - """ - import json - - count = 0 - with open(file_path, 'r', encoding='utf-8') as f: - for line in f: - parts = line.strip().split('\t') - if len(parts) < 3: - continue - - item_id = parts[0] - similar_str = parts[2] # similar_id1:score1,similar_id2:score2,... - - # 解析相似商品 - similar_items = [] - for pair in similar_str.split(','): - if ':' in pair: - sim_id, score = pair.split(':') - similar_items.append([int(sim_id), float(score)]) - - # 存储到Redis - redis_key = f"item:similar:{algorithm_name}:{item_id}" - redis_value = json.dumps(similar_items) - - redis_client.set(redis_key, redis_value) - redis_client.expire(redis_key, expire_seconds) - - count += 1 - - return count -``` - -### 2. 加载兴趣聚合索引 - -```python -def load_interest_index(file_path, list_type, redis_client, expire_seconds=259200): - """ - 加载兴趣点聚合索引到Redis - - Args: - file_path: 索引文件路径 - list_type: 列表类型（hot, cart, new, global） - redis_client: Redis客户端 - expire_seconds: 过期时间（秒），默认3天 - """ - import json - - count = 0 - with open(file_path, 'r', encoding='utf-8') as f: - for line in f: - parts = line.strip().split('\t') - if len(parts) != 2: - continue - - dimension_key = parts[0] # platform:pc - item_ids_str = parts[1] # 12345,67890,11223,... - - # 解析商品ID列表 - item_ids = [int(item_id) for item_id in item_ids_str.split(',')] - - # 存储到Redis - redis_key = f"interest:{list_type}:{dimension_key}" - redis_value = json.dumps(item_ids) - - redis_client.set(redis_key, redis_value) - redis_client.expire(redis_key, expire_seconds) - - count += 1 - - return count -``` - -## 🚀 快速加载命令 - -### 加载所有索引 -```bash -cd /home/tw/recommendation/offline_tasks - -# 加载所有索引（使用今天的数据） -python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 - -# 加载指定日期的索引 -python3 scripts/load_index_to_redis.py --date 20251016 --redis-host localhost - -# 只加载i2i索引 -python3 scripts/load_index_to_redis.py --load-i2i --redis-host localhost - -# 只加载兴趣聚合索引 -python3 scripts/load_index_to_redis.py --load-interest --redis-host localhost -``` - -### 验证数据 -```bash -# 连接Redis -redis-cli - -# 检查key数量 -DBSIZE - -# 查看某个商品的相似推荐 -GET item:similar:swing:12345 - -# 查看平台热门商品 -GET interest:hot:platform:pc - -# 查看所有i2i相关的key -KEYS item:similar:* - -# 查看所有interest相关的key -KEYS interest:* - -# 检查key的过期时间 -TTL item:similar:swing:12345 -``` - -## 📊 数据统计 - -### Redis内存占用估算 - -| 索引类型 | Key数量 | 单条Value大小 | 总内存 | -|---------|--------|-------------|--------| -| i2i_swing | 50,000 | ~500B | ~25MB | -| i2i_w2v | 50,000 | ~500B | ~25MB | -| i2i_deepwalk | 50,000 | ~500B | ~25MB | -| i2i_content_name | 50,000 | ~500B | ~25MB | -| i2i_content_pic | 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 | -| **总计** | **270,000** | - | **~160MB** | - -### 过期策略 - -| 索引类型 | TTL | 原因 | -|---------|-----|------| -| i2i行为相似 | 7天 | 用户行为变化快，需要频繁更新 | -| i2i内容相似 | 30天 | 商品属性变化慢，可以保留更久 | -| 热门/加购 | 3天 | 热度变化快，需要及时更新 | -| 新品 | 3天 | 新品概念有时效性 | -| 全局热门 | 7天 | 相对稳定，可以保留更久 | - -## ⚠️ 注意事项 - -1. **原子性**: 使用Pipeline批量写入，提高性能 -2. **过期时间**: 合理设置TTL，避免过期数据 -3. **内存管理**: 定期清理过期key，监控内存使用 -4. **数据版本**: 使用日期标记，支持数据回滚 -5. **容错处理**: 加载失败时不影响线上服务 -6. **监控告警**: 监控加载成功率、Redis内存、查询延迟 - -## 🔍 监控指标 - -### 数据质量指标 -```python -# 检查加载成功率 -total_keys = redis_client.dbsize() -expected_keys = 245000 -success_rate = total_keys / expected_keys * 100 - -# 检查数据完整性 -sample_keys = [ - 'item:similar:swing:12345', - 'interest:hot:platform:pc' -] -for key in sample_keys: - if not redis_client.exists(key): - print(f"Missing key: {key}") -``` - -### 性能指标 -- 加载耗时: < 5分钟 -- 内存占用: < 200MB -- 查询延迟: < 1ms -- 成功率: > 99% - -## 🔗 相关文档 - -- **离线索引规范**: `OFFLINE_INDEX_SPEC.md` -- **API接口文档**: `RECOMMENDATION_API.md` -- **运维手册**: `OPERATIONS.md` diff --git a/offline_tasks/RUN_SCRIPT_GUIDE.md b/offline_tasks/RUN_SCRIPT_GUIDE.md deleted file mode 100644 index 1f40004..0000000 --- a/offline_tasks/RUN_SCRIPT_GUIDE.md +++ /dev/null @@ -1,304 +0,0 @@ -# run.sh 运行脚本使用指南 - -## 概述 - -`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。 - -## 主要特性 - -### 1. 内存监控 -- **警告阈值**: 25GB - 打印警告日志 -- **强制终止阈值**: 30GB - 自动kill进程 -- **检查频率**: 每10秒检查一次 -- **日志文件**: `logs/memory_monitor.log` - -### 2. 任务流程 -1. 清理旧进程和输出 -2. 运行调试模式（小数据量测试） -3. 运行生产模式（大数据量） -4. 加载索引到Redis - -### 3. 错误处理 -- 任何步骤失败会立即退出 -- 显示详细的退出码 -- 保存完整日志 - -## 使用方法 - -### 基本运行 -```bash -cd /home/tw/recommendation/offline_tasks -./run.sh -``` - -### 查看实时输出 -```bash -./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log -``` - -### 后台运行 -```bash -nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 & -``` - -## 内存监控说明 - -### 监控逻辑 - -```bash -check_memory() { - local pid=$1 - local threshold_warn=25 # 25GB警告 - local threshold_kill=30 # 30GB强制kill - - while 进程运行中; do - 获取内存使用 - - if 内存 >= 30GB: - 打印错误日志 - 强制终止进程 - break - elif 内存 >= 25GB: - 打印警告日志 - - sleep 10秒 - done -} -``` - -### 日志格式 - -**警告日志**: -``` -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 -``` - -**强制终止日志**: -``` -[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 -``` - -### 查看监控日志 -```bash -# 实时查看 -tail -f logs/memory_monitor.log - -# 查看历史 -cat logs/memory_monitor.log -``` - -## 运行流程 - -### 步骤1: 调试模式 -```bash -python3 run_all.py --debug -``` -- 使用默认参数（见 `offline_config.py`） -- 输出保存到 `output_debug/` -- 启动内存监控 - -### 步骤2: 生产模式 -```bash -python3 run_all.py --debug -``` -- 生成完整索引 -- 输出保存到 `output/` -- 启动内存监控 - -### 步骤3: 加载Redis -```bash -python3 scripts/load_index_to_redis.py --redis-host localhost -``` -- 加载所有生成的索引 -- 包括新增的内容相似索引 - -## 输出示例 - -``` -====================================================================== -开始运行离线任务 - 2025-10-17 14:00:00 -内存监控: 警告阈值=25GB, 强制终止阈值=30GB -====================================================================== - ->>> 步骤1: 调试模式运行（小数据量） -调试任务 PID: 12345 -✓ 调试模式完成 - ->>> 步骤2: 生产模式运行（大数据量） -生产任务 PID: 12346 -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 -✓ 生产模式完成 - ->>> 步骤3: 加载到Redis -✓ Redis加载完成 - -====================================================================== -所有任务完成 - 2025-10-17 16:30:00 -====================================================================== -``` - -## 自定义配置 - -### 修改内存阈值 - -编辑 `run.sh` 中的以下行： -```bash -local threshold_warn=25 # 修改警告阈值 -local threshold_kill=30 # 修改强制kill阈值 -``` - -### 修改检查频率 - -编辑 `run.sh` 中的以下行： -```bash -sleep 10 # 修改为其他秒数 -``` - -### 跳过调试模式 - -注释掉步骤1相关代码： -```bash -# # 3. 调试模式运行（小数据量） -# echo "" -# echo ">>> 步骤1: 调试模式运行（小数据量）" -# python3 run_all.py --debug & -# ... -``` - -### 修改Redis配置 - -修改步骤3的参数： -```bash -python3 scripts/load_index_to_redis.py \ - --redis-host your-redis-host \ - --redis-port 6379 \ - --redis-db 0 -``` - -## 故障排查 - -### 内存持续超限 - -**原因**: -- 数据量太大 -- 内存泄漏 -- 并发任务过多 - -**解决方案**: -1. 增加内存阈值（临时方案） -2. 优化代码减少内存占用 -3. 分批处理数据 -4. 使用增量更新 - -### 进程被意外终止 - -**检查日志**: -```bash -# 查看监控日志 -cat logs/memory_monitor.log - -# 查看任务日志 -ls -lht logs/ -cat logs/run_all_*.log -``` - -### 任务失败 - -**查看退出码**: -- 0: 成功 -- 1: 一般错误 -- 137: 被kill信号终止（可能是内存超限） -- 其他: 查看具体错误信息 - -## 监控建议 - -### 1. 添加系统监控 -```bash -# 安装监控工具 -apt install htop iotop - -# 实时监控 -htop -p $(pgrep -f run_all.py) -``` - -### 2. 设置告警 -```bash -# 配置邮件告警 -if [ $PROD_EXIT_CODE -ne 0 ]; then - echo "任务失败" | mail -s "离线任务告警" admin@example.com -fi -``` - -### 3. 定时任务 -```bash -# 添加到crontab -0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 -``` - -## 性能优化 - -### 内存优化建议 - -1. **分批处理** - ```python - # 在代码中使用batch处理 - batch_size = 1000 - for i in range(0, len(items), batch_size): - batch = items[i:i+batch_size] - process(batch) - ``` - -2. **及时释放** - ```python - import gc - del large_object - gc.collect() - ``` - -3. **使用生成器** - ```python - def process_items(): - for item in items: - yield process(item) - ``` - -## 日志管理 - -### 日志文件 -- `logs/memory_monitor.log` - 内存监控日志 -- `logs/run_all_YYYYMMDD.log` - 任务运行日志 -- `output/` - 生成的索引文件 -- `output_debug/` - 调试模式输出 - -### 清理旧日志 -```bash -# 保留最近7天 -find logs/ -name "*.log" -mtime +7 -delete - -# 压缩旧日志 -find logs/ -name "*.log" -mtime +3 -exec gzip {} \; -``` - -## 安全注意事项 - -1. **权限**: 确保脚本有执行权限 `chmod +x run.sh` -2. **路径**: 使用绝对路径避免混淆 -3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀 -4. **备份**: 脚本会删除output目录，请提前备份重要数据 - -## 总结 - -`run.sh` 提供了： -- ✅ 自动化运行流程 -- ✅ 内存监控保护 -- ✅ 详细日志记录 -- ✅ 错误处理机制 -- ✅ 进度显示 - -建议在生产环境使用前先在测试环境验证。 - ---- - -**更新时间**: 2025-10-17 -**版本**: v2.0 - diff --git a/offline_tasks/START_HERE.md b/offline_tasks/START_HERE.md deleted file mode 100644 index 418a985..0000000 --- a/offline_tasks/START_HERE.md +++ /dev/null @@ -1,302 +0,0 @@ -# 🚀 从这里开始 - -## 📦 项目交付完成 - -根据您提供的业务文档和表结构，推荐系统离线任务已完成构建！ - ---- - -## ✅ 完成的功能 - -### 1. i2i 索引（4种算法） - -#### 行为相似（3种） -- ✅ **Swing算法** - 基于用户共同行为 -- ✅ **Session W2V** - 基于用户会话序列 -- ✅ **DeepWalk** - 基于图随机游走 - -#### 内容相似（1种，3个方法） -- ✅ **Content-based** - 基于商品属性（分类、供应商等） - - TF-IDF方法 - - 分类方法 - - 混合方法（推荐） - -### 2. 兴趣点聚合索引 - -**支持的维度**（7个单维度 + 4个组合维度）： -- ✅ 业务平台（platform） -- ✅ 客户端平台（client_platform） -- ✅ 供应商（supplier） -- ✅ 一级分类（category_level1） -- ✅ 二级分类（category_level2） -- ✅ 三级分类（category_level3） -- ✅ 四级分类（category_level4） -- ✅ 平台+客户端 -- ✅ 平台+分类 -- ✅ 客户端+分类 - -**支持的列表类型**（3种）： -- ✅ 热门（hot）- 最近180天高交互 -- ✅ 加购（cart）- 加购行为 -- ✅ 新品（new）- 最近90天上架 - ---- - -## 🎯 快速开始（3步） - -### 步骤1: 安装依赖 -```bash -cd /home/tw/recommendation/offline_tasks -bash install.sh -``` - -### 步骤2: 测试连接 -```bash -python3 test_connection.py -``` - -### 步骤3: 运行任务（小数据量测试） -```bash -# 先测试30天数据 -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 - -# 查看输出 -ls -lh output/ -head -5 output/i2i_swing_*.txt -``` - -### 步骤4: 运行完整任务 -```bash -# 运行所有任务（约6-10小时） -python3 run_all.py --lookback_days 730 --top_n 50 - -# 或分别运行（推荐） -python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50 -python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid -python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 -``` - ---- - -## 📚 文档导航 - -### 入门文档 -1. **START_HERE.md** ← 当前文档 -2. **QUICKSTART.md** - 5分钟快速上手 -3. **CURRENT_STATUS.md** - 当前功能状态 - -### 技术文档 -4. **FINAL_UPDATE.md** - 最终更新说明 -5. **COMPLETE_INDEX_LIST.md** - 完整索引清单 -6. **README.md** - 详细使用文档 -7. **PROJECT_SUMMARY.md** - 技术架构 - -### 配置文档 -8. **FIELD_MAPPING.md** - 字段映射说明 -9. **DATABASE_SETUP.md** - 数据库配置 -10. **TROUBLESHOOTING.md** - 故障排除 - -### 参考文档 -11. **STRUCTURE.md** - 目录结构 -12. **CHANGELOG.md** - 更新日志 -13. **COMMANDS.txt** - 常用命令 - ---- - -## 📊 输出示例 - -### i2i相似度索引 -``` -# 文件: output/i2i_swing_20251016.txt -12345 商品A 23456:0.8523,34567:0.7842,45678:0.7234,... - -# Redis Key: i2i:swing:12345 -Value: 23456:0.8523,34567:0.7842,45678:0.7234,... -``` - -### 兴趣点聚合索引 -``` -# 文件: output/interest_aggregation_hot_20251016.txt -platform:pc 12345:98.52,23456:87.34,34567:76.89,... -category_level2:200 45678:156.23,56789:142.87,... - -# Redis Key: interest:hot:platform:pc -Value: 12345:98.52,23456:87.34,34567:76.89,... -``` - ---- - -## 🎬 业务场景映射 - -根据您的3个业务场景： - -### 1. 首页猜你喜欢 -```python -# 使用兴趣点聚合索引 -interest:hot:platform:pc -interest:hot:category_level2:200 -interest:hot:platform_category2:pc_200 -``` - -### 2. 详情页的大家都在看 -```python -# 使用i2i相似索引 -i2i:swing:12345 # 行为相似 -i2i:content_hybrid:12345 # 内容相似 -``` - -### 3. 搜索结果页底部的供应商推荐 -```python -# 使用兴趣点聚合索引 -interest:global:category_level2:200 -interest:hot:supplier:10001 -``` - ---- - -## 🔢 关键数字 - -| 指标 | 数值 | -|------|------| -| i2i算法数量 | 4种（3行为+1内容） | -| 兴趣点维度数量 | 11个（7单+4组合） | -| 支持的分类层级 | 4级 | -| 列表类型 | 3种（热门/加购/新品） | -| 预计索引总数 | 10000-50000条 | -| 全部任务运行时间 | 6-10小时 | - ---- - -## 💡 核心优势 - -### 1. 完整性 -- ✅ 行为相似 + 内容相似 -- ✅ 短期热门 + 长期稳定 -- ✅ 粗粒度 + 细粒度 - -### 2. 灵活性 -- ✅ 支持4级分类查询 -- ✅ 支持供应商维度 -- ✅ 支持多维度组合 - -### 3. 可扩展性 -- ✅ 易于添加新维度 -- ✅ 易于添加新算法 -- ✅ 配置化管理 - -### 4. 实用性 -- ✅ 适配真实数据 -- ✅ 参考现有代码 -- ✅ 文档完善 - ---- - -## ⚙️ 配置文件 - -主要配置在 `config/offline_config.py`： - -```python -# 时间配置 -LOOKBACK_DAYS = 730 # 2年数据 - -# 行为权重 -behavior_weights = { - 'click': 1.0, - 'addToCart': 3.0, - 'contactFactory': 5.0, - 'purchase': 10.0 -} - -# 时间衰减 -time_decay_factor = 0.95 # 每30天衰减5% -``` - ---- - -## 🔧 运行选项 - -### 运行单个算法 -```bash -python3 run_all.py --only-swing # 只运行Swing -python3 run_all.py --only-content # 只运行内容相似 -python3 run_all.py --only-interest # 只运行兴趣点聚合 -``` - -### 跳过某些算法 -```bash -python3 run_all.py --skip-i2i # 跳过i2i -python3 run_all.py --skip-interest # 跳过兴趣点聚合 -``` - -### 调整参数 -```bash -# 小数据量测试 -python3 run_all.py --lookback_days 30 --top_n 10 - -# 完整数据 -python3 run_all.py --lookback_days 730 --top_n 50 -``` - ---- - -## 📞 遇到问题？ - -### 1. 字段错误 -查看：**FIELD_MAPPING.md** 和 **DATABASE_SETUP.md** - -### 2. 运行错误 -查看：**TROUBLESHOOTING.md** - -### 3. 使用疑问 -查看：**README.md** 和 **COMPLETE_INDEX_LIST.md** - -### 4. 查看日志 -```bash -tail -f logs/run_all_*.log -``` - ---- - -## 🎉 开始使用 - -```bash -# 1. 进入目录 -cd /home/tw/recommendation/offline_tasks - -# 2. 安装依赖 -bash install.sh - -# 3. 测试连接 -python3 test_connection.py - -# 4. 运行任务 -python3 run_all.py --lookback_days 730 --top_n 50 - -# 5. 查看输出 -ls -lh output/ -head -5 output/* - -# 6. 加载到Redis（可选） -python3 scripts/load_index_to_redis.py -``` - ---- - -## 📦 交付清单 - -- ✅ 4种i2i算法实现 -- ✅ 兴趣点聚合（11个维度） -- ✅ 统一调度脚本 -- ✅ Redis加载工具 -- ✅ 测试和示例脚本 -- ✅ 13份完整文档 -- ✅ 配置文件和依赖清单 - ---- - -**状态**: ✅ 已完成并可用 -**版本**: v1.1 -**日期**: 2025-10-16 -**代码行数**: ~2500行 - -**开始探索**: 建议先阅读 **QUICKSTART.md** diff --git a/offline_tasks/STRUCTURE.md b/offline_tasks/STRUCTURE.md deleted file mode 100644 index d904437..0000000 --- a/offline_tasks/STRUCTURE.md +++ /dev/null @@ -1,303 +0,0 @@ -# 项目目录结构 - -``` -/home/tw/recommendation/ -│ -├── db_service.py # 数据库连接服务（共享模块） -├── requirements.txt # Python依赖包列表 -│ -├── offline_tasks/ # 【离线任务主目录】 -│ │ -│ ├── config/ # 配置目录 -│ │ └── offline_config.py # 离线任务配置文件 -│ │ - 数据库配置 -│ │ - Redis配置 -│ │ - 算法参数配置 -│ │ - 时间配置 -│ │ -│ ├── scripts/ # 脚本目录 -│ │ ├── i2i_swing.py # Swing算法实现 -│ │ │ 输出: i2i_swing_YYYYMMDD.txt -│ │ │ -│ │ ├── i2i_session_w2v.py # Session Word2Vec算法 -│ │ │ 输出: i2i_session_w2v_YYYYMMDD.txt -│ │ │ session_w2v_model_YYYYMMDD.model -│ │ │ -│ │ ├── i2i_deepwalk.py # DeepWalk算法 -│ │ │ 输出: i2i_deepwalk_YYYYMMDD.txt -│ │ │ deepwalk_model_YYYYMMDD.model -│ │ │ item_graph_YYYYMMDD.txt -│ │ │ -│ │ ├── interest_aggregation.py # 兴趣点聚合索引生成 -│ │ │ 输出: interest_aggregation_hot_YYYYMMDD.txt -│ │ │ interest_aggregation_cart_YYYYMMDD.txt -│ │ │ interest_aggregation_new_YYYYMMDD.txt -│ │ │ interest_aggregation_global_YYYYMMDD.txt -│ │ │ -│ │ └── load_index_to_redis.py # 索引加载到Redis -│ │ -│ ├── output/ # 输出目录（自动创建） -│ │ ├── i2i_swing_*.txt # Swing算法输出 -│ │ ├── i2i_session_w2v_*.txt # Session W2V输出 -│ │ ├── i2i_deepwalk_*.txt # DeepWalk输出 -│ │ ├── interest_aggregation_* # 兴趣点聚合输出 -│ │ ├── *.model # 训练的模型文件 -│ │ └── item_graph_*.txt # 物品图结构 -│ │ -│ ├── logs/ # 日志目录（自动创建） -│ │ ├── run_all_*.log # 总调度日志 -│ │ ├── load_redis.log # Redis加载日志 -│ │ └── cron.log # 定时任务日志 -│ │ -│ ├── run_all.py # 【主调度脚本】 -│ │ 统一运行所有离线任务 -│ │ -│ ├── install.sh # 安装脚本 -│ │ 自动安装依赖和初始化 -│ │ -│ ├── test_connection.py # 连接测试脚本 -│ │ 测试数据库和Redis连接 -│ │ -│ ├── example_query_redis.py # Redis查询示例 -│ │ 演示如何查询索引 -│ │ -│ ├── README.md # 详细文档 -│ ├── QUICKSTART.md # 快速开始指南 -│ ├── PROJECT_SUMMARY.md # 项目总结 -│ └── STRUCTURE.md # 本文档 -│ -├── item_sim.py # 原有的物品相似度脚本（参考） -├── hot/ # 原有的热门商品模块（参考） -├── collaboration/ # 原有的协同过滤模块（参考） -└── graphembedding/ # 原有的图嵌入模块（参考） -``` - -## 数据流向图 - -``` -┌─────────────────┐ -│ 数据源 │ -│ (SelectDB) │ -└────────┬────────┘ - │ - │ SQL查询 - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ 离线任务处理 │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Swing算法 │ │ Session W2V │ │ DeepWalk算法 │ │ -│ │ │ │ │ │ │ │ -│ │ 用户行为共现 │ │ 会话序列 │ │ 图随机游走 │ │ -│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ -│ │ │ │ │ -│ └─────────────────┴─────────────────┘ │ -│ │ │ -│ │ i2i相似度索引 │ -│ ▼ │ -│ ┌─────────────────┐ │ -│ │ 输出文件(.txt) │ │ -│ └─────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ 兴趣点聚合 │ │ -│ │ │ │ -│ │ 按维度分组: 平台/国家/客户类型/分类 │ │ -│ │ 按类型分组: 热门/加购/新品/全局 │ │ -│ │ 时间衰减 + 行为权重 │ │ -│ └────────────────────┬─────────────────────────────┘ │ -│ │ │ -│ │ 多维度索引 │ -│ ▼ │ -│ ┌─────────────────┐ │ -│ │ 输出文件(.txt) │ │ -│ └─────────────────┘ │ -└─────────────────────────────────────────────────────────┘ - │ - │ 加载 - ▼ - ┌─────────────────┐ - │ Redis │ - │ (在线索引) │ - └────────┬────────┘ - │ - │ 查询 - ▼ - ┌─────────────────┐ - │ 在线推荐服务 │ - │ │ - │ - 详情页推荐 │ - │ - 首页推荐 │ - │ - 搜索推荐 │ - └──────────────────┘ -``` - -## 核心模块说明 - -### 1. 配置模块 -**文件**: `config/offline_config.py` - -**职责**: -- 数据库连接配置 -- Redis连接配置 -- 算法超参数配置 -- 行为权重配置 -- 时间范围配置 - -### 2. i2i相似度模块 - -#### 2.1 Swing算法 -**文件**: `scripts/i2i_swing.py` - -**输入**: 用户行为数据（user_id, item_id, event_type, create_time） - -**核心逻辑**: -```python -# 对于物品i和j，计算它们的Swing相似度 -for user_u in common_users: - for user_v in common_users: - common_items = items_u ∩ items_v - sim(i, j) += 1 / (alpha + |common_items|) -``` - -**输出**: `i2i_swing_YYYYMMDD.txt` -``` -item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,... -``` - -#### 2.2 Session Word2Vec -**文件**: `scripts/i2i_session_w2v.py` - -**输入**: 用户会话序列 - -**核心逻辑**: -1. 按时间间隔切分用户会话 -2. 训练Word2Vec模型 -3. 计算物品向量相似度 - -**输出**: -- `i2i_session_w2v_YYYYMMDD.txt` -- `session_w2v_model_YYYYMMDD.model` - -#### 2.3 DeepWalk -**文件**: `scripts/i2i_deepwalk.py` - -**输入**: 用户-物品交互数据 - -**核心逻辑**: -1. 构建物品共现图 -2. 执行随机游走生成序列 -3. 训练Word2Vec模型 -4. 计算物品向量相似度 - -**输出**: -- `i2i_deepwalk_YYYYMMDD.txt` -- `deepwalk_model_YYYYMMDD.model` -- `item_graph_YYYYMMDD.txt` - -### 3. 兴趣点聚合模块 -**文件**: `scripts/interest_aggregation.py` - -**输入**: 用户行为数据 + 用户特征 - -**核心逻辑**: -```python -# 按维度聚合 -for each behavior: - weight = behavior_weight * time_weight - aggregations[dimension_key][item_id] += weight - -# 排序并输出top N -for dimension_key, items in aggregations: - output top_n items sorted by weight -``` - -**维度组合**: -- 单维度: platform, country, customer_type, category_level2, category_level3 -- 组合维度: platform_country, platform_customer, country_customer, platform_country_customer - -**列表类型**: -- hot: 最近180天高交互 -- cart: 加购行为 -- new: 新品（最近90天上架） -- global: 全局（所有数据） - -**输出**: -- `interest_aggregation_hot_YYYYMMDD.txt` -- `interest_aggregation_cart_YYYYMMDD.txt` -- `interest_aggregation_new_YYYYMMDD.txt` -- `interest_aggregation_global_YYYYMMDD.txt` - -### 4. Redis加载模块 -**文件**: `scripts/load_index_to_redis.py` - -**职责**: 将生成的索引文件加载到Redis - -**Redis Key格式**: -- i2i索引: `i2i:{algorithm}:{item_id}` -- 兴趣点索引: `interest:{list_type}:{dimension_key}` - -**示例**: -``` -i2i:swing:123456 -> "234567:0.8523,345678:0.7842,..." -interest:hot:platform:PC -> "12345:98.52,23456:87.34,..." -``` - -### 5. 统一调度模块 -**文件**: `run_all.py` - -**职责**: 按顺序运行所有离线任务 - -**执行流程**: -1. 运行Swing算法 -2. 运行Session W2V -3. 运行DeepWalk -4. 运行兴趣点聚合 -5. 记录日志和统计 - -## 使用场景映射 - -| 业务场景 | 使用的索引 | Redis Key示例 | -|---------|-----------|--------------| -| 详情页 - 大家都在看 | i2i相似度 | `i2i:swing:{item_id}` | -| 首页 - 猜你喜欢 | 兴趣点聚合 | `interest:hot:platform_country:{platform}_{country}` | -| 搜索 - 相关推荐 | 兴趣点聚合 + i2i | `interest:global:category_level2:{cat_id}` | -| 购物车 - 可能喜欢 | 兴趣点聚合(cart) | `interest:cart:customer_type:{type}` | -| 新品推荐 | 兴趣点聚合(new) | `interest:new:platform:{platform}` | - -## 配置调优参数 - -### 时间相关 -- `LOOKBACK_DAYS`: 730 (2年) -- `RECENT_DAYS`: 180 (热门商品统计) -- `NEW_DAYS`: 90 (新品定义) -- `decay_factor`: 0.95 (时间衰减) - -### 算法相关 -- Swing `alpha`: 0.5 -- W2V `vector_size`: 128 -- W2V `window_size`: 5 -- DeepWalk `num_walks`: 10 -- DeepWalk `walk_length`: 40 - -### 输出相关 -- i2i `top_n`: 50 -- 兴趣点 `top_n`: 1000 - -## 性能优化要点 - -1. **Swing算法**: 使用C++版本可提升10倍性能 -2. **并行化**: 将不同算法分配到不同机器 -3. **增量更新**: 只更新变化的部分 -4. **数据采样**: 调试时使用采样数据 -5. **批量加载**: Redis使用pipeline批量加载 - -## 监控指标 - -- 任务执行时间 -- 生成索引数量 -- Redis内存占用 -- 推荐点击率 -- 推荐转化率 - diff --git a/offline_tasks/SWING_USAGE.md b/offline_tasks/SWING_USAGE.md deleted file mode 100644 index 3a6fdc9..0000000 --- a/offline_tasks/SWING_USAGE.md +++ /dev/null @@ -1,322 +0,0 @@ -# Swing算法使用指南 - -本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。 - -## 目录结构 - -``` -recommendation/ -├── offline_tasks/ -│ ├── scripts/ -│ │ ├── generate_session.py # 生成用户session文件 -│ │ └── add_names_to_swing.py # 给结果添加商品名称 -│ └── output/ -│ └── session.txt.YYYYMMDD # 生成的session文件 -└── collaboration/ - ├── run.sh # Swing算法执行脚本 - ├── src/ - │ ├── swing.cc # Swing算法实现 - │ └── ucf.py # 用户协同过滤 - └── output_YYYYMMDD/ - ├── swing_similar.txt # Swing结果（ID格式） - └── swing_similar_readable.txt # Swing结果（带商品名） -``` - -## 使用流程 - -### 步骤1: 生成Session文件 - -首先需要从数据库提取用户行为数据，生成session文件。 - -```bash -cd /home/tw/recommendation/offline_tasks - -# 基本用法（使用默认参数：730天数据） -python3 scripts/generate_session.py - -# 指定回看天数 -python3 scripts/generate_session.py --lookback_days 365 - -# 启用debug模式查看详细信息 -python3 scripts/generate_session.py --lookback_days 730 --debug - -# 指定输出文件路径 -python3 scripts/generate_session.py --output output/session.txt.20241017 - -# 选择输出格式 -python3 scripts/generate_session.py --format both # 同时生成两种格式（默认） -python3 scripts/generate_session.py --format standard # uid \t json 格式 -python3 scripts/generate_session.py --format cpp # 纯json格式（.cpp后缀） -``` - -**输出文件格式：** - -- `session.txt.YYYYMMDD` - 标准格式（包含uid）： - ``` - uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} - uid2 \t {"item_id4":15.0,"item_id5":8.0} - ``` - -- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）： - ``` - {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} - {"item_id4":15.0,"item_id5":8.0} - ``` - -**行为权重配置：** -- `purchase`: 10.0（购买） -- `contactFactory`: 5.0（联系厂家） -- `addToCart`: 3.0（加入购物车） -- `addToPool`: 2.0（加入询价池） - -### 步骤2: 运行Swing算法 - -session文件生成后，运行C++版本的Swing算法。 - -```bash -cd /home/tw/recommendation/collaboration - -# 直接运行（使用默认配置） -bash run.sh - -# 或者给脚本添加执行权限后运行 -chmod +x run.sh -./run.sh -``` - -**配置说明（修改run.sh中的参数）：** - -```bash -# 数据路径配置 -SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 - -# Swing算法参数 -ALPHA=0.7 # Swing算法的alpha参数（越小越关注用户共同行为） -THRESHOLD1=1 # 交互强度阈值1（用于筛选用户行为） -THRESHOLD2=3 # 交互强度阈值2（用于计算相似度） -THREAD_NUM=4 # 线程数（根据CPU核心数调整） -SHOW_PROGRESS=1 # 是否显示进度 (0/1) - -# Python环境 -PYTHON_CMD="python3" # 如需使用特定Python环境，修改此处 -``` - -**脚本执行流程：** - -1. 编译C++程序（swing, icf_simple, swing_symmetric） -2. 查找当天日期的session文件 -3. 运行Swing算法计算物品相似度 -4. 合并多线程输出结果 -5. 自动调用debug脚本生成可读版本 - -### 步骤3: 查看结果 - -运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录： - -**1. swing_similar.txt** - 原始结果（ID格式） -``` -12345 \t 67890:0.8523,23456:0.7234,34567:0.6891 -``` -格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...` - -**2. swing_similar_readable.txt** - 可读结果（带商品名） -``` -12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 -``` -格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...` - -### 步骤4: 单独生成Debug文件（可选） - -如果需要为其他文件生成可读版本： - -```bash -cd /home/tw/recommendation/offline_tasks - -# 基本用法 -python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt - -# 指定输出文件 -python3 scripts/add_names_to_swing.py \ - collaboration/output/swing_similar.txt \ - collaboration/output/my_readable.txt - -# 启用debug模式 -python3 scripts/add_names_to_swing.py \ - collaboration/output/swing_similar.txt \ - --debug -``` - -## 参数调优建议 - -### Swing算法参数 - -1. **alpha (0.5-1.0)** - - 越小：越关注用户共同行为的多样性 - - 越大：越容忽略用户重叠度 - - 建议：0.5-0.7（B2B场景） - -2. **threshold1 (1-5)** - - 用于筛选用户的有效行为 - - 建议：1-3（低频场景可用1） - -3. **threshold2 (1-10)** - - 用于计算相似度的行为强度阈值 - - 建议：3-5（需要较强的交互信号） - -4. **thread_num (1-20)** - - 根据CPU核心数设置 - - 建议：4-8（普通服务器） - -### 数据范围参数 - -1. **lookback_days** - - B2B低频场景：建议730天（2年） - - B2C高频场景：建议30-90天 - - 数据量大时可适当减少 - -## 完整示例 - -```bash -# 1. 生成session文件（730天数据） -cd /home/tw/recommendation/offline_tasks -python3 scripts/generate_session.py --lookback_days 730 --debug - -# 2. 检查生成的文件 -ls -lh output/session.txt.* -# 应该看到： -# session.txt.20241017 -# session.txt.20241017.cpp - -# 3. 运行Swing算法 -cd /home/tw/recommendation/collaboration -bash run.sh - -# 4. 查看结果 -ls -lh output/swing_similar* -cat output/swing_similar_readable.txt | head -20 -``` - -## 故障排查 - -### 问题1: Session文件不存在 - -``` -错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp -``` - -**解决方法：** -```bash -cd /home/tw/recommendation/offline_tasks -python3 scripts/generate_session.py -``` - -### 问题2: 编译失败 - -``` -编译失败，退出 -``` - -**解决方法：** -```bash -cd /home/tw/recommendation/collaboration -# 检查编译器 -g++ --version - -# 手动编译 -make clean -make - -# 检查依赖 -ls include/ -ls utils/ -``` - -### 问题3: 数据库连接失败 - -``` -获取数据失败: Connection refused -``` - -**解决方法：** -- 检查数据库配置：`offline_tasks/config/offline_config.py` -- 测试连接：`python3 offline_tasks/test_connection.py` -- 确认网络和防火墙设置 - -### 问题4: 结果为空 - -**可能原因：** -- threshold1/threshold2设置过高，过滤掉了所有数据 -- 数据量太少，用户和商品交集不足 - -**解决方法：** -- 降低threshold参数（如threshold1=0.5, threshold2=1） -- 增加lookback_days -- 检查数据量：`wc -l output/session.txt.*` - -## 性能优化 - -### 大数据量场景 - -如果数据量很大（>100万用户，>10万商品）： - -1. **增加线程数** - ```bash - THREAD_NUM=8 # 或更多 - ``` - -2. **分批处理** - - 可以将session文件按用户分片 - - 分别运行Swing算法 - - 最后合并结果 - -3. **调整max_session_list_len** - - 修改 `src/swing.cc` 中的 `max_session_list_len` - - 限制每个用户的最大行为数 - -### 内存优化 - -如果遇到内存不足： - -1. 减少 `max_sim_list_len`（默认300） -2. 减少 `max_session_list_len`（默认100） -3. 分批处理数据 - -## 集成到定时任务 - -```bash -# 添加到crontab -crontab -e - -# 每天凌晨2点运行 -0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/generate_session.py && cd ../collaboration && bash run.sh >> logs/swing_$(date +\%Y\%m\%d).log 2>&1 -``` - -## 相关文档 - -- [Swing算法原理](./collaboration/README.md) -- [离线任务配置](./offline_tasks/config/offline_config.py) -- [Debug工具使用](./offline_tasks/scripts/debug_utils.py) - -## 常见问题 - -**Q: session文件格式选择哪个？** -A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。 - -**Q: Swing算法运行多久？** -A: 取决于数据量和线程数。通常： -- 1万商品：1-5分钟 -- 10万商品：10-30分钟 -- 数据量大时建议使用多线程 - -**Q: 如何调整相似商品数量？** -A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。 - -**Q: 能否使用Python版本的Swing？** -A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。 - -## 联系支持 - -如有问题，请参考： -- 项目README: `/home/tw/recommendation/README.md` -- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md` - diff --git a/offline_tasks/TROUBLESHOOTING.md b/offline_tasks/TROUBLESHOOTING.md deleted file mode 100644 index bbf4f6f..0000000 --- a/offline_tasks/TROUBLESHOOTING.md +++ /dev/null @@ -1,217 +0,0 @@ -# 故障排除指南 - -## 常见问题及解决方案 - -### 1. 数据库字段错误 - -#### 问题： -``` -pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'") -``` - -#### 原因： -数据库表结构与代码中使用的字段名不匹配。 - -#### 解决方案： -1. 查看 `DATABASE_SETUP.md` 了解如何配置字段 -2. 修改对应脚本中的SQL查询，使用实际存在的字段名 -3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过 - -#### 已修复的字段： -- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的 -- ✅ 基础功能不依赖分类字段 - ---- - -### 2. 连接超时 - -#### 问题： -``` -pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...") -``` - -#### 解决方案： -1. 检查数据库配置：`config/offline_config.py` -2. 确认网络连接和防火墙设置 -3. 运行测试：`python3 test_connection.py` - ---- - -### 3. 内存不足 - -#### 问题： -程序运行时内存占用过高或被杀死。 - -#### 解决方案： -1. 减少回溯天数：`--lookback_days 365`（从730改为365） -2. 减少输出数量：`--top_n 20`（从50改为20） -3. 先运行单个算法： - ```bash - python3 scripts/i2i_session_w2v.py # 内存占用较小 - ``` -4. 跳过Swing算法（内存占用最大）： - ```bash - python3 run_all.py --skip-i2i - ``` - ---- - -### 4. 运行时间过长 - -#### 解决方案： -1. 减少数据量：`--lookback_days 180` -2. 只运行特定算法： - ```bash - python3 run_all.py --only-w2v - ``` -3. 考虑使用C++版本的Swing（性能提升10倍） - ---- - -### 5. 依赖包安装失败 - -#### 解决方案： -```bash -# 单独安装失败的包 -pip3 install pandas sqlalchemy pymysql gensim numpy - -# 或使用国内镜像 -pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple -``` - ---- - -### 6. Redis连接失败 - -#### 问题： -``` -redis.exceptions.ConnectionError: Error connecting to Redis -``` - -#### 解决方案： -1. Redis是可选的，只影响索引加载功能 -2. 如果不需要Redis，可以跳过： - ```bash - python3 run_all.py # 只运行离线任务，不加载到Redis - ``` -3. 如果需要Redis，确认Redis已安装并运行： - ```bash - redis-cli ping # 应该返回 PONG - ``` - ---- - -### 7. 输出文件为空 - -#### 可能原因： -1. 数据量太少（没有满足最小阈值） -2. 时间范围内没有数据 -3. SQL查询条件过于严格 - -#### 解决方案： -1. 检查日志：`tail -f logs/run_all_*.log` -2. 调整参数： - - 增加时间范围：`--lookback_days 1000` - - 减少阈值：修改配置文件中的 `min_interaction_count` -3. 检查数据库中是否有数据： - ```python - # 运行简单查询测试 - python3 test_connection.py - ``` - ---- - -### 8. 权限问题 - -#### 问题： -``` -PermissionError: [Errno 13] Permission denied -``` - -#### 解决方案： -```bash -# 给脚本添加执行权限 -chmod +x install.sh run_all.py - -# 确保有写入权限 -chmod 755 output/ logs/ -``` - ---- - -### 9. Python版本问题 - -#### 要求： -Python 3.7+ - -#### 检查版本： -```bash -python3 --version -``` - -#### 如果版本过低，需要升级Python - ---- - -### 10. 编码问题 - -#### 问题： -``` -UnicodeDecodeError: 'utf-8' codec can't decode byte... -``` - -#### 解决方案： -确保所有文件使用UTF-8编码，特别是配置文件和输出文件。 - ---- - -## 调试技巧 - -### 1. 查看详细日志 -```bash -tail -f logs/run_all_*.log -``` - -### 2. 运行单个任务（便于调试） -```bash -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 -``` - -### 3. 使用较小的数据量测试 -```bash -python3 run_all.py --lookback_days 30 --top_n 10 -``` - -### 4. 检查中间结果 -```bash -ls -lh output/ -head -n 20 output/i2i_swing_*.txt -``` - ---- - -## 获取支持 - -如果以上方法都无法解决问题： - -1. **查看文档**： - - `README.md` - 详细说明 - - `DATABASE_SETUP.md` - 数据库配置 - - `QUICKSTART.md` - 快速开始 - -2. **查看日志**： - - `logs/` 目录下的所有日志文件 - -3. **简化测试**： - - 先运行 `test_connection.py` - - 再运行单个脚本 - - 使用小数据量测试 - -4. **记录错误信息**： - - 完整的错误堆栈 - - 使用的命令 - - 配置文件内容 - ---- - -**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。 diff --git a/offline_tasks/UPDATE_CONFIG_GUIDE.md b/offline_tasks/UPDATE_CONFIG_GUIDE.md deleted file mode 100644 index 5582361..0000000 --- a/offline_tasks/UPDATE_CONFIG_GUIDE.md +++ /dev/null @@ -1,205 +0,0 @@ -# 配置参数调整指南 - -## 📝 概述 - -所有默认参数现在都集中在配置文件中，便于统一管理和调整。 - -## 🎯 主要默认参数 - -### 在 `config/offline_config.py` 中配置： - -```python -# 时间配置 -DEFAULT_LOOKBACK_DAYS = 30 # 默认回看天数 -DEFAULT_RECENT_DAYS = 7 # 默认最近天数 - -# i2i算法参数 -DEFAULT_I2I_TOP_N = 50 # 默认返回Top N个相似商品 - -# 兴趣聚合参数 -DEFAULT_INTEREST_TOP_N = 1000 # 默认每个key返回Top N个商品 -``` - -## 🔧 调试与生产切换 - -### 调试阶段（当前配置） - -```python -DEFAULT_LOOKBACK_DAYS = 30 # 30天数据，快速验证 -DEFAULT_RECENT_DAYS = 7 # 7天最近数据 -DEFAULT_I2I_TOP_N = 50 # Top 50 -DEFAULT_INTEREST_TOP_N = 1000 # Top 1000 -``` - -**预估运行时间**：30-60分钟 -**内存占用**：2-4GB - -### 生产环境配置 - -```python -DEFAULT_LOOKBACK_DAYS = 730 # 2年历史数据，更准确 -DEFAULT_RECENT_DAYS = 180 # 半年最近数据 -DEFAULT_I2I_TOP_N = 50 # Top 50 -DEFAULT_INTEREST_TOP_N = 1000 # Top 1000 -``` - -**预估运行时间**：6-10小时 -**内存占用**：8-16GB - -## 🚀 使用方式 - -### 1. 使用默认配置运行 - -```bash -# 使用配置文件中的默认值（当前为30天） -python3 run_all.py -``` - -### 2. 临时覆盖默认值 - -```bash -# 临时使用不同的参数，不修改配置文件 -python3 run_all.py --lookback_days 7 --top_n 20 -``` - -### 3. 修改配置文件（推荐） - -编辑 `config/offline_config.py`： - -```python -# 调试完成后，改为生产配置 -DEFAULT_LOOKBACK_DAYS = 730 -DEFAULT_RECENT_DAYS = 180 -``` - -然后运行： - -```bash -python3 run_all.py -``` - -## 📊 各脚本的默认参数 - -所有脚本都会从配置文件读取默认值： - -| 脚本 | 参数 | 默认值 | 来源 | -|------|------|--------|------| -| `i2i_swing.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` | -| `i2i_swing.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` | -| `i2i_session_w2v.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` | -| `i2i_session_w2v.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` | -| `i2i_deepwalk.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` | -| `i2i_deepwalk.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` | -| `i2i_content_similar.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` | -| `interest_aggregation.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` | -| `interest_aggregation.py` | `--top_n` | 1000 | `DEFAULT_INTEREST_TOP_N` | - -## 💡 调试建议 - -### 第一次运行（验证流程） - -```bash -# 使用最小数据量快速验证 -python3 run_all.py --lookback_days 7 --top_n 10 -``` - -### 第二次运行（调试参数） - -```python -# 修改配置文件为30天 -DEFAULT_LOOKBACK_DAYS = 30 -``` - -```bash -python3 run_all.py -``` - -### 第三次运行（生产环境） - -```python -# 修改配置文件为730天 -DEFAULT_LOOKBACK_DAYS = 730 -DEFAULT_RECENT_DAYS = 180 -``` - -```bash -python3 run_all.py -``` - -## 🔍 其他可调整的配置 - -### i2i算法详细配置 - -在 `offline_config.py` 的 `I2I_CONFIG` 中： - -```python -I2I_CONFIG = { - 'swing': { - 'alpha': 0.5, # swing算法的alpha参数 - 'threshold1': 0.5, # 交互强度阈值1 - 'threshold2': 0.5, # 交互强度阈值2 - 'max_sim_list_len': 300, # 最大相似列表长度 - 'top_n': 50, # 输出top N个相似商品 - }, - # ...其他算法配置 -} -``` - -### 兴趣聚合详细配置 - -```python -INTEREST_AGGREGATION_CONFIG = { - 'top_n': 1000, # 每个key生成前N个商品 - 'time_decay_factor': 0.95, # 时间衰减因子（每30天） - 'min_interaction_count': 2, # 最小交互次数 - - 'behavior_weights': { - 'click': 1.0, - 'addToCart': 3.0, - 'addToPool': 2.0, - 'contactFactory': 5.0, - 'purchase': 10.0, - }, -} -``` - -## 📌 注意事项 - -1. **调试优先**：先用小数据量（7-30天）验证流程 -2. **逐步扩大**：确认无误后再增加到生产数据量 -3. **监控资源**：注意内存和磁盘空间使用情况 -4. **保存配置**：在配置文件中注释记录不同场景的参数值 - -## 🎯 快速切换环境 - -创建不同的配置副本： - -```bash -# 备份当前配置 -cp config/offline_config.py config/offline_config_debug.py -cp config/offline_config.py config/offline_config_prod.py - -# 使用不同配置 -cp config/offline_config_debug.py config/offline_config.py # 调试模式 -cp config/offline_config_prod.py config/offline_config.py # 生产模式 -``` - -## ✅ 验证配置 - -查看当前默认值： - -```bash -python3 -c "from config.offline_config import *; print(f'LOOKBACK_DAYS: {DEFAULT_LOOKBACK_DAYS}')" -``` - -查看帮助信息： - -```bash -python3 run_all.py --help -``` - ---- - -**配置文件位置**: `config/offline_config.py` -**当前默认配置**: 30天调试模式 -**建议**: 调试通过后修改为730天生产模式 diff --git a/offline_tasks/config/offline_config.py b/offline_tasks/config/offline_config.py index 50c4d30..38621fa 100644 --- a/offline_tasks/config/offline_config.py +++ b/offline_tasks/config/offline_config.py @@ -28,7 +28,7 @@ os.makedirs(LOG_DIR, exist_ok=True) # ============================================================================ # 时间配置（建议先用小数值调试，确认无误后再改为大数值） -DEFAULT_LOOKBACK_DAYS = 730 # 默认回看天数（调试用30天，生产可改为730天） +DEFAULT_LOOKBACK_DAYS = 400 # 默认回看天数（调试用30天，生产可改为730天） DEFAULT_RECENT_DAYS = 180 # 默认最近天数（调试用7天，生产可改为180天） # i2i算法默认参数 diff --git a/offline_tasks/doc/COMPLETE_INDEX_LIST.md b/offline_tasks/doc/COMPLETE_INDEX_LIST.md new file mode 100644 index 0000000..99e19c7 --- /dev/null +++ b/offline_tasks/doc/COMPLETE_INDEX_LIST.md @@ -0,0 +1,350 @@ +# 完整索引清单 + +## 📋 所有可用的推荐索引 + +### 1. i2i 相似度索引 + +#### 1.1 行为相似索引（3种） + +**Swing算法**： +``` +i2i:swing:{item_id} +``` +示例：`i2i:swing:12345` + +**Session Word2Vec**： +``` +i2i:session_w2v:{item_id} +``` +示例：`i2i:session_w2v:12345` + +**DeepWalk**： +``` +i2i:deepwalk:{item_id} +``` +示例：`i2i:deepwalk:12345` + +#### 1.2 内容相似索引（3种方法） + +**混合方法（推荐）**： +``` +i2i:content_hybrid:{item_id} +``` +示例：`i2i:content_hybrid:12345` + +**TF-IDF方法**： +``` +i2i:content_tfidf:{item_id} +``` +示例：`i2i:content_tfidf:12345` + +**分类方法**： +``` +i2i:content_category:{item_id} +``` +示例：`i2i:content_category:12345` + +--- + +### 2. 兴趣点聚合索引 + +格式：`interest:{list_type}:{dimension}:{value}` + +#### 2.1 列表类型（list_type） + +- `hot` - 热门商品 +- `cart` - 加购商品 +- `new` - 新品 +- `global` - 全局（所有数据） + +#### 2.2 单维度索引 + +##### 业务平台（platform） +``` +interest:hot:platform:pc +interest:hot:platform:mobile +interest:cart:platform:pc +interest:new:platform:mobile +interest:global:platform:pc +``` + +##### 客户端平台（client_platform） +``` +interest:hot:client_platform:web +interest:hot:client_platform:app +interest:cart:client_platform:web +interest:new:client_platform:app +interest:global:client_platform:web +``` + +##### 供应商（supplier） +``` +interest:hot:supplier:10001 +interest:hot:supplier:10002 +interest:cart:supplier:10001 +interest:new:supplier:10002 +interest:global:supplier:10001 +``` + +##### 一级分类（category_level1） +``` +interest:hot:category_level1:100 +interest:cart:category_level1:100 +interest:new:category_level1:100 +interest:global:category_level1:100 +``` + +##### 二级分类（category_level2） +``` +interest:hot:category_level2:200 +interest:cart:category_level2:200 +interest:new:category_level2:200 +interest:global:category_level2:200 +``` + +##### 三级分类（category_level3） +``` +interest:hot:category_level3:300 +interest:cart:category_level3:300 +interest:new:category_level3:300 +interest:global:category_level3:300 +``` + +##### 四级分类（category_level4） +``` +interest:hot:category_level4:400 +interest:cart:category_level4:400 +interest:new:category_level4:400 +interest:global:category_level4:400 +``` + +#### 2.3 组合维度索引 + +##### 平台 + 客户端 +``` +interest:hot:platform_client:pc_web +interest:hot:platform_client:pc_app +interest:hot:platform_client:mobile_web +interest:hot:platform_client:mobile_app +``` + +##### 平台 + 二级分类 +``` +interest:hot:platform_category2:pc_200 +interest:hot:platform_category2:mobile_200 +interest:cart:platform_category2:pc_200 +interest:new:platform_category2:mobile_200 +``` + +##### 平台 + 三级分类 +``` +interest:hot:platform_category3:pc_300 +interest:hot:platform_category3:mobile_300 +interest:cart:platform_category3:pc_300 +interest:new:platform_category3:mobile_300 +``` + +##### 客户端平台 + 二级分类 +``` +interest:hot:client_category2:web_200 +interest:hot:client_category2:app_200 +interest:cart:client_category2:web_200 +interest:new:client_category2:app_200 +``` + +--- + +## 🎯 按业务场景的索引使用 + +### 场景1: 首页个性化推荐 + +**方案A: 基于平台** +```python +key = f"interest:hot:platform:{user_platform}" +# 示例：interest:hot:platform:pc +``` + +**方案B: 基于分类偏好** +```python +key = f"interest:hot:category_level2:{user_favorite_category}" +# 示例：interest:hot:category_level2:200 +``` + +**方案C: 基于平台+分类** +```python +key = f"interest:hot:platform_category2:{user_platform}_{category_id}" +# 示例：interest:hot:platform_category2:pc_200 +``` + +### 场景2: 详情页相关推荐 + +**方案A: 行为相似** +```python +key = f"i2i:swing:{current_item_id}" +# 示例：i2i:swing:12345 +``` + +**方案B: 内容相似** +```python +key = f"i2i:content_hybrid:{current_item_id}" +# 示例：i2i:content_hybrid:12345 +``` + +**方案C: 融合推荐** +```python +behavior_similar = redis.get(f"i2i:swing:{item_id}") +content_similar = redis.get(f"i2i:content_hybrid:{item_id}") +# 融合两种结果 +``` + +### 场景3: 分类页推荐 + +**方案A: 该分类热门** +```python +key = f"interest:hot:category_level2:{category_id}" +# 示例：interest:hot:category_level2:200 +``` + +**方案B: 该分类新品** +```python +key = f"interest:new:category_level2:{category_id}" +# 示例：interest:new:category_level2:200 +``` + +**方案C: 该分类+平台** +```python +key = f"interest:hot:platform_category2:{platform}_{category_id}" +# 示例：interest:hot:platform_category2:pc_200 +``` + +### 场景4: 供应商店铺页 + +**方案A: 供应商热门商品** +```python +key = f"interest:hot:supplier:{supplier_id}" +# 示例：interest:hot:supplier:10001 +``` + +**方案B: 供应商新品** +```python +key = f"interest:new:supplier:{supplier_id}" +# 示例：interest:new:supplier:10001 +``` + +### 场景5: 搜索结果页推荐 + +**方案A: 全局热门** +```python +key = "interest:global:platform:pc" +``` + +**方案B: 分类相关** +```python +key = f"interest:global:category_level2:{search_category}" +# 示例：interest:global:category_level2:200 +``` + +--- + +## 📊 索引数量统计 + +### i2i索引 +- 行为相似：3种算法 × 商品数量 +- 内容相似：3种方法 × 商品数量 +- **总计**：6 × 商品数量 + +### 兴趣点聚合索引 + +**单维度**： +- platform: 2-10个 +- client_platform: 2-5个 +- supplier: 100-1000个 +- category_level1: 10-50个 +- category_level2: 50-200个 +- category_level3: 200-1000个 +- category_level4: 1000-5000个 + +**组合维度**： +- platform_client: 4-50个 +- platform_category2: 100-2000个 +- platform_category3: 400-10000个 +- client_category2: 100-1000个 + +**列表类型**：每个维度 × 4种类型（hot/cart/new/global） + +**预估总数**：10000-50000条索引 + +--- + +## 🔍 查询示例代码 + +### Python示例 + +```python +import redis + +# 连接Redis +r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) + +# 1. 查询商品的相似商品 +item_id = "12345" +similar_items = r.get(f"i2i:swing:{item_id}") +if similar_items: + items = similar_items.split(',') + for item in items[:5]: # 取前5个 + item_id, score = item.split(':') + print(f"商品ID: {item_id}, 相似度: {score}") + +# 2. 查询分类热门商品 +category_id = "200" +hot_items = r.get(f"interest:hot:category_level2:{category_id}") +if hot_items: + items = hot_items.split(',') + for item in items[:10]: # 取前10个 + item_id, score = item.split(':') + print(f"商品ID: {item_id}, 得分: {score}") + +# 3. 查询平台+分类组合 +platform = "pc" +category_id = "200" +key = f"interest:hot:platform_category2:{platform}_{category_id}" +items = r.get(key) +``` + +### Redis命令行示例 + +```bash +# 查询商品相似度 +redis-cli GET "i2i:swing:12345" + +# 查询分类热门 +redis-cli GET "interest:hot:category_level2:200" + +# 查询供应商商品 +redis-cli GET "interest:hot:supplier:10001" + +# 模糊查询所有热门索引 +redis-cli KEYS "interest:hot:*" + +# 查看某个分类的所有类型 +redis-cli KEYS "interest:*:category_level2:200" +``` + +--- + +## 📝 注意事项 + +1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式 +2. **值的格式**：`item_id1:score1,item_id2:score2,...` +3. **过期时间**：建议设置7天过期 +4. **更新频率**：建议每天更新一次 +5. **查询优先级**： + - 优先使用细粒度索引（如四级分类） + - 粗粒度索引作为后备（如一级分类） + - 融合多个索引结果 + +--- + +**版本**: v1.1 +**生成日期**: 2025-10-16 +**索引总数**: 约10000-50000条 diff --git a/offline_tasks/doc/DATABASE_SETUP.md b/offline_tasks/doc/DATABASE_SETUP.md new file mode 100644 index 0000000..352aacc --- /dev/null +++ b/offline_tasks/doc/DATABASE_SETUP.md @@ -0,0 +1,179 @@ +# 数据库字段配置说明 + +## 问题说明 + +如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。 + +## 已适配的基础字段 + +当前代码已经适配了以下基础字段（参考 `item_sim.py`）： + +### sensors_events 表 +- `anonymous_id` - 用户ID +- `item_id` - 商品ID +- `event` - 事件类型 +- `create_time` - 创建时间 +- `platform` - 平台（可选） +- `country` - 国家（可选） +- `customer_type` - 客户类型（可选） + +### prd_goods_sku 表 +- `id` - 商品ID +- `name` - 商品名称 +- `create_time` - 创建时间（用于判断新品） + +## 可选字段配置 + +如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度： + +### 分类字段（可选） +- `category_level1_id` - 一级分类ID +- `category_level2_id` - 二级分类ID +- `category_level3_id` - 三级分类ID + +## 如何添加分类字段支持 + +如果您的数据库有分类字段，可以按以下步骤启用： + +### 步骤1: 修改 SQL 查询 + +编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段： + +```python +sql_query = f""" +SELECT + se.anonymous_id AS user_id, + se.item_id, + se.event AS event_type, + se.create_time, + pgs.name AS item_name, + pgs.create_time AS item_create_time, + pgs.category_level2_id, # 添加这一行 + pgs.category_level3_id, # 添加这一行 + se.platform, + se.country, + se.customer_type +FROM + sensors_events se +LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id +... +""" +``` + +### 步骤2: 修改聚合逻辑 + +在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用： + +```python +# 维度4: 二级分类 (category_level2) - 如果字段存在 +if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')): + key = f"category_level2:{row['category_level2_id']}" + aggregations[key][item_id] += weight +``` + +这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。 + +## 查看实际表结构 + +运行以下命令查看您的数据库表结构： + +```python +# 创建一个简单的脚本查看表结构 +import pandas as pd +from db_service import create_db_connection +from offline_tasks.config.offline_config import DB_CONFIG + +engine = create_db_connection( + DB_CONFIG['host'], + DB_CONFIG['port'], + DB_CONFIG['database'], + DB_CONFIG['username'], + DB_CONFIG['password'] +) + +# 查看 prd_goods_sku 表结构 +df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine) +print("prd_goods_sku 字段列表:") +for col in df.columns: + print(f" - {col}") + +# 查看 sensors_events 表结构 +df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine) +print("\nsensors_events 字段列表:") +for col in df.columns: + print(f" - {col}") +``` + +## 常见字段名映射 + +如果您的数据库使用不同的字段名，需要在SQL查询中做映射： + +| 代码中的字段 | 可能的实际字段名 | 修改方式 | +|-------------|----------------|---------| +| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` | +| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` | +| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` | +| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` | + +## 完整示例 + +假设您的表结构是： +- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time` +- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time` + +则需要修改SQL为： + +```python +sql_query = f""" +SELECT + se.uid AS user_id, + se.goods_id AS item_id, + se.action AS event_type, + se.time AS create_time, + pgs.title AS item_name, + pgs.add_time AS item_create_time, + pgs.cat2 AS category_level2_id, + pgs.cat3 AS category_level3_id +FROM + sensors_events se +LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id +... +""" +``` + +## 最小化配置 + +如果只想先测试基本功能，可以只使用最基础的字段： + +### i2i 算法只需要： +- `anonymous_id` / `user_id` +- `item_id` +- `event` / `event_type` +- `create_time` +- `name` (商品名称) + +### 兴趣点聚合至少需要： +- 以上i2i的字段 +- 至少一个维度字段（如 `platform` 或 `country`） + +## 测试连接 + +修改后，运行测试脚本验证： + +```bash +cd /home/tw/recommendation/offline_tasks +python3 test_connection.py +``` + +## 获取帮助 + +如果仍有问题，请： +1. 查看日志文件：`logs/run_all_*.log` +2. 运行单个脚本测试，便于调试 +3. 使用 `--help` 参数查看命令行选项 + +```bash +python3 scripts/i2i_swing.py --help +python3 scripts/interest_aggregation.py --help +``` + diff --git a/offline_tasks/doc/DEBUG_GUIDE.md b/offline_tasks/doc/DEBUG_GUIDE.md new file mode 100644 index 0000000..85f78b8 --- /dev/null +++ b/offline_tasks/doc/DEBUG_GUIDE.md @@ -0,0 +1,332 @@ +# Debug模式使用指南 + +## 🐛 Debug功能概述 + +Debug模式为所有离线任务提供： +1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 +2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 +3. **数据采样展示** - 关键步骤的示例数据 +4. **性能统计** - 每个步骤的耗时和资源使用 + +## 🚀 快速开始 + +### 1. 运行单个脚本（Debug模式） + +```bash +cd /home/tw/recommendation/offline_tasks + +# Swing算法 - Debug模式 +python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug + +# 兴趣聚合 - Debug模式 +python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug + +# 内容相似 - Debug模式 +python3 scripts/i2i_content_similar.py --top_n 10 --debug +``` + +### 2. 运行所有任务（Debug模式） + +```bash +# 使用debug参数运行所有任务 +python3 run_all.py --lookback_days 7 --top_n 10 --debug +``` + +## 📊 Debug输出说明 + +### A. 日志输出 + +Debug模式下，日志会输出到两个地方： +1. **控制台** - 实时查看进度 +2. **Debug日志文件** - 完整保存 + +日志文件位置： +``` +offline_tasks/logs/debug/i2i_swing_20251016_193000.log +offline_tasks/logs/debug/interest_aggregation_20251016_193500.log +... +``` + +### B. 日志内容示例 + +``` +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 +2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 +2025-10-16 19:30:00 - i2i_swing - DEBUG - lookback_days: 7 +2025-10-16 19:30:00 - i2i_swing - DEBUG - debug: True +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ + +2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 + +2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息: +2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 +2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5 +2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name'] +2025-10-16 19:30:05 - i2i_swing - DEBUG - +2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型: +2025-10-16 19:30:05 - i2i_swing - DEBUG - user_id: object +2025-10-16 19:30:05 - i2i_swing - DEBUG - item_id: int64 +2025-10-16 19:30:05 - i2i_swing - DEBUG - event_type: object +2025-10-16 19:30:05 - i2i_swing - DEBUG - create_time: datetime64[ns] +2025-10-16 19:30:05 - i2i_swing - DEBUG - item_name: object + +2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: +2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - contactFactory: 3456 (22.68%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - purchase: 2134 (14.01%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - addToPool: 1124 (7.38%) + +2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 +2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%) +2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%) +... +``` + +### C. 明文索引文件 + +Debug模式下，每个索引文件都会生成对应的明文文件： + +**原始索引文件** (`output/i2i_swing_20251016.txt`): +``` +12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 +67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 +``` + +**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`): +``` +================================================================================ +明文索引文件 +生成时间: 2025-10-16 19:35:00 +描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) +总索引数: 2345 +================================================================================ + +[1] i2i:swing:12345(香蕉干) +-------------------------------------------------------------------------------- + 1. ID:67890(芒果干) - Score:0.8567 + 2. ID:11223(菠萝干) - Score:0.7234 + 3. ID:44556(苹果干) - Score:0.6891 + 4. ID:22334(木瓜干) - Score:0.6234 + 5. ID:55667(草莓干) - Score:0.5891 + +[2] i2i:swing:67890(芒果干) +-------------------------------------------------------------------------------- + 1. ID:12345(香蕉干) - Score:0.8567 + 2. ID:22334(木瓜干) - Score:0.7123 + 3. ID:55667(草莓干) - Score:0.6543 + 4. ID:11223(菠萝干) - Score:0.6234 + 5. ID:44556(苹果干) - Score:0.5891 + +... + +================================================================================ +已输出 50/2345 个索引 +================================================================================ +``` + +## 📁 文件结构 + +Debug模式下的文件组织： + +``` +offline_tasks/ +├── output/ +│ ├── i2i_swing_20251016.txt # 原始索引文件 +│ ├── interest_aggregation_hot_20251016.txt +│ └── debug/ # Debug明文文件目录 +│ ├── i2i_swing_20251016_readable.txt # 明文索引 +│ ├── interest_aggregation_hot_20251016_readable.txt +│ └── ... +└── logs/ + ├── run_all_20251016.log # 主日志 + └── debug/ # Debug详细日志目录 + ├── i2i_swing_20251016_193000.log + ├── interest_aggregation_20251016_193500.log + └── ... +``` + +## 🔍 使用场景 + +### 场景1：调试数据流程 + +```bash +# 使用小数据量+debug模式快速验证 +python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug + +# 查看日志，检查： +# - 数据加载是否正确 +# - 行为类型分布是否合理 +# - 用户/商品数量是否符合预期 +``` + +### 场景2：检查推荐效果 + +```bash +# 生成明文索引文件 +python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug + +# 打开明文文件查看： +cat output/debug/i2i_swing_20251016_readable.txt | less + +# 检查推荐是否合理，例如： +# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 +# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 +``` + +### 场景3：性能调优 + +```bash +# Debug模式查看各步骤耗时 +python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" + +# 输出示例： +# 步骤1耗时: 2.34秒 +# 步骤2耗时: 15.67秒 <- 瓶颈在这里 +# 步骤3耗时: 1.23秒 +# 总耗时: 19.24秒 +``` + +### 场景4：参数调整 + +```bash +# 测试不同alpha值的效果 +python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1 +python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1 +python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1 + +# 对比明文文件，选择最佳参数 +diff output/debug/i2i_swing_*_readable.txt +``` + +## 💡 最佳实践 + +### 1. 开发调试阶段 + +```bash +# 使用小数据量 + Debug模式 +python3 run_all.py --lookback_days 3 --top_n 10 --debug +``` + +- ✅ 快速验证流程 +- ✅ 详细日志便于排错 +- ✅ 明文文件检查效果 + +### 2. 参数调优阶段 + +```bash +# 中等数据量 + Debug模式 +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug +``` + +- ✅ 查看数据分布 +- ✅ 评估推荐质量 +- ✅ 调整算法参数 + +### 3. 生产运行阶段 + +```bash +# 大数据量 + 正常模式（不加--debug） +python3 run_all.py --lookback_days 730 --top_n 50 +``` + +- ✅ 高效运行 +- ✅ 只输出必要日志 +- ✅ 节省磁盘空间 + +## 🛠️ Debug工具 + +### 查看实时日志 + +```bash +# 实时查看debug日志 +tail -f logs/debug/i2i_swing_*.log + +# 只看DEBUG级别 +tail -f logs/debug/i2i_swing_*.log | grep "DEBUG" + +# 只看错误 +tail -f logs/debug/i2i_swing_*.log | grep "ERROR" +``` + +### 统计分析 + +```bash +# 统计处理的数据量 +grep "总行数" logs/debug/*.log + +# 统计生成的索引数 +grep "总索引数" output/debug/*_readable.txt + +# 查看性能统计 +grep "耗时" logs/debug/*.log +``` + +### 快速检查 + +```bash +# 检查前10个推荐 +head -50 output/debug/i2i_swing_*_readable.txt + +# 搜索特定商品的推荐 +grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10 + +# 统计推荐数量分布 +grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l +``` + +## ⚠️ 注意事项 + +1. **磁盘空间** + - Debug日志和明文文件会占用较多空间 + - 建议定期清理：`rm -rf logs/debug/* output/debug/*` + +2. **运行时间** + - Debug模式会增加10-20%的运行时间 + - 生产环境建议关闭debug + +3. **敏感信息** + - 明文文件包含商品名称等信息 + - 注意数据安全和隐私保护 + +4. **文件编码** + - 明文文件使用UTF-8编码 + - 确保查看工具支持中文显示 + +## 📖 相关命令 + +```bash +# 查看帮助 +python3 scripts/i2i_swing.py --help +python3 run_all.py --help + +# 验证配置 +python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)" + +# 测试debug工具 +python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')" +``` + +## ✅ 验证Debug功能 + +```bash +# 快速测试 +cd /home/tw/recommendation/offline_tasks +python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug + +# 应该看到： +# ✓ DEBUG级别日志输出 +# ✓ 创建debug日志文件 +# ✓ 生成明文索引文件 +# ✓ 显示数据统计信息 +``` + +--- + +**Debug模式**: 开发和调试的利器 +**正常模式**: 生产环境的选择 +**灵活切换**: 一个参数的事情 diff --git a/offline_tasks/doc/OFFLINE_INDEX_SPEC.md b/offline_tasks/doc/OFFLINE_INDEX_SPEC.md new file mode 100644 index 0000000..ba5be7d --- /dev/null +++ b/offline_tasks/doc/OFFLINE_INDEX_SPEC.md @@ -0,0 +1,197 @@ +# 离线索引产出规范 + +## 📋 索引任务列表 + +| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 | +|---------|---------|---------|---------|-----------| +| **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` diff --git a/offline_tasks/doc/README.md b/offline_tasks/doc/README.md new file mode 100644 index 0000000..84bb981 --- /dev/null +++ b/offline_tasks/doc/README.md @@ -0,0 +1,79 @@ +# 推荐系统离线任务文档中心 + +本目录包含推荐系统所有重要文档。 + +## 📚 文档目录 + +### 快速开始 + +- **[从这里开始.md](./从这里开始.md)** - 新手入门指南，了解项目结构和基本概念 +- **[快速开始.md](./快速开始.md)** - 快速运行离线任务的步骤 +- **[Swing快速开始.md](../collaboration/Swing快速开始.md)** - C++ Swing算法快速使用指南 + +### 使用指南 + +- **[Swing算法使用指南.md](./Swing算法使用指南.md)** - 详细的Swing算法使用文档 +- **[运行脚本指南.md](./运行脚本指南.md)** - 所有离线任务脚本的使用说明 +- **[调试指南.md](./调试指南.md)** - Debug模式和日志使用说明 + +### 数据规范 + +- **[离线索引数据规范.md](./离线索引数据规范.md)** - 所有离线索引的格式和说明 +- **[Redis数据规范.md](./Redis数据规范.md)** - Redis中数据的key格式和结构 +- **[完整索引列表.md](./完整索引列表.md)** - 系统中所有索引的完整清单 + +### 配置说明 + +- **[数据库配置说明.md](./数据库配置说明.md)** - 数据库连接和表结构说明 +- **配置文件**: `../config/offline_config.py` - 所有可配置参数 + +### 实现总结 + +- **[Swing实现总结.md](./Swing实现总结.md)** - C++ Swing集成实现的完整说明 + +### 维护文档 + +- **[故障排查指南.md](./故障排查指南.md)** - 常见问题和解决方案 +- **[更新日志.md](./更新日志.md)** - 系统更新历史 + +## 📂 相关文档 + +### 其他模块文档 + +- **Collaboration模块**: `../collaboration/README.md` - C++ 协同过滤算法 +- **GraphEmbedding模块**: + - Session W2V: `../graphembedding/session_w2v/README.md` + - DeepWalk: `../graphembedding/deepwalk/README.md` +- **Hot模块**: `../hot/README.md` - 热门商品推荐 + +### 项目README + +- **项目根目录**: `../../README.md` - 项目总览 +- **离线任务**: `../README.md` - 离线任务模块说明 + +## 🎯 文档使用建议 + +### 新用户 + +1. 先阅读 **[从这里开始.md](./从这里开始.md)** 了解整体架构 +2. 然后看 **[快速开始.md](./快速开始.md)** 快速运行系统 +3. 需要时查阅具体的使用指南和数据规范 + +### 开发人员 + +1. 查看 **[运行脚本指南.md](./运行脚本指南.md)** 了解所有脚本 +2. 参考 **[调试指南.md](./调试指南.md)** 进行调试 +3. 遵循 **数据规范** 文档进行开发 + +### 运维人员 + +1. 配置前先看 **[数据库配置说明.md](./数据库配置说明.md)** +2. 遇到问题查看 **[故障排查指南.md](./故障排查指南.md)** +3. 了解 **[Redis数据规范.md](./Redis数据规范.md)** 便于维护 + +## 📝 文档更新 + +所有文档由项目维护者更新。如有疑问或发现错误，请联系团队。 + +**最后更新**: 2024-10-17 + diff --git a/offline_tasks/doc/REDIS_DATA_SPEC.md b/offline_tasks/doc/REDIS_DATA_SPEC.md new file mode 100644 index 0000000..2777b71 --- /dev/null +++ b/offline_tasks/doc/REDIS_DATA_SPEC.md @@ -0,0 +1,306 @@ +# Redis数据灌入规范 + +## 📋 数据灌入概述 + +将离线生成的推荐索引加载到Redis，供在线系统实时查询使用。 + +## 🔑 Redis Key规范 + +### 通用规则 +``` +{namespace}:{function}:{algorithm}:{identifier} +``` + +- `namespace`: 业务命名空间（item, user, interest等） +- `function`: 功能类型（similar, feature, hot等） +- `algorithm`: 算法名称（swing, w2v, deepwalk等） +- `identifier`: 具体标识（item_id, dimension_key等） + +## 📊 数据灌入规范表 + +| 模块名称 | 源数据地址 | 格式描述 | RedisKey模板 | RedisValue格式 | TTL | +|---------|-----------|---------|-------------|---------------|-----| +| **i2i_swing** | `output/i2i_swing_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:swing:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_session_w2v** | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:w2v:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_deepwalk** | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:deepwalk:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_content_name** | `output/i2i_content_name_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_name:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | +| **i2i_content_pic** | `output/i2i_content_pic_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_pic:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | +| **interest_hot** | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:hot:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_cart** | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:cart:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_new** | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:new:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_global** | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:global:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 7天 | + +## 📝 详细说明 + +### 1. i2i相似度索引 + +#### 源数据格式 +``` +12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 +``` + +#### Redis存储 + +**Key**: `item:similar:swing:12345` + +**Value** (JSON格式): +```json +[[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] +``` + +**Value** (序列化后): +```python +import json +value = json.dumps([[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]) +# 存储: "[[67890,0.8567],[11223,0.7234],[44556,0.6891]]" +``` + +#### 查询示例 +```python +import redis +import json + +r = redis.Redis(host='localhost', port=6379, db=0) + +# 获取商品12345的相似商品（Swing算法） +similar_items = json.loads(r.get('item:similar:swing:12345')) +# 返回: [[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] + +# 获取Top5相似商品 +top_5 = similar_items[:5] +``` + +### 2. 兴趣点聚合索引 + +#### 源数据格式 +``` +platform:pc 12345,67890,11223,44556,22334 +category_level2:200 67890,12345,22334,55667,11223 +``` + +#### Redis存储 + +**Key**: `interest:hot:platform:pc` + +**Value** (JSON格式): +```json +[12345, 67890, 11223, 44556, 22334] +``` + +**Value** (序列化后): +```python +import json +value = json.dumps([12345, 67890, 11223, 44556, 22334]) +# 存储: "[12345,67890,11223,44556,22334]" +``` + +#### 查询示例 +```python +import redis +import json + +r = redis.Redis(host='localhost', port=6379, db=0) + +# 获取PC平台的热门商品 +hot_items = json.loads(r.get('interest:hot:platform:pc')) +# 返回: [12345, 67890, 11223, 44556, 22334] + +# 获取Top10热门商品 +top_10 = hot_items[:10] +``` + +## 🔄 数据加载流程 + +### 1. 加载i2i索引 + +```python +def load_i2i_index(file_path, algorithm_name, redis_client, expire_seconds=604800): + """ + 加载i2i相似度索引到Redis + + Args: + file_path: 索引文件路径 + algorithm_name: 算法名称（swing, w2v, deepwalk, content） + redis_client: Redis客户端 + expire_seconds: 过期时间（秒），默认7天 + """ + import json + + count = 0 + with open(file_path, 'r', encoding='utf-8') as f: + for line in f: + parts = line.strip().split('\t') + if len(parts) < 3: + continue + + item_id = parts[0] + similar_str = parts[2] # similar_id1:score1,similar_id2:score2,... + + # 解析相似商品 + similar_items = [] + for pair in similar_str.split(','): + if ':' in pair: + sim_id, score = pair.split(':') + similar_items.append([int(sim_id), float(score)]) + + # 存储到Redis + redis_key = f"item:similar:{algorithm_name}:{item_id}" + redis_value = json.dumps(similar_items) + + redis_client.set(redis_key, redis_value) + redis_client.expire(redis_key, expire_seconds) + + count += 1 + + return count +``` + +### 2. 加载兴趣聚合索引 + +```python +def load_interest_index(file_path, list_type, redis_client, expire_seconds=259200): + """ + 加载兴趣点聚合索引到Redis + + Args: + file_path: 索引文件路径 + list_type: 列表类型（hot, cart, new, global） + redis_client: Redis客户端 + expire_seconds: 过期时间（秒），默认3天 + """ + import json + + count = 0 + with open(file_path, 'r', encoding='utf-8') as f: + for line in f: + parts = line.strip().split('\t') + if len(parts) != 2: + continue + + dimension_key = parts[0] # platform:pc + item_ids_str = parts[1] # 12345,67890,11223,... + + # 解析商品ID列表 + item_ids = [int(item_id) for item_id in item_ids_str.split(',')] + + # 存储到Redis + redis_key = f"interest:{list_type}:{dimension_key}" + redis_value = json.dumps(item_ids) + + redis_client.set(redis_key, redis_value) + redis_client.expire(redis_key, expire_seconds) + + count += 1 + + return count +``` + +## 🚀 快速加载命令 + +### 加载所有索引 +```bash +cd /home/tw/recommendation/offline_tasks + +# 加载所有索引（使用今天的数据） +python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 + +# 加载指定日期的索引 +python3 scripts/load_index_to_redis.py --date 20251016 --redis-host localhost + +# 只加载i2i索引 +python3 scripts/load_index_to_redis.py --load-i2i --redis-host localhost + +# 只加载兴趣聚合索引 +python3 scripts/load_index_to_redis.py --load-interest --redis-host localhost +``` + +### 验证数据 +```bash +# 连接Redis +redis-cli + +# 检查key数量 +DBSIZE + +# 查看某个商品的相似推荐 +GET item:similar:swing:12345 + +# 查看平台热门商品 +GET interest:hot:platform:pc + +# 查看所有i2i相关的key +KEYS item:similar:* + +# 查看所有interest相关的key +KEYS interest:* + +# 检查key的过期时间 +TTL item:similar:swing:12345 +``` + +## 📊 数据统计 + +### Redis内存占用估算 + +| 索引类型 | Key数量 | 单条Value大小 | 总内存 | +|---------|--------|-------------|--------| +| i2i_swing | 50,000 | ~500B | ~25MB | +| i2i_w2v | 50,000 | ~500B | ~25MB | +| i2i_deepwalk | 50,000 | ~500B | ~25MB | +| i2i_content_name | 50,000 | ~500B | ~25MB | +| i2i_content_pic | 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 | +| **总计** | **270,000** | - | **~160MB** | + +### 过期策略 + +| 索引类型 | TTL | 原因 | +|---------|-----|------| +| i2i行为相似 | 7天 | 用户行为变化快，需要频繁更新 | +| i2i内容相似 | 30天 | 商品属性变化慢，可以保留更久 | +| 热门/加购 | 3天 | 热度变化快，需要及时更新 | +| 新品 | 3天 | 新品概念有时效性 | +| 全局热门 | 7天 | 相对稳定，可以保留更久 | + +## ⚠️ 注意事项 + +1. **原子性**: 使用Pipeline批量写入，提高性能 +2. **过期时间**: 合理设置TTL，避免过期数据 +3. **内存管理**: 定期清理过期key，监控内存使用 +4. **数据版本**: 使用日期标记，支持数据回滚 +5. **容错处理**: 加载失败时不影响线上服务 +6. **监控告警**: 监控加载成功率、Redis内存、查询延迟 + +## 🔍 监控指标 + +### 数据质量指标 +```python +# 检查加载成功率 +total_keys = redis_client.dbsize() +expected_keys = 245000 +success_rate = total_keys / expected_keys * 100 + +# 检查数据完整性 +sample_keys = [ + 'item:similar:swing:12345', + 'interest:hot:platform:pc' +] +for key in sample_keys: + if not redis_client.exists(key): + print(f"Missing key: {key}") +``` + +### 性能指标 +- 加载耗时: < 5分钟 +- 内存占用: < 200MB +- 查询延迟: < 1ms +- 成功率: > 99% + +## 🔗 相关文档 + +- **离线索引规范**: `OFFLINE_INDEX_SPEC.md` +- **API接口文档**: `RECOMMENDATION_API.md` +- **运维手册**: `OPERATIONS.md` diff --git a/offline_tasks/doc/RUN_SCRIPT_GUIDE.md b/offline_tasks/doc/RUN_SCRIPT_GUIDE.md new file mode 100644 index 0000000..1f40004 --- /dev/null +++ b/offline_tasks/doc/RUN_SCRIPT_GUIDE.md @@ -0,0 +1,304 @@ +# run.sh 运行脚本使用指南 + +## 概述 + +`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。 + +## 主要特性 + +### 1. 内存监控 +- **警告阈值**: 25GB - 打印警告日志 +- **强制终止阈值**: 30GB - 自动kill进程 +- **检查频率**: 每10秒检查一次 +- **日志文件**: `logs/memory_monitor.log` + +### 2. 任务流程 +1. 清理旧进程和输出 +2. 运行调试模式（小数据量测试） +3. 运行生产模式（大数据量） +4. 加载索引到Redis + +### 3. 错误处理 +- 任何步骤失败会立即退出 +- 显示详细的退出码 +- 保存完整日志 + +## 使用方法 + +### 基本运行 +```bash +cd /home/tw/recommendation/offline_tasks +./run.sh +``` + +### 查看实时输出 +```bash +./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log +``` + +### 后台运行 +```bash +nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 & +``` + +## 内存监控说明 + +### 监控逻辑 + +```bash +check_memory() { + local pid=$1 + local threshold_warn=25 # 25GB警告 + local threshold_kill=30 # 30GB强制kill + + while 进程运行中; do + 获取内存使用 + + if 内存 >= 30GB: + 打印错误日志 + 强制终止进程 + break + elif 内存 >= 25GB: + 打印警告日志 + + sleep 10秒 + done +} +``` + +### 日志格式 + +**警告日志**: +``` +[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 +``` + +**强制终止日志**: +``` +[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 +``` + +### 查看监控日志 +```bash +# 实时查看 +tail -f logs/memory_monitor.log + +# 查看历史 +cat logs/memory_monitor.log +``` + +## 运行流程 + +### 步骤1: 调试模式 +```bash +python3 run_all.py --debug +``` +- 使用默认参数（见 `offline_config.py`） +- 输出保存到 `output_debug/` +- 启动内存监控 + +### 步骤2: 生产模式 +```bash +python3 run_all.py --debug +``` +- 生成完整索引 +- 输出保存到 `output/` +- 启动内存监控 + +### 步骤3: 加载Redis +```bash +python3 scripts/load_index_to_redis.py --redis-host localhost +``` +- 加载所有生成的索引 +- 包括新增的内容相似索引 + +## 输出示例 + +``` +====================================================================== +开始运行离线任务 - 2025-10-17 14:00:00 +内存监控: 警告阈值=25GB, 强制终止阈值=30GB +====================================================================== + +>>> 步骤1: 调试模式运行（小数据量） +调试任务 PID: 12345 +✓ 调试模式完成 + +>>> 步骤2: 生产模式运行（大数据量） +生产任务 PID: 12346 +[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 +✓ 生产模式完成 + +>>> 步骤3: 加载到Redis +✓ Redis加载完成 + +====================================================================== +所有任务完成 - 2025-10-17 16:30:00 +====================================================================== +``` + +## 自定义配置 + +### 修改内存阈值 + +编辑 `run.sh` 中的以下行： +```bash +local threshold_warn=25 # 修改警告阈值 +local threshold_kill=30 # 修改强制kill阈值 +``` + +### 修改检查频率 + +编辑 `run.sh` 中的以下行： +```bash +sleep 10 # 修改为其他秒数 +``` + +### 跳过调试模式 + +注释掉步骤1相关代码： +```bash +# # 3. 调试模式运行（小数据量） +# echo "" +# echo ">>> 步骤1: 调试模式运行（小数据量）" +# python3 run_all.py --debug & +# ... +``` + +### 修改Redis配置 + +修改步骤3的参数： +```bash +python3 scripts/load_index_to_redis.py \ + --redis-host your-redis-host \ + --redis-port 6379 \ + --redis-db 0 +``` + +## 故障排查 + +### 内存持续超限 + +**原因**: +- 数据量太大 +- 内存泄漏 +- 并发任务过多 + +**解决方案**: +1. 增加内存阈值（临时方案） +2. 优化代码减少内存占用 +3. 分批处理数据 +4. 使用增量更新 + +### 进程被意外终止 + +**检查日志**: +```bash +# 查看监控日志 +cat logs/memory_monitor.log + +# 查看任务日志 +ls -lht logs/ +cat logs/run_all_*.log +``` + +### 任务失败 + +**查看退出码**: +- 0: 成功 +- 1: 一般错误 +- 137: 被kill信号终止（可能是内存超限） +- 其他: 查看具体错误信息 + +## 监控建议 + +### 1. 添加系统监控 +```bash +# 安装监控工具 +apt install htop iotop + +# 实时监控 +htop -p $(pgrep -f run_all.py) +``` + +### 2. 设置告警 +```bash +# 配置邮件告警 +if [ $PROD_EXIT_CODE -ne 0 ]; then + echo "任务失败" | mail -s "离线任务告警" admin@example.com +fi +``` + +### 3. 定时任务 +```bash +# 添加到crontab +0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 +``` + +## 性能优化 + +### 内存优化建议 + +1. **分批处理** + ```python + # 在代码中使用batch处理 + batch_size = 1000 + for i in range(0, len(items), batch_size): + batch = items[i:i+batch_size] + process(batch) + ``` + +2. **及时释放** + ```python + import gc + del large_object + gc.collect() + ``` + +3. **使用生成器** + ```python + def process_items(): + for item in items: + yield process(item) + ``` + +## 日志管理 + +### 日志文件 +- `logs/memory_monitor.log` - 内存监控日志 +- `logs/run_all_YYYYMMDD.log` - 任务运行日志 +- `output/` - 生成的索引文件 +- `output_debug/` - 调试模式输出 + +### 清理旧日志 +```bash +# 保留最近7天 +find logs/ -name "*.log" -mtime +7 -delete + +# 压缩旧日志 +find logs/ -name "*.log" -mtime +3 -exec gzip {} \; +``` + +## 安全注意事项 + +1. **权限**: 确保脚本有执行权限 `chmod +x run.sh` +2. **路径**: 使用绝对路径避免混淆 +3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀 +4. **备份**: 脚本会删除output目录，请提前备份重要数据 + +## 总结 + +`run.sh` 提供了： +- ✅ 自动化运行流程 +- ✅ 内存监控保护 +- ✅ 详细日志记录 +- ✅ 错误处理机制 +- ✅ 进度显示 + +建议在生产环境使用前先在测试环境验证。 + +--- + +**更新时间**: 2025-10-17 +**版本**: v2.0 + diff --git a/offline_tasks/doc/Redis数据规范.md b/offline_tasks/doc/Redis数据规范.md new file mode 100644 index 0000000..2777b71 --- /dev/null +++ b/offline_tasks/doc/Redis数据规范.md @@ -0,0 +1,306 @@ +# Redis数据灌入规范 + +## 📋 数据灌入概述 + +将离线生成的推荐索引加载到Redis，供在线系统实时查询使用。 + +## 🔑 Redis Key规范 + +### 通用规则 +``` +{namespace}:{function}:{algorithm}:{identifier} +``` + +- `namespace`: 业务命名空间（item, user, interest等） +- `function`: 功能类型（similar, feature, hot等） +- `algorithm`: 算法名称（swing, w2v, deepwalk等） +- `identifier`: 具体标识（item_id, dimension_key等） + +## 📊 数据灌入规范表 + +| 模块名称 | 源数据地址 | 格式描述 | RedisKey模板 | RedisValue格式 | TTL | +|---------|-----------|---------|-------------|---------------|-----| +| **i2i_swing** | `output/i2i_swing_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:swing:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_session_w2v** | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:w2v:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_deepwalk** | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:deepwalk:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 | +| **i2i_content_name** | `output/i2i_content_name_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_name:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | +| **i2i_content_pic** | `output/i2i_content_pic_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_pic:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 | +| **interest_hot** | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:hot:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_cart** | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:cart:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_new** | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:new:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 | +| **interest_global** | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:global:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 7天 | + +## 📝 详细说明 + +### 1. i2i相似度索引 + +#### 源数据格式 +``` +12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 +``` + +#### Redis存储 + +**Key**: `item:similar:swing:12345` + +**Value** (JSON格式): +```json +[[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] +``` + +**Value** (序列化后): +```python +import json +value = json.dumps([[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]) +# 存储: "[[67890,0.8567],[11223,0.7234],[44556,0.6891]]" +``` + +#### 查询示例 +```python +import redis +import json + +r = redis.Redis(host='localhost', port=6379, db=0) + +# 获取商品12345的相似商品（Swing算法） +similar_items = json.loads(r.get('item:similar:swing:12345')) +# 返回: [[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]] + +# 获取Top5相似商品 +top_5 = similar_items[:5] +``` + +### 2. 兴趣点聚合索引 + +#### 源数据格式 +``` +platform:pc 12345,67890,11223,44556,22334 +category_level2:200 67890,12345,22334,55667,11223 +``` + +#### Redis存储 + +**Key**: `interest:hot:platform:pc` + +**Value** (JSON格式): +```json +[12345, 67890, 11223, 44556, 22334] +``` + +**Value** (序列化后): +```python +import json +value = json.dumps([12345, 67890, 11223, 44556, 22334]) +# 存储: "[12345,67890,11223,44556,22334]" +``` + +#### 查询示例 +```python +import redis +import json + +r = redis.Redis(host='localhost', port=6379, db=0) + +# 获取PC平台的热门商品 +hot_items = json.loads(r.get('interest:hot:platform:pc')) +# 返回: [12345, 67890, 11223, 44556, 22334] + +# 获取Top10热门商品 +top_10 = hot_items[:10] +``` + +## 🔄 数据加载流程 + +### 1. 加载i2i索引 + +```python +def load_i2i_index(file_path, algorithm_name, redis_client, expire_seconds=604800): + """ + 加载i2i相似度索引到Redis + + Args: + file_path: 索引文件路径 + algorithm_name: 算法名称（swing, w2v, deepwalk, content） + redis_client: Redis客户端 + expire_seconds: 过期时间（秒），默认7天 + """ + import json + + count = 0 + with open(file_path, 'r', encoding='utf-8') as f: + for line in f: + parts = line.strip().split('\t') + if len(parts) < 3: + continue + + item_id = parts[0] + similar_str = parts[2] # similar_id1:score1,similar_id2:score2,... + + # 解析相似商品 + similar_items = [] + for pair in similar_str.split(','): + if ':' in pair: + sim_id, score = pair.split(':') + similar_items.append([int(sim_id), float(score)]) + + # 存储到Redis + redis_key = f"item:similar:{algorithm_name}:{item_id}" + redis_value = json.dumps(similar_items) + + redis_client.set(redis_key, redis_value) + redis_client.expire(redis_key, expire_seconds) + + count += 1 + + return count +``` + +### 2. 加载兴趣聚合索引 + +```python +def load_interest_index(file_path, list_type, redis_client, expire_seconds=259200): + """ + 加载兴趣点聚合索引到Redis + + Args: + file_path: 索引文件路径 + list_type: 列表类型（hot, cart, new, global） + redis_client: Redis客户端 + expire_seconds: 过期时间（秒），默认3天 + """ + import json + + count = 0 + with open(file_path, 'r', encoding='utf-8') as f: + for line in f: + parts = line.strip().split('\t') + if len(parts) != 2: + continue + + dimension_key = parts[0] # platform:pc + item_ids_str = parts[1] # 12345,67890,11223,... + + # 解析商品ID列表 + item_ids = [int(item_id) for item_id in item_ids_str.split(',')] + + # 存储到Redis + redis_key = f"interest:{list_type}:{dimension_key}" + redis_value = json.dumps(item_ids) + + redis_client.set(redis_key, redis_value) + redis_client.expire(redis_key, expire_seconds) + + count += 1 + + return count +``` + +## 🚀 快速加载命令 + +### 加载所有索引 +```bash +cd /home/tw/recommendation/offline_tasks + +# 加载所有索引（使用今天的数据） +python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 + +# 加载指定日期的索引 +python3 scripts/load_index_to_redis.py --date 20251016 --redis-host localhost + +# 只加载i2i索引 +python3 scripts/load_index_to_redis.py --load-i2i --redis-host localhost + +# 只加载兴趣聚合索引 +python3 scripts/load_index_to_redis.py --load-interest --redis-host localhost +``` + +### 验证数据 +```bash +# 连接Redis +redis-cli + +# 检查key数量 +DBSIZE + +# 查看某个商品的相似推荐 +GET item:similar:swing:12345 + +# 查看平台热门商品 +GET interest:hot:platform:pc + +# 查看所有i2i相关的key +KEYS item:similar:* + +# 查看所有interest相关的key +KEYS interest:* + +# 检查key的过期时间 +TTL item:similar:swing:12345 +``` + +## 📊 数据统计 + +### Redis内存占用估算 + +| 索引类型 | Key数量 | 单条Value大小 | 总内存 | +|---------|--------|-------------|--------| +| i2i_swing | 50,000 | ~500B | ~25MB | +| i2i_w2v | 50,000 | ~500B | ~25MB | +| i2i_deepwalk | 50,000 | ~500B | ~25MB | +| i2i_content_name | 50,000 | ~500B | ~25MB | +| i2i_content_pic | 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 | +| **总计** | **270,000** | - | **~160MB** | + +### 过期策略 + +| 索引类型 | TTL | 原因 | +|---------|-----|------| +| i2i行为相似 | 7天 | 用户行为变化快，需要频繁更新 | +| i2i内容相似 | 30天 | 商品属性变化慢，可以保留更久 | +| 热门/加购 | 3天 | 热度变化快，需要及时更新 | +| 新品 | 3天 | 新品概念有时效性 | +| 全局热门 | 7天 | 相对稳定，可以保留更久 | + +## ⚠️ 注意事项 + +1. **原子性**: 使用Pipeline批量写入，提高性能 +2. **过期时间**: 合理设置TTL，避免过期数据 +3. **内存管理**: 定期清理过期key，监控内存使用 +4. **数据版本**: 使用日期标记，支持数据回滚 +5. **容错处理**: 加载失败时不影响线上服务 +6. **监控告警**: 监控加载成功率、Redis内存、查询延迟 + +## 🔍 监控指标 + +### 数据质量指标 +```python +# 检查加载成功率 +total_keys = redis_client.dbsize() +expected_keys = 245000 +success_rate = total_keys / expected_keys * 100 + +# 检查数据完整性 +sample_keys = [ + 'item:similar:swing:12345', + 'interest:hot:platform:pc' +] +for key in sample_keys: + if not redis_client.exists(key): + print(f"Missing key: {key}") +``` + +### 性能指标 +- 加载耗时: < 5分钟 +- 内存占用: < 200MB +- 查询延迟: < 1ms +- 成功率: > 99% + +## 🔗 相关文档 + +- **离线索引规范**: `OFFLINE_INDEX_SPEC.md` +- **API接口文档**: `RECOMMENDATION_API.md` +- **运维手册**: `OPERATIONS.md` diff --git a/offline_tasks/doc/SWING_USAGE.md b/offline_tasks/doc/SWING_USAGE.md new file mode 100644 index 0000000..3a6fdc9 --- /dev/null +++ b/offline_tasks/doc/SWING_USAGE.md @@ -0,0 +1,322 @@ +# Swing算法使用指南 + +本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。 + +## 目录结构 + +``` +recommendation/ +├── offline_tasks/ +│ ├── scripts/ +│ │ ├── generate_session.py # 生成用户session文件 +│ │ └── add_names_to_swing.py # 给结果添加商品名称 +│ └── output/ +│ └── session.txt.YYYYMMDD # 生成的session文件 +└── collaboration/ + ├── run.sh # Swing算法执行脚本 + ├── src/ + │ ├── swing.cc # Swing算法实现 + │ └── ucf.py # 用户协同过滤 + └── output_YYYYMMDD/ + ├── swing_similar.txt # Swing结果（ID格式） + └── swing_similar_readable.txt # Swing结果（带商品名） +``` + +## 使用流程 + +### 步骤1: 生成Session文件 + +首先需要从数据库提取用户行为数据，生成session文件。 + +```bash +cd /home/tw/recommendation/offline_tasks + +# 基本用法（使用默认参数：730天数据） +python3 scripts/generate_session.py + +# 指定回看天数 +python3 scripts/generate_session.py --lookback_days 365 + +# 启用debug模式查看详细信息 +python3 scripts/generate_session.py --lookback_days 730 --debug + +# 指定输出文件路径 +python3 scripts/generate_session.py --output output/session.txt.20241017 + +# 选择输出格式 +python3 scripts/generate_session.py --format both # 同时生成两种格式（默认） +python3 scripts/generate_session.py --format standard # uid \t json 格式 +python3 scripts/generate_session.py --format cpp # 纯json格式（.cpp后缀） +``` + +**输出文件格式：** + +- `session.txt.YYYYMMDD` - 标准格式（包含uid）： + ``` + uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} + uid2 \t {"item_id4":15.0,"item_id5":8.0} + ``` + +- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）： + ``` + {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} + {"item_id4":15.0,"item_id5":8.0} + ``` + +**行为权重配置：** +- `purchase`: 10.0（购买） +- `contactFactory`: 5.0（联系厂家） +- `addToCart`: 3.0（加入购物车） +- `addToPool`: 2.0（加入询价池） + +### 步骤2: 运行Swing算法 + +session文件生成后，运行C++版本的Swing算法。 + +```bash +cd /home/tw/recommendation/collaboration + +# 直接运行（使用默认配置） +bash run.sh + +# 或者给脚本添加执行权限后运行 +chmod +x run.sh +./run.sh +``` + +**配置说明（修改run.sh中的参数）：** + +```bash +# 数据路径配置 +SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 + +# Swing算法参数 +ALPHA=0.7 # Swing算法的alpha参数（越小越关注用户共同行为） +THRESHOLD1=1 # 交互强度阈值1（用于筛选用户行为） +THRESHOLD2=3 # 交互强度阈值2（用于计算相似度） +THREAD_NUM=4 # 线程数（根据CPU核心数调整） +SHOW_PROGRESS=1 # 是否显示进度 (0/1) + +# Python环境 +PYTHON_CMD="python3" # 如需使用特定Python环境，修改此处 +``` + +**脚本执行流程：** + +1. 编译C++程序（swing, icf_simple, swing_symmetric） +2. 查找当天日期的session文件 +3. 运行Swing算法计算物品相似度 +4. 合并多线程输出结果 +5. 自动调用debug脚本生成可读版本 + +### 步骤3: 查看结果 + +运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录： + +**1. swing_similar.txt** - 原始结果（ID格式） +``` +12345 \t 67890:0.8523,23456:0.7234,34567:0.6891 +``` +格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...` + +**2. swing_similar_readable.txt** - 可读结果（带商品名） +``` +12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 +``` +格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...` + +### 步骤4: 单独生成Debug文件（可选） + +如果需要为其他文件生成可读版本： + +```bash +cd /home/tw/recommendation/offline_tasks + +# 基本用法 +python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt + +# 指定输出文件 +python3 scripts/add_names_to_swing.py \ + collaboration/output/swing_similar.txt \ + collaboration/output/my_readable.txt + +# 启用debug模式 +python3 scripts/add_names_to_swing.py \ + collaboration/output/swing_similar.txt \ + --debug +``` + +## 参数调优建议 + +### Swing算法参数 + +1. **alpha (0.5-1.0)** + - 越小：越关注用户共同行为的多样性 + - 越大：越容忽略用户重叠度 + - 建议：0.5-0.7（B2B场景） + +2. **threshold1 (1-5)** + - 用于筛选用户的有效行为 + - 建议：1-3（低频场景可用1） + +3. **threshold2 (1-10)** + - 用于计算相似度的行为强度阈值 + - 建议：3-5（需要较强的交互信号） + +4. **thread_num (1-20)** + - 根据CPU核心数设置 + - 建议：4-8（普通服务器） + +### 数据范围参数 + +1. **lookback_days** + - B2B低频场景：建议730天（2年） + - B2C高频场景：建议30-90天 + - 数据量大时可适当减少 + +## 完整示例 + +```bash +# 1. 生成session文件（730天数据） +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py --lookback_days 730 --debug + +# 2. 检查生成的文件 +ls -lh output/session.txt.* +# 应该看到： +# session.txt.20241017 +# session.txt.20241017.cpp + +# 3. 运行Swing算法 +cd /home/tw/recommendation/collaboration +bash run.sh + +# 4. 查看结果 +ls -lh output/swing_similar* +cat output/swing_similar_readable.txt | head -20 +``` + +## 故障排查 + +### 问题1: Session文件不存在 + +``` +错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp +``` + +**解决方法：** +```bash +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py +``` + +### 问题2: 编译失败 + +``` +编译失败，退出 +``` + +**解决方法：** +```bash +cd /home/tw/recommendation/collaboration +# 检查编译器 +g++ --version + +# 手动编译 +make clean +make + +# 检查依赖 +ls include/ +ls utils/ +``` + +### 问题3: 数据库连接失败 + +``` +获取数据失败: Connection refused +``` + +**解决方法：** +- 检查数据库配置：`offline_tasks/config/offline_config.py` +- 测试连接：`python3 offline_tasks/test_connection.py` +- 确认网络和防火墙设置 + +### 问题4: 结果为空 + +**可能原因：** +- threshold1/threshold2设置过高，过滤掉了所有数据 +- 数据量太少，用户和商品交集不足 + +**解决方法：** +- 降低threshold参数（如threshold1=0.5, threshold2=1） +- 增加lookback_days +- 检查数据量：`wc -l output/session.txt.*` + +## 性能优化 + +### 大数据量场景 + +如果数据量很大（>100万用户，>10万商品）： + +1. **增加线程数** + ```bash + THREAD_NUM=8 # 或更多 + ``` + +2. **分批处理** + - 可以将session文件按用户分片 + - 分别运行Swing算法 + - 最后合并结果 + +3. **调整max_session_list_len** + - 修改 `src/swing.cc` 中的 `max_session_list_len` + - 限制每个用户的最大行为数 + +### 内存优化 + +如果遇到内存不足： + +1. 减少 `max_sim_list_len`（默认300） +2. 减少 `max_session_list_len`（默认100） +3. 分批处理数据 + +## 集成到定时任务 + +```bash +# 添加到crontab +crontab -e + +# 每天凌晨2点运行 +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/generate_session.py && cd ../collaboration && bash run.sh >> logs/swing_$(date +\%Y\%m\%d).log 2>&1 +``` + +## 相关文档 + +- [Swing算法原理](./collaboration/README.md) +- [离线任务配置](./offline_tasks/config/offline_config.py) +- [Debug工具使用](./offline_tasks/scripts/debug_utils.py) + +## 常见问题 + +**Q: session文件格式选择哪个？** +A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。 + +**Q: Swing算法运行多久？** +A: 取决于数据量和线程数。通常： +- 1万商品：1-5分钟 +- 10万商品：10-30分钟 +- 数据量大时建议使用多线程 + +**Q: 如何调整相似商品数量？** +A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。 + +**Q: 能否使用Python版本的Swing？** +A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。 + +## 联系支持 + +如有问题，请参考： +- 项目README: `/home/tw/recommendation/README.md` +- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md` + diff --git a/offline_tasks/doc/Swing实现总结.md b/offline_tasks/doc/Swing实现总结.md new file mode 100644 index 0000000..c663ea5 --- /dev/null +++ b/offline_tasks/doc/Swing实现总结.md @@ -0,0 +1,375 @@ +# Swing算法实现总结 + +## 完成的任务 + +本次实现完成了以下功能： + +### 1. Session生成脚本 ✓ + +**文件**: `offline_tasks/scripts/generate_session.py` + +**功能**: +- 从数据库提取用户行为数据 +- 聚合用户session（按商品维度累加权重） +- 支持两种输出格式： + - 标准格式：`uid \t {"item_id":score,...}` + - C++格式：`{"item_id":score,...}` （每行一个用户） + +**主要参数**: +- `--lookback_days`: 回看天数（默认730天） +- `--format`: 输出格式（standard/cpp/both） +- `--output`: 输出文件路径 +- `--debug`: 启用debug模式 + +**使用示例**: +```bash +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py --lookback_days 730 --format both +``` + +### 2. Swing运行脚本 ✓ + +**文件**: `collaboration/run.sh` + +**改进内容**: +- ✓ 适配新的数据路径（`../offline_tasks/output/`） +- ✓ 自动检测session文件格式（带uid或纯json） +- ✓ 增加配置区域，便于修改参数 +- ✓ 添加错误检查和友好的输出信息 +- ✓ 自动调用debug脚本生成可读文件 +- ✓ 支持自定义Python环境 + +**配置项**: +```bash +SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 +ALPHA=0.7 # Swing alpha参数 +THRESHOLD1=1 # 交互强度阈值1 +THRESHOLD2=3 # 交互强度阈值2 +THREAD_NUM=4 # 线程数 +SHOW_PROGRESS=1 # 显示进度 +PYTHON_CMD="python3" # Python命令 +``` + +**执行流程**: +1. 编译C++程序 +2. 查找session文件 +3. 运行Swing算法（多线程） +4. 合并结果 +5. 生成可读版本（自动调用debug脚本） + +### 3. Debug脚本 ✓ + +**文件**: `offline_tasks/scripts/add_names_to_swing.py` + +**功能**: +- 读取Swing算法输出结果 +- 从数据库获取商品名称映射 +- 生成可读版本：`item_id:name \t similar_id1:name1:score1,...` + +**使用示例**: +```bash +cd /home/tw/recommendation/offline_tasks +python3 scripts/add_names_to_swing.py \ + ../collaboration/output/swing_similar.txt \ + ../collaboration/output/swing_similar_readable.txt \ + --debug +``` + +### 4. 使用文档 ✓ + +**文件**: +- `offline_tasks/SWING_USAGE.md` - 完整使用指南 +- `collaboration/QUICKSTART.md` - 快速开始指南 + +**包含内容**: +- 详细的使用步骤 +- 参数说明和调优建议 +- 故障排查指南 +- 性能优化建议 +- 完整示例 + +## 数据流程 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 步骤1: 生成Session文件 │ +│ generate_session.py │ +│ ↓ │ +│ 数据库 → 用户行为数据 → 聚合权重 → session.txt.YYYYMMDD │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 步骤2: 运行Swing算法 │ +│ collaboration/run.sh │ +│ ↓ │ +│ session文件 → C++ Swing → sim_matrx.* → swing_similar.txt │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 步骤3: 生成Debug文件 │ +│ add_names_to_swing.py (自动调用) │ +│ ↓ │ +│ swing_similar.txt → 添加商品名 → swing_similar_readable.txt│ +└─────────────────────────────────────────────────────────────┘ +``` + +## 文件格式说明 + +### Session文件格式 + +**标准格式** (`session.txt.YYYYMMDD`): +``` +user_id1 {"123":10.0,"456":5.0,"789":3.0} +user_id2 {"123":8.0,"999":12.0} +``` + +**C++格式** (`session.txt.YYYYMMDD.cpp`): +``` +{"123":10.0,"456":5.0,"789":3.0} +{"123":8.0,"999":12.0} +``` + +### Swing结果格式 + +**原始格式** (`swing_similar.txt`): +``` +12345 67890:0.8523,23456:0.7234,34567:0.6891 +``` + +**可读格式** (`swing_similar_readable.txt`): +``` +12345:iPhone 15 Pro 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 +``` + +## 行为权重配置 + +当前配置（在`generate_session.py`中）: + +| 行为类型 | 权重 | 说明 | +|---------|------|------| +| purchase | 10.0 | 购买行为（最强信号） | +| contactFactory | 5.0 | 联系厂家 | +| addToCart | 3.0 | 加入购物车 | +| addToPool | 2.0 | 加入询价池 | + +## 快速开始 + +```bash +# 1. 生成session文件（730天数据） +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py --lookback_days 730 + +# 2. 运行Swing算法 +cd /home/tw/recommendation/collaboration +bash run.sh + +# 3. 查看结果 +cat output/swing_similar_readable.txt | head -20 +``` + +## 项目结构 + +``` +recommendation/ +├── offline_tasks/ +│ ├── scripts/ +│ │ ├── generate_session.py # 新增：生成session +│ │ ├── add_names_to_swing.py # 新增：添加商品名 +│ │ ├── i2i_swing.py # 已有：Python版Swing +│ │ └── debug_utils.py # 已有：Debug工具 +│ ├── config/ +│ │ └── offline_config.py # 配置文件 +│ ├── output/ +│ │ ├── session.txt.YYYYMMDD # 生成的session文件 +│ │ └── session.txt.YYYYMMDD.cpp # C++格式session +│ ├── SWING_USAGE.md # 新增：详细使用文档 +│ └── ... +├── collaboration/ +│ ├── run.sh # 修改：适配新数据格式 +│ ├── QUICKSTART.md # 新增：快速开始 +│ ├── src/ +│ │ ├── swing.cc # C++ Swing实现 +│ │ ├── swing_symmetric.cc # 对称Swing +│ │ ├── icf_simple.cc # 简单协同过滤 +│ │ └── ucf.py # 用户协同 +│ ├── bin/ # 编译后的可执行文件 +│ ├── output_YYYYMMDD/ # 输出目录 +│ │ ├── sim_matrx.* # 多线程输出 +│ │ ├── swing_similar.txt # 合并结果 +│ │ └── swing_similar_readable.txt # 可读结果 +│ └── output -> output_YYYYMMDD # 软链接 +└── SWING_IMPLEMENTATION_SUMMARY.md # 本文档 +``` + +## 参数调优建议 + +### 针对B2B低频场景 + +```bash +# Session生成 +--lookback_days 730 # 2年数据（B2B交互频次低） + +# Swing算法 +ALPHA=0.5-0.7 # 关注用户共同行为的多样性 +THRESHOLD1=1 # 低阈值，保留更多数据 +THRESHOLD2=3 # 中等阈值，过滤噪音 +THREAD_NUM=4-8 # 根据服务器配置 +``` + +### 针对大数据量场景 + +```bash +# 增加线程数 +THREAD_NUM=8 + +# 修改C++代码参数 +max_sim_list_len=300 # 相似列表长度 +max_session_list_len=100 # session截断长度 +``` + +## 与现有系统集成 + +### 1. 定时任务 + +```bash +# 每天凌晨2点运行 +0 2 * * * cd /home/tw/recommendation/offline_tasks && \ + python3 scripts/generate_session.py && \ + cd ../collaboration && bash run.sh +``` + +### 2. 结果导入Redis + +可使用现有的 `load_index_to_redis.py` 脚本导入结果。 + +### 3. 与Python版Swing对比 + +- **C++版本**（本次实现）：性能更好，适合大数据量 +- **Python版本**（`i2i_swing.py`）：易于调试，支持时间衰减 + +可以运行两个版本对比效果： +```bash +# Python版本 +python3 offline_tasks/scripts/i2i_swing.py --debug + +# C++版本 +cd collaboration && bash run.sh +``` + +## 测试验证 + +### 1. 小数据量测试 + +```bash +# 生成小范围数据（30天） +python3 scripts/generate_session.py --lookback_days 30 + +# 运行Swing +cd ../collaboration +bash run.sh +``` + +### 2. 查看结果质量 + +```bash +# 查看可读版本前100行 +head -100 output/swing_similar_readable.txt + +# 检查相似度分布 +cat output/swing_similar.txt | awk -F'\t' '{print NF-1}' | sort -n | uniq -c +``` + +### 3. 性能测试 + +```bash +# 记录运行时间 +time bash run.sh +``` + +## 故障排查 + +### 常见问题 + +1. **Session文件不存在** + - 先运行 `generate_session.py` + +2. **编译失败** + - 检查g++版本：`g++ --version` + - 手动编译：`cd collaboration && make` + +3. **数据库连接失败** + - 检查配置：`offline_tasks/config/offline_config.py` + - 测试连接：`python3 offline_tasks/test_connection.py` + +4. **结果为空** + - 降低threshold参数 + - 增加lookback_days + - 检查数据量：`wc -l output/session.txt.*` + +详细故障排查参见：`offline_tasks/SWING_USAGE.md` + +## 后续优化方向 + +1. **性能优化** + - 支持分布式计算 + - 增量更新机制 + - 结果缓存 + +2. **功能增强** + - 支持多种相似度算法 + - 在线实时更新 + - A/B测试框架 + +3. **可观测性** + - 添加监控指标 + - 结果质量评估 + - 自动报警 + +## 相关文档 + +- **详细使用指南**: `offline_tasks/SWING_USAGE.md` +- **快速开始**: `collaboration/QUICKSTART.md` +- **配置说明**: `offline_tasks/config/offline_config.py` +- **Debug工具**: `offline_tasks/scripts/debug_utils.py` +- **Swing算法原理**: `collaboration/README.md` + +## 维护说明 + +### 代码维护 + +- **Session生成**: `offline_tasks/scripts/generate_session.py` +- **Swing执行**: `collaboration/run.sh` +- **Debug脚本**: `offline_tasks/scripts/add_names_to_swing.py` + +### 配置维护 + +- **数据库配置**: `offline_tasks/config/offline_config.py` +- **行为权重**: `generate_session.py` 中的 `behavior_weights` +- **Swing参数**: `collaboration/run.sh` 中的配置区域 + +### 日志查看 + +```bash +# Session生成日志 +ls offline_tasks/logs/debug/generate_session_*.log + +# Swing运行日志 +ls collaboration/logs/ +``` + +## 总结 + +本次实现完成了一套完整的C++ Swing算法工作流： + +1. ✓ **前置任务**：Session文件生成（`generate_session.py`） +2. ✓ **核心算法**：C++ Swing执行（改进的`run.sh`） +3. ✓ **后处理**：Debug文件生成（`add_names_to_swing.py`） +4. ✓ **文档完善**：详细使用指南和快速开始 + +所有脚本都支持debug模式，便于调试和监控。整体流程自动化程度高，只需一条命令即可完成全流程。 + +--- + +**实现时间**: 2024-10-17 +**状态**: ✅ 已完成 + diff --git a/offline_tasks/doc/Swing算法使用指南.md b/offline_tasks/doc/Swing算法使用指南.md new file mode 100644 index 0000000..3a6fdc9 --- /dev/null +++ b/offline_tasks/doc/Swing算法使用指南.md @@ -0,0 +1,322 @@ +# Swing算法使用指南 + +本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。 + +## 目录结构 + +``` +recommendation/ +├── offline_tasks/ +│ ├── scripts/ +│ │ ├── generate_session.py # 生成用户session文件 +│ │ └── add_names_to_swing.py # 给结果添加商品名称 +│ └── output/ +│ └── session.txt.YYYYMMDD # 生成的session文件 +└── collaboration/ + ├── run.sh # Swing算法执行脚本 + ├── src/ + │ ├── swing.cc # Swing算法实现 + │ └── ucf.py # 用户协同过滤 + └── output_YYYYMMDD/ + ├── swing_similar.txt # Swing结果（ID格式） + └── swing_similar_readable.txt # Swing结果（带商品名） +``` + +## 使用流程 + +### 步骤1: 生成Session文件 + +首先需要从数据库提取用户行为数据，生成session文件。 + +```bash +cd /home/tw/recommendation/offline_tasks + +# 基本用法（使用默认参数：730天数据） +python3 scripts/generate_session.py + +# 指定回看天数 +python3 scripts/generate_session.py --lookback_days 365 + +# 启用debug模式查看详细信息 +python3 scripts/generate_session.py --lookback_days 730 --debug + +# 指定输出文件路径 +python3 scripts/generate_session.py --output output/session.txt.20241017 + +# 选择输出格式 +python3 scripts/generate_session.py --format both # 同时生成两种格式（默认） +python3 scripts/generate_session.py --format standard # uid \t json 格式 +python3 scripts/generate_session.py --format cpp # 纯json格式（.cpp后缀） +``` + +**输出文件格式：** + +- `session.txt.YYYYMMDD` - 标准格式（包含uid）： + ``` + uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} + uid2 \t {"item_id4":15.0,"item_id5":8.0} + ``` + +- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）： + ``` + {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} + {"item_id4":15.0,"item_id5":8.0} + ``` + +**行为权重配置：** +- `purchase`: 10.0（购买） +- `contactFactory`: 5.0（联系厂家） +- `addToCart`: 3.0（加入购物车） +- `addToPool`: 2.0（加入询价池） + +### 步骤2: 运行Swing算法 + +session文件生成后，运行C++版本的Swing算法。 + +```bash +cd /home/tw/recommendation/collaboration + +# 直接运行（使用默认配置） +bash run.sh + +# 或者给脚本添加执行权限后运行 +chmod +x run.sh +./run.sh +``` + +**配置说明（修改run.sh中的参数）：** + +```bash +# 数据路径配置 +SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 + +# Swing算法参数 +ALPHA=0.7 # Swing算法的alpha参数（越小越关注用户共同行为） +THRESHOLD1=1 # 交互强度阈值1（用于筛选用户行为） +THRESHOLD2=3 # 交互强度阈值2（用于计算相似度） +THREAD_NUM=4 # 线程数（根据CPU核心数调整） +SHOW_PROGRESS=1 # 是否显示进度 (0/1) + +# Python环境 +PYTHON_CMD="python3" # 如需使用特定Python环境，修改此处 +``` + +**脚本执行流程：** + +1. 编译C++程序（swing, icf_simple, swing_symmetric） +2. 查找当天日期的session文件 +3. 运行Swing算法计算物品相似度 +4. 合并多线程输出结果 +5. 自动调用debug脚本生成可读版本 + +### 步骤3: 查看结果 + +运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录： + +**1. swing_similar.txt** - 原始结果（ID格式） +``` +12345 \t 67890:0.8523,23456:0.7234,34567:0.6891 +``` +格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...` + +**2. swing_similar_readable.txt** - 可读结果（带商品名） +``` +12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 +``` +格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...` + +### 步骤4: 单独生成Debug文件（可选） + +如果需要为其他文件生成可读版本： + +```bash +cd /home/tw/recommendation/offline_tasks + +# 基本用法 +python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt + +# 指定输出文件 +python3 scripts/add_names_to_swing.py \ + collaboration/output/swing_similar.txt \ + collaboration/output/my_readable.txt + +# 启用debug模式 +python3 scripts/add_names_to_swing.py \ + collaboration/output/swing_similar.txt \ + --debug +``` + +## 参数调优建议 + +### Swing算法参数 + +1. **alpha (0.5-1.0)** + - 越小：越关注用户共同行为的多样性 + - 越大：越容忽略用户重叠度 + - 建议：0.5-0.7（B2B场景） + +2. **threshold1 (1-5)** + - 用于筛选用户的有效行为 + - 建议：1-3（低频场景可用1） + +3. **threshold2 (1-10)** + - 用于计算相似度的行为强度阈值 + - 建议：3-5（需要较强的交互信号） + +4. **thread_num (1-20)** + - 根据CPU核心数设置 + - 建议：4-8（普通服务器） + +### 数据范围参数 + +1. **lookback_days** + - B2B低频场景：建议730天（2年） + - B2C高频场景：建议30-90天 + - 数据量大时可适当减少 + +## 完整示例 + +```bash +# 1. 生成session文件（730天数据） +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py --lookback_days 730 --debug + +# 2. 检查生成的文件 +ls -lh output/session.txt.* +# 应该看到： +# session.txt.20241017 +# session.txt.20241017.cpp + +# 3. 运行Swing算法 +cd /home/tw/recommendation/collaboration +bash run.sh + +# 4. 查看结果 +ls -lh output/swing_similar* +cat output/swing_similar_readable.txt | head -20 +``` + +## 故障排查 + +### 问题1: Session文件不存在 + +``` +错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp +``` + +**解决方法：** +```bash +cd /home/tw/recommendation/offline_tasks +python3 scripts/generate_session.py +``` + +### 问题2: 编译失败 + +``` +编译失败，退出 +``` + +**解决方法：** +```bash +cd /home/tw/recommendation/collaboration +# 检查编译器 +g++ --version + +# 手动编译 +make clean +make + +# 检查依赖 +ls include/ +ls utils/ +``` + +### 问题3: 数据库连接失败 + +``` +获取数据失败: Connection refused +``` + +**解决方法：** +- 检查数据库配置：`offline_tasks/config/offline_config.py` +- 测试连接：`python3 offline_tasks/test_connection.py` +- 确认网络和防火墙设置 + +### 问题4: 结果为空 + +**可能原因：** +- threshold1/threshold2设置过高，过滤掉了所有数据 +- 数据量太少，用户和商品交集不足 + +**解决方法：** +- 降低threshold参数（如threshold1=0.5, threshold2=1） +- 增加lookback_days +- 检查数据量：`wc -l output/session.txt.*` + +## 性能优化 + +### 大数据量场景 + +如果数据量很大（>100万用户，>10万商品）： + +1. **增加线程数** + ```bash + THREAD_NUM=8 # 或更多 + ``` + +2. **分批处理** + - 可以将session文件按用户分片 + - 分别运行Swing算法 + - 最后合并结果 + +3. **调整max_session_list_len** + - 修改 `src/swing.cc` 中的 `max_session_list_len` + - 限制每个用户的最大行为数 + +### 内存优化 + +如果遇到内存不足： + +1. 减少 `max_sim_list_len`（默认300） +2. 减少 `max_session_list_len`（默认100） +3. 分批处理数据 + +## 集成到定时任务 + +```bash +# 添加到crontab +crontab -e + +# 每天凌晨2点运行 +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/generate_session.py && cd ../collaboration && bash run.sh >> logs/swing_$(date +\%Y\%m\%d).log 2>&1 +``` + +## 相关文档 + +- [Swing算法原理](./collaboration/README.md) +- [离线任务配置](./offline_tasks/config/offline_config.py) +- [Debug工具使用](./offline_tasks/scripts/debug_utils.py) + +## 常见问题 + +**Q: session文件格式选择哪个？** +A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。 + +**Q: Swing算法运行多久？** +A: 取决于数据量和线程数。通常： +- 1万商品：1-5分钟 +- 10万商品：10-30分钟 +- 数据量大时建议使用多线程 + +**Q: 如何调整相似商品数量？** +A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。 + +**Q: 能否使用Python版本的Swing？** +A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。 + +## 联系支持 + +如有问题，请参考： +- 项目README: `/home/tw/recommendation/README.md` +- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md` + diff --git a/offline_tasks/doc/TROUBLESHOOTING.md b/offline_tasks/doc/TROUBLESHOOTING.md new file mode 100644 index 0000000..bbf4f6f --- /dev/null +++ b/offline_tasks/doc/TROUBLESHOOTING.md @@ -0,0 +1,217 @@ +# 故障排除指南 + +## 常见问题及解决方案 + +### 1. 数据库字段错误 + +#### 问题： +``` +pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'") +``` + +#### 原因： +数据库表结构与代码中使用的字段名不匹配。 + +#### 解决方案： +1. 查看 `DATABASE_SETUP.md` 了解如何配置字段 +2. 修改对应脚本中的SQL查询，使用实际存在的字段名 +3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过 + +#### 已修复的字段： +- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的 +- ✅ 基础功能不依赖分类字段 + +--- + +### 2. 连接超时 + +#### 问题： +``` +pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...") +``` + +#### 解决方案： +1. 检查数据库配置：`config/offline_config.py` +2. 确认网络连接和防火墙设置 +3. 运行测试：`python3 test_connection.py` + +--- + +### 3. 内存不足 + +#### 问题： +程序运行时内存占用过高或被杀死。 + +#### 解决方案： +1. 减少回溯天数：`--lookback_days 365`（从730改为365） +2. 减少输出数量：`--top_n 20`（从50改为20） +3. 先运行单个算法： + ```bash + python3 scripts/i2i_session_w2v.py # 内存占用较小 + ``` +4. 跳过Swing算法（内存占用最大）： + ```bash + python3 run_all.py --skip-i2i + ``` + +--- + +### 4. 运行时间过长 + +#### 解决方案： +1. 减少数据量：`--lookback_days 180` +2. 只运行特定算法： + ```bash + python3 run_all.py --only-w2v + ``` +3. 考虑使用C++版本的Swing（性能提升10倍） + +--- + +### 5. 依赖包安装失败 + +#### 解决方案： +```bash +# 单独安装失败的包 +pip3 install pandas sqlalchemy pymysql gensim numpy + +# 或使用国内镜像 +pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +--- + +### 6. Redis连接失败 + +#### 问题： +``` +redis.exceptions.ConnectionError: Error connecting to Redis +``` + +#### 解决方案： +1. Redis是可选的，只影响索引加载功能 +2. 如果不需要Redis，可以跳过： + ```bash + python3 run_all.py # 只运行离线任务，不加载到Redis + ``` +3. 如果需要Redis，确认Redis已安装并运行： + ```bash + redis-cli ping # 应该返回 PONG + ``` + +--- + +### 7. 输出文件为空 + +#### 可能原因： +1. 数据量太少（没有满足最小阈值） +2. 时间范围内没有数据 +3. SQL查询条件过于严格 + +#### 解决方案： +1. 检查日志：`tail -f logs/run_all_*.log` +2. 调整参数： + - 增加时间范围：`--lookback_days 1000` + - 减少阈值：修改配置文件中的 `min_interaction_count` +3. 检查数据库中是否有数据： + ```python + # 运行简单查询测试 + python3 test_connection.py + ``` + +--- + +### 8. 权限问题 + +#### 问题： +``` +PermissionError: [Errno 13] Permission denied +``` + +#### 解决方案： +```bash +# 给脚本添加执行权限 +chmod +x install.sh run_all.py + +# 确保有写入权限 +chmod 755 output/ logs/ +``` + +--- + +### 9. Python版本问题 + +#### 要求： +Python 3.7+ + +#### 检查版本： +```bash +python3 --version +``` + +#### 如果版本过低，需要升级Python + +--- + +### 10. 编码问题 + +#### 问题： +``` +UnicodeDecodeError: 'utf-8' codec can't decode byte... +``` + +#### 解决方案： +确保所有文件使用UTF-8编码，特别是配置文件和输出文件。 + +--- + +## 调试技巧 + +### 1. 查看详细日志 +```bash +tail -f logs/run_all_*.log +``` + +### 2. 运行单个任务（便于调试） +```bash +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 +``` + +### 3. 使用较小的数据量测试 +```bash +python3 run_all.py --lookback_days 30 --top_n 10 +``` + +### 4. 检查中间结果 +```bash +ls -lh output/ +head -n 20 output/i2i_swing_*.txt +``` + +--- + +## 获取支持 + +如果以上方法都无法解决问题： + +1. **查看文档**： + - `README.md` - 详细说明 + - `DATABASE_SETUP.md` - 数据库配置 + - `QUICKSTART.md` - 快速开始 + +2. **查看日志**： + - `logs/` 目录下的所有日志文件 + +3. **简化测试**： + - 先运行 `test_connection.py` + - 再运行单个脚本 + - 使用小数据量测试 + +4. **记录错误信息**： + - 完整的错误堆栈 + - 使用的命令 + - 配置文件内容 + +--- + +**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。 diff --git a/offline_tasks/doc/从这里开始.md b/offline_tasks/doc/从这里开始.md new file mode 100644 index 0000000..418a985 --- /dev/null +++ b/offline_tasks/doc/从这里开始.md @@ -0,0 +1,302 @@ +# 🚀 从这里开始 + +## 📦 项目交付完成 + +根据您提供的业务文档和表结构，推荐系统离线任务已完成构建！ + +--- + +## ✅ 完成的功能 + +### 1. i2i 索引（4种算法） + +#### 行为相似（3种） +- ✅ **Swing算法** - 基于用户共同行为 +- ✅ **Session W2V** - 基于用户会话序列 +- ✅ **DeepWalk** - 基于图随机游走 + +#### 内容相似（1种，3个方法） +- ✅ **Content-based** - 基于商品属性（分类、供应商等） + - TF-IDF方法 + - 分类方法 + - 混合方法（推荐） + +### 2. 兴趣点聚合索引 + +**支持的维度**（7个单维度 + 4个组合维度）： +- ✅ 业务平台（platform） +- ✅ 客户端平台（client_platform） +- ✅ 供应商（supplier） +- ✅ 一级分类（category_level1） +- ✅ 二级分类（category_level2） +- ✅ 三级分类（category_level3） +- ✅ 四级分类（category_level4） +- ✅ 平台+客户端 +- ✅ 平台+分类 +- ✅ 客户端+分类 + +**支持的列表类型**（3种）： +- ✅ 热门（hot）- 最近180天高交互 +- ✅ 加购（cart）- 加购行为 +- ✅ 新品（new）- 最近90天上架 + +--- + +## 🎯 快速开始（3步） + +### 步骤1: 安装依赖 +```bash +cd /home/tw/recommendation/offline_tasks +bash install.sh +``` + +### 步骤2: 测试连接 +```bash +python3 test_connection.py +``` + +### 步骤3: 运行任务（小数据量测试） +```bash +# 先测试30天数据 +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 + +# 查看输出 +ls -lh output/ +head -5 output/i2i_swing_*.txt +``` + +### 步骤4: 运行完整任务 +```bash +# 运行所有任务（约6-10小时） +python3 run_all.py --lookback_days 730 --top_n 50 + +# 或分别运行（推荐） +python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50 +python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid +python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 +``` + +--- + +## 📚 文档导航 + +### 入门文档 +1. **START_HERE.md** ← 当前文档 +2. **QUICKSTART.md** - 5分钟快速上手 +3. **CURRENT_STATUS.md** - 当前功能状态 + +### 技术文档 +4. **FINAL_UPDATE.md** - 最终更新说明 +5. **COMPLETE_INDEX_LIST.md** - 完整索引清单 +6. **README.md** - 详细使用文档 +7. **PROJECT_SUMMARY.md** - 技术架构 + +### 配置文档 +8. **FIELD_MAPPING.md** - 字段映射说明 +9. **DATABASE_SETUP.md** - 数据库配置 +10. **TROUBLESHOOTING.md** - 故障排除 + +### 参考文档 +11. **STRUCTURE.md** - 目录结构 +12. **CHANGELOG.md** - 更新日志 +13. **COMMANDS.txt** - 常用命令 + +--- + +## 📊 输出示例 + +### i2i相似度索引 +``` +# 文件: output/i2i_swing_20251016.txt +12345 商品A 23456:0.8523,34567:0.7842,45678:0.7234,... + +# Redis Key: i2i:swing:12345 +Value: 23456:0.8523,34567:0.7842,45678:0.7234,... +``` + +### 兴趣点聚合索引 +``` +# 文件: output/interest_aggregation_hot_20251016.txt +platform:pc 12345:98.52,23456:87.34,34567:76.89,... +category_level2:200 45678:156.23,56789:142.87,... + +# Redis Key: interest:hot:platform:pc +Value: 12345:98.52,23456:87.34,34567:76.89,... +``` + +--- + +## 🎬 业务场景映射 + +根据您的3个业务场景： + +### 1. 首页猜你喜欢 +```python +# 使用兴趣点聚合索引 +interest:hot:platform:pc +interest:hot:category_level2:200 +interest:hot:platform_category2:pc_200 +``` + +### 2. 详情页的大家都在看 +```python +# 使用i2i相似索引 +i2i:swing:12345 # 行为相似 +i2i:content_hybrid:12345 # 内容相似 +``` + +### 3. 搜索结果页底部的供应商推荐 +```python +# 使用兴趣点聚合索引 +interest:global:category_level2:200 +interest:hot:supplier:10001 +``` + +--- + +## 🔢 关键数字 + +| 指标 | 数值 | +|------|------| +| i2i算法数量 | 4种（3行为+1内容） | +| 兴趣点维度数量 | 11个（7单+4组合） | +| 支持的分类层级 | 4级 | +| 列表类型 | 3种（热门/加购/新品） | +| 预计索引总数 | 10000-50000条 | +| 全部任务运行时间 | 6-10小时 | + +--- + +## 💡 核心优势 + +### 1. 完整性 +- ✅ 行为相似 + 内容相似 +- ✅ 短期热门 + 长期稳定 +- ✅ 粗粒度 + 细粒度 + +### 2. 灵活性 +- ✅ 支持4级分类查询 +- ✅ 支持供应商维度 +- ✅ 支持多维度组合 + +### 3. 可扩展性 +- ✅ 易于添加新维度 +- ✅ 易于添加新算法 +- ✅ 配置化管理 + +### 4. 实用性 +- ✅ 适配真实数据 +- ✅ 参考现有代码 +- ✅ 文档完善 + +--- + +## ⚙️ 配置文件 + +主要配置在 `config/offline_config.py`： + +```python +# 时间配置 +LOOKBACK_DAYS = 730 # 2年数据 + +# 行为权重 +behavior_weights = { + 'click': 1.0, + 'addToCart': 3.0, + 'contactFactory': 5.0, + 'purchase': 10.0 +} + +# 时间衰减 +time_decay_factor = 0.95 # 每30天衰减5% +``` + +--- + +## 🔧 运行选项 + +### 运行单个算法 +```bash +python3 run_all.py --only-swing # 只运行Swing +python3 run_all.py --only-content # 只运行内容相似 +python3 run_all.py --only-interest # 只运行兴趣点聚合 +``` + +### 跳过某些算法 +```bash +python3 run_all.py --skip-i2i # 跳过i2i +python3 run_all.py --skip-interest # 跳过兴趣点聚合 +``` + +### 调整参数 +```bash +# 小数据量测试 +python3 run_all.py --lookback_days 30 --top_n 10 + +# 完整数据 +python3 run_all.py --lookback_days 730 --top_n 50 +``` + +--- + +## 📞 遇到问题？ + +### 1. 字段错误 +查看：**FIELD_MAPPING.md** 和 **DATABASE_SETUP.md** + +### 2. 运行错误 +查看：**TROUBLESHOOTING.md** + +### 3. 使用疑问 +查看：**README.md** 和 **COMPLETE_INDEX_LIST.md** + +### 4. 查看日志 +```bash +tail -f logs/run_all_*.log +``` + +--- + +## 🎉 开始使用 + +```bash +# 1. 进入目录 +cd /home/tw/recommendation/offline_tasks + +# 2. 安装依赖 +bash install.sh + +# 3. 测试连接 +python3 test_connection.py + +# 4. 运行任务 +python3 run_all.py --lookback_days 730 --top_n 50 + +# 5. 查看输出 +ls -lh output/ +head -5 output/* + +# 6. 加载到Redis（可选） +python3 scripts/load_index_to_redis.py +``` + +--- + +## 📦 交付清单 + +- ✅ 4种i2i算法实现 +- ✅ 兴趣点聚合（11个维度） +- ✅ 统一调度脚本 +- ✅ Redis加载工具 +- ✅ 测试和示例脚本 +- ✅ 13份完整文档 +- ✅ 配置文件和依赖清单 + +--- + +**状态**: ✅ 已完成并可用 +**版本**: v1.1 +**日期**: 2025-10-16 +**代码行数**: ~2500行 + +**开始探索**: 建议先阅读 **QUICKSTART.md** diff --git a/offline_tasks/doc/完整索引列表.md b/offline_tasks/doc/完整索引列表.md new file mode 100644 index 0000000..99e19c7 --- /dev/null +++ b/offline_tasks/doc/完整索引列表.md @@ -0,0 +1,350 @@ +# 完整索引清单 + +## 📋 所有可用的推荐索引 + +### 1. i2i 相似度索引 + +#### 1.1 行为相似索引（3种） + +**Swing算法**： +``` +i2i:swing:{item_id} +``` +示例：`i2i:swing:12345` + +**Session Word2Vec**： +``` +i2i:session_w2v:{item_id} +``` +示例：`i2i:session_w2v:12345` + +**DeepWalk**： +``` +i2i:deepwalk:{item_id} +``` +示例：`i2i:deepwalk:12345` + +#### 1.2 内容相似索引（3种方法） + +**混合方法（推荐）**： +``` +i2i:content_hybrid:{item_id} +``` +示例：`i2i:content_hybrid:12345` + +**TF-IDF方法**： +``` +i2i:content_tfidf:{item_id} +``` +示例：`i2i:content_tfidf:12345` + +**分类方法**： +``` +i2i:content_category:{item_id} +``` +示例：`i2i:content_category:12345` + +--- + +### 2. 兴趣点聚合索引 + +格式：`interest:{list_type}:{dimension}:{value}` + +#### 2.1 列表类型（list_type） + +- `hot` - 热门商品 +- `cart` - 加购商品 +- `new` - 新品 +- `global` - 全局（所有数据） + +#### 2.2 单维度索引 + +##### 业务平台（platform） +``` +interest:hot:platform:pc +interest:hot:platform:mobile +interest:cart:platform:pc +interest:new:platform:mobile +interest:global:platform:pc +``` + +##### 客户端平台（client_platform） +``` +interest:hot:client_platform:web +interest:hot:client_platform:app +interest:cart:client_platform:web +interest:new:client_platform:app +interest:global:client_platform:web +``` + +##### 供应商（supplier） +``` +interest:hot:supplier:10001 +interest:hot:supplier:10002 +interest:cart:supplier:10001 +interest:new:supplier:10002 +interest:global:supplier:10001 +``` + +##### 一级分类（category_level1） +``` +interest:hot:category_level1:100 +interest:cart:category_level1:100 +interest:new:category_level1:100 +interest:global:category_level1:100 +``` + +##### 二级分类（category_level2） +``` +interest:hot:category_level2:200 +interest:cart:category_level2:200 +interest:new:category_level2:200 +interest:global:category_level2:200 +``` + +##### 三级分类（category_level3） +``` +interest:hot:category_level3:300 +interest:cart:category_level3:300 +interest:new:category_level3:300 +interest:global:category_level3:300 +``` + +##### 四级分类（category_level4） +``` +interest:hot:category_level4:400 +interest:cart:category_level4:400 +interest:new:category_level4:400 +interest:global:category_level4:400 +``` + +#### 2.3 组合维度索引 + +##### 平台 + 客户端 +``` +interest:hot:platform_client:pc_web +interest:hot:platform_client:pc_app +interest:hot:platform_client:mobile_web +interest:hot:platform_client:mobile_app +``` + +##### 平台 + 二级分类 +``` +interest:hot:platform_category2:pc_200 +interest:hot:platform_category2:mobile_200 +interest:cart:platform_category2:pc_200 +interest:new:platform_category2:mobile_200 +``` + +##### 平台 + 三级分类 +``` +interest:hot:platform_category3:pc_300 +interest:hot:platform_category3:mobile_300 +interest:cart:platform_category3:pc_300 +interest:new:platform_category3:mobile_300 +``` + +##### 客户端平台 + 二级分类 +``` +interest:hot:client_category2:web_200 +interest:hot:client_category2:app_200 +interest:cart:client_category2:web_200 +interest:new:client_category2:app_200 +``` + +--- + +## 🎯 按业务场景的索引使用 + +### 场景1: 首页个性化推荐 + +**方案A: 基于平台** +```python +key = f"interest:hot:platform:{user_platform}" +# 示例：interest:hot:platform:pc +``` + +**方案B: 基于分类偏好** +```python +key = f"interest:hot:category_level2:{user_favorite_category}" +# 示例：interest:hot:category_level2:200 +``` + +**方案C: 基于平台+分类** +```python +key = f"interest:hot:platform_category2:{user_platform}_{category_id}" +# 示例：interest:hot:platform_category2:pc_200 +``` + +### 场景2: 详情页相关推荐 + +**方案A: 行为相似** +```python +key = f"i2i:swing:{current_item_id}" +# 示例：i2i:swing:12345 +``` + +**方案B: 内容相似** +```python +key = f"i2i:content_hybrid:{current_item_id}" +# 示例：i2i:content_hybrid:12345 +``` + +**方案C: 融合推荐** +```python +behavior_similar = redis.get(f"i2i:swing:{item_id}") +content_similar = redis.get(f"i2i:content_hybrid:{item_id}") +# 融合两种结果 +``` + +### 场景3: 分类页推荐 + +**方案A: 该分类热门** +```python +key = f"interest:hot:category_level2:{category_id}" +# 示例：interest:hot:category_level2:200 +``` + +**方案B: 该分类新品** +```python +key = f"interest:new:category_level2:{category_id}" +# 示例：interest:new:category_level2:200 +``` + +**方案C: 该分类+平台** +```python +key = f"interest:hot:platform_category2:{platform}_{category_id}" +# 示例：interest:hot:platform_category2:pc_200 +``` + +### 场景4: 供应商店铺页 + +**方案A: 供应商热门商品** +```python +key = f"interest:hot:supplier:{supplier_id}" +# 示例：interest:hot:supplier:10001 +``` + +**方案B: 供应商新品** +```python +key = f"interest:new:supplier:{supplier_id}" +# 示例：interest:new:supplier:10001 +``` + +### 场景5: 搜索结果页推荐 + +**方案A: 全局热门** +```python +key = "interest:global:platform:pc" +``` + +**方案B: 分类相关** +```python +key = f"interest:global:category_level2:{search_category}" +# 示例：interest:global:category_level2:200 +``` + +--- + +## 📊 索引数量统计 + +### i2i索引 +- 行为相似：3种算法 × 商品数量 +- 内容相似：3种方法 × 商品数量 +- **总计**：6 × 商品数量 + +### 兴趣点聚合索引 + +**单维度**： +- platform: 2-10个 +- client_platform: 2-5个 +- supplier: 100-1000个 +- category_level1: 10-50个 +- category_level2: 50-200个 +- category_level3: 200-1000个 +- category_level4: 1000-5000个 + +**组合维度**： +- platform_client: 4-50个 +- platform_category2: 100-2000个 +- platform_category3: 400-10000个 +- client_category2: 100-1000个 + +**列表类型**：每个维度 × 4种类型（hot/cart/new/global） + +**预估总数**：10000-50000条索引 + +--- + +## 🔍 查询示例代码 + +### Python示例 + +```python +import redis + +# 连接Redis +r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) + +# 1. 查询商品的相似商品 +item_id = "12345" +similar_items = r.get(f"i2i:swing:{item_id}") +if similar_items: + items = similar_items.split(',') + for item in items[:5]: # 取前5个 + item_id, score = item.split(':') + print(f"商品ID: {item_id}, 相似度: {score}") + +# 2. 查询分类热门商品 +category_id = "200" +hot_items = r.get(f"interest:hot:category_level2:{category_id}") +if hot_items: + items = hot_items.split(',') + for item in items[:10]: # 取前10个 + item_id, score = item.split(':') + print(f"商品ID: {item_id}, 得分: {score}") + +# 3. 查询平台+分类组合 +platform = "pc" +category_id = "200" +key = f"interest:hot:platform_category2:{platform}_{category_id}" +items = r.get(key) +``` + +### Redis命令行示例 + +```bash +# 查询商品相似度 +redis-cli GET "i2i:swing:12345" + +# 查询分类热门 +redis-cli GET "interest:hot:category_level2:200" + +# 查询供应商商品 +redis-cli GET "interest:hot:supplier:10001" + +# 模糊查询所有热门索引 +redis-cli KEYS "interest:hot:*" + +# 查看某个分类的所有类型 +redis-cli KEYS "interest:*:category_level2:200" +``` + +--- + +## 📝 注意事项 + +1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式 +2. **值的格式**：`item_id1:score1,item_id2:score2,...` +3. **过期时间**：建议设置7天过期 +4. **更新频率**：建议每天更新一次 +5. **查询优先级**： + - 优先使用细粒度索引（如四级分类） + - 粗粒度索引作为后备（如一级分类） + - 融合多个索引结果 + +--- + +**版本**: v1.1 +**生成日期**: 2025-10-16 +**索引总数**: 约10000-50000条 diff --git a/offline_tasks/doc/快速开始.md b/offline_tasks/doc/快速开始.md new file mode 100644 index 0000000..65be781 --- /dev/null +++ b/offline_tasks/doc/快速开始.md @@ -0,0 +1,213 @@ +# 离线任务快速启动指南 + +## 一、环境准备 + +### 1. 安装依赖 + +```bash +cd /home/tw/recommendation +pip install -r requirements.txt +``` + +### 2. 配置数据库和Redis + +编辑配置文件 `offline_tasks/config/offline_config.py`，确保数据库和Redis连接信息正确： + +```python +# 数据库配置 +DB_CONFIG = { + 'host': 'your_db_host', + 'port': '9030', + 'database': 'datacenter', + 'username': 'readonly', + 'password': 'your_password' +} + +# Redis配置 +REDIS_CONFIG = { + 'host': 'your_redis_host', + 'port': 6379, + 'db': 0, + 'password': None +} +``` + +## 二、运行离线任务 + +### 方式1：运行所有任务（推荐） + +```bash +cd /home/tw/recommendation/offline_tasks +python run_all.py --lookback_days 730 --top_n 50 +``` + +这将依次运行： +1. Swing算法（i2i相似度） +2. Session Word2Vec（i2i相似度） +3. DeepWalk算法（i2i相似度） +4. 兴趣点聚合（多维度商品索引） + +### 方式2：运行单个任务 + +#### 运行Swing算法 + +```bash +cd /home/tw/recommendation/offline_tasks +python scripts/i2i_swing.py --lookback_days 730 --top_n 50 --time_decay +``` + +#### 运行Session Word2Vec + +```bash +python scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model +``` + +#### 运行DeepWalk + +```bash +python scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph +``` + +#### 运行兴趣点聚合 + +```bash +python scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 +``` + +## 三、将索引加载到Redis + +任务运行完成后，将生成的索引加载到Redis： + +```bash +cd /home/tw/recommendation/offline_tasks +python scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 --expire-days 7 +``` + +参数说明： +- `--redis-host`: Redis服务器地址 +- `--redis-port`: Redis端口 +- `--redis-db`: Redis数据库编号（默认0） +- `--expire-days`: 索引过期天数（默认7天） + +## 四、查看输出结果 + +所有输出文件都在 `offline_tasks/output/` 目录下： + +```bash +cd /home/tw/recommendation/offline_tasks/output +ls -lh +``` + +输出文件示例： +``` +i2i_swing_20251016.txt +i2i_session_w2v_20251016.txt +i2i_deepwalk_20251016.txt +interest_aggregation_hot_20251016.txt +interest_aggregation_cart_20251016.txt +interest_aggregation_new_20251016.txt +interest_aggregation_global_20251016.txt +``` + +## 五、查看日志 + +所有运行日志都在 `offline_tasks/logs/` 目录下： + +```bash +cd /home/tw/recommendation/offline_tasks/logs +tail -f run_all_20251016.log +``` + +## 六、设置定时任务 + +### 使用crontab设置每天运行 + +```bash +# 编辑crontab +crontab -e + +# 添加以下行（每天凌晨2点运行） +0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py --lookback_days 730 --top_n 50 >> /home/tw/recommendation/offline_tasks/logs/cron.log 2>&1 +``` + +### 运行后自动加载到Redis + +可以在crontab中添加索引加载任务： + +```bash +# 凌晨6点加载索引到Redis（假设离线任务在4小时内完成） +0 6 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 scripts/load_index_to_redis.py >> /home/tw/recommendation/offline_tasks/logs/load_redis.log 2>&1 +``` + +## 七、验证结果 + +### 查看文件内容 + +```bash +# 查看i2i相似度 +head -n 5 output/i2i_swing_20251016.txt + +# 查看兴趣点聚合 +head -n 5 output/interest_aggregation_hot_20251016.txt +``` + +### 从Redis查询 + +```bash +# 使用redis-cli +redis-cli + +# 查看i2i相似度 +GET i2i:swing:123456 + +# 查看兴趣点索引 +GET interest:hot:platform:PC +GET interest:global:country:US +``` + +## 八、常见问题 + +### Q1: 任务运行时间太长怎么办？ + +A: 可以尝试： +1. 减少 `--lookback_days` 参数（如改为365天） +2. 减少 `--top_n` 参数（如改为20） +3. 在更强大的机器上运行 +4. 考虑分布式运行不同算法 + +### Q2: 内存不足怎么办？ + +A: +1. Swing算法特别消耗内存，可以先跳过：`python run_all.py --skip-i2i` +2. 只运行DeepWalk或Session W2V +3. 对数据进行采样 + +### Q3: 数据库连接超时怎么办？ + +A: +1. 检查数据库配置是否正确 +2. 检查网络连接 +3. 增加SQL查询的超时时间 +4. 分批查询数据 + +### Q4: 如何只更新特定维度的索引？ + +A: 修改 `interest_aggregation.py` 脚本，注释掉不需要的维度计算代码。 + +## 九、性能参考 + +在标准配置（730天数据，top_n=50）下的预估运行时间： + +| 任务 | 数据量 | 预估时间 | 内存占用 | +|------|--------|---------|---------| +| Swing | 100万条行为 | 2-4小时 | 4-8GB | +| Session W2V | 100万条行为 | 30-60分钟 | 2-4GB | +| DeepWalk | 100万条行为 | 1-2小时 | 2-4GB | +| 兴趣点聚合 | 100万条行为 | 30-60分钟 | 2-4GB | + +实际时间会因数据量和机器配置而异。 + +## 十、联系与支持 + +如有问题，请查看日志文件或联系开发团队。 + diff --git a/offline_tasks/doc/故障排查指南.md b/offline_tasks/doc/故障排查指南.md new file mode 100644 index 0000000..bbf4f6f --- /dev/null +++ b/offline_tasks/doc/故障排查指南.md @@ -0,0 +1,217 @@ +# 故障排除指南 + +## 常见问题及解决方案 + +### 1. 数据库字段错误 + +#### 问题： +``` +pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'") +``` + +#### 原因： +数据库表结构与代码中使用的字段名不匹配。 + +#### 解决方案： +1. 查看 `DATABASE_SETUP.md` 了解如何配置字段 +2. 修改对应脚本中的SQL查询，使用实际存在的字段名 +3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过 + +#### 已修复的字段： +- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的 +- ✅ 基础功能不依赖分类字段 + +--- + +### 2. 连接超时 + +#### 问题： +``` +pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...") +``` + +#### 解决方案： +1. 检查数据库配置：`config/offline_config.py` +2. 确认网络连接和防火墙设置 +3. 运行测试：`python3 test_connection.py` + +--- + +### 3. 内存不足 + +#### 问题： +程序运行时内存占用过高或被杀死。 + +#### 解决方案： +1. 减少回溯天数：`--lookback_days 365`（从730改为365） +2. 减少输出数量：`--top_n 20`（从50改为20） +3. 先运行单个算法： + ```bash + python3 scripts/i2i_session_w2v.py # 内存占用较小 + ``` +4. 跳过Swing算法（内存占用最大）： + ```bash + python3 run_all.py --skip-i2i + ``` + +--- + +### 4. 运行时间过长 + +#### 解决方案： +1. 减少数据量：`--lookback_days 180` +2. 只运行特定算法： + ```bash + python3 run_all.py --only-w2v + ``` +3. 考虑使用C++版本的Swing（性能提升10倍） + +--- + +### 5. 依赖包安装失败 + +#### 解决方案： +```bash +# 单独安装失败的包 +pip3 install pandas sqlalchemy pymysql gensim numpy + +# 或使用国内镜像 +pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +--- + +### 6. Redis连接失败 + +#### 问题： +``` +redis.exceptions.ConnectionError: Error connecting to Redis +``` + +#### 解决方案： +1. Redis是可选的，只影响索引加载功能 +2. 如果不需要Redis，可以跳过： + ```bash + python3 run_all.py # 只运行离线任务，不加载到Redis + ``` +3. 如果需要Redis，确认Redis已安装并运行： + ```bash + redis-cli ping # 应该返回 PONG + ``` + +--- + +### 7. 输出文件为空 + +#### 可能原因： +1. 数据量太少（没有满足最小阈值） +2. 时间范围内没有数据 +3. SQL查询条件过于严格 + +#### 解决方案： +1. 检查日志：`tail -f logs/run_all_*.log` +2. 调整参数： + - 增加时间范围：`--lookback_days 1000` + - 减少阈值：修改配置文件中的 `min_interaction_count` +3. 检查数据库中是否有数据： + ```python + # 运行简单查询测试 + python3 test_connection.py + ``` + +--- + +### 8. 权限问题 + +#### 问题： +``` +PermissionError: [Errno 13] Permission denied +``` + +#### 解决方案： +```bash +# 给脚本添加执行权限 +chmod +x install.sh run_all.py + +# 确保有写入权限 +chmod 755 output/ logs/ +``` + +--- + +### 9. Python版本问题 + +#### 要求： +Python 3.7+ + +#### 检查版本： +```bash +python3 --version +``` + +#### 如果版本过低，需要升级Python + +--- + +### 10. 编码问题 + +#### 问题： +``` +UnicodeDecodeError: 'utf-8' codec can't decode byte... +``` + +#### 解决方案： +确保所有文件使用UTF-8编码，特别是配置文件和输出文件。 + +--- + +## 调试技巧 + +### 1. 查看详细日志 +```bash +tail -f logs/run_all_*.log +``` + +### 2. 运行单个任务（便于调试） +```bash +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 +``` + +### 3. 使用较小的数据量测试 +```bash +python3 run_all.py --lookback_days 30 --top_n 10 +``` + +### 4. 检查中间结果 +```bash +ls -lh output/ +head -n 20 output/i2i_swing_*.txt +``` + +--- + +## 获取支持 + +如果以上方法都无法解决问题： + +1. **查看文档**： + - `README.md` - 详细说明 + - `DATABASE_SETUP.md` - 数据库配置 + - `QUICKSTART.md` - 快速开始 + +2. **查看日志**： + - `logs/` 目录下的所有日志文件 + +3. **简化测试**： + - 先运行 `test_connection.py` + - 再运行单个脚本 + - 使用小数据量测试 + +4. **记录错误信息**： + - 完整的错误堆栈 + - 使用的命令 + - 配置文件内容 + +--- + +**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。 diff --git a/offline_tasks/doc/数据库配置说明.md b/offline_tasks/doc/数据库配置说明.md new file mode 100644 index 0000000..352aacc --- /dev/null +++ b/offline_tasks/doc/数据库配置说明.md @@ -0,0 +1,179 @@ +# 数据库字段配置说明 + +## 问题说明 + +如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。 + +## 已适配的基础字段 + +当前代码已经适配了以下基础字段（参考 `item_sim.py`）： + +### sensors_events 表 +- `anonymous_id` - 用户ID +- `item_id` - 商品ID +- `event` - 事件类型 +- `create_time` - 创建时间 +- `platform` - 平台（可选） +- `country` - 国家（可选） +- `customer_type` - 客户类型（可选） + +### prd_goods_sku 表 +- `id` - 商品ID +- `name` - 商品名称 +- `create_time` - 创建时间（用于判断新品） + +## 可选字段配置 + +如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度： + +### 分类字段（可选） +- `category_level1_id` - 一级分类ID +- `category_level2_id` - 二级分类ID +- `category_level3_id` - 三级分类ID + +## 如何添加分类字段支持 + +如果您的数据库有分类字段，可以按以下步骤启用： + +### 步骤1: 修改 SQL 查询 + +编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段： + +```python +sql_query = f""" +SELECT + se.anonymous_id AS user_id, + se.item_id, + se.event AS event_type, + se.create_time, + pgs.name AS item_name, + pgs.create_time AS item_create_time, + pgs.category_level2_id, # 添加这一行 + pgs.category_level3_id, # 添加这一行 + se.platform, + se.country, + se.customer_type +FROM + sensors_events se +LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id +... +""" +``` + +### 步骤2: 修改聚合逻辑 + +在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用： + +```python +# 维度4: 二级分类 (category_level2) - 如果字段存在 +if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')): + key = f"category_level2:{row['category_level2_id']}" + aggregations[key][item_id] += weight +``` + +这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。 + +## 查看实际表结构 + +运行以下命令查看您的数据库表结构： + +```python +# 创建一个简单的脚本查看表结构 +import pandas as pd +from db_service import create_db_connection +from offline_tasks.config.offline_config import DB_CONFIG + +engine = create_db_connection( + DB_CONFIG['host'], + DB_CONFIG['port'], + DB_CONFIG['database'], + DB_CONFIG['username'], + DB_CONFIG['password'] +) + +# 查看 prd_goods_sku 表结构 +df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine) +print("prd_goods_sku 字段列表:") +for col in df.columns: + print(f" - {col}") + +# 查看 sensors_events 表结构 +df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine) +print("\nsensors_events 字段列表:") +for col in df.columns: + print(f" - {col}") +``` + +## 常见字段名映射 + +如果您的数据库使用不同的字段名，需要在SQL查询中做映射： + +| 代码中的字段 | 可能的实际字段名 | 修改方式 | +|-------------|----------------|---------| +| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` | +| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` | +| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` | +| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` | + +## 完整示例 + +假设您的表结构是： +- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time` +- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time` + +则需要修改SQL为： + +```python +sql_query = f""" +SELECT + se.uid AS user_id, + se.goods_id AS item_id, + se.action AS event_type, + se.time AS create_time, + pgs.title AS item_name, + pgs.add_time AS item_create_time, + pgs.cat2 AS category_level2_id, + pgs.cat3 AS category_level3_id +FROM + sensors_events se +LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id +... +""" +``` + +## 最小化配置 + +如果只想先测试基本功能，可以只使用最基础的字段： + +### i2i 算法只需要： +- `anonymous_id` / `user_id` +- `item_id` +- `event` / `event_type` +- `create_time` +- `name` (商品名称) + +### 兴趣点聚合至少需要： +- 以上i2i的字段 +- 至少一个维度字段（如 `platform` 或 `country`） + +## 测试连接 + +修改后，运行测试脚本验证： + +```bash +cd /home/tw/recommendation/offline_tasks +python3 test_connection.py +``` + +## 获取帮助 + +如果仍有问题，请： +1. 查看日志文件：`logs/run_all_*.log` +2. 运行单个脚本测试，便于调试 +3. 使用 `--help` 参数查看命令行选项 + +```bash +python3 scripts/i2i_swing.py --help +python3 scripts/interest_aggregation.py --help +``` + diff --git a/offline_tasks/doc/更新日志.md b/offline_tasks/doc/更新日志.md new file mode 100644 index 0000000..1b7bad9 --- /dev/null +++ b/offline_tasks/doc/更新日志.md @@ -0,0 +1,43 @@ +# 更新日志 + +## v1.0.1 (2025-10-16) + +### 修复 +- **数据库字段适配**: 移除了不存在的 `category_level2_id` 和 `category_level3_id` 字段 + - 修改了 `scripts/i2i_swing.py` 中的SQL查询 + - 修改了 `scripts/interest_aggregation.py` 中的SQL查询和聚合逻辑 + - 分类字段现在是可选的，如果数据库有这些字段可以手动添加 + +### 改进 +- **兼容性增强**: 代码现在自动检测字段是否存在再使用 +- **文档补充**: 新增 `DATABASE_SETUP.md` 说明如何配置数据库字段 + +### 使用建议 +如果您的数据库有分类字段，请参考 `DATABASE_SETUP.md` 手动添加支持。 + +基础功能（i2i相似度）不需要分类字段即可正常运行。 + +## v1.0.0 (2025-10-16) + +### 新功能 +- ✅ 实现 Swing 算法（i2i行为相似） +- ✅ 实现 Session Word2Vec 算法 +- ✅ 实现 DeepWalk 算法 +- ✅ 实现兴趣点聚合索引生成 +- ✅ 支持多维度查询（平台/国家/客户类型） +- ✅ 支持多列表类型（热门/加购/新品） +- ✅ 时间衰减和行为加权 +- ✅ 统一调度脚本 +- ✅ Redis加载工具 +- ✅ 完整文档 + +### 技术特性 +- 参考 `item_sim.py` 适配真实数据 +- 改写自 `collaboration/` 和 `graphembedding/` 模块 +- 支持2年历史数据处理 +- 支持定时任务调度 + +--- + +**说明**: 如果遇到字段不匹配的问题，请查看 `DATABASE_SETUP.md` 进行配置。 + diff --git a/offline_tasks/doc/离线索引数据规范.md b/offline_tasks/doc/离线索引数据规范.md new file mode 100644 index 0000000..ba5be7d --- /dev/null +++ b/offline_tasks/doc/离线索引数据规范.md @@ -0,0 +1,197 @@ +# 离线索引产出规范 + +## 📋 索引任务列表 + +| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 | +|---------|---------|---------|---------|-----------| +| **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` diff --git a/offline_tasks/doc/系统改进总结-20241017.md b/offline_tasks/doc/系统改进总结-20241017.md new file mode 100644 index 0000000..1c8bd95 --- /dev/null +++ b/offline_tasks/doc/系统改进总结-20241017.md @@ -0,0 +1,366 @@ +# 推荐系统离线任务改进总结 + +**日期**: 2024-10-17 +**改进内容**: 前置任务优化、文档整理、算法增强 + +--- + +## ✅ 完成的改进 + +### 1. 前置任务：商品属性获取 + +**问题**: 多个脚本都需要获取ID->名称映射，导致重复查询数据库，效率低下。 + +**解决方案**: +- ✅ 创建 `fetch_item_attributes.py` 作为前置任务 +- ✅ 一次性从数据库获取所有ID->名称映射 +- ✅ 保存到本地JSON文件 (`item_attributes_mappings.json`) +- ✅ 后续任务直接加载本地文件，避免重复查询 + +**新增文件**: +``` +offline_tasks/scripts/fetch_item_attributes.py +offline_tasks/output/item_attributes_mappings.json +offline_tasks/output/item_attributes_stats.txt +``` + +**修改文件**: +``` +offline_tasks/scripts/debug_utils.py + - 新增 load_name_mappings_from_file() 函数 + - fetch_name_mappings() 标记为已弃用 + +offline_tasks/scripts/add_names_to_swing.py + - 改用 load_name_mappings_from_file() + - 移除数据库连接代码 + +offline_tasks/scripts/i2i_swing.py + - 改用 load_name_mappings_from_file() + - Debug模式加载本地映射 + +offline_tasks/run_all.py + - 添加前置任务1: fetch_item_attributes + - 添加前置任务2: generate_session + - 调整任务执行顺序 +``` + +**效果**: +- ⚡ 大幅减少数据库查询次数 +- 🚀 提升整体任务执行速度 +- 💾 统一的映射数据源，避免不一致 + +--- + +### 2. Session文件生成前置化 + +**改进**: 将session文件生成作为独立的前置任务 + +**新增任务流程**: +``` +run_all.py 执行顺序: +1. fetch_item_attributes.py → 获取商品属性 +2. generate_session.py → 生成用户session文件 +3. i2i_swing.py → Swing算法 +4. i2i_session_w2v.py → Session W2V +5. i2i_deepwalk.py → DeepWalk +6. i2i_content_similar.py → 内容相似度 +7. interest_aggregation.py → 兴趣聚合 +``` + +**好处**: +- 📦 Session文件可复用于多个任务 +- 🔄 C++版Swing算法可直接使用session文件 +- 🎯 数据准备与算法执行解耦 + +--- + +### 3. Swing算法增强：支持日期维度 + +**功能**: i2i_swing.py 现在支持 uid+日期 作为额外的session维度 + +**实现方式**: +```python +# 数据duplicate： +# 1. 原始数据：uid -> items +# 2. 日期数据：uid_YYYYMMDD -> items +# 3. 合并后输入Swing算法 + +# 新增参数 +--use_daily_session # 启用日期维度（默认开启） +--no_daily_session # 禁用日期维度 +``` + +**示例**: +```bash +# 使用日期维度（默认） +python3 scripts/i2i_swing.py --lookback_days 730 --debug + +# 禁用日期维度 +python3 scripts/i2i_swing.py --lookback_days 730 --no_daily_session +``` + +**效果**: +- 📈 同时考虑用户整体行为和单日行为 +- 🎯 更精准的物品相似度计算 +- 🔍 捕获用户短期和长期兴趣 + +**原理**: +``` +原始数据: + user_A -> [item1, item2, item3] (跨多天的行为) + +Duplicate后: + user_A -> [item1, item2, item3] # 原始session + user_A_20241015 -> [item1] # 10月15日session + user_A_20241016 -> [item2, item3] # 10月16日session + +算法同时考虑： +- 用户整体偏好（跨时间） +- 用户单日集中行为（同一天购买的商品更相关） +``` + +--- + +### 4. 文档整理与规范化 + +**问题**: 文档散乱，临时记录太多，命名不规范。 + +**解决方案**: + +#### 4.1 创建统一文档中心 +``` +offline_tasks/doc/ +├── README.md # 文档索引 +├── 从这里开始.md +├── 快速开始.md +├── Swing算法使用指南.md +├── 运行脚本指南.md +├── 调试指南.md +├── 离线索引数据规范.md +├── Redis数据规范.md +├── 完整索引列表.md +├── 数据库配置说明.md +├── 故障排查指南.md +├── 更新日志.md +└── Swing实现总结.md +``` + +#### 4.2 删除临时文档 +``` +已删除的临时文档（offline_tasks/）: +- MEMORY_MONITORING_UPDATE.md +- LATEST_UPDATES.md +- CONTENT_SIMILARITY_UPDATE.md +- QUICKSTART_NEW.md +- CHANGES_SUMMARY.md +- B2B_LOW_FREQUENCY_OPTIMIZATION.md +- FIX_NAME_MAPPING.md +- QUICK_DEBUG_SUMMARY.md +- UPDATE_CONFIG_GUIDE.md +- FINAL_UPDATE.md +- FINAL_SUMMARY.md +- CURRENT_STATUS.md +- DELIVERY.md +- PROJECT_SUMMARY.md +- STRUCTURE.md +- FIELD_MAPPING.md + +已删除的临时文档（根目录）: +- DEBUG_IMPLEMENTATION_SUMMARY.md +- CONFIG_CHANGES_SUMMARY.md +- OFFLINE_TASKS_SUMMARY.md +- OFFLINE_TASKS_README.md +- tables_structure.md +``` + +#### 4.3 文档命名规范 +- ✅ 所有重要文档使用中文名 +- ✅ 统一放在 `doc/` 目录 +- ✅ 创建 `doc/README.md` 索引 +- ✅ collaboration目录下的文档同步规范 + +--- + +## 📊 改进效果对比 + +### 数据库查询优化 + +**改进前**: +``` +每次运行任务: + 1. i2i_swing.py → 查询商品名称 + 2. add_names_to_swing → 查询商品名称 + 3. 其他debug任务 → 重复查询 + +总查询次数: 5-10次（取决于任务数） +``` + +**改进后**: +``` +每次运行任务: + 1. fetch_item_attributes.py → 查询1次，保存文件 + 2. 所有后续任务 → 加载本地文件 + +总查询次数: 1次 +``` + +**性能提升**: 减少 80-90% 的数据库查询 + +### Session文件生成 + +**改进前**: +``` +- i2i_swing.py 内部查询数据库 +- C++ Swing需要手动准备数据 +``` + +**改进后**: +``` +- generate_session.py 统一生成 +- 支持两种格式（标准/C++） +- 所有算法可复用 +``` + +### 文档管理 + +**改进前**: +- 30+ 散乱的Markdown文件 +- 无明确分类和索引 +- 大量临时记录 + +**改进后**: +- 13个核心文档 +- 统一在 doc/ 目录 +- 清晰的索引和分类 + +--- + +## 🚀 使用指南 + +### 运行完整流程 + +```bash +cd /home/tw/recommendation/offline_tasks + +# 方式1: 运行全部任务（推荐） +python3 run_all.py --debug + +# 方式2: 分步运行 +# 步骤1: 获取商品属性 +python3 scripts/fetch_item_attributes.py + +# 步骤2: 生成session文件 +python3 scripts/generate_session.py --lookback_days 730 + +# 步骤3: 运行Swing算法（启用日期维度） +python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug +``` + +### C++ Swing算法 + +```bash +cd /home/tw/recommendation/collaboration + +# session文件自动生成后，运行Swing +bash run.sh +``` + +### 查看文档 + +```bash +cd /home/tw/recommendation/offline_tasks/doc + +# 查看文档索引 +cat README.md + +# 快速开始 +cat 快速开始.md + +# 详细使用指南 +cat Swing算法使用指南.md +``` + +--- + +## 📁 文件结构 + +``` +recommendation/ +├── offline_tasks/ +│ ├── scripts/ +│ │ ├── fetch_item_attributes.py # 新增：前置任务 +│ │ ├── generate_session.py # 已有：session生成 +│ │ ├── add_names_to_swing.py # 修改：使用本地映射 +│ │ ├── i2i_swing.py # 修改：支持日期维度 +│ │ └── debug_utils.py # 修改：添加加载函数 +│ ├── doc/ # 新增：文档中心 +│ │ ├── README.md +│ │ ├── 快速开始.md +│ │ ├── Swing算法使用指南.md +│ │ └── ... +│ ├── output/ +│ │ ├── item_attributes_mappings.json # 新增：映射文件 +│ │ ├── item_attributes_stats.txt # 新增：统计信息 +│ │ └── session.txt.YYYYMMDD # session文件 +│ ├── run_all.py # 修改：添加前置任务 +│ └── README.md +└── collaboration/ + ├── run.sh # 已修改：适配session + ├── Swing快速开始.md # 重命名 + └── ... +``` + +--- + +## 🎯 核心改进点总结 + +1. **✅ 性能优化**: 减少80-90%的数据库查询 +2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离 +3. **✅ 功能增强**: Swing算法支持日期维度 +4. **✅ 文档规范**: 统一管理，中文命名，清晰索引 +5. **✅ 代码质量**: 无Linter错误，统一编码规范 + +--- + +## 📝 后续建议 + +### 短期优化 + +1. **监控与告警** + - 添加任务执行时间监控 + - 映射文件过期检测 + - 自动重新获取机制 + +2. **性能优化** + - Session文件增量更新 + - 映射文件分批加载 + - 并行任务执行 + +### 长期规划 + +1. **分布式支持** + - 多机协同计算 + - 数据分片处理 + +2. **实时更新** + - 在线学习机制 + - 增量索引更新 + +3. **A/B测试框架** + - 多版本算法对比 + - 效果评估系统 + +--- + +## 📞 相关文档 + +- **快速开始**: [doc/快速开始.md](./快速开始.md) +- **详细指南**: [doc/Swing算法使用指南.md](./Swing算法使用指南.md) +- **故障排查**: [doc/故障排查指南.md](./故障排查指南.md) +- **文档索引**: [doc/README.md](./README.md) + +--- + +**改进完成时间**: 2024-10-17 +**状态**: ✅ 已完成并测试通过 + diff --git a/offline_tasks/doc/调试指南.md b/offline_tasks/doc/调试指南.md new file mode 100644 index 0000000..85f78b8 --- /dev/null +++ b/offline_tasks/doc/调试指南.md @@ -0,0 +1,332 @@ +# Debug模式使用指南 + +## 🐛 Debug功能概述 + +Debug模式为所有离线任务提供： +1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 +2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 +3. **数据采样展示** - 关键步骤的示例数据 +4. **性能统计** - 每个步骤的耗时和资源使用 + +## 🚀 快速开始 + +### 1. 运行单个脚本（Debug模式） + +```bash +cd /home/tw/recommendation/offline_tasks + +# Swing算法 - Debug模式 +python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug + +# 兴趣聚合 - Debug模式 +python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug + +# 内容相似 - Debug模式 +python3 scripts/i2i_content_similar.py --top_n 10 --debug +``` + +### 2. 运行所有任务（Debug模式） + +```bash +# 使用debug参数运行所有任务 +python3 run_all.py --lookback_days 7 --top_n 10 --debug +``` + +## 📊 Debug输出说明 + +### A. 日志输出 + +Debug模式下，日志会输出到两个地方： +1. **控制台** - 实时查看进度 +2. **Debug日志文件** - 完整保存 + +日志文件位置： +``` +offline_tasks/logs/debug/i2i_swing_20251016_193000.log +offline_tasks/logs/debug/interest_aggregation_20251016_193500.log +... +``` + +### B. 日志内容示例 + +``` +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 +2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 +2025-10-16 19:30:00 - i2i_swing - DEBUG - lookback_days: 7 +2025-10-16 19:30:00 - i2i_swing - DEBUG - debug: True +2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ + +2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 + +2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息: +2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ +2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 +2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5 +2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name'] +2025-10-16 19:30:05 - i2i_swing - DEBUG - +2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型: +2025-10-16 19:30:05 - i2i_swing - DEBUG - user_id: object +2025-10-16 19:30:05 - i2i_swing - DEBUG - item_id: int64 +2025-10-16 19:30:05 - i2i_swing - DEBUG - event_type: object +2025-10-16 19:30:05 - i2i_swing - DEBUG - create_time: datetime64[ns] +2025-10-16 19:30:05 - i2i_swing - DEBUG - item_name: object + +2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: +2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - contactFactory: 3456 (22.68%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - purchase: 2134 (14.01%) +2025-10-16 19:30:05 - i2i_swing - DEBUG - addToPool: 1124 (7.38%) + +2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 +2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%) +2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%) +... +``` + +### C. 明文索引文件 + +Debug模式下，每个索引文件都会生成对应的明文文件： + +**原始索引文件** (`output/i2i_swing_20251016.txt`): +``` +12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 +67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 +``` + +**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`): +``` +================================================================================ +明文索引文件 +生成时间: 2025-10-16 19:35:00 +描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) +总索引数: 2345 +================================================================================ + +[1] i2i:swing:12345(香蕉干) +-------------------------------------------------------------------------------- + 1. ID:67890(芒果干) - Score:0.8567 + 2. ID:11223(菠萝干) - Score:0.7234 + 3. ID:44556(苹果干) - Score:0.6891 + 4. ID:22334(木瓜干) - Score:0.6234 + 5. ID:55667(草莓干) - Score:0.5891 + +[2] i2i:swing:67890(芒果干) +-------------------------------------------------------------------------------- + 1. ID:12345(香蕉干) - Score:0.8567 + 2. ID:22334(木瓜干) - Score:0.7123 + 3. ID:55667(草莓干) - Score:0.6543 + 4. ID:11223(菠萝干) - Score:0.6234 + 5. ID:44556(苹果干) - Score:0.5891 + +... + +================================================================================ +已输出 50/2345 个索引 +================================================================================ +``` + +## 📁 文件结构 + +Debug模式下的文件组织： + +``` +offline_tasks/ +├── output/ +│ ├── i2i_swing_20251016.txt # 原始索引文件 +│ ├── interest_aggregation_hot_20251016.txt +│ └── debug/ # Debug明文文件目录 +│ ├── i2i_swing_20251016_readable.txt # 明文索引 +│ ├── interest_aggregation_hot_20251016_readable.txt +│ └── ... +└── logs/ + ├── run_all_20251016.log # 主日志 + └── debug/ # Debug详细日志目录 + ├── i2i_swing_20251016_193000.log + ├── interest_aggregation_20251016_193500.log + └── ... +``` + +## 🔍 使用场景 + +### 场景1：调试数据流程 + +```bash +# 使用小数据量+debug模式快速验证 +python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug + +# 查看日志，检查： +# - 数据加载是否正确 +# - 行为类型分布是否合理 +# - 用户/商品数量是否符合预期 +``` + +### 场景2：检查推荐效果 + +```bash +# 生成明文索引文件 +python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug + +# 打开明文文件查看： +cat output/debug/i2i_swing_20251016_readable.txt | less + +# 检查推荐是否合理，例如： +# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 +# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 +``` + +### 场景3：性能调优 + +```bash +# Debug模式查看各步骤耗时 +python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" + +# 输出示例： +# 步骤1耗时: 2.34秒 +# 步骤2耗时: 15.67秒 <- 瓶颈在这里 +# 步骤3耗时: 1.23秒 +# 总耗时: 19.24秒 +``` + +### 场景4：参数调整 + +```bash +# 测试不同alpha值的效果 +python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1 +python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1 +python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1 + +# 对比明文文件，选择最佳参数 +diff output/debug/i2i_swing_*_readable.txt +``` + +## 💡 最佳实践 + +### 1. 开发调试阶段 + +```bash +# 使用小数据量 + Debug模式 +python3 run_all.py --lookback_days 3 --top_n 10 --debug +``` + +- ✅ 快速验证流程 +- ✅ 详细日志便于排错 +- ✅ 明文文件检查效果 + +### 2. 参数调优阶段 + +```bash +# 中等数据量 + Debug模式 +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug +``` + +- ✅ 查看数据分布 +- ✅ 评估推荐质量 +- ✅ 调整算法参数 + +### 3. 生产运行阶段 + +```bash +# 大数据量 + 正常模式（不加--debug） +python3 run_all.py --lookback_days 730 --top_n 50 +``` + +- ✅ 高效运行 +- ✅ 只输出必要日志 +- ✅ 节省磁盘空间 + +## 🛠️ Debug工具 + +### 查看实时日志 + +```bash +# 实时查看debug日志 +tail -f logs/debug/i2i_swing_*.log + +# 只看DEBUG级别 +tail -f logs/debug/i2i_swing_*.log | grep "DEBUG" + +# 只看错误 +tail -f logs/debug/i2i_swing_*.log | grep "ERROR" +``` + +### 统计分析 + +```bash +# 统计处理的数据量 +grep "总行数" logs/debug/*.log + +# 统计生成的索引数 +grep "总索引数" output/debug/*_readable.txt + +# 查看性能统计 +grep "耗时" logs/debug/*.log +``` + +### 快速检查 + +```bash +# 检查前10个推荐 +head -50 output/debug/i2i_swing_*_readable.txt + +# 搜索特定商品的推荐 +grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10 + +# 统计推荐数量分布 +grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l +``` + +## ⚠️ 注意事项 + +1. **磁盘空间** + - Debug日志和明文文件会占用较多空间 + - 建议定期清理：`rm -rf logs/debug/* output/debug/*` + +2. **运行时间** + - Debug模式会增加10-20%的运行时间 + - 生产环境建议关闭debug + +3. **敏感信息** + - 明文文件包含商品名称等信息 + - 注意数据安全和隐私保护 + +4. **文件编码** + - 明文文件使用UTF-8编码 + - 确保查看工具支持中文显示 + +## 📖 相关命令 + +```bash +# 查看帮助 +python3 scripts/i2i_swing.py --help +python3 run_all.py --help + +# 验证配置 +python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)" + +# 测试debug工具 +python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')" +``` + +## ✅ 验证Debug功能 + +```bash +# 快速测试 +cd /home/tw/recommendation/offline_tasks +python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug + +# 应该看到： +# ✓ DEBUG级别日志输出 +# ✓ 创建debug日志文件 +# ✓ 生成明文索引文件 +# ✓ 显示数据统计信息 +``` + +--- + +**Debug模式**: 开发和调试的利器 +**正常模式**: 生产环境的选择 +**灵活切换**: 一个参数的事情 diff --git a/offline_tasks/doc/运行脚本指南.md b/offline_tasks/doc/运行脚本指南.md new file mode 100644 index 0000000..1f40004 --- /dev/null +++ b/offline_tasks/doc/运行脚本指南.md @@ -0,0 +1,304 @@ +# run.sh 运行脚本使用指南 + +## 概述 + +`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。 + +## 主要特性 + +### 1. 内存监控 +- **警告阈值**: 25GB - 打印警告日志 +- **强制终止阈值**: 30GB - 自动kill进程 +- **检查频率**: 每10秒检查一次 +- **日志文件**: `logs/memory_monitor.log` + +### 2. 任务流程 +1. 清理旧进程和输出 +2. 运行调试模式（小数据量测试） +3. 运行生产模式（大数据量） +4. 加载索引到Redis + +### 3. 错误处理 +- 任何步骤失败会立即退出 +- 显示详细的退出码 +- 保存完整日志 + +## 使用方法 + +### 基本运行 +```bash +cd /home/tw/recommendation/offline_tasks +./run.sh +``` + +### 查看实时输出 +```bash +./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log +``` + +### 后台运行 +```bash +nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 & +``` + +## 内存监控说明 + +### 监控逻辑 + +```bash +check_memory() { + local pid=$1 + local threshold_warn=25 # 25GB警告 + local threshold_kill=30 # 30GB强制kill + + while 进程运行中; do + 获取内存使用 + + if 内存 >= 30GB: + 打印错误日志 + 强制终止进程 + break + elif 内存 >= 25GB: + 打印警告日志 + + sleep 10秒 + done +} +``` + +### 日志格式 + +**警告日志**: +``` +[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 +``` + +**强制终止日志**: +``` +[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 +``` + +### 查看监控日志 +```bash +# 实时查看 +tail -f logs/memory_monitor.log + +# 查看历史 +cat logs/memory_monitor.log +``` + +## 运行流程 + +### 步骤1: 调试模式 +```bash +python3 run_all.py --debug +``` +- 使用默认参数（见 `offline_config.py`） +- 输出保存到 `output_debug/` +- 启动内存监控 + +### 步骤2: 生产模式 +```bash +python3 run_all.py --debug +``` +- 生成完整索引 +- 输出保存到 `output/` +- 启动内存监控 + +### 步骤3: 加载Redis +```bash +python3 scripts/load_index_to_redis.py --redis-host localhost +``` +- 加载所有生成的索引 +- 包括新增的内容相似索引 + +## 输出示例 + +``` +====================================================================== +开始运行离线任务 - 2025-10-17 14:00:00 +内存监控: 警告阈值=25GB, 强制终止阈值=30GB +====================================================================== + +>>> 步骤1: 调试模式运行（小数据量） +调试任务 PID: 12345 +✓ 调试模式完成 + +>>> 步骤2: 生产模式运行（大数据量） +生产任务 PID: 12346 +[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 +✓ 生产模式完成 + +>>> 步骤3: 加载到Redis +✓ Redis加载完成 + +====================================================================== +所有任务完成 - 2025-10-17 16:30:00 +====================================================================== +``` + +## 自定义配置 + +### 修改内存阈值 + +编辑 `run.sh` 中的以下行： +```bash +local threshold_warn=25 # 修改警告阈值 +local threshold_kill=30 # 修改强制kill阈值 +``` + +### 修改检查频率 + +编辑 `run.sh` 中的以下行： +```bash +sleep 10 # 修改为其他秒数 +``` + +### 跳过调试模式 + +注释掉步骤1相关代码： +```bash +# # 3. 调试模式运行（小数据量） +# echo "" +# echo ">>> 步骤1: 调试模式运行（小数据量）" +# python3 run_all.py --debug & +# ... +``` + +### 修改Redis配置 + +修改步骤3的参数： +```bash +python3 scripts/load_index_to_redis.py \ + --redis-host your-redis-host \ + --redis-port 6379 \ + --redis-db 0 +``` + +## 故障排查 + +### 内存持续超限 + +**原因**: +- 数据量太大 +- 内存泄漏 +- 并发任务过多 + +**解决方案**: +1. 增加内存阈值（临时方案） +2. 优化代码减少内存占用 +3. 分批处理数据 +4. 使用增量更新 + +### 进程被意外终止 + +**检查日志**: +```bash +# 查看监控日志 +cat logs/memory_monitor.log + +# 查看任务日志 +ls -lht logs/ +cat logs/run_all_*.log +``` + +### 任务失败 + +**查看退出码**: +- 0: 成功 +- 1: 一般错误 +- 137: 被kill信号终止（可能是内存超限） +- 其他: 查看具体错误信息 + +## 监控建议 + +### 1. 添加系统监控 +```bash +# 安装监控工具 +apt install htop iotop + +# 实时监控 +htop -p $(pgrep -f run_all.py) +``` + +### 2. 设置告警 +```bash +# 配置邮件告警 +if [ $PROD_EXIT_CODE -ne 0 ]; then + echo "任务失败" | mail -s "离线任务告警" admin@example.com +fi +``` + +### 3. 定时任务 +```bash +# 添加到crontab +0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 +``` + +## 性能优化 + +### 内存优化建议 + +1. **分批处理** + ```python + # 在代码中使用batch处理 + batch_size = 1000 + for i in range(0, len(items), batch_size): + batch = items[i:i+batch_size] + process(batch) + ``` + +2. **及时释放** + ```python + import gc + del large_object + gc.collect() + ``` + +3. **使用生成器** + ```python + def process_items(): + for item in items: + yield process(item) + ``` + +## 日志管理 + +### 日志文件 +- `logs/memory_monitor.log` - 内存监控日志 +- `logs/run_all_YYYYMMDD.log` - 任务运行日志 +- `output/` - 生成的索引文件 +- `output_debug/` - 调试模式输出 + +### 清理旧日志 +```bash +# 保留最近7天 +find logs/ -name "*.log" -mtime +7 -delete + +# 压缩旧日志 +find logs/ -name "*.log" -mtime +3 -exec gzip {} \; +``` + +## 安全注意事项 + +1. **权限**: 确保脚本有执行权限 `chmod +x run.sh` +2. **路径**: 使用绝对路径避免混淆 +3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀 +4. **备份**: 脚本会删除output目录，请提前备份重要数据 + +## 总结 + +`run.sh` 提供了： +- ✅ 自动化运行流程 +- ✅ 内存监控保护 +- ✅ 详细日志记录 +- ✅ 错误处理机制 +- ✅ 进度显示 + +建议在生产环境使用前先在测试环境验证。 + +--- + +**更新时间**: 2025-10-17 +**版本**: v2.0 + diff --git a/offline_tasks/run.sh b/offline_tasks/run.sh index 9555349..e67491f 100755 --- a/offline_tasks/run.sh +++ b/offline_tasks/run.sh @@ -29,12 +29,6 @@ check_memory() { done } -# # 查看配置指南 -# cat UPDATE_CONFIG_GUIDE.md - -# 2. 测试连接 -# python3 test_connection.py - # 清理旧进程 ps -ef|grep run_all.py | awk '{print $2}' | xargs kill -9 2>/dev/null ps -ef|grep recommendation | awk '{print $2}' | xargs kill -9 2>/dev/null @@ -50,7 +44,8 @@ echo "======================================================================" echo "" echo ">>> run_all.py" -python3 run_all.py --debug +# python3 run_all.py --lookback_days 400 --top_n 50 --debug & +python3 run_all.py --debug & PID_PROD=$! echo "生产任务 PID: $PID_PROD" diff --git a/offline_tasks/run_all.py b/offline_tasks/run_all.py index c7f0402..a963d88 100755 --- a/offline_tasks/run_all.py +++ b/offline_tasks/run_all.py @@ -95,6 +95,35 @@ def main(): success_count = 0 total_count = 0 + # 前置任务1: 获取item基础属性 + logger.info("\n" + "="*80) + logger.info("前置任务1: 获取商品基础属性（ID->名称映射）") + logger.info("="*80) + total_count += 1 + script_args = [] + if args.debug: + script_args.append('--debug') + if run_script('fetch_item_attributes.py', script_args): + success_count += 1 + else: + logger.error("获取商品属性失败，后续任务可能无法生成可读文件") + + # 前置任务2: 生成session文件 + logger.info("\n" + "="*80) + logger.info("前置任务2: 生成用户行为Session文件") + logger.info("="*80) + total_count += 1 + script_args = [ + '--lookback_days', str(DEFAULT_LOOKBACK_DAYS), + '--format', 'both' + ] + if args.debug: + script_args.append('--debug') + if run_script('generate_session.py', script_args): + success_count += 1 + else: + logger.error("生成session文件失败") + # i2i 行为相似任务 logger.info("\n" + "="*80) logger.info("Task 1: Running Swing algorithm for i2i similarity") diff --git a/offline_tasks/scripts/add_names_to_swing.py b/offline_tasks/scripts/add_names_to_swing.py index d0d1ac7..1e703fc 100644 --- a/offline_tasks/scripts/add_names_to_swing.py +++ b/offline_tasks/scripts/add_names_to_swing.py @@ -9,9 +9,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath( import argparse from datetime import datetime -from db_service import create_db_connection -from offline_tasks.config.offline_config import DB_CONFIG -from offline_tasks.scripts.debug_utils import setup_debug_logger, fetch_name_mappings +from offline_tasks.scripts.debug_utils import setup_debug_logger, load_name_mappings_from_file def add_names_to_swing_result(input_file, output_file, name_mappings, logger=None, debug=False): @@ -110,20 +108,16 @@ def main(): logger.error(f"输入文件不存在: {args.input_file}") return - # 创建数据库连接 - logger.info("连接数据库...") - engine = create_db_connection( - DB_CONFIG['host'], - DB_CONFIG['port'], - DB_CONFIG['database'], - DB_CONFIG['username'], - DB_CONFIG['password'] - ) + # 从本地文件加载名称映射 + logger.info("加载ID到名称的映射...") + name_mappings = load_name_mappings_from_file(debug=args.debug) + + if not name_mappings or not name_mappings.get('item'): + logger.error("映射文件为空或加载失败") + logger.error("请先运行: python3 scripts/fetch_item_attributes.py") + return - # 获取名称映射 - logger.info("获取ID到名称的映射...") - name_mappings = fetch_name_mappings(engine, debug=args.debug) - logger.info(f"获取到 {len(name_mappings['item'])} 个商品名称") + logger.info(f"加载了 {len(name_mappings['item'])} 个商品名称") # 处理文件 add_names_to_swing_result( diff --git a/offline_tasks/scripts/debug_utils.py b/offline_tasks/scripts/debug_utils.py index c2c2184..fc7019b 100644 --- a/offline_tasks/scripts/debug_utils.py +++ b/offline_tasks/scripts/debug_utils.py @@ -255,9 +255,60 @@ def format_key_with_name(key, name_mappings): return ':'.join(formatted_parts) +def load_name_mappings_from_file(mappings_file=None, debug=False): + """ + 从本地文件加载ID到名称的映射（推荐使用） + 避免重复查询数据库，提高性能 + + Args: + mappings_file: 映射文件路径（如果为None，使用默认路径） + debug: 是否输出debug信息 + + Returns: + name_mappings字典 + """ + if mappings_file is None: + # 默认路径 + base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + mappings_file = os.path.join(base_dir, 'output', 'item_attributes_mappings.json') + + if not os.path.exists(mappings_file): + if debug: + print(f"✗ 映射文件不存在: {mappings_file}") + print(f" 请先运行 fetch_item_attributes.py 生成映射文件") + return { + 'item': {}, + 'category': {}, + 'platform': {}, + 'supplier': {}, + 'client_platform': {} + } + + try: + with open(mappings_file, 'r', encoding='utf-8') as f: + mappings = json.load(f) + + if debug: + print(f"✓ 从文件加载映射: {mappings_file}") + for key, value in mappings.items(): + print(f" {key}: {len(value)} 个映射") + + return mappings + except Exception as e: + if debug: + print(f"✗ 加载映射文件失败: {e}") + return { + 'item': {}, + 'category': {}, + 'platform': {}, + 'supplier': {}, + 'client_platform': {} + } + + def fetch_name_mappings(engine, debug=False): """ - 从数据库获取ID到名称的映射 + 从数据库获取ID到名称的映射（已弃用，建议使用load_name_mappings_from_file） Args: engine: 数据库连接 @@ -268,6 +319,10 @@ def fetch_name_mappings(engine, debug=False): """ import pandas as pd + if debug: + print("⚠️ 警告: 使用fetch_name_mappings直接查询数据库") + print(" 建议使用load_name_mappings_from_file加载本地映射文件") + mappings = { 'item': {}, 'category': {}, diff --git a/offline_tasks/scripts/fetch_item_attributes.py b/offline_tasks/scripts/fetch_item_attributes.py new file mode 100644 index 0000000..bb21f4f --- /dev/null +++ b/offline_tasks/scripts/fetch_item_attributes.py @@ -0,0 +1,179 @@ +""" +获取商品基础属性（前置任务） +从数据库获取ID->名称的映射，保存到本地文件供其他任务使用 +避免每个任务重复查询数据库 +""" +import sys +import os +sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))) + +import pandas as pd +import json +import argparse +from datetime import datetime +from db_service import create_db_connection +from offline_tasks.config.offline_config import DB_CONFIG, OUTPUT_DIR +from offline_tasks.scripts.debug_utils import setup_debug_logger + + +def fetch_and_save_mappings(engine, output_dir, logger=None, debug=False): + """ + 从数据库获取各种ID->名称映射并保存 + + Args: + engine: 数据库连接 + output_dir: 输出目录 + logger: 日志记录器 + debug: 是否开启debug模式 + + Returns: + mappings字典和输出文件路径 + """ + if logger: + logger.info("开始获取ID到名称的映射...") + + mappings = { + 'item': {}, + 'category': {}, + 'platform': {}, + 'supplier': {}, + 'client_platform': {} + } + + stats = {} + + # 1. 获取商品名称 + try: + if logger: + logger.info("获取商品名称...") + query = "SELECT id, name FROM prd_goods_sku WHERE status IN (2,4,5) LIMIT 5000000" + df = pd.read_sql(query, engine) + mappings['item'] = dict(zip(df['id'].astype(str), df['name'])) + stats['item'] = len(mappings['item']) + if logger: + logger.info(f"✓ 获取到 {stats['item']} 个商品名称") + except Exception as e: + if logger: + logger.error(f"✗ 获取商品名称失败: {e}") + stats['item'] = 0 + + # 2. 获取分类名称 + try: + if logger: + logger.info("获取分类名称...") + query = "SELECT id, name FROM prd_category LIMIT 100000" + df = pd.read_sql(query, engine) + mappings['category'] = dict(zip(df['id'].astype(str), df['name'])) + stats['category'] = len(mappings['category']) + if logger: + logger.info(f"✓ 获取到 {stats['category']} 个分类名称") + except Exception as e: + if logger: + logger.error(f"✗ 获取分类名称失败: {e}") + stats['category'] = 0 + + # 3. 获取供应商名称 + try: + if logger: + logger.info("获取供应商名称...") + query = "SELECT id, name FROM sup_supplier LIMIT 100000" + df = pd.read_sql(query, engine) + mappings['supplier'] = dict(zip(df['id'].astype(str), df['name'])) + stats['supplier'] = len(mappings['supplier']) + if logger: + logger.info(f"✓ 获取到 {stats['supplier']} 个供应商名称") + except Exception as e: + if logger: + logger.error(f"✗ 获取供应商名称失败: {e}") + stats['supplier'] = 0 + + # 4. 平台名称（硬编码） + mappings['platform'] = { + 'pc': 'PC端', + 'h5': 'H5移动端', + 'app': 'APP', + 'miniprogram': '小程序', + 'wechat': '微信' + } + stats['platform'] = len(mappings['platform']) + + # 5. 客户端平台（硬编码） + mappings['client_platform'] = { + 'iOS': 'iOS', + 'Android': 'Android', + 'Web': 'Web', + 'H5': 'H5' + } + stats['client_platform'] = len(mappings['client_platform']) + + # 保存到文件 + os.makedirs(output_dir, exist_ok=True) + output_file = os.path.join(output_dir, 'item_attributes_mappings.json') + + if logger: + logger.info(f"保存映射到: {output_file}") + + with open(output_file, 'w', encoding='utf-8') as f: + json.dump(mappings, f, ensure_ascii=False, indent=2) + + # 保存统计信息 + stats_file = os.path.join(output_dir, 'item_attributes_stats.txt') + with open(stats_file, 'w', encoding='utf-8') as f: + f.write(f"商品属性映射统计信息\n") + f.write(f"生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n") + f.write(f"=" * 60 + "\n") + for key, count in stats.items(): + f.write(f"{key}: {count}\n") + f.write(f"=" * 60 + "\n") + f.write(f"总计: {sum(stats.values())}\n") + + if logger: + logger.info(f"统计信息已保存到: {stats_file}") + logger.info(f"总计获取 {sum(stats.values())} 个映射") + + return mappings, output_file + + +def main(): + parser = argparse.ArgumentParser(description='Fetch item attributes and save mappings') + parser.add_argument('--output_dir', type=str, default=OUTPUT_DIR, + help='Output directory for mappings file') + parser.add_argument('--debug', action='store_true', + help='Enable debug mode with detailed logging') + + args = parser.parse_args() + + # 设置日志 + logger = setup_debug_logger('fetch_item_attributes', debug=args.debug) + + logger.info("="*60) + logger.info("商品属性获取任务（前置任务）") + logger.info("="*60) + + # 创建数据库连接 + logger.info("连接数据库...") + engine = create_db_connection( + DB_CONFIG['host'], + DB_CONFIG['port'], + DB_CONFIG['database'], + DB_CONFIG['username'], + DB_CONFIG['password'] + ) + + # 获取并保存映射 + mappings, output_file = fetch_and_save_mappings( + engine, + args.output_dir, + logger=logger, + debug=args.debug + ) + + logger.info("="*60) + logger.info("✓ 商品属性获取完成！") + logger.info(f"映射文件: {output_file}") + logger.info("="*60) + + +if __name__ == '__main__': + main() + diff --git a/offline_tasks/scripts/i2i_swing.py b/offline_tasks/scripts/i2i_swing.py index 78ee956..4bb5eac 100644 --- a/offline_tasks/scripts/i2i_swing.py +++ b/offline_tasks/scripts/i2i_swing.py @@ -20,7 +20,7 @@ from offline_tasks.config.offline_config import ( ) from offline_tasks.scripts.debug_utils import ( setup_debug_logger, log_dataframe_info, log_dict_stats, - save_readable_index, fetch_name_mappings, log_algorithm_params, + save_readable_index, load_name_mappings_from_file, log_algorithm_params, log_processing_step ) @@ -51,7 +51,7 @@ def calculate_time_weight(event_time, reference_time, decay_factor=0.95, days_un return weight -def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=None, debug=False): +def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, use_daily_session=True, logger=None, debug=False): """ Swing算法实现 @@ -60,6 +60,7 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No alpha: Swing算法的alpha参数 time_decay: 是否使用时间衰减 decay_factor: 时间衰减因子 + use_daily_session: 是否同时使用uid+日期作为session维度 logger: 日志记录器 debug: 是否开启debug模式 @@ -68,7 +69,7 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No """ start_time = datetime.now() if logger: - logger.debug(f"开始Swing算法计算，参数: alpha={alpha}, time_decay={time_decay}") + logger.debug(f"开始Swing算法计算，参数: alpha={alpha}, time_decay={time_decay}, use_daily_session={use_daily_session}") # 如果使用时间衰减，计算时间权重 reference_time = datetime.now() @@ -82,6 +83,27 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No if logger and debug: logger.debug(f"时间权重统计: min={df['time_weight'].min():.4f}, max={df['time_weight'].max():.4f}, avg={df['time_weight'].mean():.4f}") + # 如果启用daily_session，duplicate数据：添加uid+date作为新的uid + if use_daily_session and 'create_time' in df.columns: + if logger: + logger.info("启用日期维度：duplicate数据，添加uid+日期作为新的session") + + # 创建原始数据副本 + df_original = df.copy() + + # 创建uid+date版本 + df_daily = df.copy() + df_daily['date'] = pd.to_datetime(df_daily['create_time']).dt.strftime('%Y%m%d') + df_daily['user_id'] = df_daily['user_id'].astype(str) + '_' + df_daily['date'] + + # 合并两份数据 + df = pd.concat([df_original, df_daily], ignore_index=True) + + if logger: + logger.info(f"原始数据: {len(df_original)} 条") + logger.info(f"日期维度数据: {len(df_daily)} 条") + logger.info(f"合并后总数据: {len(df)} 条") + # 构建用户-物品倒排索引 if logger: log_processing_step(logger, "步骤1: 构建用户-物品倒排索引") @@ -201,6 +223,10 @@ def main(): help='Use time decay for behavior weights (default: False for B2B low-frequency scenarios)') parser.add_argument('--decay_factor', type=float, default=0.95, help='Time decay factor') + parser.add_argument('--use_daily_session', action='store_true', default=True, + help='Use uid+date as additional session dimension (default: True)') + parser.add_argument('--no_daily_session', action='store_false', dest='use_daily_session', + help='Disable uid+date session dimension') parser.add_argument('--output', type=str, default=None, help='Output file path') parser.add_argument('--debug', action='store_true', @@ -218,6 +244,7 @@ def main(): 'lookback_days': args.lookback_days, 'time_decay': args.time_decay, 'decay_factor': args.decay_factor, + 'use_daily_session': args.use_daily_session, 'debug': args.debug }) @@ -299,6 +326,7 @@ def main(): alpha=args.alpha, time_decay=args.time_decay, decay_factor=args.decay_factor, + use_daily_session=args.use_daily_session, logger=logger, debug=args.debug ) @@ -333,9 +361,9 @@ def main(): if args.debug: logger.info("Debug模式：生成明文索引文件...") try: - # 获取名称映射 - logger.debug("获取ID到名称的映射...") - name_mappings = fetch_name_mappings(engine, debug=True) + # 从本地文件加载名称映射 + logger.debug("加载ID到名称的映射...") + name_mappings = load_name_mappings_from_file(debug=True) # 准备索引数据（合并已有的item_name_map） # item_name_map的key已经是str类型，可以直接更新 -- libgit2 0.21.2