From 0d5f0a82b42b677f980edc6169ea9072e09ab502 Mon Sep 17 00:00:00 2001 From: tangwang Date: Wed, 22 Oct 2025 11:50:49 +0800 Subject: [PATCH] docs --- 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 | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------------------------- offline_tasks/doc/RUN_SCRIPT_GUIDE.md | 304 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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/系统改进总结-20241017.md | 445 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/doc/详细设计文档.md | 711 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ offline_tasks/doc/调试指南.md | 332 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/doc/运行脚本指南.md | 304 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- offline_tasks/doc/项目重构说明-20241017.md | 397 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 21 files changed, 783 insertions(+), 5430 deletions(-) delete mode 100644 offline_tasks/doc/COMPLETE_INDEX_LIST.md delete mode 100644 offline_tasks/doc/DATABASE_SETUP.md delete mode 100644 offline_tasks/doc/DEBUG_GUIDE.md delete mode 100644 offline_tasks/doc/OFFLINE_INDEX_SPEC.md delete mode 100644 offline_tasks/doc/RUN_SCRIPT_GUIDE.md delete mode 100644 offline_tasks/doc/SWING_USAGE.md delete mode 100644 offline_tasks/doc/Swing实现总结.md delete mode 100644 offline_tasks/doc/Swing算法使用指南.md delete mode 100644 offline_tasks/doc/TROUBLESHOOTING.md delete mode 100644 offline_tasks/doc/从这里开始.md delete mode 100644 offline_tasks/doc/完整索引列表.md delete mode 100644 offline_tasks/doc/快速开始.md delete mode 100644 offline_tasks/doc/故障排查指南.md delete mode 100644 offline_tasks/doc/数据库配置说明.md delete mode 100644 offline_tasks/doc/更新日志.md delete mode 100644 offline_tasks/doc/系统改进总结-20241017.md create mode 100644 offline_tasks/doc/详细设计文档.md delete mode 100644 offline_tasks/doc/调试指南.md delete mode 100644 offline_tasks/doc/运行脚本指南.md delete mode 100644 offline_tasks/doc/项目重构说明-20241017.md diff --git a/offline_tasks/doc/COMPLETE_INDEX_LIST.md b/offline_tasks/doc/COMPLETE_INDEX_LIST.md deleted file mode 100644 index 99e19c7..0000000 --- a/offline_tasks/doc/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/doc/DATABASE_SETUP.md b/offline_tasks/doc/DATABASE_SETUP.md deleted file mode 100644 index 352aacc..0000000 --- a/offline_tasks/doc/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/doc/DEBUG_GUIDE.md b/offline_tasks/doc/DEBUG_GUIDE.md deleted file mode 100644 index 85f78b8..0000000 --- a/offline_tasks/doc/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/doc/OFFLINE_INDEX_SPEC.md b/offline_tasks/doc/OFFLINE_INDEX_SPEC.md deleted file mode 100644 index ba5be7d..0000000 --- a/offline_tasks/doc/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/doc/README.md b/offline_tasks/doc/README.md index cf64c37..f35fad7 100644 --- a/offline_tasks/doc/README.md +++ b/offline_tasks/doc/README.md @@ -1,81 +1,103 @@ # 推荐系统离线任务文档中心 -本目录包含推荐系统所有重要文档。 +本目录包含推荐系统离线任务的核心文档。 -## 📚 文档目录 +--- -### 快速开始 +## 📚 核心文档 -- **[从这里开始.md](./从这里开始.md)** - 新手入门指南，了解项目结构和基本概念 -- **[快速开始.md](./快速开始.md)** - 快速运行离线任务的步骤 -- **[Swing快速开始.md](../collaboration/Swing快速开始.md)** - C++ Swing算法快速使用指南 +### 1. 详细设计文档 -### 使用指南 +**文件**: [详细设计文档.md](./详细设计文档.md) -- **[Swing算法使用指南.md](./Swing算法使用指南.md)** - 详细的Swing算法使用文档 -- **[运行脚本指南.md](./运行脚本指南.md)** - 所有离线任务脚本的使用说明 -- **[调试指南.md](./调试指南.md)** - Debug模式和日志使用说明 +**内容**: +- 项目概述和系统架构 +- 功能模块详解（i2i相似度、兴趣聚合） +- 使用指南和参数配置 +- 业务场景应用示例 +- 故障排查和性能优化 -### 数据规范 +**适用对象**: 开发人员、产品经理、新人入门 -- **[离线索引数据规范.md](./离线索引数据规范.md)** - 所有离线索引的格式和说明 -- **[Redis数据规范.md](./Redis数据规范.md)** - Redis中数据的key格式和结构 -- **[完整索引列表.md](./完整索引列表.md)** - 系统中所有索引的完整清单 +--- -### 配置说明 +### 2. 离线索引数据规范 -- **[数据库配置说明.md](./数据库配置说明.md)** - 数据库连接和表结构说明 -- **配置文件**: `../config/offline_config.py` - 所有可配置参数 +**文件**: [离线索引数据规范.md](./离线索引数据规范.md) -### 实现总结 +**内容**: +- 索引任务列表和调度频次 +- 输出文件格式详细说明 +- i2i索引规范（C++ Swing、Python Swing、W2V、DeepWalk、Content） +- 兴趣聚合索引规范（维度、列表类型） +- 文件命名规范和数据质量检查 -- **[Swing实现总结.md](./Swing实现总结.md)** - C++ Swing集成实现的完整说明 -- **[系统改进总结-20241017.md](./系统改进总结-20241017.md)** - 2024-10-17系统改进汇总 -- **[项目重构说明-20241017.md](./项目重构说明-20241017.md)** - 目录结构和执行脚本重构详解 🆕 +**适用对象**: 开发人员、数据工程师、运维人员 -### 维护文档 +--- -- **[故障排查指南.md](./故障排查指南.md)** - 常见问题和解决方案 -- **[更新日志.md](./更新日志.md)** - 系统更新历史 +### 3. Redis数据规范 -## 📂 相关文档 +**文件**: [Redis数据规范.md](./Redis数据规范.md) -### 其他模块文档 +**内容**: +- Redis Key命名规范 +- 数据灌入规范表 +- i2i索引和兴趣聚合索引的存储格式 +- 数据加载流程和示例代码 +- 查询示例和监控指标 -- **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. 参考文档中的"快速开始"部分运行系统 +3. 遇到问题查看"故障排查"章节 -### 新用户 +### 我是开发人员 +1. 查看 **[详细设计文档.md](./详细设计文档.md)** 的"功能模块详解" +2. 参考 **[离线索引数据规范.md](./离线索引数据规范.md)** 了解数据格式 +3. 开发在线接口时参考 **[Redis数据规范.md](./Redis数据规范.md)** -1. 先阅读 **[从这里开始.md](./从这里开始.md)** 了解整体架构 -2. 然后看 **[快速开始.md](./快速开始.md)** 快速运行系统 -3. 需要时查阅具体的使用指南和数据规范 +### 我是运维人员 +1. 查看 **[详细设计文档.md](./详细设计文档.md)** 的"定时任务设置" +2. 参考 **[Redis数据规范.md](./Redis数据规范.md)** 进行数据加载 +3. 遇到问题查看"故障排查"和日志文件 -### 开发人员 +--- -1. 查看 **[运行脚本指南.md](./运行脚本指南.md)** 了解所有脚本 -2. 参考 **[调试指南.md](./调试指南.md)** 进行调试 -3. 遵循 **数据规范** 文档进行开发 +## 📂 其他资源 -### 运维人员 +### 配置文件 +- **离线任务配置**: `../config/offline_config.py` +- **主执行脚本**: `../run.sh` -1. 配置前先看 **[数据库配置说明.md](./数据库配置说明.md)** -2. 遇到问题查看 **[故障排查指南.md](./故障排查指南.md)** -3. 了解 **[Redis数据规范.md](./Redis数据规范.md)** 便于维护 +### 相关模块文档 +- **Collaboration模块** (C++ Swing): `../collaboration/README.md` +- **GraphEmbedding模块**: `../graphembedding/*/README.md` +- **Hot模块**: `../hot/README.md` -## 📝 文档更新 +### 项目README +- **项目总览**: `../../README.md` +- **离线任务模块**: `../README.md` -所有文档由项目维护者更新。如有疑问或发现错误，请联系团队。 +--- -**最后更新**: 2024-10-17 +## 🔄 文档更新记录 + +- **2024-10-17**: 整合文档，简化为3个核心文档 +- **2024-10-16**: 初始版本，包含完整功能文档 + +--- +## 📝 文档维护 + +所有文档由推荐系统团队维护。 + +如有疑问、发现错误或建议改进，请联系团队。 + +**最后更新**: 2024-10-17 diff --git a/offline_tasks/doc/RUN_SCRIPT_GUIDE.md b/offline_tasks/doc/RUN_SCRIPT_GUIDE.md deleted file mode 100644 index 1f40004..0000000 --- a/offline_tasks/doc/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/doc/SWING_USAGE.md b/offline_tasks/doc/SWING_USAGE.md deleted file mode 100644 index 3a6fdc9..0000000 --- a/offline_tasks/doc/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/doc/Swing实现总结.md b/offline_tasks/doc/Swing实现总结.md deleted file mode 100644 index c663ea5..0000000 --- a/offline_tasks/doc/Swing实现总结.md +++ /dev/null @@ -1,375 +0,0 @@ -# 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 deleted file mode 100644 index 3a6fdc9..0000000 --- a/offline_tasks/doc/Swing算法使用指南.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/doc/TROUBLESHOOTING.md b/offline_tasks/doc/TROUBLESHOOTING.md deleted file mode 100644 index bbf4f6f..0000000 --- a/offline_tasks/doc/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/doc/从这里开始.md b/offline_tasks/doc/从这里开始.md deleted file mode 100644 index 418a985..0000000 --- a/offline_tasks/doc/从这里开始.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/doc/完整索引列表.md b/offline_tasks/doc/完整索引列表.md deleted file mode 100644 index 99e19c7..0000000 --- a/offline_tasks/doc/完整索引列表.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/doc/快速开始.md b/offline_tasks/doc/快速开始.md deleted file mode 100644 index 65be781..0000000 --- a/offline_tasks/doc/快速开始.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/doc/故障排查指南.md b/offline_tasks/doc/故障排查指南.md deleted file mode 100644 index bbf4f6f..0000000 --- a/offline_tasks/doc/故障排查指南.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/doc/数据库配置说明.md b/offline_tasks/doc/数据库配置说明.md deleted file mode 100644 index 352aacc..0000000 --- a/offline_tasks/doc/数据库配置说明.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/doc/更新日志.md b/offline_tasks/doc/更新日志.md deleted file mode 100644 index 1b7bad9..0000000 --- a/offline_tasks/doc/更新日志.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/doc/系统改进总结-20241017.md b/offline_tasks/doc/系统改进总结-20241017.md deleted file mode 100644 index b21173b..0000000 --- a/offline_tasks/doc/系统改进总结-20241017.md +++ /dev/null @@ -1,445 +0,0 @@ -# 推荐系统离线任务改进总结 - -**日期**: 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. run_cpp_swing() → C++ Swing算法（使用session） - -核心算法任务: -4. i2i_swing.py → Python Swing算法（启用日期维度） -5. i2i_session_w2v.py → Session W2V -6. i2i_deepwalk.py → DeepWalk -7. i2i_content_similar.py → 内容相似度 -8. 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: 运行全部任务（推荐） -bash run.sh - -# 方式2: 使用Python版本（简化版） -python3 run_all.py --debug - -# 方式3: 分步运行 -# 步骤1: 获取商品属性 -python3 scripts/fetch_item_attributes.py - -# 步骤2: 生成session文件 -python3 scripts/generate_session.py --lookback_days 730 - -# 步骤3: 运行C++ Swing -cd collaboration && bash run.sh && cd .. - -# 步骤4: 运行Python Swing（启用日期维度） -python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug -``` - -### C++ Swing算法 - -```bash -# C++ Swing现已集成到run.sh，会自动执行 -# 如需单独运行: -cd /home/tw/recommendation/offline_tasks/collaboration -bash run.sh - -# 查看结果 -ls -lh output/swing_similar*.txt -cat output/swing_similar_readable.txt | head -20 -``` - -### 查看文档 - -```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 # 修改：添加加载函数 -│ ├── collaboration/ # 移动：C++ Swing目录 -│ │ ├── src/ -│ │ ├── bin/ -│ │ ├── run.sh # 修改：路径更新 -│ │ └── output/ -│ ├── doc/ # 新增：文档中心 -│ │ ├── README.md -│ │ ├── 快速开始.md -│ │ ├── Swing算法使用指南.md -│ │ └── ... -│ ├── output/ -│ │ ├── item_attributes_mappings.json # 新增：映射文件 -│ │ ├── item_attributes_stats.txt # 新增：统计信息 -│ │ └── session.txt.YYYYMMDD # session文件 -│ ├── run.sh # 新增：主执行脚本 -│ ├── run_all.py # 修改：简化版本 -│ └── README.md -``` - ---- - -## 🔧 C++ Swing算法集成 - -### 改进内容 - -**之前**: C++ Swing在外层目录，需要手动切换 -```bash -cd /home/tw/recommendation/collaboration -bash run.sh -``` - -**现在**: 已移入offline_tasks，集成到`run.sh`自动执行 - -### 执行流程 - -``` -run.sh: -1. fetch_item_attributes.py -2. generate_session.py ← 生成session.txt.YYYYMMDD.cpp -3. collaboration/run.sh ← 直接调用C++ Swing - ├─ 编译C++程序 - ├─ 读取session文件 - ├─ 运行Swing算法 - ├─ 合并多线程结果 - └─ 生成可读版本（自动添加商品名） -4. i2i_swing.py ← Python Swing -5. i2i_session_w2v.py ← Session W2V -6. i2i_deepwalk.py ← DeepWalk -7. i2i_content_similar.py ← 内容相似度 -8. interest_aggregation.py ← 兴趣聚合 -9. load_index_to_redis.py ← 加载到Redis -``` - -### 输出结果 - -C++ Swing执行后，结果保存在： -``` -offline_tasks/collaboration/output_YYYYMMDD/ -├── sim_matrx.* # 多线程输出 -├── swing_similar.txt # 合并结果（ID格式） -└── swing_similar_readable.txt # 可读版本（ID:名称格式） - -offline_tasks/collaboration/output -> output_YYYYMMDD # 软链接 -``` - -### 优势 - -- ✅ **自动化**: 无需手动切换目录 -- ✅ **依赖管理**: 确保session文件已生成 -- ✅ **错误处理**: 失败不影响后续任务 -- ✅ **日志统一**: 所有任务日志在同一个文件 -- ✅ **性能**: C++版本比Python版快10-100倍 - -### 单独运行 - -如需单独运行C++ Swing（不执行其他任务）： -```bash -cd /home/tw/recommendation/offline_tasks/collaboration -bash run.sh -``` - ---- - -## 🎯 核心改进点总结 - -1. **✅ 性能优化**: 减少80-90%的数据库查询 -2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离 -3. **✅ 功能增强**: Swing算法支持日期维度 -4. **✅ 集成优化**: C++ Swing集成到统一流程 -5. **✅ 文档规范**: 统一管理，中文命名，清晰索引 -6. **✅ 代码质量**: 无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..fdf27c0 --- /dev/null +++ b/offline_tasks/doc/详细设计文档.md @@ -0,0 +1,711 @@ +# 推荐系统离线任务详细设计文档 + +## 📋 文档说明 + +本文档是推荐系统离线任务的详细设计文档，包含系统架构、功能模块、实现细节和使用指南。 + +**最后更新**: 2024-10-17 +**版本**: v1.1 +**状态**: ✅ 已完成并可用 + +--- + +## 📦 项目概述 + +推荐系统离线任务负责生成各类推荐索引，包括商品相似度索引（i2i）和兴趣点聚合索引，为在线推荐系统提供数据支撑。 + +### 核心功能 + +1. **i2i相似度索引**（4种算法） + - Swing算法（C++高性能版 + Python版） + - Session Word2Vec + - DeepWalk + - Content-based（内容相似度） + +2. **兴趣点聚合索引**（11个维度） + - 7个单维度：platform、client_platform、supplier、category_level1-4 + - 4个组合维度：platform_client、platform_category2、platform_category3、client_category2 + - 3种列表类型：hot（热门）、cart（加购）、new（新品）、global（全局） + +### 技术特点 + +- ✅ **完整性**: 行为相似 + 内容相似，短期热门 + 长期稳定 +- ✅ **灵活性**: 支持4级分类查询，支持多维度组合 +- ✅ **可扩展性**: 易于添加新维度和新算法 +- ✅ **高性能**: C++ Swing算法性能比Python快10-100倍 + +--- + +## 🏗️ 系统架构 + +### 目录结构 + +``` +offline_tasks/ +├── scripts/ # Python脚本 +│ ├── fetch_item_attributes.py # 前置任务：获取商品属性 +│ ├── generate_session.py # 前置任务：生成session +│ ├── i2i_swing.py # Python Swing算法 +│ ├── i2i_session_w2v.py # Session W2V +│ ├── i2i_deepwalk.py # DeepWalk +│ ├── i2i_content_similar.py # 内容相似度 +│ ├── interest_aggregation.py # 兴趣聚合 +│ ├── load_index_to_redis.py # 加载到Redis +│ ├── add_names_to_swing.py # 添加商品名 +│ └── debug_utils.py # Debug工具 +├── collaboration/ # C++ Swing算法 +│ ├── src/ # C++源码 +│ ├── run.sh # 执行脚本 +│ └── output/ # 输出目录 +├── config/ +│ └── offline_config.py # 配置文件 +├── doc/ # 文档目录 +│ ├── 详细设计文档.md # 本文档 +│ ├── 离线索引数据规范.md # 数据输出规范 +│ └── Redis数据规范.md # Redis存储规范 +├── output/ # 输出文件 +├── logs/ # 日志文件 +├── run.sh # ⭐ 主执行脚本 +├── run_all.py # Python版本执行脚本 +└── README.md +``` + +### 执行流程 + +``` +1. 环境准备 + └─ 清理旧进程、创建必要目录 + +2. 前置任务 + ├─ fetch_item_attributes.py → 商品属性映射（避免重复查询数据库） + ├─ generate_session.py → 用户session文件 + └─ collaboration/run.sh → C++ Swing (高性能版本) + +3. i2i算法任务 + ├─ i2i_swing.py → Python Swing (支持日期维度) + ├─ i2i_session_w2v.py → Session W2V + ├─ i2i_deepwalk.py → DeepWalk + └─ i2i_content_similar.py → 内容相似度 + +4. 兴趣聚合 + └─ interest_aggregation.py → 多维度聚合 + +5. 加载Redis + └─ load_index_to_redis.py → 导入Redis + +6. 完成 + └─ 输出结果文件列表 +``` + +--- + +## 🎯 功能模块详解 + +### 1. i2i相似度索引 + +#### 1.1 Swing算法 + +**两个版本：** + +**C++高性能版本** +- 文件位置: `offline_tasks/collaboration/` +- 性能: 比Python快10-100倍 +- 适用场景: 生产环境，海量数据（>50,000商品） +- 输出格式: `item_id \t similar_id1:score1,similar_id2:score2,...` +- 分数特点: 原始Swing分数（未归一化） + +**Python标准版本** +- 文件: `scripts/i2i_swing.py` +- 性能: 适中，易于调试 +- 适用场景: 开发测试，需要高级特性（时间衰减、日期维度） +- 输出格式: `item_id \t item_name \t similar_id1:score1,...` +- 分数特点: 归一化到0-1区间 + +**参数配置：** +```bash +# C++ Swing +ALPHA=0.7 # Swing alpha参数（0.5-1.0） +THRESHOLD1=1 # 交互强度阈值1 +THRESHOLD2=3 # 交互强度阈值2 +THREAD_NUM=4 # 线程数 + +# Python Swing +--lookback_days 730 # 回看天数 +--use_daily_session # 启用日期维度（同时考虑用户整体行为和单日行为） +--time_decay # 启用时间衰减 +--debug # Debug模式 +``` + +#### 1.2 Session Word2Vec + +基于用户会话序列的商品相似度计算，捕捉用户浏览顺序关系。 + +**特点：** +- 基于Word2Vec算法 +- 考虑商品在会话中的顺序 +- 适合"看了又看"场景 + +**参数：** +```bash +python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model +``` + +#### 1.3 DeepWalk + +基于图随机游走的商品相似度计算，发现商品间的深层关系。 + +**特点：** +- 构建商品关系图 +- 随机游走生成序列 +- 发现间接关联 + +**参数：** +```bash +python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph +``` + +#### 1.4 Content-based 内容相似度 + +基于商品属性（分类、供应商等）计算相似度。 + +**三种方法：** +- TF-IDF方法: 基于商品名称文本 +- 分类方法: 基于商品分类层级 +- 混合方法: 综合多种特征（推荐） + +**参数：** +```bash +python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid +``` + +### 2. 兴趣点聚合索引 + +根据不同维度聚合热门商品，支持个性化推荐。 + +#### 支持的维度 + +**单维度（7个）：** +- `platform`: 业务平台（pc, h5, app等） +- `client_platform`: 客户端平台（iOS, Android, Web等） +- `supplier`: 供应商 +- `category_level1`: 一级分类 +- `category_level2`: 二级分类 +- `category_level3`: 三级分类 +- `category_level4`: 四级分类 + +**组合维度（4个）：** +- `platform_client`: 平台+客户端 +- `platform_category2`: 平台+二级分类 +- `platform_category3`: 平台+三级分类 +- `client_category2`: 客户端+二级分类 + +#### 列表类型 + +- **hot**: 热门商品（最近N天高交互） +- **cart**: 加购商品（高加购率） +- **new**: 新品（最近90天上架） +- **global**: 全局热门 + +**参数：** +```bash +python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 +``` + +### 3. 前置任务 + +#### 3.1 商品属性获取 + +**问题**: 多个脚本需要商品名称，重复查询数据库效率低。 + +**解决方案**: 前置任务一次性获取，保存到本地文件。 + +```bash +python3 scripts/fetch_item_attributes.py +``` + +**输出**: +- `output/item_attributes_mappings.json`: 商品ID->名称映射 +- `output/item_attributes_stats.txt`: 统计信息 + +**效果**: 减少80-90%的数据库查询次数 + +#### 3.2 Session文件生成 + +从数据库提取用户行为数据，生成session文件供算法使用。 + +```bash +python3 scripts/generate_session.py --lookback_days 730 --format both +``` + +**输出格式：** +- `session.txt.YYYYMMDD`: 标准格式（包含uid） +- `session.txt.YYYYMMDD.cpp`: C++格式（纯json） + +**行为权重：** +- purchase: 10.0（购买） +- contactFactory: 5.0（联系厂家） +- addToCart: 3.0（加入购物车） +- addToPool: 2.0（加入询价池） + +--- + +## 🚀 使用指南 + +### 快速开始（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 + +# 完整任务（推荐使用run.sh） +bash run.sh +``` + +### 运行完整流程 + +**方式1: 使用run.sh（推荐）** +```bash +cd /home/tw/recommendation/offline_tasks +bash run.sh +``` + +这将自动执行： +- 前置任务（商品属性、session生成） +- C++ Swing算法 +- Python算法（Swing、W2V、DeepWalk、内容相似度） +- 兴趣聚合 +- Redis加载 + +**方式2: 使用run_all.py（简化版）** +```bash +python3 run_all.py --debug +``` + +不包括C++ Swing和Redis加载。 + +**方式3: 单独运行任务** +```bash +# 1. 前置任务 +python3 scripts/fetch_item_attributes.py +python3 scripts/generate_session.py --lookback_days 730 + +# 2. C++ Swing +cd collaboration && bash run.sh && cd .. + +# 3. Python算法 +python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug +python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 +python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 +python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid + +# 4. 兴趣聚合 +python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 + +# 5. 加载到Redis +python3 scripts/load_index_to_redis.py --redis-host localhost +``` + +### 配置说明 + +主要配置在 `config/offline_config.py`： + +```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 +} + +# 时间配置 +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% +``` + +### 查看输出结果 + +所有输出文件在 `output/` 目录： + +```bash +cd /home/tw/recommendation/offline_tasks/output +ls -lh + +# 查看i2i相似度 +head -5 i2i_swing_20251016.txt + +# 查看兴趣点聚合 +head -5 interest_aggregation_hot_20251016.txt +``` + +### 查看日志 + +```bash +cd /home/tw/recommendation/offline_tasks/logs + +# 主日志 +tail -f run_all_20251016.log + +# 内存监控日志 +tail -f memory_monitor.log + +# Debug日志 +ls debug/ +``` + +--- + +## 📊 输出数据示例 + +### i2i相似度索引 + +**C++ Swing（高性能版）：** +``` +# 文件: collaboration/output/swing_similar.txt +3600052 2704531:0.00431593,2503886:0.00431593,3371410:0.00431593 + +# 可读版本: collaboration/output/swing_similar_readable.txt +3600052:商品A 2704531:商品B:0.00431593,2503886:商品C:0.00431593 +``` + +**Python Swing：** +``` +# 文件: output/i2i_swing_20251016.txt +12345 商品A 23456:0.8523,34567:0.7842,45678:0.7234 +``` + +### 兴趣点聚合索引 + +``` +# 文件: output/interest_aggregation_hot_20251016.txt +platform:pc 12345,23456,34567,45678,56789 +category_level2:200 45678,56789,67890,78901,89012 +platform_category2:pc_200 12345,23456,34567,45678 +``` + +--- + +## 🎬 业务场景应用 + +### 场景1: 首页猜你喜欢 + +**使用索引：** +```python +# 基于平台 +interest:hot:platform:pc + +# 基于分类偏好 +interest:hot:category_level2:200 + +# 基于平台+分类 +interest:hot:platform_category2:pc_200 +``` + +### 场景2: 详情页相关推荐 + +**使用索引：** +```python +# 行为相似（C++ Swing，生产推荐） +item:similar:swing_cpp:12345 + +# 行为相似（Python Swing） +item:similar:swing:12345 + +# 内容相似 +item:similar:content_hybrid:12345 + +# 融合推荐（多算法） +swing_items = redis.get('item:similar:swing_cpp:12345') +w2v_items = redis.get('item:similar:w2v:12345') +content_items = redis.get('item:similar:content_hybrid:12345') +# 融合多个算法结果... +``` + +### 场景3: 搜索结果页推荐 + +**使用索引：** +```python +# 全局热门 +interest:global:platform:pc + +# 分类相关 +interest:global:category_level2:200 +``` + +### 场景4: 供应商店铺页 + +**使用索引：** +```python +# 供应商热门 +interest:hot:supplier:10001 + +# 供应商新品 +interest:new:supplier:10001 +``` + +--- + +## ⚙️ 参数调优建议 + +### Swing算法参数 + +**alpha (0.5-1.0)** +- 越小：越关注用户共同行为的多样性 +- 越大：越容易忽略用户重叠度 +- B2B场景建议：0.5-0.7 + +**threshold1/threshold2** +- threshold1: 筛选用户有效行为（建议1-3） +- threshold2: 计算相似度阈值（建议3-5） +- B2B低频场景可适当降低 + +**thread_num** +- 根据CPU核心数设置 +- 建议：4-8（普通服务器） + +### 数据范围参数 + +**lookback_days** +- B2B低频场景：建议730天（2年） +- B2C高频场景：建议30-90天 +- 数据量大时可适当减少 + +**top_n** +- i2i相似度：建议10-50 +- 兴趣聚合：建议50-1000 + +--- + +## 🔧 故障排查 + +### 常见问题 + +**Q1: 任务运行时间太长** +- 减少 `--lookback_days` 参数（如改为365天） +- 减少 `--top_n` 参数 +- 在更强大的机器上运行 +- 使用C++ Swing代替Python Swing + +**Q2: 内存不足** +- Swing算法特别消耗内存，可以先跳过 +- 只运行DeepWalk或Session W2V +- 对数据进行采样 +- 调整C++代码中的max_session_list_len和max_sim_list_len + +**Q3: 数据库连接超时** +- 检查数据库配置: `config/offline_config.py` +- 测试连接: `python3 test_connection.py` +- 检查网络和防火墙 +- 增加SQL查询超时时间 + +**Q4: Session文件不存在** +```bash +# 重新生成session文件 +python3 scripts/generate_session.py --lookback_days 730 +``` + +**Q5: 编译失败（C++ Swing）** +```bash +# 检查编译器 +g++ --version + +# 手动编译 +cd collaboration +make clean +make +``` + +**Q6: 结果为空** +- 降低threshold参数 +- 增加lookback_days +- 检查数据量: `wc -l output/session.txt.*` + +### 查看错误日志 + +```bash +# 查看最新日志 +tail -100 logs/run_all_$(date +%Y%m%d).log + +# 查看特定任务日志 +tail -100 logs/debug/i2i_swing_*.log + +# 搜索错误信息 +grep -i "error" logs/run_all_*.log +``` + +--- + +## 📈 性能参考 + +在标准配置（730天数据，top_n=50）下的预估运行时间： + +| 任务 | 数据量 | 预估时间 | 内存占用 | +|------|--------|---------|---------| +| C++ Swing | 100万条行为 | 30-120分钟 | 4-8GB | +| Python Swing | 100万条行为 | 2-4小时 | 4-8GB | +| Session W2V | 100万条行为 | 30-60分钟 | 2-4GB | +| DeepWalk | 100万条行为 | 1-2小时 | 2-4GB | +| 内容相似度 | 5万商品 | 10-30分钟 | 1-2GB | +| 兴趣点聚合 | 100万条行为 | 30-60分钟 | 2-4GB | + +**总计**: 约4-8小时（取决于数据量和机器配置） + +--- + +## 🔄 定时任务设置 + +### 使用crontab + +```bash +# 编辑crontab +crontab -e + +# 每天凌晨2点运行（推荐） +0 2 * * * cd /home/tw/recommendation/offline_tasks && bash run.sh >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 + +# 或者使用Python版本（不含C++ Swing和Redis加载） +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 +``` + +### 分任务调度 + +```bash +# 每天凌晨2点运行i2i算法 +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_swing.py --lookback_days 730 + +# 每天凌晨4点运行兴趣聚合 +0 4 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/interest_aggregation.py --lookback_days 730 + +# 每周日凌晨3点运行内容相似度（变化慢） +0 3 * * 0 cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_content_similar.py --top_n 50 +``` + +--- + +## 📊 数据量统计 + +### 索引数量估算 + +| 索引类型 | 索引数量 | 单条大小 | 总大小 | 更新频率 | +|---------|---------|---------|--------|---------| +| i2i_swing_cpp | ~50,000 | ~400B | ~20MB | 每天 | +| i2i_swing | ~50,000 | ~500B | ~25MB | 每天 | +| i2i_session_w2v | ~50,000 | ~500B | ~25MB | 每天 | +| i2i_deepwalk | ~50,000 | ~500B | ~25MB | 每天 | +| i2i_content | ~50,000 | ~500B | ~25MB | 每周 | +| interest_hot | ~10,000 | ~1KB | ~10MB | 每天 | +| interest_cart | ~10,000 | ~1KB | ~10MB | 每天 | +| interest_new | ~5,000 | ~1KB | ~5MB | 每天 | +| interest_global | ~10,000 | ~1KB | ~10MB | 每天 | +| **总计** | **~295,000** | - | **~155MB** | - | + +### Redis内存占用 + +加载到Redis后的内存占用约 **180MB**（包含key开销） + +--- + +## 💡 核心优势 + +### 1. 完整性 +- ✅ 行为相似 + 内容相似 +- ✅ 短期热门 + 长期稳定 +- ✅ 粗粒度 + 细粒度 + +### 2. 灵活性 +- ✅ 支持4级分类查询 +- ✅ 支持供应商维度 +- ✅ 支持多维度组合 + +### 3. 可扩展性 +- ✅ 易于添加新维度 +- ✅ 易于添加新算法 +- ✅ 配置化管理 + +### 4. 高性能 +- ✅ C++ Swing高性能实现 +- ✅ 前置任务减少数据库查询 +- ✅ 多线程并行处理 + +### 5. 实用性 +- ✅ 适配真实B2B数据 +- ✅ 文档完善 +- ✅ 易于维护 + +--- + +## 🎯 关键改进点总结 + +1. **✅ 性能优化**: 前置任务减少80-90%的数据库查询，C++ Swing提升10-100倍性能 +2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离 +3. **✅ 功能增强**: Swing算法支持日期维度，同时考虑用户整体和单日行为 +4. **✅ 集成优化**: C++ Swing集成到统一流程，一键执行 +5. **✅ 文档规范**: 统一管理，清晰索引 +6. **✅ 代码质量**: 统一编码规范，完善错误处理 + +--- + +## 📝 相关文档 + +1. **离线索引数据规范** (`离线索引数据规范.md`) + - 任务输出数据的详细格式说明 + - 文件命名规范 + - 数据质量检查 + +2. **Redis数据规范** (`Redis数据规范.md`) + - Redis Key规范 + - 数据加载流程 + - 查询示例 + +3. **配置文件** (`config/offline_config.py`) + - 数据库配置 + - Redis配置 + - 算法参数 + +--- + +## 📞 联系与支持 + +如有问题，请： +1. 查看本文档的故障排查部分 +2. 查看日志文件: `logs/` +3. 查看相关文档: `doc/离线索引数据规范.md`、`doc/Redis数据规范.md` +4. 联系开发团队 + +--- + +**文档版本**: v1.1 +**最后更新**: 2024-10-17 +**维护者**: 推荐系统团队 + diff --git a/offline_tasks/doc/调试指南.md b/offline_tasks/doc/调试指南.md deleted file mode 100644 index 85f78b8..0000000 --- a/offline_tasks/doc/调试指南.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/doc/运行脚本指南.md b/offline_tasks/doc/运行脚本指南.md deleted file mode 100644 index 1f40004..0000000 --- a/offline_tasks/doc/运行脚本指南.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/doc/项目重构说明-20241017.md b/offline_tasks/doc/项目重构说明-20241017.md deleted file mode 100644 index 88af7ce..0000000 --- a/offline_tasks/doc/项目重构说明-20241017.md +++ /dev/null @@ -1,397 +0,0 @@ -# 项目重构说明 - 2024-10-17 - -## ✅ 完成的重构 - -### 1. 目录结构调整 - -**改动**: 将`collaboration`目录移入`offline_tasks` - -**之前**: -``` -recommendation/ -├── offline_tasks/ -│ ├── scripts/ -│ └── ... -└── collaboration/ # 外层目录 - ├── src/ - └── run.sh -``` - -**之后**: -``` -recommendation/ -└── offline_tasks/ - ├── scripts/ - ├── collaboration/ # 移入内部 - │ ├── src/ - │ └── run.sh - └── ... -``` - -**优势**: -- ✅ 统一目录结构，所有离线任务在同一目录 -- ✅ 简化路径配置 -- ✅ 便于统一管理和部署 - ---- - -### 2. 执行脚本简化 - -**改动**: 主执行脚本从`run_all.py`改为`run.sh`，直接调用各个脚本 - -**之前的流程**: -```python -# run_all.py (Python实现) -run_script('fetch_item_attributes.py') -run_script('generate_session.py') -run_cpp_swing() # 调用collaboration/run.sh -run_script('i2i_swing.py') -# ... -``` - -**现在的流程**: -```bash -# run.sh (Shell实现) -python3 scripts/fetch_item_attributes.py -python3 scripts/generate_session.py -cd collaboration && bash run.sh && cd .. -python3 scripts/i2i_swing.py -# ... -``` - -**优势**: -- ✅ 代码更简洁，减少抽象层 -- ✅ 直接调用，易于理解和调试 -- ✅ 内存监控、错误处理更灵活 -- ✅ 配置参数集中在顶部，便于修改 - ---- - -### 3. 路径更新 - -所有相关路径已更新： - -**collaboration/run.sh**: -- `SESSION_DATA_DIR="../offline_tasks/output"` → `"../output"` -- `DEBUG_SCRIPT="../offline_tasks/scripts/..."` → `"../scripts/..."` - -**文档更新**: -- ✅ `README.md` -- ✅ `doc/离线索引数据规范.md` -- ✅ `doc/Redis数据规范.md` -- ✅ `doc/系统改进总结-20241017.md` - ---- - -## 📋 新的项目结构 - -``` -offline_tasks/ -├── scripts/ # Python脚本 -│ ├── fetch_item_attributes.py # 前置：获取商品属性 -│ ├── generate_session.py # 前置：生成session -│ ├── i2i_swing.py # Python Swing -│ ├── i2i_session_w2v.py # Session W2V -│ ├── i2i_deepwalk.py # DeepWalk -│ ├── i2i_content_similar.py # 内容相似度 -│ ├── interest_aggregation.py # 兴趣聚合 -│ ├── load_index_to_redis.py # 加载到Redis -│ ├── add_names_to_swing.py # 添加商品名 -│ └── debug_utils.py # Debug工具 -├── collaboration/ # C++ Swing算法 -│ ├── src/ -│ │ ├── swing.cc # Swing实现 -│ │ ├── swing_symmetric.cc # 对称Swing -│ │ ├── icf_simple.cc # 简单协同 -│ │ └── ucf.py # 用户协同 -│ ├── bin/ # 编译后的二进制 -│ ├── include/ # 头文件 -│ ├── utils/ # 工具函数 -│ ├── run.sh # C++ Swing执行脚本 -│ ├── Makefile # 编译配置 -│ └── output/ # 输出目录 -├── config/ -│ └── offline_config.py # 配置文件 -├── doc/ # 文档中心 -│ ├── README.md -│ ├── 快速开始.md -│ ├── Swing算法使用指南.md -│ ├── 离线索引数据规范.md -│ ├── Redis数据规范.md -│ └── ... -├── output/ # 输出文件 -│ ├── item_attributes_mappings.json -│ ├── session.txt.* -│ └── *.txt -├── logs/ # 日志文件 -├── run.sh # ⭐ 主执行脚本（推荐） -├── run_all.py # Python版本（保留但简化） -└── README.md -``` - ---- - -## 🚀 使用方式 - -### 主要方式：run.sh（推荐） - -```bash -cd /home/tw/recommendation/offline_tasks - -# 直接运行（使用默认配置） -bash run.sh - -# 修改配置后运行 -# 编辑 run.sh 顶部的配置区域 -vim run.sh - -# 查看帮助 -cat run.sh | head -40 # 查看配置说明 -``` - -**run.sh配置项**: -```bash -# 算法参数 -LOOKBACK_DAYS=730 -TOP_N=50 -DEBUG_MODE="--debug" # 留空则不开启debug - -# Redis配置 -REDIS_HOST="localhost" -REDIS_PORT=6379 - -# 内存监控阈值 -MEM_WARN_THRESHOLD=25 # GB -MEM_KILL_THRESHOLD=35 # GB -``` - -### 备用方式：run_all.py（简化版） - -```bash -cd /home/tw/recommendation/offline_tasks - -# 运行（不包括C++ Swing和Redis加载） -python3 run_all.py --debug -``` - -**注意**: `run_all.py`已简化，只包含： -- 前置任务（商品属性、session） -- Python算法任务（Swing、W2V、DeepWalk等） -- 不包括C++ Swing和Redis加载 - ---- - -## 📊 执行流程对比 - -### run.sh（完整流程） - -``` -1. 环境准备 - ├─ 清理旧进程 - └─ 创建必要目录 - -2. 前置任务 - ├─ fetch_item_attributes.py → 商品属性映射 - ├─ generate_session.py → 用户session - └─ collaboration/run.sh → C++ Swing (高性能) - -3. i2i算法任务 - ├─ i2i_swing.py → Python Swing (日期维度) - ├─ i2i_session_w2v.py → Session W2V - ├─ i2i_deepwalk.py → DeepWalk - └─ i2i_content_similar.py → 内容相似度 - -4. 兴趣聚合 - └─ interest_aggregation.py → 多维度聚合 - -5. 加载Redis - └─ load_index_to_redis.py → 导入Redis - -6. 完成 - └─ 输出结果文件列表 -``` - -### run_all.py（简化流程） - -``` -1. 前置任务 - ├─ fetch_item_attributes.py - └─ generate_session.py - -2. i2i算法任务 - ├─ i2i_swing.py - ├─ i2i_session_w2v.py - ├─ i2i_deepwalk.py - └─ i2i_content_similar.py - -3. 兴趣聚合 - └─ interest_aggregation.py -``` - ---- - -## 💡 关键改进 - -### 1. 代码简化 - -**删除的冗余代码**: -- `run_all.py`中的`run_cpp_swing()`函数（45行） -- 复杂的子进程调用和错误处理 - -**简化效果**: -- run.sh: 直接调用，清晰明了 -- run_all.py: 从270行简化到211行 - -### 2. 灵活性提升 - -**run.sh的优势**: -```bash -# 内存监控（自动） -check_memory $pid "$task_name" & - -# 任务函数（统一） -run_task "任务名" "python3 scripts/xxx.py" - -# 配置集中（顶部） -LOOKBACK_DAYS=730 -DEBUG_MODE="--debug" -``` - -### 3. 错误处理 - -**之前**: -- Python捕获异常，日志分散 -- 失败后需要手动排查 - -**现在**: -- Shell直接显示错误 -- 内存监控自动处理OOM -- 任务失败继续执行后续任务 - ---- - -## 🔧 常见操作 - -### 修改算法参数 - -```bash -# 编辑 run.sh -vim run.sh - -# 修改这些参数 -LOOKBACK_DAYS=365 # 回看天数 -TOP_N=100 # 推荐数量 -DEBUG_MODE="" # 关闭debug -``` - -### 只运行特定任务 - -```bash -cd /home/tw/recommendation/offline_tasks - -# 只运行C++ Swing -cd collaboration && bash run.sh && cd .. - -# 只运行Python Swing -python3 scripts/i2i_swing.py --lookback_days 730 --debug - -# 只加载Redis -python3 scripts/load_index_to_redis.py --redis-host localhost -``` - -### 查看日志 - -```bash -# 主日志 -tail -f logs/run_all_$(date +%Y%m%d).log - -# 内存监控日志 -tail -f logs/memory_monitor.log - -# Debug日志 -ls logs/debug/ -``` - ---- - -## 📝 迁移指南 - -如果你之前使用`python3 run_all.py`，现在改用`bash run.sh`： - -### 命令对应关系 - -| 之前 | 现在 | 说明 | -|------|------|------| -| `python3 run_all.py` | `bash run.sh` | 完整流程 | -| `python3 run_all.py --debug` | `bash run.sh` | run.sh默认开启debug | -| 无对应命令 | `bash run.sh` | 现在包含Redis加载 | - -### 定时任务更新 - -**旧的crontab**: -```cron -0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py -``` - -**新的crontab**: -```cron -0 3 * * * cd /home/tw/recommendation/offline_tasks && bash run.sh >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 -``` - ---- - -## ⚠️ 注意事项 - -1. **路径依赖**: - - 确保在`offline_tasks`目录下执行`bash run.sh` - - 不要在其他目录执行 - -2. **内存监控**: - - 默认阈值：警告25GB，终止35GB - - 根据服务器配置调整`MEM_WARN_THRESHOLD`和`MEM_KILL_THRESHOLD` - -3. **并行执行**: - - 不建议同时运行多个`run.sh`实例 - - 脚本会自动清理旧进程 - -4. **失败处理**: - - 单个任务失败不会终止整体流程 - - 查看日志确认失败原因 - ---- - -## 🎯 总结 - -### 改进前后对比 - -| 方面 | 改进前 | 改进后 | -|------|--------|--------| -| **目录结构** | collaboration在外层 | 统一在offline_tasks内 | -| **主执行脚本** | run_all.py (Python) | run.sh (Shell) | -| **代码复杂度** | 270行，多层抽象 | 214行，直接调用 | -| **配置方式** | 参数分散 | 集中在顶部 | -| **内存监控** | 无 | 自动监控+自动终止 | -| **错误处理** | Python异常捕获 | Shell直接显示 | -| **包含任务** | 不含Redis加载 | 含完整流程 | - -### 核心改进 - -1. ✅ **结构简化**: collaboration目录移入，统一管理 -2. ✅ **代码简化**: 去除冗余抽象，直接调用脚本 -3. ✅ **功能增强**: 添加内存监控、统一任务管理 -4. ✅ **易用性**: 配置集中、日志清晰、错误明确 - ---- - -## 📚 相关文档 - -- [快速开始](./快速开始.md) -- [运行脚本指南](./运行脚本指南.md) -- [故障排查指南](./故障排查指南.md) -- [系统改进总结](./系统改进总结-20241017.md) - ---- - -**更新时间**: 2024-10-17 -**状态**: ✅ 已完成并测试 - -- libgit2 0.21.2