Commit 0d5f0a82b42b677f980edc6169ea9072e09ab502
1 parent
2915a5b4
docs
Showing
21 changed files
with
783 additions
and
5430 deletions
Show diff stats
offline_tasks/doc/COMPLETE_INDEX_LIST.md deleted
| @@ -1,350 +0,0 @@ | @@ -1,350 +0,0 @@ | ||
| 1 | -# 完整索引清单 | ||
| 2 | - | ||
| 3 | -## 📋 所有可用的推荐索引 | ||
| 4 | - | ||
| 5 | -### 1. i2i 相似度索引 | ||
| 6 | - | ||
| 7 | -#### 1.1 行为相似索引（3种） | ||
| 8 | - | ||
| 9 | -**Swing算法**： | ||
| 10 | -``` | ||
| 11 | -i2i:swing:{item_id} | ||
| 12 | -``` | ||
| 13 | -示例：`i2i:swing:12345` | ||
| 14 | - | ||
| 15 | -**Session Word2Vec**： | ||
| 16 | -``` | ||
| 17 | -i2i:session_w2v:{item_id} | ||
| 18 | -``` | ||
| 19 | -示例：`i2i:session_w2v:12345` | ||
| 20 | - | ||
| 21 | -**DeepWalk**： | ||
| 22 | -``` | ||
| 23 | -i2i:deepwalk:{item_id} | ||
| 24 | -``` | ||
| 25 | -示例：`i2i:deepwalk:12345` | ||
| 26 | - | ||
| 27 | -#### 1.2 内容相似索引（3种方法） | ||
| 28 | - | ||
| 29 | -**混合方法（推荐）**： | ||
| 30 | -``` | ||
| 31 | -i2i:content_hybrid:{item_id} | ||
| 32 | -``` | ||
| 33 | -示例：`i2i:content_hybrid:12345` | ||
| 34 | - | ||
| 35 | -**TF-IDF方法**： | ||
| 36 | -``` | ||
| 37 | -i2i:content_tfidf:{item_id} | ||
| 38 | -``` | ||
| 39 | -示例：`i2i:content_tfidf:12345` | ||
| 40 | - | ||
| 41 | -**分类方法**： | ||
| 42 | -``` | ||
| 43 | -i2i:content_category:{item_id} | ||
| 44 | -``` | ||
| 45 | -示例：`i2i:content_category:12345` | ||
| 46 | - | ||
| 47 | ---- | ||
| 48 | - | ||
| 49 | -### 2. 兴趣点聚合索引 | ||
| 50 | - | ||
| 51 | -格式：`interest:{list_type}:{dimension}:{value}` | ||
| 52 | - | ||
| 53 | -#### 2.1 列表类型（list_type） | ||
| 54 | - | ||
| 55 | -- `hot` - 热门商品 | ||
| 56 | -- `cart` - 加购商品 | ||
| 57 | -- `new` - 新品 | ||
| 58 | -- `global` - 全局（所有数据） | ||
| 59 | - | ||
| 60 | -#### 2.2 单维度索引 | ||
| 61 | - | ||
| 62 | -##### 业务平台（platform） | ||
| 63 | -``` | ||
| 64 | -interest:hot:platform:pc | ||
| 65 | -interest:hot:platform:mobile | ||
| 66 | -interest:cart:platform:pc | ||
| 67 | -interest:new:platform:mobile | ||
| 68 | -interest:global:platform:pc | ||
| 69 | -``` | ||
| 70 | - | ||
| 71 | -##### 客户端平台（client_platform） | ||
| 72 | -``` | ||
| 73 | -interest:hot:client_platform:web | ||
| 74 | -interest:hot:client_platform:app | ||
| 75 | -interest:cart:client_platform:web | ||
| 76 | -interest:new:client_platform:app | ||
| 77 | -interest:global:client_platform:web | ||
| 78 | -``` | ||
| 79 | - | ||
| 80 | -##### 供应商（supplier） | ||
| 81 | -``` | ||
| 82 | -interest:hot:supplier:10001 | ||
| 83 | -interest:hot:supplier:10002 | ||
| 84 | -interest:cart:supplier:10001 | ||
| 85 | -interest:new:supplier:10002 | ||
| 86 | -interest:global:supplier:10001 | ||
| 87 | -``` | ||
| 88 | - | ||
| 89 | -##### 一级分类（category_level1） | ||
| 90 | -``` | ||
| 91 | -interest:hot:category_level1:100 | ||
| 92 | -interest:cart:category_level1:100 | ||
| 93 | -interest:new:category_level1:100 | ||
| 94 | -interest:global:category_level1:100 | ||
| 95 | -``` | ||
| 96 | - | ||
| 97 | -##### 二级分类（category_level2） | ||
| 98 | -``` | ||
| 99 | -interest:hot:category_level2:200 | ||
| 100 | -interest:cart:category_level2:200 | ||
| 101 | -interest:new:category_level2:200 | ||
| 102 | -interest:global:category_level2:200 | ||
| 103 | -``` | ||
| 104 | - | ||
| 105 | -##### 三级分类（category_level3） | ||
| 106 | -``` | ||
| 107 | -interest:hot:category_level3:300 | ||
| 108 | -interest:cart:category_level3:300 | ||
| 109 | -interest:new:category_level3:300 | ||
| 110 | -interest:global:category_level3:300 | ||
| 111 | -``` | ||
| 112 | - | ||
| 113 | -##### 四级分类（category_level4） | ||
| 114 | -``` | ||
| 115 | -interest:hot:category_level4:400 | ||
| 116 | -interest:cart:category_level4:400 | ||
| 117 | -interest:new:category_level4:400 | ||
| 118 | -interest:global:category_level4:400 | ||
| 119 | -``` | ||
| 120 | - | ||
| 121 | -#### 2.3 组合维度索引 | ||
| 122 | - | ||
| 123 | -##### 平台 + 客户端 | ||
| 124 | -``` | ||
| 125 | -interest:hot:platform_client:pc_web | ||
| 126 | -interest:hot:platform_client:pc_app | ||
| 127 | -interest:hot:platform_client:mobile_web | ||
| 128 | -interest:hot:platform_client:mobile_app | ||
| 129 | -``` | ||
| 130 | - | ||
| 131 | -##### 平台 + 二级分类 | ||
| 132 | -``` | ||
| 133 | -interest:hot:platform_category2:pc_200 | ||
| 134 | -interest:hot:platform_category2:mobile_200 | ||
| 135 | -interest:cart:platform_category2:pc_200 | ||
| 136 | -interest:new:platform_category2:mobile_200 | ||
| 137 | -``` | ||
| 138 | - | ||
| 139 | -##### 平台 + 三级分类 | ||
| 140 | -``` | ||
| 141 | -interest:hot:platform_category3:pc_300 | ||
| 142 | -interest:hot:platform_category3:mobile_300 | ||
| 143 | -interest:cart:platform_category3:pc_300 | ||
| 144 | -interest:new:platform_category3:mobile_300 | ||
| 145 | -``` | ||
| 146 | - | ||
| 147 | -##### 客户端平台 + 二级分类 | ||
| 148 | -``` | ||
| 149 | -interest:hot:client_category2:web_200 | ||
| 150 | -interest:hot:client_category2:app_200 | ||
| 151 | -interest:cart:client_category2:web_200 | ||
| 152 | -interest:new:client_category2:app_200 | ||
| 153 | -``` | ||
| 154 | - | ||
| 155 | ---- | ||
| 156 | - | ||
| 157 | -## 🎯 按业务场景的索引使用 | ||
| 158 | - | ||
| 159 | -### 场景1: 首页个性化推荐 | ||
| 160 | - | ||
| 161 | -**方案A: 基于平台** | ||
| 162 | -```python | ||
| 163 | -key = f"interest:hot:platform:{user_platform}" | ||
| 164 | -# 示例：interest:hot:platform:pc | ||
| 165 | -``` | ||
| 166 | - | ||
| 167 | -**方案B: 基于分类偏好** | ||
| 168 | -```python | ||
| 169 | -key = f"interest:hot:category_level2:{user_favorite_category}" | ||
| 170 | -# 示例：interest:hot:category_level2:200 | ||
| 171 | -``` | ||
| 172 | - | ||
| 173 | -**方案C: 基于平台+分类** | ||
| 174 | -```python | ||
| 175 | -key = f"interest:hot:platform_category2:{user_platform}_{category_id}" | ||
| 176 | -# 示例：interest:hot:platform_category2:pc_200 | ||
| 177 | -``` | ||
| 178 | - | ||
| 179 | -### 场景2: 详情页相关推荐 | ||
| 180 | - | ||
| 181 | -**方案A: 行为相似** | ||
| 182 | -```python | ||
| 183 | -key = f"i2i:swing:{current_item_id}" | ||
| 184 | -# 示例：i2i:swing:12345 | ||
| 185 | -``` | ||
| 186 | - | ||
| 187 | -**方案B: 内容相似** | ||
| 188 | -```python | ||
| 189 | -key = f"i2i:content_hybrid:{current_item_id}" | ||
| 190 | -# 示例：i2i:content_hybrid:12345 | ||
| 191 | -``` | ||
| 192 | - | ||
| 193 | -**方案C: 融合推荐** | ||
| 194 | -```python | ||
| 195 | -behavior_similar = redis.get(f"i2i:swing:{item_id}") | ||
| 196 | -content_similar = redis.get(f"i2i:content_hybrid:{item_id}") | ||
| 197 | -# 融合两种结果 | ||
| 198 | -``` | ||
| 199 | - | ||
| 200 | -### 场景3: 分类页推荐 | ||
| 201 | - | ||
| 202 | -**方案A: 该分类热门** | ||
| 203 | -```python | ||
| 204 | -key = f"interest:hot:category_level2:{category_id}" | ||
| 205 | -# 示例：interest:hot:category_level2:200 | ||
| 206 | -``` | ||
| 207 | - | ||
| 208 | -**方案B: 该分类新品** | ||
| 209 | -```python | ||
| 210 | -key = f"interest:new:category_level2:{category_id}" | ||
| 211 | -# 示例：interest:new:category_level2:200 | ||
| 212 | -``` | ||
| 213 | - | ||
| 214 | -**方案C: 该分类+平台** | ||
| 215 | -```python | ||
| 216 | -key = f"interest:hot:platform_category2:{platform}_{category_id}" | ||
| 217 | -# 示例：interest:hot:platform_category2:pc_200 | ||
| 218 | -``` | ||
| 219 | - | ||
| 220 | -### 场景4: 供应商店铺页 | ||
| 221 | - | ||
| 222 | -**方案A: 供应商热门商品** | ||
| 223 | -```python | ||
| 224 | -key = f"interest:hot:supplier:{supplier_id}" | ||
| 225 | -# 示例：interest:hot:supplier:10001 | ||
| 226 | -``` | ||
| 227 | - | ||
| 228 | -**方案B: 供应商新品** | ||
| 229 | -```python | ||
| 230 | -key = f"interest:new:supplier:{supplier_id}" | ||
| 231 | -# 示例：interest:new:supplier:10001 | ||
| 232 | -``` | ||
| 233 | - | ||
| 234 | -### 场景5: 搜索结果页推荐 | ||
| 235 | - | ||
| 236 | -**方案A: 全局热门** | ||
| 237 | -```python | ||
| 238 | -key = "interest:global:platform:pc" | ||
| 239 | -``` | ||
| 240 | - | ||
| 241 | -**方案B: 分类相关** | ||
| 242 | -```python | ||
| 243 | -key = f"interest:global:category_level2:{search_category}" | ||
| 244 | -# 示例：interest:global:category_level2:200 | ||
| 245 | -``` | ||
| 246 | - | ||
| 247 | ---- | ||
| 248 | - | ||
| 249 | -## 📊 索引数量统计 | ||
| 250 | - | ||
| 251 | -### i2i索引 | ||
| 252 | -- 行为相似：3种算法 × 商品数量 | ||
| 253 | -- 内容相似：3种方法 × 商品数量 | ||
| 254 | -- **总计**：6 × 商品数量 | ||
| 255 | - | ||
| 256 | -### 兴趣点聚合索引 | ||
| 257 | - | ||
| 258 | -**单维度**： | ||
| 259 | -- platform: 2-10个 | ||
| 260 | -- client_platform: 2-5个 | ||
| 261 | -- supplier: 100-1000个 | ||
| 262 | -- category_level1: 10-50个 | ||
| 263 | -- category_level2: 50-200个 | ||
| 264 | -- category_level3: 200-1000个 | ||
| 265 | -- category_level4: 1000-5000个 | ||
| 266 | - | ||
| 267 | -**组合维度**： | ||
| 268 | -- platform_client: 4-50个 | ||
| 269 | -- platform_category2: 100-2000个 | ||
| 270 | -- platform_category3: 400-10000个 | ||
| 271 | -- client_category2: 100-1000个 | ||
| 272 | - | ||
| 273 | -**列表类型**：每个维度 × 4种类型（hot/cart/new/global） | ||
| 274 | - | ||
| 275 | -**预估总数**：10000-50000条索引 | ||
| 276 | - | ||
| 277 | ---- | ||
| 278 | - | ||
| 279 | -## 🔍 查询示例代码 | ||
| 280 | - | ||
| 281 | -### Python示例 | ||
| 282 | - | ||
| 283 | -```python | ||
| 284 | -import redis | ||
| 285 | - | ||
| 286 | -# 连接Redis | ||
| 287 | -r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) | ||
| 288 | - | ||
| 289 | -# 1. 查询商品的相似商品 | ||
| 290 | -item_id = "12345" | ||
| 291 | -similar_items = r.get(f"i2i:swing:{item_id}") | ||
| 292 | -if similar_items: | ||
| 293 | - items = similar_items.split(',') | ||
| 294 | - for item in items[:5]: # 取前5个 | ||
| 295 | - item_id, score = item.split(':') | ||
| 296 | - print(f"商品ID: {item_id}, 相似度: {score}") | ||
| 297 | - | ||
| 298 | -# 2. 查询分类热门商品 | ||
| 299 | -category_id = "200" | ||
| 300 | -hot_items = r.get(f"interest:hot:category_level2:{category_id}") | ||
| 301 | -if hot_items: | ||
| 302 | - items = hot_items.split(',') | ||
| 303 | - for item in items[:10]: # 取前10个 | ||
| 304 | - item_id, score = item.split(':') | ||
| 305 | - print(f"商品ID: {item_id}, 得分: {score}") | ||
| 306 | - | ||
| 307 | -# 3. 查询平台+分类组合 | ||
| 308 | -platform = "pc" | ||
| 309 | -category_id = "200" | ||
| 310 | -key = f"interest:hot:platform_category2:{platform}_{category_id}" | ||
| 311 | -items = r.get(key) | ||
| 312 | -``` | ||
| 313 | - | ||
| 314 | -### Redis命令行示例 | ||
| 315 | - | ||
| 316 | -```bash | ||
| 317 | -# 查询商品相似度 | ||
| 318 | -redis-cli GET "i2i:swing:12345" | ||
| 319 | - | ||
| 320 | -# 查询分类热门 | ||
| 321 | -redis-cli GET "interest:hot:category_level2:200" | ||
| 322 | - | ||
| 323 | -# 查询供应商商品 | ||
| 324 | -redis-cli GET "interest:hot:supplier:10001" | ||
| 325 | - | ||
| 326 | -# 模糊查询所有热门索引 | ||
| 327 | -redis-cli KEYS "interest:hot:*" | ||
| 328 | - | ||
| 329 | -# 查看某个分类的所有类型 | ||
| 330 | -redis-cli KEYS "interest:*:category_level2:200" | ||
| 331 | -``` | ||
| 332 | - | ||
| 333 | ---- | ||
| 334 | - | ||
| 335 | -## 📝 注意事项 | ||
| 336 | - | ||
| 337 | -1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式 | ||
| 338 | -2. **值的格式**：`item_id1:score1,item_id2:score2,...` | ||
| 339 | -3. **过期时间**：建议设置7天过期 | ||
| 340 | -4. **更新频率**：建议每天更新一次 | ||
| 341 | -5. **查询优先级**： | ||
| 342 | - - 优先使用细粒度索引（如四级分类） | ||
| 343 | - - 粗粒度索引作为后备（如一级分类） | ||
| 344 | - - 融合多个索引结果 | ||
| 345 | - | ||
| 346 | ---- | ||
| 347 | - | ||
| 348 | -**版本**: v1.1 | ||
| 349 | -**生成日期**: 2025-10-16 | ||
| 350 | -**索引总数**: 约10000-50000条 |
offline_tasks/doc/DATABASE_SETUP.md deleted
| @@ -1,179 +0,0 @@ | @@ -1,179 +0,0 @@ | ||
| 1 | -# 数据库字段配置说明 | ||
| 2 | - | ||
| 3 | -## 问题说明 | ||
| 4 | - | ||
| 5 | -如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。 | ||
| 6 | - | ||
| 7 | -## 已适配的基础字段 | ||
| 8 | - | ||
| 9 | -当前代码已经适配了以下基础字段（参考 `item_sim.py`）： | ||
| 10 | - | ||
| 11 | -### sensors_events 表 | ||
| 12 | -- `anonymous_id` - 用户ID | ||
| 13 | -- `item_id` - 商品ID | ||
| 14 | -- `event` - 事件类型 | ||
| 15 | -- `create_time` - 创建时间 | ||
| 16 | -- `platform` - 平台（可选） | ||
| 17 | -- `country` - 国家（可选） | ||
| 18 | -- `customer_type` - 客户类型（可选） | ||
| 19 | - | ||
| 20 | -### prd_goods_sku 表 | ||
| 21 | -- `id` - 商品ID | ||
| 22 | -- `name` - 商品名称 | ||
| 23 | -- `create_time` - 创建时间（用于判断新品） | ||
| 24 | - | ||
| 25 | -## 可选字段配置 | ||
| 26 | - | ||
| 27 | -如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度： | ||
| 28 | - | ||
| 29 | -### 分类字段（可选） | ||
| 30 | -- `category_level1_id` - 一级分类ID | ||
| 31 | -- `category_level2_id` - 二级分类ID | ||
| 32 | -- `category_level3_id` - 三级分类ID | ||
| 33 | - | ||
| 34 | -## 如何添加分类字段支持 | ||
| 35 | - | ||
| 36 | -如果您的数据库有分类字段，可以按以下步骤启用： | ||
| 37 | - | ||
| 38 | -### 步骤1: 修改 SQL 查询 | ||
| 39 | - | ||
| 40 | -编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段： | ||
| 41 | - | ||
| 42 | -```python | ||
| 43 | -sql_query = f""" | ||
| 44 | -SELECT | ||
| 45 | - se.anonymous_id AS user_id, | ||
| 46 | - se.item_id, | ||
| 47 | - se.event AS event_type, | ||
| 48 | - se.create_time, | ||
| 49 | - pgs.name AS item_name, | ||
| 50 | - pgs.create_time AS item_create_time, | ||
| 51 | - pgs.category_level2_id, # 添加这一行 | ||
| 52 | - pgs.category_level3_id, # 添加这一行 | ||
| 53 | - se.platform, | ||
| 54 | - se.country, | ||
| 55 | - se.customer_type | ||
| 56 | -FROM | ||
| 57 | - sensors_events se | ||
| 58 | -LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id | ||
| 59 | -... | ||
| 60 | -""" | ||
| 61 | -``` | ||
| 62 | - | ||
| 63 | -### 步骤2: 修改聚合逻辑 | ||
| 64 | - | ||
| 65 | -在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用： | ||
| 66 | - | ||
| 67 | -```python | ||
| 68 | -# 维度4: 二级分类 (category_level2) - 如果字段存在 | ||
| 69 | -if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')): | ||
| 70 | - key = f"category_level2:{row['category_level2_id']}" | ||
| 71 | - aggregations[key][item_id] += weight | ||
| 72 | -``` | ||
| 73 | - | ||
| 74 | -这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。 | ||
| 75 | - | ||
| 76 | -## 查看实际表结构 | ||
| 77 | - | ||
| 78 | -运行以下命令查看您的数据库表结构： | ||
| 79 | - | ||
| 80 | -```python | ||
| 81 | -# 创建一个简单的脚本查看表结构 | ||
| 82 | -import pandas as pd | ||
| 83 | -from db_service import create_db_connection | ||
| 84 | -from offline_tasks.config.offline_config import DB_CONFIG | ||
| 85 | - | ||
| 86 | -engine = create_db_connection( | ||
| 87 | - DB_CONFIG['host'], | ||
| 88 | - DB_CONFIG['port'], | ||
| 89 | - DB_CONFIG['database'], | ||
| 90 | - DB_CONFIG['username'], | ||
| 91 | - DB_CONFIG['password'] | ||
| 92 | -) | ||
| 93 | - | ||
| 94 | -# 查看 prd_goods_sku 表结构 | ||
| 95 | -df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine) | ||
| 96 | -print("prd_goods_sku 字段列表:") | ||
| 97 | -for col in df.columns: | ||
| 98 | - print(f" - {col}") | ||
| 99 | - | ||
| 100 | -# 查看 sensors_events 表结构 | ||
| 101 | -df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine) | ||
| 102 | -print("\nsensors_events 字段列表:") | ||
| 103 | -for col in df.columns: | ||
| 104 | - print(f" - {col}") | ||
| 105 | -``` | ||
| 106 | - | ||
| 107 | -## 常见字段名映射 | ||
| 108 | - | ||
| 109 | -如果您的数据库使用不同的字段名，需要在SQL查询中做映射： | ||
| 110 | - | ||
| 111 | -| 代码中的字段 | 可能的实际字段名 | 修改方式 | | ||
| 112 | -|-------------|----------------|---------| | ||
| 113 | -| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` | | ||
| 114 | -| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` | | ||
| 115 | -| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` | | ||
| 116 | -| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` | | ||
| 117 | - | ||
| 118 | -## 完整示例 | ||
| 119 | - | ||
| 120 | -假设您的表结构是： | ||
| 121 | -- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time` | ||
| 122 | -- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time` | ||
| 123 | - | ||
| 124 | -则需要修改SQL为： | ||
| 125 | - | ||
| 126 | -```python | ||
| 127 | -sql_query = f""" | ||
| 128 | -SELECT | ||
| 129 | - se.uid AS user_id, | ||
| 130 | - se.goods_id AS item_id, | ||
| 131 | - se.action AS event_type, | ||
| 132 | - se.time AS create_time, | ||
| 133 | - pgs.title AS item_name, | ||
| 134 | - pgs.add_time AS item_create_time, | ||
| 135 | - pgs.cat2 AS category_level2_id, | ||
| 136 | - pgs.cat3 AS category_level3_id | ||
| 137 | -FROM | ||
| 138 | - sensors_events se | ||
| 139 | -LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id | ||
| 140 | -... | ||
| 141 | -""" | ||
| 142 | -``` | ||
| 143 | - | ||
| 144 | -## 最小化配置 | ||
| 145 | - | ||
| 146 | -如果只想先测试基本功能，可以只使用最基础的字段： | ||
| 147 | - | ||
| 148 | -### i2i 算法只需要： | ||
| 149 | -- `anonymous_id` / `user_id` | ||
| 150 | -- `item_id` | ||
| 151 | -- `event` / `event_type` | ||
| 152 | -- `create_time` | ||
| 153 | -- `name` (商品名称) | ||
| 154 | - | ||
| 155 | -### 兴趣点聚合至少需要： | ||
| 156 | -- 以上i2i的字段 | ||
| 157 | -- 至少一个维度字段（如 `platform` 或 `country`） | ||
| 158 | - | ||
| 159 | -## 测试连接 | ||
| 160 | - | ||
| 161 | -修改后，运行测试脚本验证： | ||
| 162 | - | ||
| 163 | -```bash | ||
| 164 | -cd /home/tw/recommendation/offline_tasks | ||
| 165 | -python3 test_connection.py | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -## 获取帮助 | ||
| 169 | - | ||
| 170 | -如果仍有问题，请： | ||
| 171 | -1. 查看日志文件：`logs/run_all_*.log` | ||
| 172 | -2. 运行单个脚本测试，便于调试 | ||
| 173 | -3. 使用 `--help` 参数查看命令行选项 | ||
| 174 | - | ||
| 175 | -```bash | ||
| 176 | -python3 scripts/i2i_swing.py --help | ||
| 177 | -python3 scripts/interest_aggregation.py --help | ||
| 178 | -``` | ||
| 179 | - |
offline_tasks/doc/DEBUG_GUIDE.md deleted
| @@ -1,332 +0,0 @@ | @@ -1,332 +0,0 @@ | ||
| 1 | -# Debug模式使用指南 | ||
| 2 | - | ||
| 3 | -## 🐛 Debug功能概述 | ||
| 4 | - | ||
| 5 | -Debug模式为所有离线任务提供： | ||
| 6 | -1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 | ||
| 7 | -2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 | ||
| 8 | -3. **数据采样展示** - 关键步骤的示例数据 | ||
| 9 | -4. **性能统计** - 每个步骤的耗时和资源使用 | ||
| 10 | - | ||
| 11 | -## 🚀 快速开始 | ||
| 12 | - | ||
| 13 | -### 1. 运行单个脚本（Debug模式） | ||
| 14 | - | ||
| 15 | -```bash | ||
| 16 | -cd /home/tw/recommendation/offline_tasks | ||
| 17 | - | ||
| 18 | -# Swing算法 - Debug模式 | ||
| 19 | -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug | ||
| 20 | - | ||
| 21 | -# 兴趣聚合 - Debug模式 | ||
| 22 | -python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug | ||
| 23 | - | ||
| 24 | -# 内容相似 - Debug模式 | ||
| 25 | -python3 scripts/i2i_content_similar.py --top_n 10 --debug | ||
| 26 | -``` | ||
| 27 | - | ||
| 28 | -### 2. 运行所有任务（Debug模式） | ||
| 29 | - | ||
| 30 | -```bash | ||
| 31 | -# 使用debug参数运行所有任务 | ||
| 32 | -python3 run_all.py --lookback_days 7 --top_n 10 --debug | ||
| 33 | -``` | ||
| 34 | - | ||
| 35 | -## 📊 Debug输出说明 | ||
| 36 | - | ||
| 37 | -### A. 日志输出 | ||
| 38 | - | ||
| 39 | -Debug模式下，日志会输出到两个地方： | ||
| 40 | -1. **控制台** - 实时查看进度 | ||
| 41 | -2. **Debug日志文件** - 完整保存 | ||
| 42 | - | ||
| 43 | -日志文件位置： | ||
| 44 | -``` | ||
| 45 | -offline_tasks/logs/debug/i2i_swing_20251016_193000.log | ||
| 46 | -offline_tasks/logs/debug/interest_aggregation_20251016_193500.log | ||
| 47 | -... | ||
| 48 | -``` | ||
| 49 | - | ||
| 50 | -### B. 日志内容示例 | ||
| 51 | - | ||
| 52 | -``` | ||
| 53 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 54 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: | ||
| 55 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 56 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 | ||
| 57 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 | ||
| 58 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - lookback_days: 7 | ||
| 59 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - debug: True | ||
| 60 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 61 | - | ||
| 62 | -2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 | ||
| 63 | - | ||
| 64 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ | ||
| 65 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息: | ||
| 66 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ | ||
| 67 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 | ||
| 68 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5 | ||
| 69 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name'] | ||
| 70 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - | ||
| 71 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型: | ||
| 72 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - user_id: object | ||
| 73 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_id: int64 | ||
| 74 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - event_type: object | ||
| 75 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - create_time: datetime64[ns] | ||
| 76 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_name: object | ||
| 77 | - | ||
| 78 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: | ||
| 79 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) | ||
| 80 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - contactFactory: 3456 (22.68%) | ||
| 81 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - purchase: 2134 (14.01%) | ||
| 82 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToPool: 1124 (7.38%) | ||
| 83 | - | ||
| 84 | -2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 | ||
| 85 | -2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%) | ||
| 86 | -2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%) | ||
| 87 | -... | ||
| 88 | -``` | ||
| 89 | - | ||
| 90 | -### C. 明文索引文件 | ||
| 91 | - | ||
| 92 | -Debug模式下，每个索引文件都会生成对应的明文文件： | ||
| 93 | - | ||
| 94 | -**原始索引文件** (`output/i2i_swing_20251016.txt`): | ||
| 95 | -``` | ||
| 96 | -12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 | ||
| 97 | -67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 | ||
| 98 | -``` | ||
| 99 | - | ||
| 100 | -**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`): | ||
| 101 | -``` | ||
| 102 | -================================================================================ | ||
| 103 | -明文索引文件 | ||
| 104 | -生成时间: 2025-10-16 19:35:00 | ||
| 105 | -描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) | ||
| 106 | -总索引数: 2345 | ||
| 107 | -================================================================================ | ||
| 108 | - | ||
| 109 | -[1] i2i:swing:12345(香蕉干) | ||
| 110 | --------------------------------------------------------------------------------- | ||
| 111 | - 1. ID:67890(芒果干) - Score:0.8567 | ||
| 112 | - 2. ID:11223(菠萝干) - Score:0.7234 | ||
| 113 | - 3. ID:44556(苹果干) - Score:0.6891 | ||
| 114 | - 4. ID:22334(木瓜干) - Score:0.6234 | ||
| 115 | - 5. ID:55667(草莓干) - Score:0.5891 | ||
| 116 | - | ||
| 117 | -[2] i2i:swing:67890(芒果干) | ||
| 118 | --------------------------------------------------------------------------------- | ||
| 119 | - 1. ID:12345(香蕉干) - Score:0.8567 | ||
| 120 | - 2. ID:22334(木瓜干) - Score:0.7123 | ||
| 121 | - 3. ID:55667(草莓干) - Score:0.6543 | ||
| 122 | - 4. ID:11223(菠萝干) - Score:0.6234 | ||
| 123 | - 5. ID:44556(苹果干) - Score:0.5891 | ||
| 124 | - | ||
| 125 | -... | ||
| 126 | - | ||
| 127 | -================================================================================ | ||
| 128 | -已输出 50/2345 个索引 | ||
| 129 | -================================================================================ | ||
| 130 | -``` | ||
| 131 | - | ||
| 132 | -## 📁 文件结构 | ||
| 133 | - | ||
| 134 | -Debug模式下的文件组织： | ||
| 135 | - | ||
| 136 | -``` | ||
| 137 | -offline_tasks/ | ||
| 138 | -├── output/ | ||
| 139 | -│ ├── i2i_swing_20251016.txt # 原始索引文件 | ||
| 140 | -│ ├── interest_aggregation_hot_20251016.txt | ||
| 141 | -│ └── debug/ # Debug明文文件目录 | ||
| 142 | -│ ├── i2i_swing_20251016_readable.txt # 明文索引 | ||
| 143 | -│ ├── interest_aggregation_hot_20251016_readable.txt | ||
| 144 | -│ └── ... | ||
| 145 | -└── logs/ | ||
| 146 | - ├── run_all_20251016.log # 主日志 | ||
| 147 | - └── debug/ # Debug详细日志目录 | ||
| 148 | - ├── i2i_swing_20251016_193000.log | ||
| 149 | - ├── interest_aggregation_20251016_193500.log | ||
| 150 | - └── ... | ||
| 151 | -``` | ||
| 152 | - | ||
| 153 | -## 🔍 使用场景 | ||
| 154 | - | ||
| 155 | -### 场景1：调试数据流程 | ||
| 156 | - | ||
| 157 | -```bash | ||
| 158 | -# 使用小数据量+debug模式快速验证 | ||
| 159 | -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug | ||
| 160 | - | ||
| 161 | -# 查看日志，检查： | ||
| 162 | -# - 数据加载是否正确 | ||
| 163 | -# - 行为类型分布是否合理 | ||
| 164 | -# - 用户/商品数量是否符合预期 | ||
| 165 | -``` | ||
| 166 | - | ||
| 167 | -### 场景2：检查推荐效果 | ||
| 168 | - | ||
| 169 | -```bash | ||
| 170 | -# 生成明文索引文件 | ||
| 171 | -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug | ||
| 172 | - | ||
| 173 | -# 打开明文文件查看： | ||
| 174 | -cat output/debug/i2i_swing_20251016_readable.txt | less | ||
| 175 | - | ||
| 176 | -# 检查推荐是否合理，例如： | ||
| 177 | -# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 | ||
| 178 | -# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 | ||
| 179 | -``` | ||
| 180 | - | ||
| 181 | -### 场景3：性能调优 | ||
| 182 | - | ||
| 183 | -```bash | ||
| 184 | -# Debug模式查看各步骤耗时 | ||
| 185 | -python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" | ||
| 186 | - | ||
| 187 | -# 输出示例： | ||
| 188 | -# 步骤1耗时: 2.34秒 | ||
| 189 | -# 步骤2耗时: 15.67秒 <- 瓶颈在这里 | ||
| 190 | -# 步骤3耗时: 1.23秒 | ||
| 191 | -# 总耗时: 19.24秒 | ||
| 192 | -``` | ||
| 193 | - | ||
| 194 | -### 场景4：参数调整 | ||
| 195 | - | ||
| 196 | -```bash | ||
| 197 | -# 测试不同alpha值的效果 | ||
| 198 | -python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1 | ||
| 199 | -python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1 | ||
| 200 | -python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1 | ||
| 201 | - | ||
| 202 | -# 对比明文文件，选择最佳参数 | ||
| 203 | -diff output/debug/i2i_swing_*_readable.txt | ||
| 204 | -``` | ||
| 205 | - | ||
| 206 | -## 💡 最佳实践 | ||
| 207 | - | ||
| 208 | -### 1. 开发调试阶段 | ||
| 209 | - | ||
| 210 | -```bash | ||
| 211 | -# 使用小数据量 + Debug模式 | ||
| 212 | -python3 run_all.py --lookback_days 3 --top_n 10 --debug | ||
| 213 | -``` | ||
| 214 | - | ||
| 215 | -- ✅ 快速验证流程 | ||
| 216 | -- ✅ 详细日志便于排错 | ||
| 217 | -- ✅ 明文文件检查效果 | ||
| 218 | - | ||
| 219 | -### 2. 参数调优阶段 | ||
| 220 | - | ||
| 221 | -```bash | ||
| 222 | -# 中等数据量 + Debug模式 | ||
| 223 | -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug | ||
| 224 | -``` | ||
| 225 | - | ||
| 226 | -- ✅ 查看数据分布 | ||
| 227 | -- ✅ 评估推荐质量 | ||
| 228 | -- ✅ 调整算法参数 | ||
| 229 | - | ||
| 230 | -### 3. 生产运行阶段 | ||
| 231 | - | ||
| 232 | -```bash | ||
| 233 | -# 大数据量 + 正常模式（不加--debug） | ||
| 234 | -python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 235 | -``` | ||
| 236 | - | ||
| 237 | -- ✅ 高效运行 | ||
| 238 | -- ✅ 只输出必要日志 | ||
| 239 | -- ✅ 节省磁盘空间 | ||
| 240 | - | ||
| 241 | -## 🛠️ Debug工具 | ||
| 242 | - | ||
| 243 | -### 查看实时日志 | ||
| 244 | - | ||
| 245 | -```bash | ||
| 246 | -# 实时查看debug日志 | ||
| 247 | -tail -f logs/debug/i2i_swing_*.log | ||
| 248 | - | ||
| 249 | -# 只看DEBUG级别 | ||
| 250 | -tail -f logs/debug/i2i_swing_*.log | grep "DEBUG" | ||
| 251 | - | ||
| 252 | -# 只看错误 | ||
| 253 | -tail -f logs/debug/i2i_swing_*.log | grep "ERROR" | ||
| 254 | -``` | ||
| 255 | - | ||
| 256 | -### 统计分析 | ||
| 257 | - | ||
| 258 | -```bash | ||
| 259 | -# 统计处理的数据量 | ||
| 260 | -grep "总行数" logs/debug/*.log | ||
| 261 | - | ||
| 262 | -# 统计生成的索引数 | ||
| 263 | -grep "总索引数" output/debug/*_readable.txt | ||
| 264 | - | ||
| 265 | -# 查看性能统计 | ||
| 266 | -grep "耗时" logs/debug/*.log | ||
| 267 | -``` | ||
| 268 | - | ||
| 269 | -### 快速检查 | ||
| 270 | - | ||
| 271 | -```bash | ||
| 272 | -# 检查前10个推荐 | ||
| 273 | -head -50 output/debug/i2i_swing_*_readable.txt | ||
| 274 | - | ||
| 275 | -# 搜索特定商品的推荐 | ||
| 276 | -grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10 | ||
| 277 | - | ||
| 278 | -# 统计推荐数量分布 | ||
| 279 | -grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -## ⚠️ 注意事项 | ||
| 283 | - | ||
| 284 | -1. **磁盘空间** | ||
| 285 | - - Debug日志和明文文件会占用较多空间 | ||
| 286 | - - 建议定期清理：`rm -rf logs/debug/* output/debug/*` | ||
| 287 | - | ||
| 288 | -2. **运行时间** | ||
| 289 | - - Debug模式会增加10-20%的运行时间 | ||
| 290 | - - 生产环境建议关闭debug | ||
| 291 | - | ||
| 292 | -3. **敏感信息** | ||
| 293 | - - 明文文件包含商品名称等信息 | ||
| 294 | - - 注意数据安全和隐私保护 | ||
| 295 | - | ||
| 296 | -4. **文件编码** | ||
| 297 | - - 明文文件使用UTF-8编码 | ||
| 298 | - - 确保查看工具支持中文显示 | ||
| 299 | - | ||
| 300 | -## 📖 相关命令 | ||
| 301 | - | ||
| 302 | -```bash | ||
| 303 | -# 查看帮助 | ||
| 304 | -python3 scripts/i2i_swing.py --help | ||
| 305 | -python3 run_all.py --help | ||
| 306 | - | ||
| 307 | -# 验证配置 | ||
| 308 | -python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)" | ||
| 309 | - | ||
| 310 | -# 测试debug工具 | ||
| 311 | -python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')" | ||
| 312 | -``` | ||
| 313 | - | ||
| 314 | -## ✅ 验证Debug功能 | ||
| 315 | - | ||
| 316 | -```bash | ||
| 317 | -# 快速测试 | ||
| 318 | -cd /home/tw/recommendation/offline_tasks | ||
| 319 | -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug | ||
| 320 | - | ||
| 321 | -# 应该看到： | ||
| 322 | -# ✓ DEBUG级别日志输出 | ||
| 323 | -# ✓ 创建debug日志文件 | ||
| 324 | -# ✓ 生成明文索引文件 | ||
| 325 | -# ✓ 显示数据统计信息 | ||
| 326 | -``` | ||
| 327 | - | ||
| 328 | ---- | ||
| 329 | - | ||
| 330 | -**Debug模式**: 开发和调试的利器 | ||
| 331 | -**正常模式**: 生产环境的选择 | ||
| 332 | -**灵活切换**: 一个参数的事情 |
offline_tasks/doc/OFFLINE_INDEX_SPEC.md deleted
| @@ -1,197 +0,0 @@ | @@ -1,197 +0,0 @@ | ||
| 1 | -# 离线索引产出规范 | ||
| 2 | - | ||
| 3 | -## 📋 索引任务列表 | ||
| 4 | - | ||
| 5 | -| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 | | ||
| 6 | -|---------|---------|---------|---------|-----------| | ||
| 7 | -| **i2i_swing** | `python3 scripts/i2i_swing.py` | 每天 | `output/i2i_swing_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` | | ||
| 8 | -| **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,...` | | ||
| 9 | -| **i2i_deepwalk** | `python3 scripts/i2i_deepwalk.py` | 每天 | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` | | ||
| 10 | -| **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,...` | | ||
| 11 | -| **interest_hot** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` | | ||
| 12 | -| **interest_cart** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` | | ||
| 13 | -| **interest_new** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` | | ||
| 14 | -| **interest_global** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` | | ||
| 15 | - | ||
| 16 | -## 📊 详细格式说明 | ||
| 17 | - | ||
| 18 | -### 1. i2i相似度索引 | ||
| 19 | - | ||
| 20 | -#### 输出格式 | ||
| 21 | -``` | ||
| 22 | -item_id \t item_name \t similar_id1:score1,similar_id2:score2,... | ||
| 23 | -``` | ||
| 24 | - | ||
| 25 | -#### 示例 | ||
| 26 | -``` | ||
| 27 | -12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 | ||
| 28 | -67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 | ||
| 29 | -``` | ||
| 30 | - | ||
| 31 | -#### 字段说明 | ||
| 32 | -- `item_id`: 商品SKU ID | ||
| 33 | -- `item_name`: 商品名称 | ||
| 34 | -- `similar_id`: 相似商品ID | ||
| 35 | -- `score`: 相似度分数（0-1之间，越大越相似） | ||
| 36 | - | ||
| 37 | -#### 算法差异 | ||
| 38 | -| 算法 | 特点 | 适用场景 | | ||
| 39 | -|------|------|---------| | ||
| 40 | -| **Swing** | 基于用户共同行为，发现购买关联 | 详情页"大家都在看" | | ||
| 41 | -| **Session W2V** | 基于会话序列，捕捉浏览顺序 | 详情页"看了又看" | | ||
| 42 | -| **DeepWalk** | 基于图结构，发现深层关系 | 详情页"相关推荐" | | ||
| 43 | -| **Content** | 基于商品属性，类目相似 | 冷启动商品推荐 | | ||
| 44 | - | ||
| 45 | -### 2. 兴趣点聚合索引 | ||
| 46 | - | ||
| 47 | -#### 输出格式 | ||
| 48 | -``` | ||
| 49 | -dimension_key \t item_id1,item_id2,item_id3,... | ||
| 50 | -``` | ||
| 51 | - | ||
| 52 | -#### 示例 | ||
| 53 | -``` | ||
| 54 | -platform:pc 12345,67890,11223,44556,22334 | ||
| 55 | -category_level2:200 67890,12345,22334,55667,11223 | ||
| 56 | -platform_category2:pc_200 12345,67890,22334,11223,55667 | ||
| 57 | -supplier:10001 12345,44556,22334,67890,11223 | ||
| 58 | -``` | ||
| 59 | - | ||
| 60 | -#### 维度说明 | ||
| 61 | - | ||
| 62 | -**单维度（7个）** | ||
| 63 | -- `platform:{platform_id}` - 业务平台（pc, h5, app等） | ||
| 64 | -- `client_platform:{client}` - 客户端平台（iOS, Android, Web等） | ||
| 65 | -- `supplier:{supplier_id}` - 供应商 | ||
| 66 | -- `category_level1:{cat_id}` - 一级分类 | ||
| 67 | -- `category_level2:{cat_id}` - 二级分类 | ||
| 68 | -- `category_level3:{cat_id}` - 三级分类 | ||
| 69 | -- `category_level4:{cat_id}` - 四级分类 | ||
| 70 | - | ||
| 71 | -**组合维度（4个）** | ||
| 72 | -- `platform_client:{platform}_{client}` - 平台+客户端 | ||
| 73 | -- `platform_category2:{platform}_{cat_id}` - 平台+二级分类 | ||
| 74 | -- `platform_category3:{platform}_{cat_id}` - 平台+三级分类 | ||
| 75 | -- `client_category2:{client}_{cat_id}` - 客户端+二级分类 | ||
| 76 | - | ||
| 77 | -#### 列表类型说明 | ||
| 78 | - | ||
| 79 | -| 类型 | 文件名 | 计算逻辑 | 适用场景 | | ||
| 80 | -|------|--------|---------|---------| | ||
| 81 | -| **hot** | `interest_aggregation_hot_YYYYMMDD.txt` | 最近N天的高频交互商品 | 首页"热门推荐" | | ||
| 82 | -| **cart** | `interest_aggregation_cart_YYYYMMDD.txt` | 高加购率商品 | 首页"热门加购" | | ||
| 83 | -| **new** | `interest_aggregation_new_YYYYMMDD.txt` | 最近上架的新品 | 首页"新品推荐" | | ||
| 84 | -| **global** | `interest_aggregation_global_YYYYMMDD.txt` | 全局热门商品 | 首页"猜你喜欢" | | ||
| 85 | - | ||
| 86 | -## 🔄 调度建议 | ||
| 87 | - | ||
| 88 | -### 每日调度（数据量大，变化快） | ||
| 89 | -```bash | ||
| 90 | -# 每天凌晨3点执行 | ||
| 91 | -0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 92 | -``` | ||
| 93 | - | ||
| 94 | -### 每周调度（数据量小，变化慢） | ||
| 95 | -```bash | ||
| 96 | -# 每周日凌晨4点执行 | ||
| 97 | -0 4 * * 0 cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_content_similar.py --top_n 50 | ||
| 98 | -``` | ||
| 99 | - | ||
| 100 | -## 📁 文件命名规范 | ||
| 101 | - | ||
| 102 | -### 标准格式 | ||
| 103 | -``` | ||
| 104 | -{algorithm_name}_{date}.txt | ||
| 105 | -``` | ||
| 106 | - | ||
| 107 | -### 示例 | ||
| 108 | -``` | ||
| 109 | -i2i_swing_20251016.txt | ||
| 110 | -i2i_session_w2v_20251016.txt | ||
| 111 | -interest_aggregation_hot_20251016.txt | ||
| 112 | -``` | ||
| 113 | - | ||
| 114 | -### Debug文件（开发调试用） | ||
| 115 | -``` | ||
| 116 | -output/debug/{algorithm_name}_{date}_readable.txt | ||
| 117 | -logs/debug/{algorithm_name}_{date}_{time}.log | ||
| 118 | -``` | ||
| 119 | - | ||
| 120 | -## 📈 数据量估算 | ||
| 121 | - | ||
| 122 | -| 索引类型 | 索引数量 | 单条大小 | 总大小 | 更新频率 | | ||
| 123 | -|---------|---------|---------|--------|---------| | ||
| 124 | -| i2i_swing | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 125 | -| i2i_session_w2v | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 126 | -| i2i_deepwalk | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 127 | -| i2i_content | ~50,000 | ~500B | ~25MB | 每周 | | ||
| 128 | -| interest_hot | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 129 | -| interest_cart | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 130 | -| interest_new | ~5,000 | ~1KB | ~5MB | 每天 | | ||
| 131 | -| interest_global | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 132 | -| **总计** | **~245,000** | - | **~135MB** | - | | ||
| 133 | - | ||
| 134 | -## 🎯 质量检查 | ||
| 135 | - | ||
| 136 | -### 数据完整性检查 | ||
| 137 | -```bash | ||
| 138 | -# 检查文件是否生成 | ||
| 139 | -ls -lh output/*_$(date +%Y%m%d).txt | ||
| 140 | - | ||
| 141 | -# 检查行数 | ||
| 142 | -wc -l output/*_$(date +%Y%m%d).txt | ||
| 143 | - | ||
| 144 | -# 检查格式 | ||
| 145 | -head -5 output/i2i_swing_$(date +%Y%m%d).txt | ||
| 146 | -``` | ||
| 147 | - | ||
| 148 | -### 数据质量指标 | ||
| 149 | - | ||
| 150 | -**i2i索引质量** | ||
| 151 | -- 覆盖率：有推荐的商品数 / 总商品数 > 80% | ||
| 152 | -- 推荐数量：每个商品推荐10-50个相似商品 | ||
| 153 | -- 分数范围：相似度分数在0.01-1.0之间 | ||
| 154 | - | ||
| 155 | -**兴趣聚合质量** | ||
| 156 | -- 覆盖率：有数据的维度数 / 总维度数 > 60% | ||
| 157 | -- 推荐数量：每个维度推荐50-1000个商品 | ||
| 158 | -- 商品去重：同一商品在列表中只出现一次 | ||
| 159 | - | ||
| 160 | -## 🔍 查询示例 | ||
| 161 | - | ||
| 162 | -### 查看特定商品的相似推荐 | ||
| 163 | -```bash | ||
| 164 | -# 查看商品12345的相似商品 | ||
| 165 | -grep "^12345\t" output/i2i_swing_20251016.txt | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -### 查看特定维度的热门商品 | ||
| 169 | -```bash | ||
| 170 | -# 查看PC平台的热门商品 | ||
| 171 | -grep "^platform:pc\t" output/interest_aggregation_hot_20251016.txt | ||
| 172 | -``` | ||
| 173 | - | ||
| 174 | -### 统计索引数量 | ||
| 175 | -```bash | ||
| 176 | -# 统计各类型索引数量 | ||
| 177 | -for file in output/*_20251016.txt; do | ||
| 178 | - echo "$file: $(wc -l < $file) 条" | ||
| 179 | -done | ||
| 180 | -``` | ||
| 181 | - | ||
| 182 | -## ⚠️ 注意事项 | ||
| 183 | - | ||
| 184 | -1. **文件编码**: 所有文件使用UTF-8编码 | ||
| 185 | -2. **分隔符**: 使用Tab（\t）分隔字段 | ||
| 186 | -3. **商品ID**: 使用数字类型，不带引号 | ||
| 187 | -4. **分数精度**: 相似度分数保留4位小数 | ||
| 188 | -5. **排序规则**: 相似商品按分数降序排列 | ||
| 189 | -6. **去重**: 确保推荐列表中没有重复商品 | ||
| 190 | -7. **有效性**: 推荐的商品必须是在售状态 | ||
| 191 | - | ||
| 192 | -## 🔗 相关文档 | ||
| 193 | - | ||
| 194 | -- **Redis数据规范**: `REDIS_DATA_SPEC.md` | ||
| 195 | -- **API接口文档**: `RECOMMENDATION_API.md` | ||
| 196 | -- **Debug指南**: `DEBUG_GUIDE.md` | ||
| 197 | -- **配置说明**: `UPDATE_CONFIG_GUIDE.md` |
offline_tasks/doc/README.md
| 1 | # 推荐系统离线任务文档中心 | 1 | # 推荐系统离线任务文档中心 |
| 2 | 2 | ||
| 3 | -本目录包含推荐系统所有重要文档。 | 3 | +本目录包含推荐系统离线任务的核心文档。 |
| 4 | 4 | ||
| 5 | -## 📚 文档目录 | 5 | +--- |
| 6 | 6 | ||
| 7 | -### 快速开始 | 7 | +## 📚 核心文档 |
| 8 | 8 | ||
| 9 | -- **[从这里开始.md](./从这里开始.md)** - 新手入门指南，了解项目结构和基本概念 | ||
| 10 | -- **[快速开始.md](./快速开始.md)** - 快速运行离线任务的步骤 | ||
| 11 | -- **[Swing快速开始.md](../collaboration/Swing快速开始.md)** - C++ Swing算法快速使用指南 | 9 | +### 1. 详细设计文档 |
| 12 | 10 | ||
| 13 | -### 使用指南 | 11 | +**文件**: [详细设计文档.md](./详细设计文档.md) |
| 14 | 12 | ||
| 15 | -- **[Swing算法使用指南.md](./Swing算法使用指南.md)** - 详细的Swing算法使用文档 | ||
| 16 | -- **[运行脚本指南.md](./运行脚本指南.md)** - 所有离线任务脚本的使用说明 | ||
| 17 | -- **[调试指南.md](./调试指南.md)** - Debug模式和日志使用说明 | 13 | +**内容**: |
| 14 | +- 项目概述和系统架构 | ||
| 15 | +- 功能模块详解（i2i相似度、兴趣聚合） | ||
| 16 | +- 使用指南和参数配置 | ||
| 17 | +- 业务场景应用示例 | ||
| 18 | +- 故障排查和性能优化 | ||
| 18 | 19 | ||
| 19 | -### 数据规范 | 20 | +**适用对象**: 开发人员、产品经理、新人入门 |
| 20 | 21 | ||
| 21 | -- **[离线索引数据规范.md](./离线索引数据规范.md)** - 所有离线索引的格式和说明 | ||
| 22 | -- **[Redis数据规范.md](./Redis数据规范.md)** - Redis中数据的key格式和结构 | ||
| 23 | -- **[完整索引列表.md](./完整索引列表.md)** - 系统中所有索引的完整清单 | 22 | +--- |
| 24 | 23 | ||
| 25 | -### 配置说明 | 24 | +### 2. 离线索引数据规范 |
| 26 | 25 | ||
| 27 | -- **[数据库配置说明.md](./数据库配置说明.md)** - 数据库连接和表结构说明 | ||
| 28 | -- **配置文件**: `../config/offline_config.py` - 所有可配置参数 | 26 | +**文件**: [离线索引数据规范.md](./离线索引数据规范.md) |
| 29 | 27 | ||
| 30 | -### 实现总结 | 28 | +**内容**: |
| 29 | +- 索引任务列表和调度频次 | ||
| 30 | +- 输出文件格式详细说明 | ||
| 31 | +- i2i索引规范（C++ Swing、Python Swing、W2V、DeepWalk、Content） | ||
| 32 | +- 兴趣聚合索引规范（维度、列表类型） | ||
| 33 | +- 文件命名规范和数据质量检查 | ||
| 31 | 34 | ||
| 32 | -- **[Swing实现总结.md](./Swing实现总结.md)** - C++ Swing集成实现的完整说明 | ||
| 33 | -- **[系统改进总结-20241017.md](./系统改进总结-20241017.md)** - 2024-10-17系统改进汇总 | ||
| 34 | -- **[项目重构说明-20241017.md](./项目重构说明-20241017.md)** - 目录结构和执行脚本重构详解 🆕 | 35 | +**适用对象**: 开发人员、数据工程师、运维人员 |
| 35 | 36 | ||
| 36 | -### 维护文档 | 37 | +--- |
| 37 | 38 | ||
| 38 | -- **[故障排查指南.md](./故障排查指南.md)** - 常见问题和解决方案 | ||
| 39 | -- **[更新日志.md](./更新日志.md)** - 系统更新历史 | 39 | +### 3. Redis数据规范 |
| 40 | 40 | ||
| 41 | -## 📂 相关文档 | 41 | +**文件**: [Redis数据规范.md](./Redis数据规范.md) |
| 42 | 42 | ||
| 43 | -### 其他模块文档 | 43 | +**内容**: |
| 44 | +- Redis Key命名规范 | ||
| 45 | +- 数据灌入规范表 | ||
| 46 | +- i2i索引和兴趣聚合索引的存储格式 | ||
| 47 | +- 数据加载流程和示例代码 | ||
| 48 | +- 查询示例和监控指标 | ||
| 44 | 49 | ||
| 45 | -- **Collaboration模块**: `../collaboration/README.md` - C++ 协同过滤算法 | ||
| 46 | -- **GraphEmbedding模块**: | ||
| 47 | - - Session W2V: `../graphembedding/session_w2v/README.md` | ||
| 48 | - - DeepWalk: `../graphembedding/deepwalk/README.md` | ||
| 49 | -- **Hot模块**: `../hot/README.md` - 热门商品推荐 | 50 | +**适用对象**: 后端开发人员、运维人员 |
| 50 | 51 | ||
| 51 | -### 项目README | 52 | +--- |
| 52 | 53 | ||
| 53 | -- **项目根目录**: `../../README.md` - 项目总览 | ||
| 54 | -- **离线任务**: `../README.md` - 离线任务模块说明 | 54 | +## 🎯 快速导航 |
| 55 | 55 | ||
| 56 | -## 🎯 文档使用建议 | 56 | +### 我是新用户 |
| 57 | +1. 先阅读 **[详细设计文档.md](./详细设计文档.md)** 了解整体架构 | ||
| 58 | +2. 参考文档中的"快速开始"部分运行系统 | ||
| 59 | +3. 遇到问题查看"故障排查"章节 | ||
| 57 | 60 | ||
| 58 | -### 新用户 | 61 | +### 我是开发人员 |
| 62 | +1. 查看 **[详细设计文档.md](./详细设计文档.md)** 的"功能模块详解" | ||
| 63 | +2. 参考 **[离线索引数据规范.md](./离线索引数据规范.md)** 了解数据格式 | ||
| 64 | +3. 开发在线接口时参考 **[Redis数据规范.md](./Redis数据规范.md)** | ||
| 59 | 65 | ||
| 60 | -1. 先阅读 **[从这里开始.md](./从这里开始.md)** 了解整体架构 | ||
| 61 | -2. 然后看 **[快速开始.md](./快速开始.md)** 快速运行系统 | ||
| 62 | -3. 需要时查阅具体的使用指南和数据规范 | 66 | +### 我是运维人员 |
| 67 | +1. 查看 **[详细设计文档.md](./详细设计文档.md)** 的"定时任务设置" | ||
| 68 | +2. 参考 **[Redis数据规范.md](./Redis数据规范.md)** 进行数据加载 | ||
| 69 | +3. 遇到问题查看"故障排查"和日志文件 | ||
| 63 | 70 | ||
| 64 | -### 开发人员 | 71 | +--- |
| 65 | 72 | ||
| 66 | -1. 查看 **[运行脚本指南.md](./运行脚本指南.md)** 了解所有脚本 | ||
| 67 | -2. 参考 **[调试指南.md](./调试指南.md)** 进行调试 | ||
| 68 | -3. 遵循 **数据规范** 文档进行开发 | 73 | +## 📂 其他资源 |
| 69 | 74 | ||
| 70 | -### 运维人员 | 75 | +### 配置文件 |
| 76 | +- **离线任务配置**: `../config/offline_config.py` | ||
| 77 | +- **主执行脚本**: `../run.sh` | ||
| 71 | 78 | ||
| 72 | -1. 配置前先看 **[数据库配置说明.md](./数据库配置说明.md)** | ||
| 73 | -2. 遇到问题查看 **[故障排查指南.md](./故障排查指南.md)** | ||
| 74 | -3. 了解 **[Redis数据规范.md](./Redis数据规范.md)** 便于维护 | 79 | +### 相关模块文档 |
| 80 | +- **Collaboration模块** (C++ Swing): `../collaboration/README.md` | ||
| 81 | +- **GraphEmbedding模块**: `../graphembedding/*/README.md` | ||
| 82 | +- **Hot模块**: `../hot/README.md` | ||
| 75 | 83 | ||
| 76 | -## 📝 文档更新 | 84 | +### 项目README |
| 85 | +- **项目总览**: `../../README.md` | ||
| 86 | +- **离线任务模块**: `../README.md` | ||
| 77 | 87 | ||
| 78 | -所有文档由项目维护者更新。如有疑问或发现错误，请联系团队。 | 88 | +--- |
| 79 | 89 | ||
| 80 | -**最后更新**: 2024-10-17 | 90 | +## 🔄 文档更新记录 |
| 91 | + | ||
| 92 | +- **2024-10-17**: 整合文档，简化为3个核心文档 | ||
| 93 | +- **2024-10-16**: 初始版本，包含完整功能文档 | ||
| 94 | + | ||
| 95 | +--- | ||
| 81 | 96 | ||
| 97 | +## 📝 文档维护 | ||
| 98 | + | ||
| 99 | +所有文档由推荐系统团队维护。 | ||
| 100 | + | ||
| 101 | +如有疑问、发现错误或建议改进，请联系团队。 | ||
| 102 | + | ||
| 103 | +**最后更新**: 2024-10-17 |
offline_tasks/doc/RUN_SCRIPT_GUIDE.md deleted
| @@ -1,304 +0,0 @@ | @@ -1,304 +0,0 @@ | ||
| 1 | -# run.sh 运行脚本使用指南 | ||
| 2 | - | ||
| 3 | -## 概述 | ||
| 4 | - | ||
| 5 | -`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。 | ||
| 6 | - | ||
| 7 | -## 主要特性 | ||
| 8 | - | ||
| 9 | -### 1. 内存监控 | ||
| 10 | -- **警告阈值**: 25GB - 打印警告日志 | ||
| 11 | -- **强制终止阈值**: 30GB - 自动kill进程 | ||
| 12 | -- **检查频率**: 每10秒检查一次 | ||
| 13 | -- **日志文件**: `logs/memory_monitor.log` | ||
| 14 | - | ||
| 15 | -### 2. 任务流程 | ||
| 16 | -1. 清理旧进程和输出 | ||
| 17 | -2. 运行调试模式（小数据量测试） | ||
| 18 | -3. 运行生产模式（大数据量） | ||
| 19 | -4. 加载索引到Redis | ||
| 20 | - | ||
| 21 | -### 3. 错误处理 | ||
| 22 | -- 任何步骤失败会立即退出 | ||
| 23 | -- 显示详细的退出码 | ||
| 24 | -- 保存完整日志 | ||
| 25 | - | ||
| 26 | -## 使用方法 | ||
| 27 | - | ||
| 28 | -### 基本运行 | ||
| 29 | -```bash | ||
| 30 | -cd /home/tw/recommendation/offline_tasks | ||
| 31 | -./run.sh | ||
| 32 | -``` | ||
| 33 | - | ||
| 34 | -### 查看实时输出 | ||
| 35 | -```bash | ||
| 36 | -./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log | ||
| 37 | -``` | ||
| 38 | - | ||
| 39 | -### 后台运行 | ||
| 40 | -```bash | ||
| 41 | -nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 & | ||
| 42 | -``` | ||
| 43 | - | ||
| 44 | -## 内存监控说明 | ||
| 45 | - | ||
| 46 | -### 监控逻辑 | ||
| 47 | - | ||
| 48 | -```bash | ||
| 49 | -check_memory() { | ||
| 50 | - local pid=$1 | ||
| 51 | - local threshold_warn=25 # 25GB警告 | ||
| 52 | - local threshold_kill=30 # 30GB强制kill | ||
| 53 | - | ||
| 54 | - while 进程运行中; do | ||
| 55 | - 获取内存使用 | ||
| 56 | - | ||
| 57 | - if 内存 >= 30GB: | ||
| 58 | - 打印错误日志 | ||
| 59 | - 强制终止进程 | ||
| 60 | - break | ||
| 61 | - elif 内存 >= 25GB: | ||
| 62 | - 打印警告日志 | ||
| 63 | - | ||
| 64 | - sleep 10秒 | ||
| 65 | - done | ||
| 66 | -} | ||
| 67 | -``` | ||
| 68 | - | ||
| 69 | -### 日志格式 | ||
| 70 | - | ||
| 71 | -**警告日志**: | ||
| 72 | -``` | ||
| 73 | -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 | ||
| 74 | -``` | ||
| 75 | - | ||
| 76 | -**强制终止日志**: | ||
| 77 | -``` | ||
| 78 | -[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 | ||
| 79 | -``` | ||
| 80 | - | ||
| 81 | -### 查看监控日志 | ||
| 82 | -```bash | ||
| 83 | -# 实时查看 | ||
| 84 | -tail -f logs/memory_monitor.log | ||
| 85 | - | ||
| 86 | -# 查看历史 | ||
| 87 | -cat logs/memory_monitor.log | ||
| 88 | -``` | ||
| 89 | - | ||
| 90 | -## 运行流程 | ||
| 91 | - | ||
| 92 | -### 步骤1: 调试模式 | ||
| 93 | -```bash | ||
| 94 | -python3 run_all.py --debug | ||
| 95 | -``` | ||
| 96 | -- 使用默认参数（见 `offline_config.py`） | ||
| 97 | -- 输出保存到 `output_debug/` | ||
| 98 | -- 启动内存监控 | ||
| 99 | - | ||
| 100 | -### 步骤2: 生产模式 | ||
| 101 | -```bash | ||
| 102 | -python3 run_all.py --debug | ||
| 103 | -``` | ||
| 104 | -- 生成完整索引 | ||
| 105 | -- 输出保存到 `output/` | ||
| 106 | -- 启动内存监控 | ||
| 107 | - | ||
| 108 | -### 步骤3: 加载Redis | ||
| 109 | -```bash | ||
| 110 | -python3 scripts/load_index_to_redis.py --redis-host localhost | ||
| 111 | -``` | ||
| 112 | -- 加载所有生成的索引 | ||
| 113 | -- 包括新增的内容相似索引 | ||
| 114 | - | ||
| 115 | -## 输出示例 | ||
| 116 | - | ||
| 117 | -``` | ||
| 118 | -====================================================================== | ||
| 119 | -开始运行离线任务 - 2025-10-17 14:00:00 | ||
| 120 | -内存监控: 警告阈值=25GB, 强制终止阈值=30GB | ||
| 121 | -====================================================================== | ||
| 122 | - | ||
| 123 | ->>> 步骤1: 调试模式运行（小数据量） | ||
| 124 | -调试任务 PID: 12345 | ||
| 125 | -✓ 调试模式完成 | ||
| 126 | - | ||
| 127 | ->>> 步骤2: 生产模式运行（大数据量） | ||
| 128 | -生产任务 PID: 12346 | ||
| 129 | -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 | ||
| 130 | -✓ 生产模式完成 | ||
| 131 | - | ||
| 132 | ->>> 步骤3: 加载到Redis | ||
| 133 | -✓ Redis加载完成 | ||
| 134 | - | ||
| 135 | -====================================================================== | ||
| 136 | -所有任务完成 - 2025-10-17 16:30:00 | ||
| 137 | -====================================================================== | ||
| 138 | -``` | ||
| 139 | - | ||
| 140 | -## 自定义配置 | ||
| 141 | - | ||
| 142 | -### 修改内存阈值 | ||
| 143 | - | ||
| 144 | -编辑 `run.sh` 中的以下行： | ||
| 145 | -```bash | ||
| 146 | -local threshold_warn=25 # 修改警告阈值 | ||
| 147 | -local threshold_kill=30 # 修改强制kill阈值 | ||
| 148 | -``` | ||
| 149 | - | ||
| 150 | -### 修改检查频率 | ||
| 151 | - | ||
| 152 | -编辑 `run.sh` 中的以下行： | ||
| 153 | -```bash | ||
| 154 | -sleep 10 # 修改为其他秒数 | ||
| 155 | -``` | ||
| 156 | - | ||
| 157 | -### 跳过调试模式 | ||
| 158 | - | ||
| 159 | -注释掉步骤1相关代码： | ||
| 160 | -```bash | ||
| 161 | -# # 3. 调试模式运行（小数据量） | ||
| 162 | -# echo "" | ||
| 163 | -# echo ">>> 步骤1: 调试模式运行（小数据量）" | ||
| 164 | -# python3 run_all.py --debug & | ||
| 165 | -# ... | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -### 修改Redis配置 | ||
| 169 | - | ||
| 170 | -修改步骤3的参数： | ||
| 171 | -```bash | ||
| 172 | -python3 scripts/load_index_to_redis.py \ | ||
| 173 | - --redis-host your-redis-host \ | ||
| 174 | - --redis-port 6379 \ | ||
| 175 | - --redis-db 0 | ||
| 176 | -``` | ||
| 177 | - | ||
| 178 | -## 故障排查 | ||
| 179 | - | ||
| 180 | -### 内存持续超限 | ||
| 181 | - | ||
| 182 | -**原因**: | ||
| 183 | -- 数据量太大 | ||
| 184 | -- 内存泄漏 | ||
| 185 | -- 并发任务过多 | ||
| 186 | - | ||
| 187 | -**解决方案**: | ||
| 188 | -1. 增加内存阈值（临时方案） | ||
| 189 | -2. 优化代码减少内存占用 | ||
| 190 | -3. 分批处理数据 | ||
| 191 | -4. 使用增量更新 | ||
| 192 | - | ||
| 193 | -### 进程被意外终止 | ||
| 194 | - | ||
| 195 | -**检查日志**: | ||
| 196 | -```bash | ||
| 197 | -# 查看监控日志 | ||
| 198 | -cat logs/memory_monitor.log | ||
| 199 | - | ||
| 200 | -# 查看任务日志 | ||
| 201 | -ls -lht logs/ | ||
| 202 | -cat logs/run_all_*.log | ||
| 203 | -``` | ||
| 204 | - | ||
| 205 | -### 任务失败 | ||
| 206 | - | ||
| 207 | -**查看退出码**: | ||
| 208 | -- 0: 成功 | ||
| 209 | -- 1: 一般错误 | ||
| 210 | -- 137: 被kill信号终止（可能是内存超限） | ||
| 211 | -- 其他: 查看具体错误信息 | ||
| 212 | - | ||
| 213 | -## 监控建议 | ||
| 214 | - | ||
| 215 | -### 1. 添加系统监控 | ||
| 216 | -```bash | ||
| 217 | -# 安装监控工具 | ||
| 218 | -apt install htop iotop | ||
| 219 | - | ||
| 220 | -# 实时监控 | ||
| 221 | -htop -p $(pgrep -f run_all.py) | ||
| 222 | -``` | ||
| 223 | - | ||
| 224 | -### 2. 设置告警 | ||
| 225 | -```bash | ||
| 226 | -# 配置邮件告警 | ||
| 227 | -if [ $PROD_EXIT_CODE -ne 0 ]; then | ||
| 228 | - echo "任务失败" | mail -s "离线任务告警" admin@example.com | ||
| 229 | -fi | ||
| 230 | -``` | ||
| 231 | - | ||
| 232 | -### 3. 定时任务 | ||
| 233 | -```bash | ||
| 234 | -# 添加到crontab | ||
| 235 | -0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 | ||
| 236 | -``` | ||
| 237 | - | ||
| 238 | -## 性能优化 | ||
| 239 | - | ||
| 240 | -### 内存优化建议 | ||
| 241 | - | ||
| 242 | -1. **分批处理** | ||
| 243 | - ```python | ||
| 244 | - # 在代码中使用batch处理 | ||
| 245 | - batch_size = 1000 | ||
| 246 | - for i in range(0, len(items), batch_size): | ||
| 247 | - batch = items[i:i+batch_size] | ||
| 248 | - process(batch) | ||
| 249 | - ``` | ||
| 250 | - | ||
| 251 | -2. **及时释放** | ||
| 252 | - ```python | ||
| 253 | - import gc | ||
| 254 | - del large_object | ||
| 255 | - gc.collect() | ||
| 256 | - ``` | ||
| 257 | - | ||
| 258 | -3. **使用生成器** | ||
| 259 | - ```python | ||
| 260 | - def process_items(): | ||
| 261 | - for item in items: | ||
| 262 | - yield process(item) | ||
| 263 | - ``` | ||
| 264 | - | ||
| 265 | -## 日志管理 | ||
| 266 | - | ||
| 267 | -### 日志文件 | ||
| 268 | -- `logs/memory_monitor.log` - 内存监控日志 | ||
| 269 | -- `logs/run_all_YYYYMMDD.log` - 任务运行日志 | ||
| 270 | -- `output/` - 生成的索引文件 | ||
| 271 | -- `output_debug/` - 调试模式输出 | ||
| 272 | - | ||
| 273 | -### 清理旧日志 | ||
| 274 | -```bash | ||
| 275 | -# 保留最近7天 | ||
| 276 | -find logs/ -name "*.log" -mtime +7 -delete | ||
| 277 | - | ||
| 278 | -# 压缩旧日志 | ||
| 279 | -find logs/ -name "*.log" -mtime +3 -exec gzip {} \; | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -## 安全注意事项 | ||
| 283 | - | ||
| 284 | -1. **权限**: 确保脚本有执行权限 `chmod +x run.sh` | ||
| 285 | -2. **路径**: 使用绝对路径避免混淆 | ||
| 286 | -3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀 | ||
| 287 | -4. **备份**: 脚本会删除output目录，请提前备份重要数据 | ||
| 288 | - | ||
| 289 | -## 总结 | ||
| 290 | - | ||
| 291 | -`run.sh` 提供了： | ||
| 292 | -- ✅ 自动化运行流程 | ||
| 293 | -- ✅ 内存监控保护 | ||
| 294 | -- ✅ 详细日志记录 | ||
| 295 | -- ✅ 错误处理机制 | ||
| 296 | -- ✅ 进度显示 | ||
| 297 | - | ||
| 298 | -建议在生产环境使用前先在测试环境验证。 | ||
| 299 | - | ||
| 300 | ---- | ||
| 301 | - | ||
| 302 | -**更新时间**: 2025-10-17 | ||
| 303 | -**版本**: v2.0 | ||
| 304 | - |
offline_tasks/doc/SWING_USAGE.md deleted
| @@ -1,322 +0,0 @@ | @@ -1,322 +0,0 @@ | ||
| 1 | -# Swing算法使用指南 | ||
| 2 | - | ||
| 3 | -本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。 | ||
| 4 | - | ||
| 5 | -## 目录结构 | ||
| 6 | - | ||
| 7 | -``` | ||
| 8 | -recommendation/ | ||
| 9 | -├── offline_tasks/ | ||
| 10 | -│ ├── scripts/ | ||
| 11 | -│ │ ├── generate_session.py # 生成用户session文件 | ||
| 12 | -│ │ └── add_names_to_swing.py # 给结果添加商品名称 | ||
| 13 | -│ └── output/ | ||
| 14 | -│ └── session.txt.YYYYMMDD # 生成的session文件 | ||
| 15 | -└── collaboration/ | ||
| 16 | - ├── run.sh # Swing算法执行脚本 | ||
| 17 | - ├── src/ | ||
| 18 | - │ ├── swing.cc # Swing算法实现 | ||
| 19 | - │ └── ucf.py # 用户协同过滤 | ||
| 20 | - └── output_YYYYMMDD/ | ||
| 21 | - ├── swing_similar.txt # Swing结果（ID格式） | ||
| 22 | - └── swing_similar_readable.txt # Swing结果（带商品名） | ||
| 23 | -``` | ||
| 24 | - | ||
| 25 | -## 使用流程 | ||
| 26 | - | ||
| 27 | -### 步骤1: 生成Session文件 | ||
| 28 | - | ||
| 29 | -首先需要从数据库提取用户行为数据，生成session文件。 | ||
| 30 | - | ||
| 31 | -```bash | ||
| 32 | -cd /home/tw/recommendation/offline_tasks | ||
| 33 | - | ||
| 34 | -# 基本用法（使用默认参数：730天数据） | ||
| 35 | -python3 scripts/generate_session.py | ||
| 36 | - | ||
| 37 | -# 指定回看天数 | ||
| 38 | -python3 scripts/generate_session.py --lookback_days 365 | ||
| 39 | - | ||
| 40 | -# 启用debug模式查看详细信息 | ||
| 41 | -python3 scripts/generate_session.py --lookback_days 730 --debug | ||
| 42 | - | ||
| 43 | -# 指定输出文件路径 | ||
| 44 | -python3 scripts/generate_session.py --output output/session.txt.20241017 | ||
| 45 | - | ||
| 46 | -# 选择输出格式 | ||
| 47 | -python3 scripts/generate_session.py --format both # 同时生成两种格式（默认） | ||
| 48 | -python3 scripts/generate_session.py --format standard # uid \t json 格式 | ||
| 49 | -python3 scripts/generate_session.py --format cpp # 纯json格式（.cpp后缀） | ||
| 50 | -``` | ||
| 51 | - | ||
| 52 | -**输出文件格式：** | ||
| 53 | - | ||
| 54 | -- `session.txt.YYYYMMDD` - 标准格式（包含uid）： | ||
| 55 | - ``` | ||
| 56 | - uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} | ||
| 57 | - uid2 \t {"item_id4":15.0,"item_id5":8.0} | ||
| 58 | - ``` | ||
| 59 | - | ||
| 60 | -- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）： | ||
| 61 | - ``` | ||
| 62 | - {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} | ||
| 63 | - {"item_id4":15.0,"item_id5":8.0} | ||
| 64 | - ``` | ||
| 65 | - | ||
| 66 | -**行为权重配置：** | ||
| 67 | -- `purchase`: 10.0（购买） | ||
| 68 | -- `contactFactory`: 5.0（联系厂家） | ||
| 69 | -- `addToCart`: 3.0（加入购物车） | ||
| 70 | -- `addToPool`: 2.0（加入询价池） | ||
| 71 | - | ||
| 72 | -### 步骤2: 运行Swing算法 | ||
| 73 | - | ||
| 74 | -session文件生成后，运行C++版本的Swing算法。 | ||
| 75 | - | ||
| 76 | -```bash | ||
| 77 | -cd /home/tw/recommendation/collaboration | ||
| 78 | - | ||
| 79 | -# 直接运行（使用默认配置） | ||
| 80 | -bash run.sh | ||
| 81 | - | ||
| 82 | -# 或者给脚本添加执行权限后运行 | ||
| 83 | -chmod +x run.sh | ||
| 84 | -./run.sh | ||
| 85 | -``` | ||
| 86 | - | ||
| 87 | -**配置说明（修改run.sh中的参数）：** | ||
| 88 | - | ||
| 89 | -```bash | ||
| 90 | -# 数据路径配置 | ||
| 91 | -SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 | ||
| 92 | - | ||
| 93 | -# Swing算法参数 | ||
| 94 | -ALPHA=0.7 # Swing算法的alpha参数（越小越关注用户共同行为） | ||
| 95 | -THRESHOLD1=1 # 交互强度阈值1（用于筛选用户行为） | ||
| 96 | -THRESHOLD2=3 # 交互强度阈值2（用于计算相似度） | ||
| 97 | -THREAD_NUM=4 # 线程数（根据CPU核心数调整） | ||
| 98 | -SHOW_PROGRESS=1 # 是否显示进度 (0/1) | ||
| 99 | - | ||
| 100 | -# Python环境 | ||
| 101 | -PYTHON_CMD="python3" # 如需使用特定Python环境，修改此处 | ||
| 102 | -``` | ||
| 103 | - | ||
| 104 | -**脚本执行流程：** | ||
| 105 | - | ||
| 106 | -1. 编译C++程序（swing, icf_simple, swing_symmetric） | ||
| 107 | -2. 查找当天日期的session文件 | ||
| 108 | -3. 运行Swing算法计算物品相似度 | ||
| 109 | -4. 合并多线程输出结果 | ||
| 110 | -5. 自动调用debug脚本生成可读版本 | ||
| 111 | - | ||
| 112 | -### 步骤3: 查看结果 | ||
| 113 | - | ||
| 114 | -运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录： | ||
| 115 | - | ||
| 116 | -**1. swing_similar.txt** - 原始结果（ID格式） | ||
| 117 | -``` | ||
| 118 | -12345 \t 67890:0.8523,23456:0.7234,34567:0.6891 | ||
| 119 | -``` | ||
| 120 | -格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...` | ||
| 121 | - | ||
| 122 | -**2. swing_similar_readable.txt** - 可读结果（带商品名） | ||
| 123 | -``` | ||
| 124 | -12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 | ||
| 125 | -``` | ||
| 126 | -格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...` | ||
| 127 | - | ||
| 128 | -### 步骤4: 单独生成Debug文件（可选） | ||
| 129 | - | ||
| 130 | -如果需要为其他文件生成可读版本： | ||
| 131 | - | ||
| 132 | -```bash | ||
| 133 | -cd /home/tw/recommendation/offline_tasks | ||
| 134 | - | ||
| 135 | -# 基本用法 | ||
| 136 | -python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt | ||
| 137 | - | ||
| 138 | -# 指定输出文件 | ||
| 139 | -python3 scripts/add_names_to_swing.py \ | ||
| 140 | - collaboration/output/swing_similar.txt \ | ||
| 141 | - collaboration/output/my_readable.txt | ||
| 142 | - | ||
| 143 | -# 启用debug模式 | ||
| 144 | -python3 scripts/add_names_to_swing.py \ | ||
| 145 | - collaboration/output/swing_similar.txt \ | ||
| 146 | - --debug | ||
| 147 | -``` | ||
| 148 | - | ||
| 149 | -## 参数调优建议 | ||
| 150 | - | ||
| 151 | -### Swing算法参数 | ||
| 152 | - | ||
| 153 | -1. **alpha (0.5-1.0)** | ||
| 154 | - - 越小：越关注用户共同行为的多样性 | ||
| 155 | - - 越大：越容忽略用户重叠度 | ||
| 156 | - - 建议：0.5-0.7（B2B场景） | ||
| 157 | - | ||
| 158 | -2. **threshold1 (1-5)** | ||
| 159 | - - 用于筛选用户的有效行为 | ||
| 160 | - - 建议：1-3（低频场景可用1） | ||
| 161 | - | ||
| 162 | -3. **threshold2 (1-10)** | ||
| 163 | - - 用于计算相似度的行为强度阈值 | ||
| 164 | - - 建议：3-5（需要较强的交互信号） | ||
| 165 | - | ||
| 166 | -4. **thread_num (1-20)** | ||
| 167 | - - 根据CPU核心数设置 | ||
| 168 | - - 建议：4-8（普通服务器） | ||
| 169 | - | ||
| 170 | -### 数据范围参数 | ||
| 171 | - | ||
| 172 | -1. **lookback_days** | ||
| 173 | - - B2B低频场景：建议730天（2年） | ||
| 174 | - - B2C高频场景：建议30-90天 | ||
| 175 | - - 数据量大时可适当减少 | ||
| 176 | - | ||
| 177 | -## 完整示例 | ||
| 178 | - | ||
| 179 | -```bash | ||
| 180 | -# 1. 生成session文件（730天数据） | ||
| 181 | -cd /home/tw/recommendation/offline_tasks | ||
| 182 | -python3 scripts/generate_session.py --lookback_days 730 --debug | ||
| 183 | - | ||
| 184 | -# 2. 检查生成的文件 | ||
| 185 | -ls -lh output/session.txt.* | ||
| 186 | -# 应该看到： | ||
| 187 | -# session.txt.20241017 | ||
| 188 | -# session.txt.20241017.cpp | ||
| 189 | - | ||
| 190 | -# 3. 运行Swing算法 | ||
| 191 | -cd /home/tw/recommendation/collaboration | ||
| 192 | -bash run.sh | ||
| 193 | - | ||
| 194 | -# 4. 查看结果 | ||
| 195 | -ls -lh output/swing_similar* | ||
| 196 | -cat output/swing_similar_readable.txt | head -20 | ||
| 197 | -``` | ||
| 198 | - | ||
| 199 | -## 故障排查 | ||
| 200 | - | ||
| 201 | -### 问题1: Session文件不存在 | ||
| 202 | - | ||
| 203 | -``` | ||
| 204 | -错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp | ||
| 205 | -``` | ||
| 206 | - | ||
| 207 | -**解决方法：** | ||
| 208 | -```bash | ||
| 209 | -cd /home/tw/recommendation/offline_tasks | ||
| 210 | -python3 scripts/generate_session.py | ||
| 211 | -``` | ||
| 212 | - | ||
| 213 | -### 问题2: 编译失败 | ||
| 214 | - | ||
| 215 | -``` | ||
| 216 | -编译失败，退出 | ||
| 217 | -``` | ||
| 218 | - | ||
| 219 | -**解决方法：** | ||
| 220 | -```bash | ||
| 221 | -cd /home/tw/recommendation/collaboration | ||
| 222 | -# 检查编译器 | ||
| 223 | -g++ --version | ||
| 224 | - | ||
| 225 | -# 手动编译 | ||
| 226 | -make clean | ||
| 227 | -make | ||
| 228 | - | ||
| 229 | -# 检查依赖 | ||
| 230 | -ls include/ | ||
| 231 | -ls utils/ | ||
| 232 | -``` | ||
| 233 | - | ||
| 234 | -### 问题3: 数据库连接失败 | ||
| 235 | - | ||
| 236 | -``` | ||
| 237 | -获取数据失败: Connection refused | ||
| 238 | -``` | ||
| 239 | - | ||
| 240 | -**解决方法：** | ||
| 241 | -- 检查数据库配置：`offline_tasks/config/offline_config.py` | ||
| 242 | -- 测试连接：`python3 offline_tasks/test_connection.py` | ||
| 243 | -- 确认网络和防火墙设置 | ||
| 244 | - | ||
| 245 | -### 问题4: 结果为空 | ||
| 246 | - | ||
| 247 | -**可能原因：** | ||
| 248 | -- threshold1/threshold2设置过高，过滤掉了所有数据 | ||
| 249 | -- 数据量太少，用户和商品交集不足 | ||
| 250 | - | ||
| 251 | -**解决方法：** | ||
| 252 | -- 降低threshold参数（如threshold1=0.5, threshold2=1） | ||
| 253 | -- 增加lookback_days | ||
| 254 | -- 检查数据量：`wc -l output/session.txt.*` | ||
| 255 | - | ||
| 256 | -## 性能优化 | ||
| 257 | - | ||
| 258 | -### 大数据量场景 | ||
| 259 | - | ||
| 260 | -如果数据量很大（>100万用户，>10万商品）： | ||
| 261 | - | ||
| 262 | -1. **增加线程数** | ||
| 263 | - ```bash | ||
| 264 | - THREAD_NUM=8 # 或更多 | ||
| 265 | - ``` | ||
| 266 | - | ||
| 267 | -2. **分批处理** | ||
| 268 | - - 可以将session文件按用户分片 | ||
| 269 | - - 分别运行Swing算法 | ||
| 270 | - - 最后合并结果 | ||
| 271 | - | ||
| 272 | -3. **调整max_session_list_len** | ||
| 273 | - - 修改 `src/swing.cc` 中的 `max_session_list_len` | ||
| 274 | - - 限制每个用户的最大行为数 | ||
| 275 | - | ||
| 276 | -### 内存优化 | ||
| 277 | - | ||
| 278 | -如果遇到内存不足： | ||
| 279 | - | ||
| 280 | -1. 减少 `max_sim_list_len`（默认300） | ||
| 281 | -2. 减少 `max_session_list_len`（默认100） | ||
| 282 | -3. 分批处理数据 | ||
| 283 | - | ||
| 284 | -## 集成到定时任务 | ||
| 285 | - | ||
| 286 | -```bash | ||
| 287 | -# 添加到crontab | ||
| 288 | -crontab -e | ||
| 289 | - | ||
| 290 | -# 每天凌晨2点运行 | ||
| 291 | -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 | ||
| 292 | -``` | ||
| 293 | - | ||
| 294 | -## 相关文档 | ||
| 295 | - | ||
| 296 | -- [Swing算法原理](./collaboration/README.md) | ||
| 297 | -- [离线任务配置](./offline_tasks/config/offline_config.py) | ||
| 298 | -- [Debug工具使用](./offline_tasks/scripts/debug_utils.py) | ||
| 299 | - | ||
| 300 | -## 常见问题 | ||
| 301 | - | ||
| 302 | -**Q: session文件格式选择哪个？** | ||
| 303 | -A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。 | ||
| 304 | - | ||
| 305 | -**Q: Swing算法运行多久？** | ||
| 306 | -A: 取决于数据量和线程数。通常： | ||
| 307 | -- 1万商品：1-5分钟 | ||
| 308 | -- 10万商品：10-30分钟 | ||
| 309 | -- 数据量大时建议使用多线程 | ||
| 310 | - | ||
| 311 | -**Q: 如何调整相似商品数量？** | ||
| 312 | -A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。 | ||
| 313 | - | ||
| 314 | -**Q: 能否使用Python版本的Swing？** | ||
| 315 | -A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。 | ||
| 316 | - | ||
| 317 | -## 联系支持 | ||
| 318 | - | ||
| 319 | -如有问题，请参考： | ||
| 320 | -- 项目README: `/home/tw/recommendation/README.md` | ||
| 321 | -- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md` | ||
| 322 | - |
offline_tasks/doc/Swing实现总结.md deleted
| @@ -1,375 +0,0 @@ | @@ -1,375 +0,0 @@ | ||
| 1 | -# Swing算法实现总结 | ||
| 2 | - | ||
| 3 | -## 完成的任务 | ||
| 4 | - | ||
| 5 | -本次实现完成了以下功能： | ||
| 6 | - | ||
| 7 | -### 1. Session生成脚本 ✓ | ||
| 8 | - | ||
| 9 | -**文件**: `offline_tasks/scripts/generate_session.py` | ||
| 10 | - | ||
| 11 | -**功能**: | ||
| 12 | -- 从数据库提取用户行为数据 | ||
| 13 | -- 聚合用户session（按商品维度累加权重） | ||
| 14 | -- 支持两种输出格式： | ||
| 15 | - - 标准格式：`uid \t {"item_id":score,...}` | ||
| 16 | - - C++格式：`{"item_id":score,...}` （每行一个用户） | ||
| 17 | - | ||
| 18 | -**主要参数**: | ||
| 19 | -- `--lookback_days`: 回看天数（默认730天） | ||
| 20 | -- `--format`: 输出格式（standard/cpp/both） | ||
| 21 | -- `--output`: 输出文件路径 | ||
| 22 | -- `--debug`: 启用debug模式 | ||
| 23 | - | ||
| 24 | -**使用示例**: | ||
| 25 | -```bash | ||
| 26 | -cd /home/tw/recommendation/offline_tasks | ||
| 27 | -python3 scripts/generate_session.py --lookback_days 730 --format both | ||
| 28 | -``` | ||
| 29 | - | ||
| 30 | -### 2. Swing运行脚本 ✓ | ||
| 31 | - | ||
| 32 | -**文件**: `collaboration/run.sh` | ||
| 33 | - | ||
| 34 | -**改进内容**: | ||
| 35 | -- ✓ 适配新的数据路径（`../offline_tasks/output/`） | ||
| 36 | -- ✓ 自动检测session文件格式（带uid或纯json） | ||
| 37 | -- ✓ 增加配置区域，便于修改参数 | ||
| 38 | -- ✓ 添加错误检查和友好的输出信息 | ||
| 39 | -- ✓ 自动调用debug脚本生成可读文件 | ||
| 40 | -- ✓ 支持自定义Python环境 | ||
| 41 | - | ||
| 42 | -**配置项**: | ||
| 43 | -```bash | ||
| 44 | -SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 | ||
| 45 | -ALPHA=0.7 # Swing alpha参数 | ||
| 46 | -THRESHOLD1=1 # 交互强度阈值1 | ||
| 47 | -THRESHOLD2=3 # 交互强度阈值2 | ||
| 48 | -THREAD_NUM=4 # 线程数 | ||
| 49 | -SHOW_PROGRESS=1 # 显示进度 | ||
| 50 | -PYTHON_CMD="python3" # Python命令 | ||
| 51 | -``` | ||
| 52 | - | ||
| 53 | -**执行流程**: | ||
| 54 | -1. 编译C++程序 | ||
| 55 | -2. 查找session文件 | ||
| 56 | -3. 运行Swing算法（多线程） | ||
| 57 | -4. 合并结果 | ||
| 58 | -5. 生成可读版本（自动调用debug脚本） | ||
| 59 | - | ||
| 60 | -### 3. Debug脚本 ✓ | ||
| 61 | - | ||
| 62 | -**文件**: `offline_tasks/scripts/add_names_to_swing.py` | ||
| 63 | - | ||
| 64 | -**功能**: | ||
| 65 | -- 读取Swing算法输出结果 | ||
| 66 | -- 从数据库获取商品名称映射 | ||
| 67 | -- 生成可读版本：`item_id:name \t similar_id1:name1:score1,...` | ||
| 68 | - | ||
| 69 | -**使用示例**: | ||
| 70 | -```bash | ||
| 71 | -cd /home/tw/recommendation/offline_tasks | ||
| 72 | -python3 scripts/add_names_to_swing.py \ | ||
| 73 | - ../collaboration/output/swing_similar.txt \ | ||
| 74 | - ../collaboration/output/swing_similar_readable.txt \ | ||
| 75 | - --debug | ||
| 76 | -``` | ||
| 77 | - | ||
| 78 | -### 4. 使用文档 ✓ | ||
| 79 | - | ||
| 80 | -**文件**: | ||
| 81 | -- `offline_tasks/SWING_USAGE.md` - 完整使用指南 | ||
| 82 | -- `collaboration/QUICKSTART.md` - 快速开始指南 | ||
| 83 | - | ||
| 84 | -**包含内容**: | ||
| 85 | -- 详细的使用步骤 | ||
| 86 | -- 参数说明和调优建议 | ||
| 87 | -- 故障排查指南 | ||
| 88 | -- 性能优化建议 | ||
| 89 | -- 完整示例 | ||
| 90 | - | ||
| 91 | -## 数据流程 | ||
| 92 | - | ||
| 93 | -``` | ||
| 94 | -┌─────────────────────────────────────────────────────────────┐ | ||
| 95 | -│ 步骤1: 生成Session文件 │ | ||
| 96 | -│ generate_session.py │ | ||
| 97 | -│ ↓ │ | ||
| 98 | -│ 数据库 → 用户行为数据 → 聚合权重 → session.txt.YYYYMMDD │ | ||
| 99 | -└─────────────────────────────────────────────────────────────┘ | ||
| 100 | - ↓ | ||
| 101 | -┌─────────────────────────────────────────────────────────────┐ | ||
| 102 | -│ 步骤2: 运行Swing算法 │ | ||
| 103 | -│ collaboration/run.sh │ | ||
| 104 | -│ ↓ │ | ||
| 105 | -│ session文件 → C++ Swing → sim_matrx.* → swing_similar.txt │ | ||
| 106 | -└─────────────────────────────────────────────────────────────┘ | ||
| 107 | - ↓ | ||
| 108 | -┌─────────────────────────────────────────────────────────────┐ | ||
| 109 | -│ 步骤3: 生成Debug文件 │ | ||
| 110 | -│ add_names_to_swing.py (自动调用) │ | ||
| 111 | -│ ↓ │ | ||
| 112 | -│ swing_similar.txt → 添加商品名 → swing_similar_readable.txt│ | ||
| 113 | -└─────────────────────────────────────────────────────────────┘ | ||
| 114 | -``` | ||
| 115 | - | ||
| 116 | -## 文件格式说明 | ||
| 117 | - | ||
| 118 | -### Session文件格式 | ||
| 119 | - | ||
| 120 | -**标准格式** (`session.txt.YYYYMMDD`): | ||
| 121 | -``` | ||
| 122 | -user_id1 {"123":10.0,"456":5.0,"789":3.0} | ||
| 123 | -user_id2 {"123":8.0,"999":12.0} | ||
| 124 | -``` | ||
| 125 | - | ||
| 126 | -**C++格式** (`session.txt.YYYYMMDD.cpp`): | ||
| 127 | -``` | ||
| 128 | -{"123":10.0,"456":5.0,"789":3.0} | ||
| 129 | -{"123":8.0,"999":12.0} | ||
| 130 | -``` | ||
| 131 | - | ||
| 132 | -### Swing结果格式 | ||
| 133 | - | ||
| 134 | -**原始格式** (`swing_similar.txt`): | ||
| 135 | -``` | ||
| 136 | -12345 67890:0.8523,23456:0.7234,34567:0.6891 | ||
| 137 | -``` | ||
| 138 | - | ||
| 139 | -**可读格式** (`swing_similar_readable.txt`): | ||
| 140 | -``` | ||
| 141 | -12345:iPhone 15 Pro 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 | ||
| 142 | -``` | ||
| 143 | - | ||
| 144 | -## 行为权重配置 | ||
| 145 | - | ||
| 146 | -当前配置（在`generate_session.py`中）: | ||
| 147 | - | ||
| 148 | -| 行为类型 | 权重 | 说明 | | ||
| 149 | -|---------|------|------| | ||
| 150 | -| purchase | 10.0 | 购买行为（最强信号） | | ||
| 151 | -| contactFactory | 5.0 | 联系厂家 | | ||
| 152 | -| addToCart | 3.0 | 加入购物车 | | ||
| 153 | -| addToPool | 2.0 | 加入询价池 | | ||
| 154 | - | ||
| 155 | -## 快速开始 | ||
| 156 | - | ||
| 157 | -```bash | ||
| 158 | -# 1. 生成session文件（730天数据） | ||
| 159 | -cd /home/tw/recommendation/offline_tasks | ||
| 160 | -python3 scripts/generate_session.py --lookback_days 730 | ||
| 161 | - | ||
| 162 | -# 2. 运行Swing算法 | ||
| 163 | -cd /home/tw/recommendation/collaboration | ||
| 164 | -bash run.sh | ||
| 165 | - | ||
| 166 | -# 3. 查看结果 | ||
| 167 | -cat output/swing_similar_readable.txt | head -20 | ||
| 168 | -``` | ||
| 169 | - | ||
| 170 | -## 项目结构 | ||
| 171 | - | ||
| 172 | -``` | ||
| 173 | -recommendation/ | ||
| 174 | -├── offline_tasks/ | ||
| 175 | -│ ├── scripts/ | ||
| 176 | -│ │ ├── generate_session.py # 新增：生成session | ||
| 177 | -│ │ ├── add_names_to_swing.py # 新增：添加商品名 | ||
| 178 | -│ │ ├── i2i_swing.py # 已有：Python版Swing | ||
| 179 | -│ │ └── debug_utils.py # 已有：Debug工具 | ||
| 180 | -│ ├── config/ | ||
| 181 | -│ │ └── offline_config.py # 配置文件 | ||
| 182 | -│ ├── output/ | ||
| 183 | -│ │ ├── session.txt.YYYYMMDD # 生成的session文件 | ||
| 184 | -│ │ └── session.txt.YYYYMMDD.cpp # C++格式session | ||
| 185 | -│ ├── SWING_USAGE.md # 新增：详细使用文档 | ||
| 186 | -│ └── ... | ||
| 187 | -├── collaboration/ | ||
| 188 | -│ ├── run.sh # 修改：适配新数据格式 | ||
| 189 | -│ ├── QUICKSTART.md # 新增：快速开始 | ||
| 190 | -│ ├── src/ | ||
| 191 | -│ │ ├── swing.cc # C++ Swing实现 | ||
| 192 | -│ │ ├── swing_symmetric.cc # 对称Swing | ||
| 193 | -│ │ ├── icf_simple.cc # 简单协同过滤 | ||
| 194 | -│ │ └── ucf.py # 用户协同 | ||
| 195 | -│ ├── bin/ # 编译后的可执行文件 | ||
| 196 | -│ ├── output_YYYYMMDD/ # 输出目录 | ||
| 197 | -│ │ ├── sim_matrx.* # 多线程输出 | ||
| 198 | -│ │ ├── swing_similar.txt # 合并结果 | ||
| 199 | -│ │ └── swing_similar_readable.txt # 可读结果 | ||
| 200 | -│ └── output -> output_YYYYMMDD # 软链接 | ||
| 201 | -└── SWING_IMPLEMENTATION_SUMMARY.md # 本文档 | ||
| 202 | -``` | ||
| 203 | - | ||
| 204 | -## 参数调优建议 | ||
| 205 | - | ||
| 206 | -### 针对B2B低频场景 | ||
| 207 | - | ||
| 208 | -```bash | ||
| 209 | -# Session生成 | ||
| 210 | ---lookback_days 730 # 2年数据（B2B交互频次低） | ||
| 211 | - | ||
| 212 | -# Swing算法 | ||
| 213 | -ALPHA=0.5-0.7 # 关注用户共同行为的多样性 | ||
| 214 | -THRESHOLD1=1 # 低阈值，保留更多数据 | ||
| 215 | -THRESHOLD2=3 # 中等阈值，过滤噪音 | ||
| 216 | -THREAD_NUM=4-8 # 根据服务器配置 | ||
| 217 | -``` | ||
| 218 | - | ||
| 219 | -### 针对大数据量场景 | ||
| 220 | - | ||
| 221 | -```bash | ||
| 222 | -# 增加线程数 | ||
| 223 | -THREAD_NUM=8 | ||
| 224 | - | ||
| 225 | -# 修改C++代码参数 | ||
| 226 | -max_sim_list_len=300 # 相似列表长度 | ||
| 227 | -max_session_list_len=100 # session截断长度 | ||
| 228 | -``` | ||
| 229 | - | ||
| 230 | -## 与现有系统集成 | ||
| 231 | - | ||
| 232 | -### 1. 定时任务 | ||
| 233 | - | ||
| 234 | -```bash | ||
| 235 | -# 每天凌晨2点运行 | ||
| 236 | -0 2 * * * cd /home/tw/recommendation/offline_tasks && \ | ||
| 237 | - python3 scripts/generate_session.py && \ | ||
| 238 | - cd ../collaboration && bash run.sh | ||
| 239 | -``` | ||
| 240 | - | ||
| 241 | -### 2. 结果导入Redis | ||
| 242 | - | ||
| 243 | -可使用现有的 `load_index_to_redis.py` 脚本导入结果。 | ||
| 244 | - | ||
| 245 | -### 3. 与Python版Swing对比 | ||
| 246 | - | ||
| 247 | -- **C++版本**（本次实现）：性能更好，适合大数据量 | ||
| 248 | -- **Python版本**（`i2i_swing.py`）：易于调试，支持时间衰减 | ||
| 249 | - | ||
| 250 | -可以运行两个版本对比效果： | ||
| 251 | -```bash | ||
| 252 | -# Python版本 | ||
| 253 | -python3 offline_tasks/scripts/i2i_swing.py --debug | ||
| 254 | - | ||
| 255 | -# C++版本 | ||
| 256 | -cd collaboration && bash run.sh | ||
| 257 | -``` | ||
| 258 | - | ||
| 259 | -## 测试验证 | ||
| 260 | - | ||
| 261 | -### 1. 小数据量测试 | ||
| 262 | - | ||
| 263 | -```bash | ||
| 264 | -# 生成小范围数据（30天） | ||
| 265 | -python3 scripts/generate_session.py --lookback_days 30 | ||
| 266 | - | ||
| 267 | -# 运行Swing | ||
| 268 | -cd ../collaboration | ||
| 269 | -bash run.sh | ||
| 270 | -``` | ||
| 271 | - | ||
| 272 | -### 2. 查看结果质量 | ||
| 273 | - | ||
| 274 | -```bash | ||
| 275 | -# 查看可读版本前100行 | ||
| 276 | -head -100 output/swing_similar_readable.txt | ||
| 277 | - | ||
| 278 | -# 检查相似度分布 | ||
| 279 | -cat output/swing_similar.txt | awk -F'\t' '{print NF-1}' | sort -n | uniq -c | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -### 3. 性能测试 | ||
| 283 | - | ||
| 284 | -```bash | ||
| 285 | -# 记录运行时间 | ||
| 286 | -time bash run.sh | ||
| 287 | -``` | ||
| 288 | - | ||
| 289 | -## 故障排查 | ||
| 290 | - | ||
| 291 | -### 常见问题 | ||
| 292 | - | ||
| 293 | -1. **Session文件不存在** | ||
| 294 | - - 先运行 `generate_session.py` | ||
| 295 | - | ||
| 296 | -2. **编译失败** | ||
| 297 | - - 检查g++版本：`g++ --version` | ||
| 298 | - - 手动编译：`cd collaboration && make` | ||
| 299 | - | ||
| 300 | -3. **数据库连接失败** | ||
| 301 | - - 检查配置：`offline_tasks/config/offline_config.py` | ||
| 302 | - - 测试连接：`python3 offline_tasks/test_connection.py` | ||
| 303 | - | ||
| 304 | -4. **结果为空** | ||
| 305 | - - 降低threshold参数 | ||
| 306 | - - 增加lookback_days | ||
| 307 | - - 检查数据量：`wc -l output/session.txt.*` | ||
| 308 | - | ||
| 309 | -详细故障排查参见：`offline_tasks/SWING_USAGE.md` | ||
| 310 | - | ||
| 311 | -## 后续优化方向 | ||
| 312 | - | ||
| 313 | -1. **性能优化** | ||
| 314 | - - 支持分布式计算 | ||
| 315 | - - 增量更新机制 | ||
| 316 | - - 结果缓存 | ||
| 317 | - | ||
| 318 | -2. **功能增强** | ||
| 319 | - - 支持多种相似度算法 | ||
| 320 | - - 在线实时更新 | ||
| 321 | - - A/B测试框架 | ||
| 322 | - | ||
| 323 | -3. **可观测性** | ||
| 324 | - - 添加监控指标 | ||
| 325 | - - 结果质量评估 | ||
| 326 | - - 自动报警 | ||
| 327 | - | ||
| 328 | -## 相关文档 | ||
| 329 | - | ||
| 330 | -- **详细使用指南**: `offline_tasks/SWING_USAGE.md` | ||
| 331 | -- **快速开始**: `collaboration/QUICKSTART.md` | ||
| 332 | -- **配置说明**: `offline_tasks/config/offline_config.py` | ||
| 333 | -- **Debug工具**: `offline_tasks/scripts/debug_utils.py` | ||
| 334 | -- **Swing算法原理**: `collaboration/README.md` | ||
| 335 | - | ||
| 336 | -## 维护说明 | ||
| 337 | - | ||
| 338 | -### 代码维护 | ||
| 339 | - | ||
| 340 | -- **Session生成**: `offline_tasks/scripts/generate_session.py` | ||
| 341 | -- **Swing执行**: `collaboration/run.sh` | ||
| 342 | -- **Debug脚本**: `offline_tasks/scripts/add_names_to_swing.py` | ||
| 343 | - | ||
| 344 | -### 配置维护 | ||
| 345 | - | ||
| 346 | -- **数据库配置**: `offline_tasks/config/offline_config.py` | ||
| 347 | -- **行为权重**: `generate_session.py` 中的 `behavior_weights` | ||
| 348 | -- **Swing参数**: `collaboration/run.sh` 中的配置区域 | ||
| 349 | - | ||
| 350 | -### 日志查看 | ||
| 351 | - | ||
| 352 | -```bash | ||
| 353 | -# Session生成日志 | ||
| 354 | -ls offline_tasks/logs/debug/generate_session_*.log | ||
| 355 | - | ||
| 356 | -# Swing运行日志 | ||
| 357 | -ls collaboration/logs/ | ||
| 358 | -``` | ||
| 359 | - | ||
| 360 | -## 总结 | ||
| 361 | - | ||
| 362 | -本次实现完成了一套完整的C++ Swing算法工作流： | ||
| 363 | - | ||
| 364 | -1. ✓ **前置任务**：Session文件生成（`generate_session.py`） | ||
| 365 | -2. ✓ **核心算法**：C++ Swing执行（改进的`run.sh`） | ||
| 366 | -3. ✓ **后处理**：Debug文件生成（`add_names_to_swing.py`） | ||
| 367 | -4. ✓ **文档完善**：详细使用指南和快速开始 | ||
| 368 | - | ||
| 369 | -所有脚本都支持debug模式，便于调试和监控。整体流程自动化程度高，只需一条命令即可完成全流程。 | ||
| 370 | - | ||
| 371 | ---- | ||
| 372 | - | ||
| 373 | -**实现时间**: 2024-10-17 | ||
| 374 | -**状态**: ✅ 已完成 | ||
| 375 | - |
offline_tasks/doc/Swing算法使用指南.md deleted
| @@ -1,322 +0,0 @@ | @@ -1,322 +0,0 @@ | ||
| 1 | -# Swing算法使用指南 | ||
| 2 | - | ||
| 3 | -本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。 | ||
| 4 | - | ||
| 5 | -## 目录结构 | ||
| 6 | - | ||
| 7 | -``` | ||
| 8 | -recommendation/ | ||
| 9 | -├── offline_tasks/ | ||
| 10 | -│ ├── scripts/ | ||
| 11 | -│ │ ├── generate_session.py # 生成用户session文件 | ||
| 12 | -│ │ └── add_names_to_swing.py # 给结果添加商品名称 | ||
| 13 | -│ └── output/ | ||
| 14 | -│ └── session.txt.YYYYMMDD # 生成的session文件 | ||
| 15 | -└── collaboration/ | ||
| 16 | - ├── run.sh # Swing算法执行脚本 | ||
| 17 | - ├── src/ | ||
| 18 | - │ ├── swing.cc # Swing算法实现 | ||
| 19 | - │ └── ucf.py # 用户协同过滤 | ||
| 20 | - └── output_YYYYMMDD/ | ||
| 21 | - ├── swing_similar.txt # Swing结果（ID格式） | ||
| 22 | - └── swing_similar_readable.txt # Swing结果（带商品名） | ||
| 23 | -``` | ||
| 24 | - | ||
| 25 | -## 使用流程 | ||
| 26 | - | ||
| 27 | -### 步骤1: 生成Session文件 | ||
| 28 | - | ||
| 29 | -首先需要从数据库提取用户行为数据，生成session文件。 | ||
| 30 | - | ||
| 31 | -```bash | ||
| 32 | -cd /home/tw/recommendation/offline_tasks | ||
| 33 | - | ||
| 34 | -# 基本用法（使用默认参数：730天数据） | ||
| 35 | -python3 scripts/generate_session.py | ||
| 36 | - | ||
| 37 | -# 指定回看天数 | ||
| 38 | -python3 scripts/generate_session.py --lookback_days 365 | ||
| 39 | - | ||
| 40 | -# 启用debug模式查看详细信息 | ||
| 41 | -python3 scripts/generate_session.py --lookback_days 730 --debug | ||
| 42 | - | ||
| 43 | -# 指定输出文件路径 | ||
| 44 | -python3 scripts/generate_session.py --output output/session.txt.20241017 | ||
| 45 | - | ||
| 46 | -# 选择输出格式 | ||
| 47 | -python3 scripts/generate_session.py --format both # 同时生成两种格式（默认） | ||
| 48 | -python3 scripts/generate_session.py --format standard # uid \t json 格式 | ||
| 49 | -python3 scripts/generate_session.py --format cpp # 纯json格式（.cpp后缀） | ||
| 50 | -``` | ||
| 51 | - | ||
| 52 | -**输出文件格式：** | ||
| 53 | - | ||
| 54 | -- `session.txt.YYYYMMDD` - 标准格式（包含uid）： | ||
| 55 | - ``` | ||
| 56 | - uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} | ||
| 57 | - uid2 \t {"item_id4":15.0,"item_id5":8.0} | ||
| 58 | - ``` | ||
| 59 | - | ||
| 60 | -- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）： | ||
| 61 | - ``` | ||
| 62 | - {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0} | ||
| 63 | - {"item_id4":15.0,"item_id5":8.0} | ||
| 64 | - ``` | ||
| 65 | - | ||
| 66 | -**行为权重配置：** | ||
| 67 | -- `purchase`: 10.0（购买） | ||
| 68 | -- `contactFactory`: 5.0（联系厂家） | ||
| 69 | -- `addToCart`: 3.0（加入购物车） | ||
| 70 | -- `addToPool`: 2.0（加入询价池） | ||
| 71 | - | ||
| 72 | -### 步骤2: 运行Swing算法 | ||
| 73 | - | ||
| 74 | -session文件生成后，运行C++版本的Swing算法。 | ||
| 75 | - | ||
| 76 | -```bash | ||
| 77 | -cd /home/tw/recommendation/collaboration | ||
| 78 | - | ||
| 79 | -# 直接运行（使用默认配置） | ||
| 80 | -bash run.sh | ||
| 81 | - | ||
| 82 | -# 或者给脚本添加执行权限后运行 | ||
| 83 | -chmod +x run.sh | ||
| 84 | -./run.sh | ||
| 85 | -``` | ||
| 86 | - | ||
| 87 | -**配置说明（修改run.sh中的参数）：** | ||
| 88 | - | ||
| 89 | -```bash | ||
| 90 | -# 数据路径配置 | ||
| 91 | -SESSION_DATA_DIR="../offline_tasks/output" # session文件目录 | ||
| 92 | - | ||
| 93 | -# Swing算法参数 | ||
| 94 | -ALPHA=0.7 # Swing算法的alpha参数（越小越关注用户共同行为） | ||
| 95 | -THRESHOLD1=1 # 交互强度阈值1（用于筛选用户行为） | ||
| 96 | -THRESHOLD2=3 # 交互强度阈值2（用于计算相似度） | ||
| 97 | -THREAD_NUM=4 # 线程数（根据CPU核心数调整） | ||
| 98 | -SHOW_PROGRESS=1 # 是否显示进度 (0/1) | ||
| 99 | - | ||
| 100 | -# Python环境 | ||
| 101 | -PYTHON_CMD="python3" # 如需使用特定Python环境，修改此处 | ||
| 102 | -``` | ||
| 103 | - | ||
| 104 | -**脚本执行流程：** | ||
| 105 | - | ||
| 106 | -1. 编译C++程序（swing, icf_simple, swing_symmetric） | ||
| 107 | -2. 查找当天日期的session文件 | ||
| 108 | -3. 运行Swing算法计算物品相似度 | ||
| 109 | -4. 合并多线程输出结果 | ||
| 110 | -5. 自动调用debug脚本生成可读版本 | ||
| 111 | - | ||
| 112 | -### 步骤3: 查看结果 | ||
| 113 | - | ||
| 114 | -运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录： | ||
| 115 | - | ||
| 116 | -**1. swing_similar.txt** - 原始结果（ID格式） | ||
| 117 | -``` | ||
| 118 | -12345 \t 67890:0.8523,23456:0.7234,34567:0.6891 | ||
| 119 | -``` | ||
| 120 | -格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...` | ||
| 121 | - | ||
| 122 | -**2. swing_similar_readable.txt** - 可读结果（带商品名） | ||
| 123 | -``` | ||
| 124 | -12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234 | ||
| 125 | -``` | ||
| 126 | -格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...` | ||
| 127 | - | ||
| 128 | -### 步骤4: 单独生成Debug文件（可选） | ||
| 129 | - | ||
| 130 | -如果需要为其他文件生成可读版本： | ||
| 131 | - | ||
| 132 | -```bash | ||
| 133 | -cd /home/tw/recommendation/offline_tasks | ||
| 134 | - | ||
| 135 | -# 基本用法 | ||
| 136 | -python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt | ||
| 137 | - | ||
| 138 | -# 指定输出文件 | ||
| 139 | -python3 scripts/add_names_to_swing.py \ | ||
| 140 | - collaboration/output/swing_similar.txt \ | ||
| 141 | - collaboration/output/my_readable.txt | ||
| 142 | - | ||
| 143 | -# 启用debug模式 | ||
| 144 | -python3 scripts/add_names_to_swing.py \ | ||
| 145 | - collaboration/output/swing_similar.txt \ | ||
| 146 | - --debug | ||
| 147 | -``` | ||
| 148 | - | ||
| 149 | -## 参数调优建议 | ||
| 150 | - | ||
| 151 | -### Swing算法参数 | ||
| 152 | - | ||
| 153 | -1. **alpha (0.5-1.0)** | ||
| 154 | - - 越小：越关注用户共同行为的多样性 | ||
| 155 | - - 越大：越容忽略用户重叠度 | ||
| 156 | - - 建议：0.5-0.7（B2B场景） | ||
| 157 | - | ||
| 158 | -2. **threshold1 (1-5)** | ||
| 159 | - - 用于筛选用户的有效行为 | ||
| 160 | - - 建议：1-3（低频场景可用1） | ||
| 161 | - | ||
| 162 | -3. **threshold2 (1-10)** | ||
| 163 | - - 用于计算相似度的行为强度阈值 | ||
| 164 | - - 建议：3-5（需要较强的交互信号） | ||
| 165 | - | ||
| 166 | -4. **thread_num (1-20)** | ||
| 167 | - - 根据CPU核心数设置 | ||
| 168 | - - 建议：4-8（普通服务器） | ||
| 169 | - | ||
| 170 | -### 数据范围参数 | ||
| 171 | - | ||
| 172 | -1. **lookback_days** | ||
| 173 | - - B2B低频场景：建议730天（2年） | ||
| 174 | - - B2C高频场景：建议30-90天 | ||
| 175 | - - 数据量大时可适当减少 | ||
| 176 | - | ||
| 177 | -## 完整示例 | ||
| 178 | - | ||
| 179 | -```bash | ||
| 180 | -# 1. 生成session文件（730天数据） | ||
| 181 | -cd /home/tw/recommendation/offline_tasks | ||
| 182 | -python3 scripts/generate_session.py --lookback_days 730 --debug | ||
| 183 | - | ||
| 184 | -# 2. 检查生成的文件 | ||
| 185 | -ls -lh output/session.txt.* | ||
| 186 | -# 应该看到： | ||
| 187 | -# session.txt.20241017 | ||
| 188 | -# session.txt.20241017.cpp | ||
| 189 | - | ||
| 190 | -# 3. 运行Swing算法 | ||
| 191 | -cd /home/tw/recommendation/collaboration | ||
| 192 | -bash run.sh | ||
| 193 | - | ||
| 194 | -# 4. 查看结果 | ||
| 195 | -ls -lh output/swing_similar* | ||
| 196 | -cat output/swing_similar_readable.txt | head -20 | ||
| 197 | -``` | ||
| 198 | - | ||
| 199 | -## 故障排查 | ||
| 200 | - | ||
| 201 | -### 问题1: Session文件不存在 | ||
| 202 | - | ||
| 203 | -``` | ||
| 204 | -错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp | ||
| 205 | -``` | ||
| 206 | - | ||
| 207 | -**解决方法：** | ||
| 208 | -```bash | ||
| 209 | -cd /home/tw/recommendation/offline_tasks | ||
| 210 | -python3 scripts/generate_session.py | ||
| 211 | -``` | ||
| 212 | - | ||
| 213 | -### 问题2: 编译失败 | ||
| 214 | - | ||
| 215 | -``` | ||
| 216 | -编译失败，退出 | ||
| 217 | -``` | ||
| 218 | - | ||
| 219 | -**解决方法：** | ||
| 220 | -```bash | ||
| 221 | -cd /home/tw/recommendation/collaboration | ||
| 222 | -# 检查编译器 | ||
| 223 | -g++ --version | ||
| 224 | - | ||
| 225 | -# 手动编译 | ||
| 226 | -make clean | ||
| 227 | -make | ||
| 228 | - | ||
| 229 | -# 检查依赖 | ||
| 230 | -ls include/ | ||
| 231 | -ls utils/ | ||
| 232 | -``` | ||
| 233 | - | ||
| 234 | -### 问题3: 数据库连接失败 | ||
| 235 | - | ||
| 236 | -``` | ||
| 237 | -获取数据失败: Connection refused | ||
| 238 | -``` | ||
| 239 | - | ||
| 240 | -**解决方法：** | ||
| 241 | -- 检查数据库配置：`offline_tasks/config/offline_config.py` | ||
| 242 | -- 测试连接：`python3 offline_tasks/test_connection.py` | ||
| 243 | -- 确认网络和防火墙设置 | ||
| 244 | - | ||
| 245 | -### 问题4: 结果为空 | ||
| 246 | - | ||
| 247 | -**可能原因：** | ||
| 248 | -- threshold1/threshold2设置过高，过滤掉了所有数据 | ||
| 249 | -- 数据量太少，用户和商品交集不足 | ||
| 250 | - | ||
| 251 | -**解决方法：** | ||
| 252 | -- 降低threshold参数（如threshold1=0.5, threshold2=1） | ||
| 253 | -- 增加lookback_days | ||
| 254 | -- 检查数据量：`wc -l output/session.txt.*` | ||
| 255 | - | ||
| 256 | -## 性能优化 | ||
| 257 | - | ||
| 258 | -### 大数据量场景 | ||
| 259 | - | ||
| 260 | -如果数据量很大（>100万用户，>10万商品）： | ||
| 261 | - | ||
| 262 | -1. **增加线程数** | ||
| 263 | - ```bash | ||
| 264 | - THREAD_NUM=8 # 或更多 | ||
| 265 | - ``` | ||
| 266 | - | ||
| 267 | -2. **分批处理** | ||
| 268 | - - 可以将session文件按用户分片 | ||
| 269 | - - 分别运行Swing算法 | ||
| 270 | - - 最后合并结果 | ||
| 271 | - | ||
| 272 | -3. **调整max_session_list_len** | ||
| 273 | - - 修改 `src/swing.cc` 中的 `max_session_list_len` | ||
| 274 | - - 限制每个用户的最大行为数 | ||
| 275 | - | ||
| 276 | -### 内存优化 | ||
| 277 | - | ||
| 278 | -如果遇到内存不足： | ||
| 279 | - | ||
| 280 | -1. 减少 `max_sim_list_len`（默认300） | ||
| 281 | -2. 减少 `max_session_list_len`（默认100） | ||
| 282 | -3. 分批处理数据 | ||
| 283 | - | ||
| 284 | -## 集成到定时任务 | ||
| 285 | - | ||
| 286 | -```bash | ||
| 287 | -# 添加到crontab | ||
| 288 | -crontab -e | ||
| 289 | - | ||
| 290 | -# 每天凌晨2点运行 | ||
| 291 | -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 | ||
| 292 | -``` | ||
| 293 | - | ||
| 294 | -## 相关文档 | ||
| 295 | - | ||
| 296 | -- [Swing算法原理](./collaboration/README.md) | ||
| 297 | -- [离线任务配置](./offline_tasks/config/offline_config.py) | ||
| 298 | -- [Debug工具使用](./offline_tasks/scripts/debug_utils.py) | ||
| 299 | - | ||
| 300 | -## 常见问题 | ||
| 301 | - | ||
| 302 | -**Q: session文件格式选择哪个？** | ||
| 303 | -A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。 | ||
| 304 | - | ||
| 305 | -**Q: Swing算法运行多久？** | ||
| 306 | -A: 取决于数据量和线程数。通常： | ||
| 307 | -- 1万商品：1-5分钟 | ||
| 308 | -- 10万商品：10-30分钟 | ||
| 309 | -- 数据量大时建议使用多线程 | ||
| 310 | - | ||
| 311 | -**Q: 如何调整相似商品数量？** | ||
| 312 | -A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。 | ||
| 313 | - | ||
| 314 | -**Q: 能否使用Python版本的Swing？** | ||
| 315 | -A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。 | ||
| 316 | - | ||
| 317 | -## 联系支持 | ||
| 318 | - | ||
| 319 | -如有问题，请参考： | ||
| 320 | -- 项目README: `/home/tw/recommendation/README.md` | ||
| 321 | -- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md` | ||
| 322 | - |
offline_tasks/doc/TROUBLESHOOTING.md deleted
| @@ -1,217 +0,0 @@ | @@ -1,217 +0,0 @@ | ||
| 1 | -# 故障排除指南 | ||
| 2 | - | ||
| 3 | -## 常见问题及解决方案 | ||
| 4 | - | ||
| 5 | -### 1. 数据库字段错误 | ||
| 6 | - | ||
| 7 | -#### 问题： | ||
| 8 | -``` | ||
| 9 | -pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'") | ||
| 10 | -``` | ||
| 11 | - | ||
| 12 | -#### 原因： | ||
| 13 | -数据库表结构与代码中使用的字段名不匹配。 | ||
| 14 | - | ||
| 15 | -#### 解决方案： | ||
| 16 | -1. 查看 `DATABASE_SETUP.md` 了解如何配置字段 | ||
| 17 | -2. 修改对应脚本中的SQL查询，使用实际存在的字段名 | ||
| 18 | -3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过 | ||
| 19 | - | ||
| 20 | -#### 已修复的字段： | ||
| 21 | -- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的 | ||
| 22 | -- ✅ 基础功能不依赖分类字段 | ||
| 23 | - | ||
| 24 | ---- | ||
| 25 | - | ||
| 26 | -### 2. 连接超时 | ||
| 27 | - | ||
| 28 | -#### 问题： | ||
| 29 | -``` | ||
| 30 | -pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...") | ||
| 31 | -``` | ||
| 32 | - | ||
| 33 | -#### 解决方案： | ||
| 34 | -1. 检查数据库配置：`config/offline_config.py` | ||
| 35 | -2. 确认网络连接和防火墙设置 | ||
| 36 | -3. 运行测试：`python3 test_connection.py` | ||
| 37 | - | ||
| 38 | ---- | ||
| 39 | - | ||
| 40 | -### 3. 内存不足 | ||
| 41 | - | ||
| 42 | -#### 问题： | ||
| 43 | -程序运行时内存占用过高或被杀死。 | ||
| 44 | - | ||
| 45 | -#### 解决方案： | ||
| 46 | -1. 减少回溯天数：`--lookback_days 365`（从730改为365） | ||
| 47 | -2. 减少输出数量：`--top_n 20`（从50改为20） | ||
| 48 | -3. 先运行单个算法： | ||
| 49 | - ```bash | ||
| 50 | - python3 scripts/i2i_session_w2v.py # 内存占用较小 | ||
| 51 | - ``` | ||
| 52 | -4. 跳过Swing算法（内存占用最大）： | ||
| 53 | - ```bash | ||
| 54 | - python3 run_all.py --skip-i2i | ||
| 55 | - ``` | ||
| 56 | - | ||
| 57 | ---- | ||
| 58 | - | ||
| 59 | -### 4. 运行时间过长 | ||
| 60 | - | ||
| 61 | -#### 解决方案： | ||
| 62 | -1. 减少数据量：`--lookback_days 180` | ||
| 63 | -2. 只运行特定算法： | ||
| 64 | - ```bash | ||
| 65 | - python3 run_all.py --only-w2v | ||
| 66 | - ``` | ||
| 67 | -3. 考虑使用C++版本的Swing（性能提升10倍） | ||
| 68 | - | ||
| 69 | ---- | ||
| 70 | - | ||
| 71 | -### 5. 依赖包安装失败 | ||
| 72 | - | ||
| 73 | -#### 解决方案： | ||
| 74 | -```bash | ||
| 75 | -# 单独安装失败的包 | ||
| 76 | -pip3 install pandas sqlalchemy pymysql gensim numpy | ||
| 77 | - | ||
| 78 | -# 或使用国内镜像 | ||
| 79 | -pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple | ||
| 80 | -``` | ||
| 81 | - | ||
| 82 | ---- | ||
| 83 | - | ||
| 84 | -### 6. Redis连接失败 | ||
| 85 | - | ||
| 86 | -#### 问题： | ||
| 87 | -``` | ||
| 88 | -redis.exceptions.ConnectionError: Error connecting to Redis | ||
| 89 | -``` | ||
| 90 | - | ||
| 91 | -#### 解决方案： | ||
| 92 | -1. Redis是可选的，只影响索引加载功能 | ||
| 93 | -2. 如果不需要Redis，可以跳过： | ||
| 94 | - ```bash | ||
| 95 | - python3 run_all.py # 只运行离线任务，不加载到Redis | ||
| 96 | - ``` | ||
| 97 | -3. 如果需要Redis，确认Redis已安装并运行： | ||
| 98 | - ```bash | ||
| 99 | - redis-cli ping # 应该返回 PONG | ||
| 100 | - ``` | ||
| 101 | - | ||
| 102 | ---- | ||
| 103 | - | ||
| 104 | -### 7. 输出文件为空 | ||
| 105 | - | ||
| 106 | -#### 可能原因： | ||
| 107 | -1. 数据量太少（没有满足最小阈值） | ||
| 108 | -2. 时间范围内没有数据 | ||
| 109 | -3. SQL查询条件过于严格 | ||
| 110 | - | ||
| 111 | -#### 解决方案： | ||
| 112 | -1. 检查日志：`tail -f logs/run_all_*.log` | ||
| 113 | -2. 调整参数： | ||
| 114 | - - 增加时间范围：`--lookback_days 1000` | ||
| 115 | - - 减少阈值：修改配置文件中的 `min_interaction_count` | ||
| 116 | -3. 检查数据库中是否有数据： | ||
| 117 | - ```python | ||
| 118 | - # 运行简单查询测试 | ||
| 119 | - python3 test_connection.py | ||
| 120 | - ``` | ||
| 121 | - | ||
| 122 | ---- | ||
| 123 | - | ||
| 124 | -### 8. 权限问题 | ||
| 125 | - | ||
| 126 | -#### 问题： | ||
| 127 | -``` | ||
| 128 | -PermissionError: [Errno 13] Permission denied | ||
| 129 | -``` | ||
| 130 | - | ||
| 131 | -#### 解决方案： | ||
| 132 | -```bash | ||
| 133 | -# 给脚本添加执行权限 | ||
| 134 | -chmod +x install.sh run_all.py | ||
| 135 | - | ||
| 136 | -# 确保有写入权限 | ||
| 137 | -chmod 755 output/ logs/ | ||
| 138 | -``` | ||
| 139 | - | ||
| 140 | ---- | ||
| 141 | - | ||
| 142 | -### 9. Python版本问题 | ||
| 143 | - | ||
| 144 | -#### 要求： | ||
| 145 | -Python 3.7+ | ||
| 146 | - | ||
| 147 | -#### 检查版本： | ||
| 148 | -```bash | ||
| 149 | -python3 --version | ||
| 150 | -``` | ||
| 151 | - | ||
| 152 | -#### 如果版本过低，需要升级Python | ||
| 153 | - | ||
| 154 | ---- | ||
| 155 | - | ||
| 156 | -### 10. 编码问题 | ||
| 157 | - | ||
| 158 | -#### 问题： | ||
| 159 | -``` | ||
| 160 | -UnicodeDecodeError: 'utf-8' codec can't decode byte... | ||
| 161 | -``` | ||
| 162 | - | ||
| 163 | -#### 解决方案： | ||
| 164 | -确保所有文件使用UTF-8编码，特别是配置文件和输出文件。 | ||
| 165 | - | ||
| 166 | ---- | ||
| 167 | - | ||
| 168 | -## 调试技巧 | ||
| 169 | - | ||
| 170 | -### 1. 查看详细日志 | ||
| 171 | -```bash | ||
| 172 | -tail -f logs/run_all_*.log | ||
| 173 | -``` | ||
| 174 | - | ||
| 175 | -### 2. 运行单个任务（便于调试） | ||
| 176 | -```bash | ||
| 177 | -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 | ||
| 178 | -``` | ||
| 179 | - | ||
| 180 | -### 3. 使用较小的数据量测试 | ||
| 181 | -```bash | ||
| 182 | -python3 run_all.py --lookback_days 30 --top_n 10 | ||
| 183 | -``` | ||
| 184 | - | ||
| 185 | -### 4. 检查中间结果 | ||
| 186 | -```bash | ||
| 187 | -ls -lh output/ | ||
| 188 | -head -n 20 output/i2i_swing_*.txt | ||
| 189 | -``` | ||
| 190 | - | ||
| 191 | ---- | ||
| 192 | - | ||
| 193 | -## 获取支持 | ||
| 194 | - | ||
| 195 | -如果以上方法都无法解决问题： | ||
| 196 | - | ||
| 197 | -1. **查看文档**： | ||
| 198 | - - `README.md` - 详细说明 | ||
| 199 | - - `DATABASE_SETUP.md` - 数据库配置 | ||
| 200 | - - `QUICKSTART.md` - 快速开始 | ||
| 201 | - | ||
| 202 | -2. **查看日志**： | ||
| 203 | - - `logs/` 目录下的所有日志文件 | ||
| 204 | - | ||
| 205 | -3. **简化测试**： | ||
| 206 | - - 先运行 `test_connection.py` | ||
| 207 | - - 再运行单个脚本 | ||
| 208 | - - 使用小数据量测试 | ||
| 209 | - | ||
| 210 | -4. **记录错误信息**： | ||
| 211 | - - 完整的错误堆栈 | ||
| 212 | - - 使用的命令 | ||
| 213 | - - 配置文件内容 | ||
| 214 | - | ||
| 215 | ---- | ||
| 216 | - | ||
| 217 | -**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。 |
offline_tasks/doc/从这里开始.md deleted
| @@ -1,302 +0,0 @@ | @@ -1,302 +0,0 @@ | ||
| 1 | -# 🚀 从这里开始 | ||
| 2 | - | ||
| 3 | -## 📦 项目交付完成 | ||
| 4 | - | ||
| 5 | -根据您提供的业务文档和表结构，推荐系统离线任务已完成构建！ | ||
| 6 | - | ||
| 7 | ---- | ||
| 8 | - | ||
| 9 | -## ✅ 完成的功能 | ||
| 10 | - | ||
| 11 | -### 1. i2i 索引（4种算法） | ||
| 12 | - | ||
| 13 | -#### 行为相似（3种） | ||
| 14 | -- ✅ **Swing算法** - 基于用户共同行为 | ||
| 15 | -- ✅ **Session W2V** - 基于用户会话序列 | ||
| 16 | -- ✅ **DeepWalk** - 基于图随机游走 | ||
| 17 | - | ||
| 18 | -#### 内容相似（1种，3个方法） | ||
| 19 | -- ✅ **Content-based** - 基于商品属性（分类、供应商等） | ||
| 20 | - - TF-IDF方法 | ||
| 21 | - - 分类方法 | ||
| 22 | - - 混合方法（推荐） | ||
| 23 | - | ||
| 24 | -### 2. 兴趣点聚合索引 | ||
| 25 | - | ||
| 26 | -**支持的维度**（7个单维度 + 4个组合维度）： | ||
| 27 | -- ✅ 业务平台（platform） | ||
| 28 | -- ✅ 客户端平台（client_platform） | ||
| 29 | -- ✅ 供应商（supplier） | ||
| 30 | -- ✅ 一级分类（category_level1） | ||
| 31 | -- ✅ 二级分类（category_level2） | ||
| 32 | -- ✅ 三级分类（category_level3） | ||
| 33 | -- ✅ 四级分类（category_level4） | ||
| 34 | -- ✅ 平台+客户端 | ||
| 35 | -- ✅ 平台+分类 | ||
| 36 | -- ✅ 客户端+分类 | ||
| 37 | - | ||
| 38 | -**支持的列表类型**（3种）： | ||
| 39 | -- ✅ 热门（hot）- 最近180天高交互 | ||
| 40 | -- ✅ 加购（cart）- 加购行为 | ||
| 41 | -- ✅ 新品（new）- 最近90天上架 | ||
| 42 | - | ||
| 43 | ---- | ||
| 44 | - | ||
| 45 | -## 🎯 快速开始（3步） | ||
| 46 | - | ||
| 47 | -### 步骤1: 安装依赖 | ||
| 48 | -```bash | ||
| 49 | -cd /home/tw/recommendation/offline_tasks | ||
| 50 | -bash install.sh | ||
| 51 | -``` | ||
| 52 | - | ||
| 53 | -### 步骤2: 测试连接 | ||
| 54 | -```bash | ||
| 55 | -python3 test_connection.py | ||
| 56 | -``` | ||
| 57 | - | ||
| 58 | -### 步骤3: 运行任务（小数据量测试） | ||
| 59 | -```bash | ||
| 60 | -# 先测试30天数据 | ||
| 61 | -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 | ||
| 62 | - | ||
| 63 | -# 查看输出 | ||
| 64 | -ls -lh output/ | ||
| 65 | -head -5 output/i2i_swing_*.txt | ||
| 66 | -``` | ||
| 67 | - | ||
| 68 | -### 步骤4: 运行完整任务 | ||
| 69 | -```bash | ||
| 70 | -# 运行所有任务（约6-10小时） | ||
| 71 | -python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 72 | - | ||
| 73 | -# 或分别运行（推荐） | ||
| 74 | -python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50 | ||
| 75 | -python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid | ||
| 76 | -python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 | ||
| 77 | -``` | ||
| 78 | - | ||
| 79 | ---- | ||
| 80 | - | ||
| 81 | -## 📚 文档导航 | ||
| 82 | - | ||
| 83 | -### 入门文档 | ||
| 84 | -1. **START_HERE.md** ← 当前文档 | ||
| 85 | -2. **QUICKSTART.md** - 5分钟快速上手 | ||
| 86 | -3. **CURRENT_STATUS.md** - 当前功能状态 | ||
| 87 | - | ||
| 88 | -### 技术文档 | ||
| 89 | -4. **FINAL_UPDATE.md** - 最终更新说明 | ||
| 90 | -5. **COMPLETE_INDEX_LIST.md** - 完整索引清单 | ||
| 91 | -6. **README.md** - 详细使用文档 | ||
| 92 | -7. **PROJECT_SUMMARY.md** - 技术架构 | ||
| 93 | - | ||
| 94 | -### 配置文档 | ||
| 95 | -8. **FIELD_MAPPING.md** - 字段映射说明 | ||
| 96 | -9. **DATABASE_SETUP.md** - 数据库配置 | ||
| 97 | -10. **TROUBLESHOOTING.md** - 故障排除 | ||
| 98 | - | ||
| 99 | -### 参考文档 | ||
| 100 | -11. **STRUCTURE.md** - 目录结构 | ||
| 101 | -12. **CHANGELOG.md** - 更新日志 | ||
| 102 | -13. **COMMANDS.txt** - 常用命令 | ||
| 103 | - | ||
| 104 | ---- | ||
| 105 | - | ||
| 106 | -## 📊 输出示例 | ||
| 107 | - | ||
| 108 | -### i2i相似度索引 | ||
| 109 | -``` | ||
| 110 | -# 文件: output/i2i_swing_20251016.txt | ||
| 111 | -12345 商品A 23456:0.8523,34567:0.7842,45678:0.7234,... | ||
| 112 | - | ||
| 113 | -# Redis Key: i2i:swing:12345 | ||
| 114 | -Value: 23456:0.8523,34567:0.7842,45678:0.7234,... | ||
| 115 | -``` | ||
| 116 | - | ||
| 117 | -### 兴趣点聚合索引 | ||
| 118 | -``` | ||
| 119 | -# 文件: output/interest_aggregation_hot_20251016.txt | ||
| 120 | -platform:pc 12345:98.52,23456:87.34,34567:76.89,... | ||
| 121 | -category_level2:200 45678:156.23,56789:142.87,... | ||
| 122 | - | ||
| 123 | -# Redis Key: interest:hot:platform:pc | ||
| 124 | -Value: 12345:98.52,23456:87.34,34567:76.89,... | ||
| 125 | -``` | ||
| 126 | - | ||
| 127 | ---- | ||
| 128 | - | ||
| 129 | -## 🎬 业务场景映射 | ||
| 130 | - | ||
| 131 | -根据您的3个业务场景： | ||
| 132 | - | ||
| 133 | -### 1. 首页猜你喜欢 | ||
| 134 | -```python | ||
| 135 | -# 使用兴趣点聚合索引 | ||
| 136 | -interest:hot:platform:pc | ||
| 137 | -interest:hot:category_level2:200 | ||
| 138 | -interest:hot:platform_category2:pc_200 | ||
| 139 | -``` | ||
| 140 | - | ||
| 141 | -### 2. 详情页的大家都在看 | ||
| 142 | -```python | ||
| 143 | -# 使用i2i相似索引 | ||
| 144 | -i2i:swing:12345 # 行为相似 | ||
| 145 | -i2i:content_hybrid:12345 # 内容相似 | ||
| 146 | -``` | ||
| 147 | - | ||
| 148 | -### 3. 搜索结果页底部的供应商推荐 | ||
| 149 | -```python | ||
| 150 | -# 使用兴趣点聚合索引 | ||
| 151 | -interest:global:category_level2:200 | ||
| 152 | -interest:hot:supplier:10001 | ||
| 153 | -``` | ||
| 154 | - | ||
| 155 | ---- | ||
| 156 | - | ||
| 157 | -## 🔢 关键数字 | ||
| 158 | - | ||
| 159 | -| 指标 | 数值 | | ||
| 160 | -|------|------| | ||
| 161 | -| i2i算法数量 | 4种（3行为+1内容） | | ||
| 162 | -| 兴趣点维度数量 | 11个（7单+4组合） | | ||
| 163 | -| 支持的分类层级 | 4级 | | ||
| 164 | -| 列表类型 | 3种（热门/加购/新品） | | ||
| 165 | -| 预计索引总数 | 10000-50000条 | | ||
| 166 | -| 全部任务运行时间 | 6-10小时 | | ||
| 167 | - | ||
| 168 | ---- | ||
| 169 | - | ||
| 170 | -## 💡 核心优势 | ||
| 171 | - | ||
| 172 | -### 1. 完整性 | ||
| 173 | -- ✅ 行为相似 + 内容相似 | ||
| 174 | -- ✅ 短期热门 + 长期稳定 | ||
| 175 | -- ✅ 粗粒度 + 细粒度 | ||
| 176 | - | ||
| 177 | -### 2. 灵活性 | ||
| 178 | -- ✅ 支持4级分类查询 | ||
| 179 | -- ✅ 支持供应商维度 | ||
| 180 | -- ✅ 支持多维度组合 | ||
| 181 | - | ||
| 182 | -### 3. 可扩展性 | ||
| 183 | -- ✅ 易于添加新维度 | ||
| 184 | -- ✅ 易于添加新算法 | ||
| 185 | -- ✅ 配置化管理 | ||
| 186 | - | ||
| 187 | -### 4. 实用性 | ||
| 188 | -- ✅ 适配真实数据 | ||
| 189 | -- ✅ 参考现有代码 | ||
| 190 | -- ✅ 文档完善 | ||
| 191 | - | ||
| 192 | ---- | ||
| 193 | - | ||
| 194 | -## ⚙️ 配置文件 | ||
| 195 | - | ||
| 196 | -主要配置在 `config/offline_config.py`： | ||
| 197 | - | ||
| 198 | -```python | ||
| 199 | -# 时间配置 | ||
| 200 | -LOOKBACK_DAYS = 730 # 2年数据 | ||
| 201 | - | ||
| 202 | -# 行为权重 | ||
| 203 | -behavior_weights = { | ||
| 204 | - 'click': 1.0, | ||
| 205 | - 'addToCart': 3.0, | ||
| 206 | - 'contactFactory': 5.0, | ||
| 207 | - 'purchase': 10.0 | ||
| 208 | -} | ||
| 209 | - | ||
| 210 | -# 时间衰减 | ||
| 211 | -time_decay_factor = 0.95 # 每30天衰减5% | ||
| 212 | -``` | ||
| 213 | - | ||
| 214 | ---- | ||
| 215 | - | ||
| 216 | -## 🔧 运行选项 | ||
| 217 | - | ||
| 218 | -### 运行单个算法 | ||
| 219 | -```bash | ||
| 220 | -python3 run_all.py --only-swing # 只运行Swing | ||
| 221 | -python3 run_all.py --only-content # 只运行内容相似 | ||
| 222 | -python3 run_all.py --only-interest # 只运行兴趣点聚合 | ||
| 223 | -``` | ||
| 224 | - | ||
| 225 | -### 跳过某些算法 | ||
| 226 | -```bash | ||
| 227 | -python3 run_all.py --skip-i2i # 跳过i2i | ||
| 228 | -python3 run_all.py --skip-interest # 跳过兴趣点聚合 | ||
| 229 | -``` | ||
| 230 | - | ||
| 231 | -### 调整参数 | ||
| 232 | -```bash | ||
| 233 | -# 小数据量测试 | ||
| 234 | -python3 run_all.py --lookback_days 30 --top_n 10 | ||
| 235 | - | ||
| 236 | -# 完整数据 | ||
| 237 | -python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 238 | -``` | ||
| 239 | - | ||
| 240 | ---- | ||
| 241 | - | ||
| 242 | -## 📞 遇到问题？ | ||
| 243 | - | ||
| 244 | -### 1. 字段错误 | ||
| 245 | -查看：**FIELD_MAPPING.md** 和 **DATABASE_SETUP.md** | ||
| 246 | - | ||
| 247 | -### 2. 运行错误 | ||
| 248 | -查看：**TROUBLESHOOTING.md** | ||
| 249 | - | ||
| 250 | -### 3. 使用疑问 | ||
| 251 | -查看：**README.md** 和 **COMPLETE_INDEX_LIST.md** | ||
| 252 | - | ||
| 253 | -### 4. 查看日志 | ||
| 254 | -```bash | ||
| 255 | -tail -f logs/run_all_*.log | ||
| 256 | -``` | ||
| 257 | - | ||
| 258 | ---- | ||
| 259 | - | ||
| 260 | -## 🎉 开始使用 | ||
| 261 | - | ||
| 262 | -```bash | ||
| 263 | -# 1. 进入目录 | ||
| 264 | -cd /home/tw/recommendation/offline_tasks | ||
| 265 | - | ||
| 266 | -# 2. 安装依赖 | ||
| 267 | -bash install.sh | ||
| 268 | - | ||
| 269 | -# 3. 测试连接 | ||
| 270 | -python3 test_connection.py | ||
| 271 | - | ||
| 272 | -# 4. 运行任务 | ||
| 273 | -python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 274 | - | ||
| 275 | -# 5. 查看输出 | ||
| 276 | -ls -lh output/ | ||
| 277 | -head -5 output/* | ||
| 278 | - | ||
| 279 | -# 6. 加载到Redis（可选） | ||
| 280 | -python3 scripts/load_index_to_redis.py | ||
| 281 | -``` | ||
| 282 | - | ||
| 283 | ---- | ||
| 284 | - | ||
| 285 | -## 📦 交付清单 | ||
| 286 | - | ||
| 287 | -- ✅ 4种i2i算法实现 | ||
| 288 | -- ✅ 兴趣点聚合（11个维度） | ||
| 289 | -- ✅ 统一调度脚本 | ||
| 290 | -- ✅ Redis加载工具 | ||
| 291 | -- ✅ 测试和示例脚本 | ||
| 292 | -- ✅ 13份完整文档 | ||
| 293 | -- ✅ 配置文件和依赖清单 | ||
| 294 | - | ||
| 295 | ---- | ||
| 296 | - | ||
| 297 | -**状态**: ✅ 已完成并可用 | ||
| 298 | -**版本**: v1.1 | ||
| 299 | -**日期**: 2025-10-16 | ||
| 300 | -**代码行数**: ~2500行 | ||
| 301 | - | ||
| 302 | -**开始探索**: 建议先阅读 **QUICKSTART.md** |
offline_tasks/doc/完整索引列表.md deleted
| @@ -1,350 +0,0 @@ | @@ -1,350 +0,0 @@ | ||
| 1 | -# 完整索引清单 | ||
| 2 | - | ||
| 3 | -## 📋 所有可用的推荐索引 | ||
| 4 | - | ||
| 5 | -### 1. i2i 相似度索引 | ||
| 6 | - | ||
| 7 | -#### 1.1 行为相似索引（3种） | ||
| 8 | - | ||
| 9 | -**Swing算法**： | ||
| 10 | -``` | ||
| 11 | -i2i:swing:{item_id} | ||
| 12 | -``` | ||
| 13 | -示例：`i2i:swing:12345` | ||
| 14 | - | ||
| 15 | -**Session Word2Vec**： | ||
| 16 | -``` | ||
| 17 | -i2i:session_w2v:{item_id} | ||
| 18 | -``` | ||
| 19 | -示例：`i2i:session_w2v:12345` | ||
| 20 | - | ||
| 21 | -**DeepWalk**： | ||
| 22 | -``` | ||
| 23 | -i2i:deepwalk:{item_id} | ||
| 24 | -``` | ||
| 25 | -示例：`i2i:deepwalk:12345` | ||
| 26 | - | ||
| 27 | -#### 1.2 内容相似索引（3种方法） | ||
| 28 | - | ||
| 29 | -**混合方法（推荐）**： | ||
| 30 | -``` | ||
| 31 | -i2i:content_hybrid:{item_id} | ||
| 32 | -``` | ||
| 33 | -示例：`i2i:content_hybrid:12345` | ||
| 34 | - | ||
| 35 | -**TF-IDF方法**： | ||
| 36 | -``` | ||
| 37 | -i2i:content_tfidf:{item_id} | ||
| 38 | -``` | ||
| 39 | -示例：`i2i:content_tfidf:12345` | ||
| 40 | - | ||
| 41 | -**分类方法**： | ||
| 42 | -``` | ||
| 43 | -i2i:content_category:{item_id} | ||
| 44 | -``` | ||
| 45 | -示例：`i2i:content_category:12345` | ||
| 46 | - | ||
| 47 | ---- | ||
| 48 | - | ||
| 49 | -### 2. 兴趣点聚合索引 | ||
| 50 | - | ||
| 51 | -格式：`interest:{list_type}:{dimension}:{value}` | ||
| 52 | - | ||
| 53 | -#### 2.1 列表类型（list_type） | ||
| 54 | - | ||
| 55 | -- `hot` - 热门商品 | ||
| 56 | -- `cart` - 加购商品 | ||
| 57 | -- `new` - 新品 | ||
| 58 | -- `global` - 全局（所有数据） | ||
| 59 | - | ||
| 60 | -#### 2.2 单维度索引 | ||
| 61 | - | ||
| 62 | -##### 业务平台（platform） | ||
| 63 | -``` | ||
| 64 | -interest:hot:platform:pc | ||
| 65 | -interest:hot:platform:mobile | ||
| 66 | -interest:cart:platform:pc | ||
| 67 | -interest:new:platform:mobile | ||
| 68 | -interest:global:platform:pc | ||
| 69 | -``` | ||
| 70 | - | ||
| 71 | -##### 客户端平台（client_platform） | ||
| 72 | -``` | ||
| 73 | -interest:hot:client_platform:web | ||
| 74 | -interest:hot:client_platform:app | ||
| 75 | -interest:cart:client_platform:web | ||
| 76 | -interest:new:client_platform:app | ||
| 77 | -interest:global:client_platform:web | ||
| 78 | -``` | ||
| 79 | - | ||
| 80 | -##### 供应商（supplier） | ||
| 81 | -``` | ||
| 82 | -interest:hot:supplier:10001 | ||
| 83 | -interest:hot:supplier:10002 | ||
| 84 | -interest:cart:supplier:10001 | ||
| 85 | -interest:new:supplier:10002 | ||
| 86 | -interest:global:supplier:10001 | ||
| 87 | -``` | ||
| 88 | - | ||
| 89 | -##### 一级分类（category_level1） | ||
| 90 | -``` | ||
| 91 | -interest:hot:category_level1:100 | ||
| 92 | -interest:cart:category_level1:100 | ||
| 93 | -interest:new:category_level1:100 | ||
| 94 | -interest:global:category_level1:100 | ||
| 95 | -``` | ||
| 96 | - | ||
| 97 | -##### 二级分类（category_level2） | ||
| 98 | -``` | ||
| 99 | -interest:hot:category_level2:200 | ||
| 100 | -interest:cart:category_level2:200 | ||
| 101 | -interest:new:category_level2:200 | ||
| 102 | -interest:global:category_level2:200 | ||
| 103 | -``` | ||
| 104 | - | ||
| 105 | -##### 三级分类（category_level3） | ||
| 106 | -``` | ||
| 107 | -interest:hot:category_level3:300 | ||
| 108 | -interest:cart:category_level3:300 | ||
| 109 | -interest:new:category_level3:300 | ||
| 110 | -interest:global:category_level3:300 | ||
| 111 | -``` | ||
| 112 | - | ||
| 113 | -##### 四级分类（category_level4） | ||
| 114 | -``` | ||
| 115 | -interest:hot:category_level4:400 | ||
| 116 | -interest:cart:category_level4:400 | ||
| 117 | -interest:new:category_level4:400 | ||
| 118 | -interest:global:category_level4:400 | ||
| 119 | -``` | ||
| 120 | - | ||
| 121 | -#### 2.3 组合维度索引 | ||
| 122 | - | ||
| 123 | -##### 平台 + 客户端 | ||
| 124 | -``` | ||
| 125 | -interest:hot:platform_client:pc_web | ||
| 126 | -interest:hot:platform_client:pc_app | ||
| 127 | -interest:hot:platform_client:mobile_web | ||
| 128 | -interest:hot:platform_client:mobile_app | ||
| 129 | -``` | ||
| 130 | - | ||
| 131 | -##### 平台 + 二级分类 | ||
| 132 | -``` | ||
| 133 | -interest:hot:platform_category2:pc_200 | ||
| 134 | -interest:hot:platform_category2:mobile_200 | ||
| 135 | -interest:cart:platform_category2:pc_200 | ||
| 136 | -interest:new:platform_category2:mobile_200 | ||
| 137 | -``` | ||
| 138 | - | ||
| 139 | -##### 平台 + 三级分类 | ||
| 140 | -``` | ||
| 141 | -interest:hot:platform_category3:pc_300 | ||
| 142 | -interest:hot:platform_category3:mobile_300 | ||
| 143 | -interest:cart:platform_category3:pc_300 | ||
| 144 | -interest:new:platform_category3:mobile_300 | ||
| 145 | -``` | ||
| 146 | - | ||
| 147 | -##### 客户端平台 + 二级分类 | ||
| 148 | -``` | ||
| 149 | -interest:hot:client_category2:web_200 | ||
| 150 | -interest:hot:client_category2:app_200 | ||
| 151 | -interest:cart:client_category2:web_200 | ||
| 152 | -interest:new:client_category2:app_200 | ||
| 153 | -``` | ||
| 154 | - | ||
| 155 | ---- | ||
| 156 | - | ||
| 157 | -## 🎯 按业务场景的索引使用 | ||
| 158 | - | ||
| 159 | -### 场景1: 首页个性化推荐 | ||
| 160 | - | ||
| 161 | -**方案A: 基于平台** | ||
| 162 | -```python | ||
| 163 | -key = f"interest:hot:platform:{user_platform}" | ||
| 164 | -# 示例：interest:hot:platform:pc | ||
| 165 | -``` | ||
| 166 | - | ||
| 167 | -**方案B: 基于分类偏好** | ||
| 168 | -```python | ||
| 169 | -key = f"interest:hot:category_level2:{user_favorite_category}" | ||
| 170 | -# 示例：interest:hot:category_level2:200 | ||
| 171 | -``` | ||
| 172 | - | ||
| 173 | -**方案C: 基于平台+分类** | ||
| 174 | -```python | ||
| 175 | -key = f"interest:hot:platform_category2:{user_platform}_{category_id}" | ||
| 176 | -# 示例：interest:hot:platform_category2:pc_200 | ||
| 177 | -``` | ||
| 178 | - | ||
| 179 | -### 场景2: 详情页相关推荐 | ||
| 180 | - | ||
| 181 | -**方案A: 行为相似** | ||
| 182 | -```python | ||
| 183 | -key = f"i2i:swing:{current_item_id}" | ||
| 184 | -# 示例：i2i:swing:12345 | ||
| 185 | -``` | ||
| 186 | - | ||
| 187 | -**方案B: 内容相似** | ||
| 188 | -```python | ||
| 189 | -key = f"i2i:content_hybrid:{current_item_id}" | ||
| 190 | -# 示例：i2i:content_hybrid:12345 | ||
| 191 | -``` | ||
| 192 | - | ||
| 193 | -**方案C: 融合推荐** | ||
| 194 | -```python | ||
| 195 | -behavior_similar = redis.get(f"i2i:swing:{item_id}") | ||
| 196 | -content_similar = redis.get(f"i2i:content_hybrid:{item_id}") | ||
| 197 | -# 融合两种结果 | ||
| 198 | -``` | ||
| 199 | - | ||
| 200 | -### 场景3: 分类页推荐 | ||
| 201 | - | ||
| 202 | -**方案A: 该分类热门** | ||
| 203 | -```python | ||
| 204 | -key = f"interest:hot:category_level2:{category_id}" | ||
| 205 | -# 示例：interest:hot:category_level2:200 | ||
| 206 | -``` | ||
| 207 | - | ||
| 208 | -**方案B: 该分类新品** | ||
| 209 | -```python | ||
| 210 | -key = f"interest:new:category_level2:{category_id}" | ||
| 211 | -# 示例：interest:new:category_level2:200 | ||
| 212 | -``` | ||
| 213 | - | ||
| 214 | -**方案C: 该分类+平台** | ||
| 215 | -```python | ||
| 216 | -key = f"interest:hot:platform_category2:{platform}_{category_id}" | ||
| 217 | -# 示例：interest:hot:platform_category2:pc_200 | ||
| 218 | -``` | ||
| 219 | - | ||
| 220 | -### 场景4: 供应商店铺页 | ||
| 221 | - | ||
| 222 | -**方案A: 供应商热门商品** | ||
| 223 | -```python | ||
| 224 | -key = f"interest:hot:supplier:{supplier_id}" | ||
| 225 | -# 示例：interest:hot:supplier:10001 | ||
| 226 | -``` | ||
| 227 | - | ||
| 228 | -**方案B: 供应商新品** | ||
| 229 | -```python | ||
| 230 | -key = f"interest:new:supplier:{supplier_id}" | ||
| 231 | -# 示例：interest:new:supplier:10001 | ||
| 232 | -``` | ||
| 233 | - | ||
| 234 | -### 场景5: 搜索结果页推荐 | ||
| 235 | - | ||
| 236 | -**方案A: 全局热门** | ||
| 237 | -```python | ||
| 238 | -key = "interest:global:platform:pc" | ||
| 239 | -``` | ||
| 240 | - | ||
| 241 | -**方案B: 分类相关** | ||
| 242 | -```python | ||
| 243 | -key = f"interest:global:category_level2:{search_category}" | ||
| 244 | -# 示例：interest:global:category_level2:200 | ||
| 245 | -``` | ||
| 246 | - | ||
| 247 | ---- | ||
| 248 | - | ||
| 249 | -## 📊 索引数量统计 | ||
| 250 | - | ||
| 251 | -### i2i索引 | ||
| 252 | -- 行为相似：3种算法 × 商品数量 | ||
| 253 | -- 内容相似：3种方法 × 商品数量 | ||
| 254 | -- **总计**：6 × 商品数量 | ||
| 255 | - | ||
| 256 | -### 兴趣点聚合索引 | ||
| 257 | - | ||
| 258 | -**单维度**： | ||
| 259 | -- platform: 2-10个 | ||
| 260 | -- client_platform: 2-5个 | ||
| 261 | -- supplier: 100-1000个 | ||
| 262 | -- category_level1: 10-50个 | ||
| 263 | -- category_level2: 50-200个 | ||
| 264 | -- category_level3: 200-1000个 | ||
| 265 | -- category_level4: 1000-5000个 | ||
| 266 | - | ||
| 267 | -**组合维度**： | ||
| 268 | -- platform_client: 4-50个 | ||
| 269 | -- platform_category2: 100-2000个 | ||
| 270 | -- platform_category3: 400-10000个 | ||
| 271 | -- client_category2: 100-1000个 | ||
| 272 | - | ||
| 273 | -**列表类型**：每个维度 × 4种类型（hot/cart/new/global） | ||
| 274 | - | ||
| 275 | -**预估总数**：10000-50000条索引 | ||
| 276 | - | ||
| 277 | ---- | ||
| 278 | - | ||
| 279 | -## 🔍 查询示例代码 | ||
| 280 | - | ||
| 281 | -### Python示例 | ||
| 282 | - | ||
| 283 | -```python | ||
| 284 | -import redis | ||
| 285 | - | ||
| 286 | -# 连接Redis | ||
| 287 | -r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True) | ||
| 288 | - | ||
| 289 | -# 1. 查询商品的相似商品 | ||
| 290 | -item_id = "12345" | ||
| 291 | -similar_items = r.get(f"i2i:swing:{item_id}") | ||
| 292 | -if similar_items: | ||
| 293 | - items = similar_items.split(',') | ||
| 294 | - for item in items[:5]: # 取前5个 | ||
| 295 | - item_id, score = item.split(':') | ||
| 296 | - print(f"商品ID: {item_id}, 相似度: {score}") | ||
| 297 | - | ||
| 298 | -# 2. 查询分类热门商品 | ||
| 299 | -category_id = "200" | ||
| 300 | -hot_items = r.get(f"interest:hot:category_level2:{category_id}") | ||
| 301 | -if hot_items: | ||
| 302 | - items = hot_items.split(',') | ||
| 303 | - for item in items[:10]: # 取前10个 | ||
| 304 | - item_id, score = item.split(':') | ||
| 305 | - print(f"商品ID: {item_id}, 得分: {score}") | ||
| 306 | - | ||
| 307 | -# 3. 查询平台+分类组合 | ||
| 308 | -platform = "pc" | ||
| 309 | -category_id = "200" | ||
| 310 | -key = f"interest:hot:platform_category2:{platform}_{category_id}" | ||
| 311 | -items = r.get(key) | ||
| 312 | -``` | ||
| 313 | - | ||
| 314 | -### Redis命令行示例 | ||
| 315 | - | ||
| 316 | -```bash | ||
| 317 | -# 查询商品相似度 | ||
| 318 | -redis-cli GET "i2i:swing:12345" | ||
| 319 | - | ||
| 320 | -# 查询分类热门 | ||
| 321 | -redis-cli GET "interest:hot:category_level2:200" | ||
| 322 | - | ||
| 323 | -# 查询供应商商品 | ||
| 324 | -redis-cli GET "interest:hot:supplier:10001" | ||
| 325 | - | ||
| 326 | -# 模糊查询所有热门索引 | ||
| 327 | -redis-cli KEYS "interest:hot:*" | ||
| 328 | - | ||
| 329 | -# 查看某个分类的所有类型 | ||
| 330 | -redis-cli KEYS "interest:*:category_level2:200" | ||
| 331 | -``` | ||
| 332 | - | ||
| 333 | ---- | ||
| 334 | - | ||
| 335 | -## 📝 注意事项 | ||
| 336 | - | ||
| 337 | -1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式 | ||
| 338 | -2. **值的格式**：`item_id1:score1,item_id2:score2,...` | ||
| 339 | -3. **过期时间**：建议设置7天过期 | ||
| 340 | -4. **更新频率**：建议每天更新一次 | ||
| 341 | -5. **查询优先级**： | ||
| 342 | - - 优先使用细粒度索引（如四级分类） | ||
| 343 | - - 粗粒度索引作为后备（如一级分类） | ||
| 344 | - - 融合多个索引结果 | ||
| 345 | - | ||
| 346 | ---- | ||
| 347 | - | ||
| 348 | -**版本**: v1.1 | ||
| 349 | -**生成日期**: 2025-10-16 | ||
| 350 | -**索引总数**: 约10000-50000条 |
offline_tasks/doc/快速开始.md deleted
| @@ -1,213 +0,0 @@ | @@ -1,213 +0,0 @@ | ||
| 1 | -# 离线任务快速启动指南 | ||
| 2 | - | ||
| 3 | -## 一、环境准备 | ||
| 4 | - | ||
| 5 | -### 1. 安装依赖 | ||
| 6 | - | ||
| 7 | -```bash | ||
| 8 | -cd /home/tw/recommendation | ||
| 9 | -pip install -r requirements.txt | ||
| 10 | -``` | ||
| 11 | - | ||
| 12 | -### 2. 配置数据库和Redis | ||
| 13 | - | ||
| 14 | -编辑配置文件 `offline_tasks/config/offline_config.py`，确保数据库和Redis连接信息正确： | ||
| 15 | - | ||
| 16 | -```python | ||
| 17 | -# 数据库配置 | ||
| 18 | -DB_CONFIG = { | ||
| 19 | - 'host': 'your_db_host', | ||
| 20 | - 'port': '9030', | ||
| 21 | - 'database': 'datacenter', | ||
| 22 | - 'username': 'readonly', | ||
| 23 | - 'password': 'your_password' | ||
| 24 | -} | ||
| 25 | - | ||
| 26 | -# Redis配置 | ||
| 27 | -REDIS_CONFIG = { | ||
| 28 | - 'host': 'your_redis_host', | ||
| 29 | - 'port': 6379, | ||
| 30 | - 'db': 0, | ||
| 31 | - 'password': None | ||
| 32 | -} | ||
| 33 | -``` | ||
| 34 | - | ||
| 35 | -## 二、运行离线任务 | ||
| 36 | - | ||
| 37 | -### 方式1：运行所有任务（推荐） | ||
| 38 | - | ||
| 39 | -```bash | ||
| 40 | -cd /home/tw/recommendation/offline_tasks | ||
| 41 | -python run_all.py --lookback_days 730 --top_n 50 | ||
| 42 | -``` | ||
| 43 | - | ||
| 44 | -这将依次运行： | ||
| 45 | -1. Swing算法（i2i相似度） | ||
| 46 | -2. Session Word2Vec（i2i相似度） | ||
| 47 | -3. DeepWalk算法（i2i相似度） | ||
| 48 | -4. 兴趣点聚合（多维度商品索引） | ||
| 49 | - | ||
| 50 | -### 方式2：运行单个任务 | ||
| 51 | - | ||
| 52 | -#### 运行Swing算法 | ||
| 53 | - | ||
| 54 | -```bash | ||
| 55 | -cd /home/tw/recommendation/offline_tasks | ||
| 56 | -python scripts/i2i_swing.py --lookback_days 730 --top_n 50 --time_decay | ||
| 57 | -``` | ||
| 58 | - | ||
| 59 | -#### 运行Session Word2Vec | ||
| 60 | - | ||
| 61 | -```bash | ||
| 62 | -python scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model | ||
| 63 | -``` | ||
| 64 | - | ||
| 65 | -#### 运行DeepWalk | ||
| 66 | - | ||
| 67 | -```bash | ||
| 68 | -python scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph | ||
| 69 | -``` | ||
| 70 | - | ||
| 71 | -#### 运行兴趣点聚合 | ||
| 72 | - | ||
| 73 | -```bash | ||
| 74 | -python scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 | ||
| 75 | -``` | ||
| 76 | - | ||
| 77 | -## 三、将索引加载到Redis | ||
| 78 | - | ||
| 79 | -任务运行完成后，将生成的索引加载到Redis： | ||
| 80 | - | ||
| 81 | -```bash | ||
| 82 | -cd /home/tw/recommendation/offline_tasks | ||
| 83 | -python scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379 --expire-days 7 | ||
| 84 | -``` | ||
| 85 | - | ||
| 86 | -参数说明： | ||
| 87 | -- `--redis-host`: Redis服务器地址 | ||
| 88 | -- `--redis-port`: Redis端口 | ||
| 89 | -- `--redis-db`: Redis数据库编号（默认0） | ||
| 90 | -- `--expire-days`: 索引过期天数（默认7天） | ||
| 91 | - | ||
| 92 | -## 四、查看输出结果 | ||
| 93 | - | ||
| 94 | -所有输出文件都在 `offline_tasks/output/` 目录下： | ||
| 95 | - | ||
| 96 | -```bash | ||
| 97 | -cd /home/tw/recommendation/offline_tasks/output | ||
| 98 | -ls -lh | ||
| 99 | -``` | ||
| 100 | - | ||
| 101 | -输出文件示例： | ||
| 102 | -``` | ||
| 103 | -i2i_swing_20251016.txt | ||
| 104 | -i2i_session_w2v_20251016.txt | ||
| 105 | -i2i_deepwalk_20251016.txt | ||
| 106 | -interest_aggregation_hot_20251016.txt | ||
| 107 | -interest_aggregation_cart_20251016.txt | ||
| 108 | -interest_aggregation_new_20251016.txt | ||
| 109 | -interest_aggregation_global_20251016.txt | ||
| 110 | -``` | ||
| 111 | - | ||
| 112 | -## 五、查看日志 | ||
| 113 | - | ||
| 114 | -所有运行日志都在 `offline_tasks/logs/` 目录下： | ||
| 115 | - | ||
| 116 | -```bash | ||
| 117 | -cd /home/tw/recommendation/offline_tasks/logs | ||
| 118 | -tail -f run_all_20251016.log | ||
| 119 | -``` | ||
| 120 | - | ||
| 121 | -## 六、设置定时任务 | ||
| 122 | - | ||
| 123 | -### 使用crontab设置每天运行 | ||
| 124 | - | ||
| 125 | -```bash | ||
| 126 | -# 编辑crontab | ||
| 127 | -crontab -e | ||
| 128 | - | ||
| 129 | -# 添加以下行（每天凌晨2点运行） | ||
| 130 | -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 | ||
| 131 | -``` | ||
| 132 | - | ||
| 133 | -### 运行后自动加载到Redis | ||
| 134 | - | ||
| 135 | -可以在crontab中添加索引加载任务： | ||
| 136 | - | ||
| 137 | -```bash | ||
| 138 | -# 凌晨6点加载索引到Redis（假设离线任务在4小时内完成） | ||
| 139 | -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 | ||
| 140 | -``` | ||
| 141 | - | ||
| 142 | -## 七、验证结果 | ||
| 143 | - | ||
| 144 | -### 查看文件内容 | ||
| 145 | - | ||
| 146 | -```bash | ||
| 147 | -# 查看i2i相似度 | ||
| 148 | -head -n 5 output/i2i_swing_20251016.txt | ||
| 149 | - | ||
| 150 | -# 查看兴趣点聚合 | ||
| 151 | -head -n 5 output/interest_aggregation_hot_20251016.txt | ||
| 152 | -``` | ||
| 153 | - | ||
| 154 | -### 从Redis查询 | ||
| 155 | - | ||
| 156 | -```bash | ||
| 157 | -# 使用redis-cli | ||
| 158 | -redis-cli | ||
| 159 | - | ||
| 160 | -# 查看i2i相似度 | ||
| 161 | -GET i2i:swing:123456 | ||
| 162 | - | ||
| 163 | -# 查看兴趣点索引 | ||
| 164 | -GET interest:hot:platform:PC | ||
| 165 | -GET interest:global:country:US | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -## 八、常见问题 | ||
| 169 | - | ||
| 170 | -### Q1: 任务运行时间太长怎么办？ | ||
| 171 | - | ||
| 172 | -A: 可以尝试： | ||
| 173 | -1. 减少 `--lookback_days` 参数（如改为365天） | ||
| 174 | -2. 减少 `--top_n` 参数（如改为20） | ||
| 175 | -3. 在更强大的机器上运行 | ||
| 176 | -4. 考虑分布式运行不同算法 | ||
| 177 | - | ||
| 178 | -### Q2: 内存不足怎么办？ | ||
| 179 | - | ||
| 180 | -A: | ||
| 181 | -1. Swing算法特别消耗内存，可以先跳过：`python run_all.py --skip-i2i` | ||
| 182 | -2. 只运行DeepWalk或Session W2V | ||
| 183 | -3. 对数据进行采样 | ||
| 184 | - | ||
| 185 | -### Q3: 数据库连接超时怎么办？ | ||
| 186 | - | ||
| 187 | -A: | ||
| 188 | -1. 检查数据库配置是否正确 | ||
| 189 | -2. 检查网络连接 | ||
| 190 | -3. 增加SQL查询的超时时间 | ||
| 191 | -4. 分批查询数据 | ||
| 192 | - | ||
| 193 | -### Q4: 如何只更新特定维度的索引？ | ||
| 194 | - | ||
| 195 | -A: 修改 `interest_aggregation.py` 脚本，注释掉不需要的维度计算代码。 | ||
| 196 | - | ||
| 197 | -## 九、性能参考 | ||
| 198 | - | ||
| 199 | -在标准配置（730天数据，top_n=50）下的预估运行时间： | ||
| 200 | - | ||
| 201 | -| 任务 | 数据量 | 预估时间 | 内存占用 | | ||
| 202 | -|------|--------|---------|---------| | ||
| 203 | -| Swing | 100万条行为 | 2-4小时 | 4-8GB | | ||
| 204 | -| Session W2V | 100万条行为 | 30-60分钟 | 2-4GB | | ||
| 205 | -| DeepWalk | 100万条行为 | 1-2小时 | 2-4GB | | ||
| 206 | -| 兴趣点聚合 | 100万条行为 | 30-60分钟 | 2-4GB | | ||
| 207 | - | ||
| 208 | -实际时间会因数据量和机器配置而异。 | ||
| 209 | - | ||
| 210 | -## 十、联系与支持 | ||
| 211 | - | ||
| 212 | -如有问题，请查看日志文件或联系开发团队。 | ||
| 213 | - |
offline_tasks/doc/故障排查指南.md deleted
| @@ -1,217 +0,0 @@ | @@ -1,217 +0,0 @@ | ||
| 1 | -# 故障排除指南 | ||
| 2 | - | ||
| 3 | -## 常见问题及解决方案 | ||
| 4 | - | ||
| 5 | -### 1. 数据库字段错误 | ||
| 6 | - | ||
| 7 | -#### 问题： | ||
| 8 | -``` | ||
| 9 | -pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'") | ||
| 10 | -``` | ||
| 11 | - | ||
| 12 | -#### 原因： | ||
| 13 | -数据库表结构与代码中使用的字段名不匹配。 | ||
| 14 | - | ||
| 15 | -#### 解决方案： | ||
| 16 | -1. 查看 `DATABASE_SETUP.md` 了解如何配置字段 | ||
| 17 | -2. 修改对应脚本中的SQL查询，使用实际存在的字段名 | ||
| 18 | -3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过 | ||
| 19 | - | ||
| 20 | -#### 已修复的字段： | ||
| 21 | -- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的 | ||
| 22 | -- ✅ 基础功能不依赖分类字段 | ||
| 23 | - | ||
| 24 | ---- | ||
| 25 | - | ||
| 26 | -### 2. 连接超时 | ||
| 27 | - | ||
| 28 | -#### 问题： | ||
| 29 | -``` | ||
| 30 | -pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...") | ||
| 31 | -``` | ||
| 32 | - | ||
| 33 | -#### 解决方案： | ||
| 34 | -1. 检查数据库配置：`config/offline_config.py` | ||
| 35 | -2. 确认网络连接和防火墙设置 | ||
| 36 | -3. 运行测试：`python3 test_connection.py` | ||
| 37 | - | ||
| 38 | ---- | ||
| 39 | - | ||
| 40 | -### 3. 内存不足 | ||
| 41 | - | ||
| 42 | -#### 问题： | ||
| 43 | -程序运行时内存占用过高或被杀死。 | ||
| 44 | - | ||
| 45 | -#### 解决方案： | ||
| 46 | -1. 减少回溯天数：`--lookback_days 365`（从730改为365） | ||
| 47 | -2. 减少输出数量：`--top_n 20`（从50改为20） | ||
| 48 | -3. 先运行单个算法： | ||
| 49 | - ```bash | ||
| 50 | - python3 scripts/i2i_session_w2v.py # 内存占用较小 | ||
| 51 | - ``` | ||
| 52 | -4. 跳过Swing算法（内存占用最大）： | ||
| 53 | - ```bash | ||
| 54 | - python3 run_all.py --skip-i2i | ||
| 55 | - ``` | ||
| 56 | - | ||
| 57 | ---- | ||
| 58 | - | ||
| 59 | -### 4. 运行时间过长 | ||
| 60 | - | ||
| 61 | -#### 解决方案： | ||
| 62 | -1. 减少数据量：`--lookback_days 180` | ||
| 63 | -2. 只运行特定算法： | ||
| 64 | - ```bash | ||
| 65 | - python3 run_all.py --only-w2v | ||
| 66 | - ``` | ||
| 67 | -3. 考虑使用C++版本的Swing（性能提升10倍） | ||
| 68 | - | ||
| 69 | ---- | ||
| 70 | - | ||
| 71 | -### 5. 依赖包安装失败 | ||
| 72 | - | ||
| 73 | -#### 解决方案： | ||
| 74 | -```bash | ||
| 75 | -# 单独安装失败的包 | ||
| 76 | -pip3 install pandas sqlalchemy pymysql gensim numpy | ||
| 77 | - | ||
| 78 | -# 或使用国内镜像 | ||
| 79 | -pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple | ||
| 80 | -``` | ||
| 81 | - | ||
| 82 | ---- | ||
| 83 | - | ||
| 84 | -### 6. Redis连接失败 | ||
| 85 | - | ||
| 86 | -#### 问题： | ||
| 87 | -``` | ||
| 88 | -redis.exceptions.ConnectionError: Error connecting to Redis | ||
| 89 | -``` | ||
| 90 | - | ||
| 91 | -#### 解决方案： | ||
| 92 | -1. Redis是可选的，只影响索引加载功能 | ||
| 93 | -2. 如果不需要Redis，可以跳过： | ||
| 94 | - ```bash | ||
| 95 | - python3 run_all.py # 只运行离线任务，不加载到Redis | ||
| 96 | - ``` | ||
| 97 | -3. 如果需要Redis，确认Redis已安装并运行： | ||
| 98 | - ```bash | ||
| 99 | - redis-cli ping # 应该返回 PONG | ||
| 100 | - ``` | ||
| 101 | - | ||
| 102 | ---- | ||
| 103 | - | ||
| 104 | -### 7. 输出文件为空 | ||
| 105 | - | ||
| 106 | -#### 可能原因： | ||
| 107 | -1. 数据量太少（没有满足最小阈值） | ||
| 108 | -2. 时间范围内没有数据 | ||
| 109 | -3. SQL查询条件过于严格 | ||
| 110 | - | ||
| 111 | -#### 解决方案： | ||
| 112 | -1. 检查日志：`tail -f logs/run_all_*.log` | ||
| 113 | -2. 调整参数： | ||
| 114 | - - 增加时间范围：`--lookback_days 1000` | ||
| 115 | - - 减少阈值：修改配置文件中的 `min_interaction_count` | ||
| 116 | -3. 检查数据库中是否有数据： | ||
| 117 | - ```python | ||
| 118 | - # 运行简单查询测试 | ||
| 119 | - python3 test_connection.py | ||
| 120 | - ``` | ||
| 121 | - | ||
| 122 | ---- | ||
| 123 | - | ||
| 124 | -### 8. 权限问题 | ||
| 125 | - | ||
| 126 | -#### 问题： | ||
| 127 | -``` | ||
| 128 | -PermissionError: [Errno 13] Permission denied | ||
| 129 | -``` | ||
| 130 | - | ||
| 131 | -#### 解决方案： | ||
| 132 | -```bash | ||
| 133 | -# 给脚本添加执行权限 | ||
| 134 | -chmod +x install.sh run_all.py | ||
| 135 | - | ||
| 136 | -# 确保有写入权限 | ||
| 137 | -chmod 755 output/ logs/ | ||
| 138 | -``` | ||
| 139 | - | ||
| 140 | ---- | ||
| 141 | - | ||
| 142 | -### 9. Python版本问题 | ||
| 143 | - | ||
| 144 | -#### 要求： | ||
| 145 | -Python 3.7+ | ||
| 146 | - | ||
| 147 | -#### 检查版本： | ||
| 148 | -```bash | ||
| 149 | -python3 --version | ||
| 150 | -``` | ||
| 151 | - | ||
| 152 | -#### 如果版本过低，需要升级Python | ||
| 153 | - | ||
| 154 | ---- | ||
| 155 | - | ||
| 156 | -### 10. 编码问题 | ||
| 157 | - | ||
| 158 | -#### 问题： | ||
| 159 | -``` | ||
| 160 | -UnicodeDecodeError: 'utf-8' codec can't decode byte... | ||
| 161 | -``` | ||
| 162 | - | ||
| 163 | -#### 解决方案： | ||
| 164 | -确保所有文件使用UTF-8编码，特别是配置文件和输出文件。 | ||
| 165 | - | ||
| 166 | ---- | ||
| 167 | - | ||
| 168 | -## 调试技巧 | ||
| 169 | - | ||
| 170 | -### 1. 查看详细日志 | ||
| 171 | -```bash | ||
| 172 | -tail -f logs/run_all_*.log | ||
| 173 | -``` | ||
| 174 | - | ||
| 175 | -### 2. 运行单个任务（便于调试） | ||
| 176 | -```bash | ||
| 177 | -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 | ||
| 178 | -``` | ||
| 179 | - | ||
| 180 | -### 3. 使用较小的数据量测试 | ||
| 181 | -```bash | ||
| 182 | -python3 run_all.py --lookback_days 30 --top_n 10 | ||
| 183 | -``` | ||
| 184 | - | ||
| 185 | -### 4. 检查中间结果 | ||
| 186 | -```bash | ||
| 187 | -ls -lh output/ | ||
| 188 | -head -n 20 output/i2i_swing_*.txt | ||
| 189 | -``` | ||
| 190 | - | ||
| 191 | ---- | ||
| 192 | - | ||
| 193 | -## 获取支持 | ||
| 194 | - | ||
| 195 | -如果以上方法都无法解决问题： | ||
| 196 | - | ||
| 197 | -1. **查看文档**： | ||
| 198 | - - `README.md` - 详细说明 | ||
| 199 | - - `DATABASE_SETUP.md` - 数据库配置 | ||
| 200 | - - `QUICKSTART.md` - 快速开始 | ||
| 201 | - | ||
| 202 | -2. **查看日志**： | ||
| 203 | - - `logs/` 目录下的所有日志文件 | ||
| 204 | - | ||
| 205 | -3. **简化测试**： | ||
| 206 | - - 先运行 `test_connection.py` | ||
| 207 | - - 再运行单个脚本 | ||
| 208 | - - 使用小数据量测试 | ||
| 209 | - | ||
| 210 | -4. **记录错误信息**： | ||
| 211 | - - 完整的错误堆栈 | ||
| 212 | - - 使用的命令 | ||
| 213 | - - 配置文件内容 | ||
| 214 | - | ||
| 215 | ---- | ||
| 216 | - | ||
| 217 | -**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。 |
offline_tasks/doc/数据库配置说明.md deleted
| @@ -1,179 +0,0 @@ | @@ -1,179 +0,0 @@ | ||
| 1 | -# 数据库字段配置说明 | ||
| 2 | - | ||
| 3 | -## 问题说明 | ||
| 4 | - | ||
| 5 | -如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。 | ||
| 6 | - | ||
| 7 | -## 已适配的基础字段 | ||
| 8 | - | ||
| 9 | -当前代码已经适配了以下基础字段（参考 `item_sim.py`）： | ||
| 10 | - | ||
| 11 | -### sensors_events 表 | ||
| 12 | -- `anonymous_id` - 用户ID | ||
| 13 | -- `item_id` - 商品ID | ||
| 14 | -- `event` - 事件类型 | ||
| 15 | -- `create_time` - 创建时间 | ||
| 16 | -- `platform` - 平台（可选） | ||
| 17 | -- `country` - 国家（可选） | ||
| 18 | -- `customer_type` - 客户类型（可选） | ||
| 19 | - | ||
| 20 | -### prd_goods_sku 表 | ||
| 21 | -- `id` - 商品ID | ||
| 22 | -- `name` - 商品名称 | ||
| 23 | -- `create_time` - 创建时间（用于判断新品） | ||
| 24 | - | ||
| 25 | -## 可选字段配置 | ||
| 26 | - | ||
| 27 | -如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度： | ||
| 28 | - | ||
| 29 | -### 分类字段（可选） | ||
| 30 | -- `category_level1_id` - 一级分类ID | ||
| 31 | -- `category_level2_id` - 二级分类ID | ||
| 32 | -- `category_level3_id` - 三级分类ID | ||
| 33 | - | ||
| 34 | -## 如何添加分类字段支持 | ||
| 35 | - | ||
| 36 | -如果您的数据库有分类字段，可以按以下步骤启用： | ||
| 37 | - | ||
| 38 | -### 步骤1: 修改 SQL 查询 | ||
| 39 | - | ||
| 40 | -编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段： | ||
| 41 | - | ||
| 42 | -```python | ||
| 43 | -sql_query = f""" | ||
| 44 | -SELECT | ||
| 45 | - se.anonymous_id AS user_id, | ||
| 46 | - se.item_id, | ||
| 47 | - se.event AS event_type, | ||
| 48 | - se.create_time, | ||
| 49 | - pgs.name AS item_name, | ||
| 50 | - pgs.create_time AS item_create_time, | ||
| 51 | - pgs.category_level2_id, # 添加这一行 | ||
| 52 | - pgs.category_level3_id, # 添加这一行 | ||
| 53 | - se.platform, | ||
| 54 | - se.country, | ||
| 55 | - se.customer_type | ||
| 56 | -FROM | ||
| 57 | - sensors_events se | ||
| 58 | -LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id | ||
| 59 | -... | ||
| 60 | -""" | ||
| 61 | -``` | ||
| 62 | - | ||
| 63 | -### 步骤2: 修改聚合逻辑 | ||
| 64 | - | ||
| 65 | -在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用： | ||
| 66 | - | ||
| 67 | -```python | ||
| 68 | -# 维度4: 二级分类 (category_level2) - 如果字段存在 | ||
| 69 | -if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')): | ||
| 70 | - key = f"category_level2:{row['category_level2_id']}" | ||
| 71 | - aggregations[key][item_id] += weight | ||
| 72 | -``` | ||
| 73 | - | ||
| 74 | -这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。 | ||
| 75 | - | ||
| 76 | -## 查看实际表结构 | ||
| 77 | - | ||
| 78 | -运行以下命令查看您的数据库表结构： | ||
| 79 | - | ||
| 80 | -```python | ||
| 81 | -# 创建一个简单的脚本查看表结构 | ||
| 82 | -import pandas as pd | ||
| 83 | -from db_service import create_db_connection | ||
| 84 | -from offline_tasks.config.offline_config import DB_CONFIG | ||
| 85 | - | ||
| 86 | -engine = create_db_connection( | ||
| 87 | - DB_CONFIG['host'], | ||
| 88 | - DB_CONFIG['port'], | ||
| 89 | - DB_CONFIG['database'], | ||
| 90 | - DB_CONFIG['username'], | ||
| 91 | - DB_CONFIG['password'] | ||
| 92 | -) | ||
| 93 | - | ||
| 94 | -# 查看 prd_goods_sku 表结构 | ||
| 95 | -df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine) | ||
| 96 | -print("prd_goods_sku 字段列表:") | ||
| 97 | -for col in df.columns: | ||
| 98 | - print(f" - {col}") | ||
| 99 | - | ||
| 100 | -# 查看 sensors_events 表结构 | ||
| 101 | -df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine) | ||
| 102 | -print("\nsensors_events 字段列表:") | ||
| 103 | -for col in df.columns: | ||
| 104 | - print(f" - {col}") | ||
| 105 | -``` | ||
| 106 | - | ||
| 107 | -## 常见字段名映射 | ||
| 108 | - | ||
| 109 | -如果您的数据库使用不同的字段名，需要在SQL查询中做映射： | ||
| 110 | - | ||
| 111 | -| 代码中的字段 | 可能的实际字段名 | 修改方式 | | ||
| 112 | -|-------------|----------------|---------| | ||
| 113 | -| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` | | ||
| 114 | -| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` | | ||
| 115 | -| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` | | ||
| 116 | -| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` | | ||
| 117 | - | ||
| 118 | -## 完整示例 | ||
| 119 | - | ||
| 120 | -假设您的表结构是： | ||
| 121 | -- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time` | ||
| 122 | -- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time` | ||
| 123 | - | ||
| 124 | -则需要修改SQL为： | ||
| 125 | - | ||
| 126 | -```python | ||
| 127 | -sql_query = f""" | ||
| 128 | -SELECT | ||
| 129 | - se.uid AS user_id, | ||
| 130 | - se.goods_id AS item_id, | ||
| 131 | - se.action AS event_type, | ||
| 132 | - se.time AS create_time, | ||
| 133 | - pgs.title AS item_name, | ||
| 134 | - pgs.add_time AS item_create_time, | ||
| 135 | - pgs.cat2 AS category_level2_id, | ||
| 136 | - pgs.cat3 AS category_level3_id | ||
| 137 | -FROM | ||
| 138 | - sensors_events se | ||
| 139 | -LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id | ||
| 140 | -... | ||
| 141 | -""" | ||
| 142 | -``` | ||
| 143 | - | ||
| 144 | -## 最小化配置 | ||
| 145 | - | ||
| 146 | -如果只想先测试基本功能，可以只使用最基础的字段： | ||
| 147 | - | ||
| 148 | -### i2i 算法只需要： | ||
| 149 | -- `anonymous_id` / `user_id` | ||
| 150 | -- `item_id` | ||
| 151 | -- `event` / `event_type` | ||
| 152 | -- `create_time` | ||
| 153 | -- `name` (商品名称) | ||
| 154 | - | ||
| 155 | -### 兴趣点聚合至少需要： | ||
| 156 | -- 以上i2i的字段 | ||
| 157 | -- 至少一个维度字段（如 `platform` 或 `country`） | ||
| 158 | - | ||
| 159 | -## 测试连接 | ||
| 160 | - | ||
| 161 | -修改后，运行测试脚本验证： | ||
| 162 | - | ||
| 163 | -```bash | ||
| 164 | -cd /home/tw/recommendation/offline_tasks | ||
| 165 | -python3 test_connection.py | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -## 获取帮助 | ||
| 169 | - | ||
| 170 | -如果仍有问题，请： | ||
| 171 | -1. 查看日志文件：`logs/run_all_*.log` | ||
| 172 | -2. 运行单个脚本测试，便于调试 | ||
| 173 | -3. 使用 `--help` 参数查看命令行选项 | ||
| 174 | - | ||
| 175 | -```bash | ||
| 176 | -python3 scripts/i2i_swing.py --help | ||
| 177 | -python3 scripts/interest_aggregation.py --help | ||
| 178 | -``` | ||
| 179 | - |
offline_tasks/doc/更新日志.md deleted
| @@ -1,43 +0,0 @@ | @@ -1,43 +0,0 @@ | ||
| 1 | -# 更新日志 | ||
| 2 | - | ||
| 3 | -## v1.0.1 (2025-10-16) | ||
| 4 | - | ||
| 5 | -### 修复 | ||
| 6 | -- **数据库字段适配**: 移除了不存在的 `category_level2_id` 和 `category_level3_id` 字段 | ||
| 7 | - - 修改了 `scripts/i2i_swing.py` 中的SQL查询 | ||
| 8 | - - 修改了 `scripts/interest_aggregation.py` 中的SQL查询和聚合逻辑 | ||
| 9 | - - 分类字段现在是可选的，如果数据库有这些字段可以手动添加 | ||
| 10 | - | ||
| 11 | -### 改进 | ||
| 12 | -- **兼容性增强**: 代码现在自动检测字段是否存在再使用 | ||
| 13 | -- **文档补充**: 新增 `DATABASE_SETUP.md` 说明如何配置数据库字段 | ||
| 14 | - | ||
| 15 | -### 使用建议 | ||
| 16 | -如果您的数据库有分类字段，请参考 `DATABASE_SETUP.md` 手动添加支持。 | ||
| 17 | - | ||
| 18 | -基础功能（i2i相似度）不需要分类字段即可正常运行。 | ||
| 19 | - | ||
| 20 | -## v1.0.0 (2025-10-16) | ||
| 21 | - | ||
| 22 | -### 新功能 | ||
| 23 | -- ✅ 实现 Swing 算法（i2i行为相似） | ||
| 24 | -- ✅ 实现 Session Word2Vec 算法 | ||
| 25 | -- ✅ 实现 DeepWalk 算法 | ||
| 26 | -- ✅ 实现兴趣点聚合索引生成 | ||
| 27 | -- ✅ 支持多维度查询（平台/国家/客户类型） | ||
| 28 | -- ✅ 支持多列表类型（热门/加购/新品） | ||
| 29 | -- ✅ 时间衰减和行为加权 | ||
| 30 | -- ✅ 统一调度脚本 | ||
| 31 | -- ✅ Redis加载工具 | ||
| 32 | -- ✅ 完整文档 | ||
| 33 | - | ||
| 34 | -### 技术特性 | ||
| 35 | -- 参考 `item_sim.py` 适配真实数据 | ||
| 36 | -- 改写自 `collaboration/` 和 `graphembedding/` 模块 | ||
| 37 | -- 支持2年历史数据处理 | ||
| 38 | -- 支持定时任务调度 | ||
| 39 | - | ||
| 40 | ---- | ||
| 41 | - | ||
| 42 | -**说明**: 如果遇到字段不匹配的问题，请查看 `DATABASE_SETUP.md` 进行配置。 | ||
| 43 | - |
offline_tasks/doc/系统改进总结-20241017.md deleted
| @@ -1,445 +0,0 @@ | @@ -1,445 +0,0 @@ | ||
| 1 | -# 推荐系统离线任务改进总结 | ||
| 2 | - | ||
| 3 | -**日期**: 2024-10-17 | ||
| 4 | -**改进内容**: 前置任务优化、文档整理、算法增强 | ||
| 5 | - | ||
| 6 | ---- | ||
| 7 | - | ||
| 8 | -## ✅ 完成的改进 | ||
| 9 | - | ||
| 10 | -### 1. 前置任务：商品属性获取 | ||
| 11 | - | ||
| 12 | -**问题**: 多个脚本都需要获取ID->名称映射，导致重复查询数据库，效率低下。 | ||
| 13 | - | ||
| 14 | -**解决方案**: | ||
| 15 | -- ✅ 创建 `fetch_item_attributes.py` 作为前置任务 | ||
| 16 | -- ✅ 一次性从数据库获取所有ID->名称映射 | ||
| 17 | -- ✅ 保存到本地JSON文件 (`item_attributes_mappings.json`) | ||
| 18 | -- ✅ 后续任务直接加载本地文件，避免重复查询 | ||
| 19 | - | ||
| 20 | -**新增文件**: | ||
| 21 | -``` | ||
| 22 | -offline_tasks/scripts/fetch_item_attributes.py | ||
| 23 | -offline_tasks/output/item_attributes_mappings.json | ||
| 24 | -offline_tasks/output/item_attributes_stats.txt | ||
| 25 | -``` | ||
| 26 | - | ||
| 27 | -**修改文件**: | ||
| 28 | -``` | ||
| 29 | -offline_tasks/scripts/debug_utils.py | ||
| 30 | - - 新增 load_name_mappings_from_file() 函数 | ||
| 31 | - - fetch_name_mappings() 标记为已弃用 | ||
| 32 | - | ||
| 33 | -offline_tasks/scripts/add_names_to_swing.py | ||
| 34 | - - 改用 load_name_mappings_from_file() | ||
| 35 | - - 移除数据库连接代码 | ||
| 36 | - | ||
| 37 | -offline_tasks/scripts/i2i_swing.py | ||
| 38 | - - 改用 load_name_mappings_from_file() | ||
| 39 | - - Debug模式加载本地映射 | ||
| 40 | - | ||
| 41 | -offline_tasks/run_all.py | ||
| 42 | - - 添加前置任务1: fetch_item_attributes | ||
| 43 | - - 添加前置任务2: generate_session | ||
| 44 | - - 调整任务执行顺序 | ||
| 45 | -``` | ||
| 46 | - | ||
| 47 | -**效果**: | ||
| 48 | -- ⚡ 大幅减少数据库查询次数 | ||
| 49 | -- 🚀 提升整体任务执行速度 | ||
| 50 | -- 💾 统一的映射数据源，避免不一致 | ||
| 51 | - | ||
| 52 | ---- | ||
| 53 | - | ||
| 54 | -### 2. Session文件生成前置化 | ||
| 55 | - | ||
| 56 | -**改进**: 将session文件生成作为独立的前置任务 | ||
| 57 | - | ||
| 58 | -**新增任务流程**: | ||
| 59 | -``` | ||
| 60 | -run_all.py 执行顺序: | ||
| 61 | -前置任务: | ||
| 62 | -1. fetch_item_attributes.py → 获取商品属性 | ||
| 63 | -2. generate_session.py → 生成用户session文件 | ||
| 64 | -3. run_cpp_swing() → C++ Swing算法（使用session） | ||
| 65 | - | ||
| 66 | -核心算法任务: | ||
| 67 | -4. i2i_swing.py → Python Swing算法（启用日期维度） | ||
| 68 | -5. i2i_session_w2v.py → Session W2V | ||
| 69 | -6. i2i_deepwalk.py → DeepWalk | ||
| 70 | -7. i2i_content_similar.py → 内容相似度 | ||
| 71 | -8. interest_aggregation.py → 兴趣聚合 | ||
| 72 | -``` | ||
| 73 | - | ||
| 74 | -**好处**: | ||
| 75 | -- 📦 Session文件可复用于多个任务 | ||
| 76 | -- 🔄 C++版Swing算法可直接使用session文件 | ||
| 77 | -- 🎯 数据准备与算法执行解耦 | ||
| 78 | - | ||
| 79 | ---- | ||
| 80 | - | ||
| 81 | -### 3. Swing算法增强：支持日期维度 | ||
| 82 | - | ||
| 83 | -**功能**: i2i_swing.py 现在支持 uid+日期 作为额外的session维度 | ||
| 84 | - | ||
| 85 | -**实现方式**: | ||
| 86 | -```python | ||
| 87 | -# 数据duplicate： | ||
| 88 | -# 1. 原始数据：uid -> items | ||
| 89 | -# 2. 日期数据：uid_YYYYMMDD -> items | ||
| 90 | -# 3. 合并后输入Swing算法 | ||
| 91 | - | ||
| 92 | -# 新增参数 | ||
| 93 | ---use_daily_session # 启用日期维度（默认开启） | ||
| 94 | ---no_daily_session # 禁用日期维度 | ||
| 95 | -``` | ||
| 96 | - | ||
| 97 | -**示例**: | ||
| 98 | -```bash | ||
| 99 | -# 使用日期维度（默认） | ||
| 100 | -python3 scripts/i2i_swing.py --lookback_days 730 --debug | ||
| 101 | - | ||
| 102 | -# 禁用日期维度 | ||
| 103 | -python3 scripts/i2i_swing.py --lookback_days 730 --no_daily_session | ||
| 104 | -``` | ||
| 105 | - | ||
| 106 | -**效果**: | ||
| 107 | -- 📈 同时考虑用户整体行为和单日行为 | ||
| 108 | -- 🎯 更精准的物品相似度计算 | ||
| 109 | -- 🔍 捕获用户短期和长期兴趣 | ||
| 110 | - | ||
| 111 | -**原理**: | ||
| 112 | -``` | ||
| 113 | -原始数据: | ||
| 114 | - user_A -> [item1, item2, item3] (跨多天的行为) | ||
| 115 | - | ||
| 116 | -Duplicate后: | ||
| 117 | - user_A -> [item1, item2, item3] # 原始session | ||
| 118 | - user_A_20241015 -> [item1] # 10月15日session | ||
| 119 | - user_A_20241016 -> [item2, item3] # 10月16日session | ||
| 120 | - | ||
| 121 | -算法同时考虑： | ||
| 122 | -- 用户整体偏好（跨时间） | ||
| 123 | -- 用户单日集中行为（同一天购买的商品更相关） | ||
| 124 | -``` | ||
| 125 | - | ||
| 126 | ---- | ||
| 127 | - | ||
| 128 | -### 4. 文档整理与规范化 | ||
| 129 | - | ||
| 130 | -**问题**: 文档散乱，临时记录太多，命名不规范。 | ||
| 131 | - | ||
| 132 | -**解决方案**: | ||
| 133 | - | ||
| 134 | -#### 4.1 创建统一文档中心 | ||
| 135 | -``` | ||
| 136 | -offline_tasks/doc/ | ||
| 137 | -├── README.md # 文档索引 | ||
| 138 | -├── 从这里开始.md | ||
| 139 | -├── 快速开始.md | ||
| 140 | -├── Swing算法使用指南.md | ||
| 141 | -├── 运行脚本指南.md | ||
| 142 | -├── 调试指南.md | ||
| 143 | -├── 离线索引数据规范.md | ||
| 144 | -├── Redis数据规范.md | ||
| 145 | -├── 完整索引列表.md | ||
| 146 | -├── 数据库配置说明.md | ||
| 147 | -├── 故障排查指南.md | ||
| 148 | -├── 更新日志.md | ||
| 149 | -└── Swing实现总结.md | ||
| 150 | -``` | ||
| 151 | - | ||
| 152 | -#### 4.2 删除临时文档 | ||
| 153 | -``` | ||
| 154 | -已删除的临时文档（offline_tasks/）: | ||
| 155 | -- MEMORY_MONITORING_UPDATE.md | ||
| 156 | -- LATEST_UPDATES.md | ||
| 157 | -- CONTENT_SIMILARITY_UPDATE.md | ||
| 158 | -- QUICKSTART_NEW.md | ||
| 159 | -- CHANGES_SUMMARY.md | ||
| 160 | -- B2B_LOW_FREQUENCY_OPTIMIZATION.md | ||
| 161 | -- FIX_NAME_MAPPING.md | ||
| 162 | -- QUICK_DEBUG_SUMMARY.md | ||
| 163 | -- UPDATE_CONFIG_GUIDE.md | ||
| 164 | -- FINAL_UPDATE.md | ||
| 165 | -- FINAL_SUMMARY.md | ||
| 166 | -- CURRENT_STATUS.md | ||
| 167 | -- DELIVERY.md | ||
| 168 | -- PROJECT_SUMMARY.md | ||
| 169 | -- STRUCTURE.md | ||
| 170 | -- FIELD_MAPPING.md | ||
| 171 | - | ||
| 172 | -已删除的临时文档（根目录）: | ||
| 173 | -- DEBUG_IMPLEMENTATION_SUMMARY.md | ||
| 174 | -- CONFIG_CHANGES_SUMMARY.md | ||
| 175 | -- OFFLINE_TASKS_SUMMARY.md | ||
| 176 | -- OFFLINE_TASKS_README.md | ||
| 177 | -- tables_structure.md | ||
| 178 | -``` | ||
| 179 | - | ||
| 180 | -#### 4.3 文档命名规范 | ||
| 181 | -- ✅ 所有重要文档使用中文名 | ||
| 182 | -- ✅ 统一放在 `doc/` 目录 | ||
| 183 | -- ✅ 创建 `doc/README.md` 索引 | ||
| 184 | -- ✅ collaboration目录下的文档同步规范 | ||
| 185 | - | ||
| 186 | ---- | ||
| 187 | - | ||
| 188 | -## 📊 改进效果对比 | ||
| 189 | - | ||
| 190 | -### 数据库查询优化 | ||
| 191 | - | ||
| 192 | -**改进前**: | ||
| 193 | -``` | ||
| 194 | -每次运行任务: | ||
| 195 | - 1. i2i_swing.py → 查询商品名称 | ||
| 196 | - 2. add_names_to_swing → 查询商品名称 | ||
| 197 | - 3. 其他debug任务 → 重复查询 | ||
| 198 | - | ||
| 199 | -总查询次数: 5-10次（取决于任务数） | ||
| 200 | -``` | ||
| 201 | - | ||
| 202 | -**改进后**: | ||
| 203 | -``` | ||
| 204 | -每次运行任务: | ||
| 205 | - 1. fetch_item_attributes.py → 查询1次，保存文件 | ||
| 206 | - 2. 所有后续任务 → 加载本地文件 | ||
| 207 | - | ||
| 208 | -总查询次数: 1次 | ||
| 209 | -``` | ||
| 210 | - | ||
| 211 | -**性能提升**: 减少 80-90% 的数据库查询 | ||
| 212 | - | ||
| 213 | -### Session文件生成 | ||
| 214 | - | ||
| 215 | -**改进前**: | ||
| 216 | -``` | ||
| 217 | -- i2i_swing.py 内部查询数据库 | ||
| 218 | -- C++ Swing需要手动准备数据 | ||
| 219 | -``` | ||
| 220 | - | ||
| 221 | -**改进后**: | ||
| 222 | -``` | ||
| 223 | -- generate_session.py 统一生成 | ||
| 224 | -- 支持两种格式（标准/C++） | ||
| 225 | -- 所有算法可复用 | ||
| 226 | -``` | ||
| 227 | - | ||
| 228 | -### 文档管理 | ||
| 229 | - | ||
| 230 | -**改进前**: | ||
| 231 | -- 30+ 散乱的Markdown文件 | ||
| 232 | -- 无明确分类和索引 | ||
| 233 | -- 大量临时记录 | ||
| 234 | - | ||
| 235 | -**改进后**: | ||
| 236 | -- 13个核心文档 | ||
| 237 | -- 统一在 doc/ 目录 | ||
| 238 | -- 清晰的索引和分类 | ||
| 239 | - | ||
| 240 | ---- | ||
| 241 | - | ||
| 242 | -## 🚀 使用指南 | ||
| 243 | - | ||
| 244 | -### 运行完整流程 | ||
| 245 | - | ||
| 246 | -```bash | ||
| 247 | -cd /home/tw/recommendation/offline_tasks | ||
| 248 | - | ||
| 249 | -# 方式1: 运行全部任务（推荐） | ||
| 250 | -bash run.sh | ||
| 251 | - | ||
| 252 | -# 方式2: 使用Python版本（简化版） | ||
| 253 | -python3 run_all.py --debug | ||
| 254 | - | ||
| 255 | -# 方式3: 分步运行 | ||
| 256 | -# 步骤1: 获取商品属性 | ||
| 257 | -python3 scripts/fetch_item_attributes.py | ||
| 258 | - | ||
| 259 | -# 步骤2: 生成session文件 | ||
| 260 | -python3 scripts/generate_session.py --lookback_days 730 | ||
| 261 | - | ||
| 262 | -# 步骤3: 运行C++ Swing | ||
| 263 | -cd collaboration && bash run.sh && cd .. | ||
| 264 | - | ||
| 265 | -# 步骤4: 运行Python Swing（启用日期维度） | ||
| 266 | -python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug | ||
| 267 | -``` | ||
| 268 | - | ||
| 269 | -### C++ Swing算法 | ||
| 270 | - | ||
| 271 | -```bash | ||
| 272 | -# C++ Swing现已集成到run.sh，会自动执行 | ||
| 273 | -# 如需单独运行: | ||
| 274 | -cd /home/tw/recommendation/offline_tasks/collaboration | ||
| 275 | -bash run.sh | ||
| 276 | - | ||
| 277 | -# 查看结果 | ||
| 278 | -ls -lh output/swing_similar*.txt | ||
| 279 | -cat output/swing_similar_readable.txt | head -20 | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -### 查看文档 | ||
| 283 | - | ||
| 284 | -```bash | ||
| 285 | -cd /home/tw/recommendation/offline_tasks/doc | ||
| 286 | - | ||
| 287 | -# 查看文档索引 | ||
| 288 | -cat README.md | ||
| 289 | - | ||
| 290 | -# 快速开始 | ||
| 291 | -cat 快速开始.md | ||
| 292 | - | ||
| 293 | -# 详细使用指南 | ||
| 294 | -cat Swing算法使用指南.md | ||
| 295 | -``` | ||
| 296 | - | ||
| 297 | ---- | ||
| 298 | - | ||
| 299 | -## 📁 文件结构 | ||
| 300 | - | ||
| 301 | -``` | ||
| 302 | -recommendation/ | ||
| 303 | -├── offline_tasks/ | ||
| 304 | -│ ├── scripts/ | ||
| 305 | -│ │ ├── fetch_item_attributes.py # 新增：前置任务 | ||
| 306 | -│ │ ├── generate_session.py # 已有：session生成 | ||
| 307 | -│ │ ├── add_names_to_swing.py # 修改：使用本地映射 | ||
| 308 | -│ │ ├── i2i_swing.py # 修改：支持日期维度 | ||
| 309 | -│ │ └── debug_utils.py # 修改：添加加载函数 | ||
| 310 | -│ ├── collaboration/ # 移动：C++ Swing目录 | ||
| 311 | -│ │ ├── src/ | ||
| 312 | -│ │ ├── bin/ | ||
| 313 | -│ │ ├── run.sh # 修改：路径更新 | ||
| 314 | -│ │ └── output/ | ||
| 315 | -│ ├── doc/ # 新增：文档中心 | ||
| 316 | -│ │ ├── README.md | ||
| 317 | -│ │ ├── 快速开始.md | ||
| 318 | -│ │ ├── Swing算法使用指南.md | ||
| 319 | -│ │ └── ... | ||
| 320 | -│ ├── output/ | ||
| 321 | -│ │ ├── item_attributes_mappings.json # 新增：映射文件 | ||
| 322 | -│ │ ├── item_attributes_stats.txt # 新增：统计信息 | ||
| 323 | -│ │ └── session.txt.YYYYMMDD # session文件 | ||
| 324 | -│ ├── run.sh # 新增：主执行脚本 | ||
| 325 | -│ ├── run_all.py # 修改：简化版本 | ||
| 326 | -│ └── README.md | ||
| 327 | -``` | ||
| 328 | - | ||
| 329 | ---- | ||
| 330 | - | ||
| 331 | -## 🔧 C++ Swing算法集成 | ||
| 332 | - | ||
| 333 | -### 改进内容 | ||
| 334 | - | ||
| 335 | -**之前**: C++ Swing在外层目录，需要手动切换 | ||
| 336 | -```bash | ||
| 337 | -cd /home/tw/recommendation/collaboration | ||
| 338 | -bash run.sh | ||
| 339 | -``` | ||
| 340 | - | ||
| 341 | -**现在**: 已移入offline_tasks，集成到`run.sh`自动执行 | ||
| 342 | - | ||
| 343 | -### 执行流程 | ||
| 344 | - | ||
| 345 | -``` | ||
| 346 | -run.sh: | ||
| 347 | -1. fetch_item_attributes.py | ||
| 348 | -2. generate_session.py ← 生成session.txt.YYYYMMDD.cpp | ||
| 349 | -3. collaboration/run.sh ← 直接调用C++ Swing | ||
| 350 | - ├─ 编译C++程序 | ||
| 351 | - ├─ 读取session文件 | ||
| 352 | - ├─ 运行Swing算法 | ||
| 353 | - ├─ 合并多线程结果 | ||
| 354 | - └─ 生成可读版本（自动添加商品名） | ||
| 355 | -4. i2i_swing.py ← Python Swing | ||
| 356 | -5. i2i_session_w2v.py ← Session W2V | ||
| 357 | -6. i2i_deepwalk.py ← DeepWalk | ||
| 358 | -7. i2i_content_similar.py ← 内容相似度 | ||
| 359 | -8. interest_aggregation.py ← 兴趣聚合 | ||
| 360 | -9. load_index_to_redis.py ← 加载到Redis | ||
| 361 | -``` | ||
| 362 | - | ||
| 363 | -### 输出结果 | ||
| 364 | - | ||
| 365 | -C++ Swing执行后，结果保存在： | ||
| 366 | -``` | ||
| 367 | -offline_tasks/collaboration/output_YYYYMMDD/ | ||
| 368 | -├── sim_matrx.* # 多线程输出 | ||
| 369 | -├── swing_similar.txt # 合并结果（ID格式） | ||
| 370 | -└── swing_similar_readable.txt # 可读版本（ID:名称格式） | ||
| 371 | - | ||
| 372 | -offline_tasks/collaboration/output -> output_YYYYMMDD # 软链接 | ||
| 373 | -``` | ||
| 374 | - | ||
| 375 | -### 优势 | ||
| 376 | - | ||
| 377 | -- ✅ **自动化**: 无需手动切换目录 | ||
| 378 | -- ✅ **依赖管理**: 确保session文件已生成 | ||
| 379 | -- ✅ **错误处理**: 失败不影响后续任务 | ||
| 380 | -- ✅ **日志统一**: 所有任务日志在同一个文件 | ||
| 381 | -- ✅ **性能**: C++版本比Python版快10-100倍 | ||
| 382 | - | ||
| 383 | -### 单独运行 | ||
| 384 | - | ||
| 385 | -如需单独运行C++ Swing（不执行其他任务）： | ||
| 386 | -```bash | ||
| 387 | -cd /home/tw/recommendation/offline_tasks/collaboration | ||
| 388 | -bash run.sh | ||
| 389 | -``` | ||
| 390 | - | ||
| 391 | ---- | ||
| 392 | - | ||
| 393 | -## 🎯 核心改进点总结 | ||
| 394 | - | ||
| 395 | -1. **✅ 性能优化**: 减少80-90%的数据库查询 | ||
| 396 | -2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离 | ||
| 397 | -3. **✅ 功能增强**: Swing算法支持日期维度 | ||
| 398 | -4. **✅ 集成优化**: C++ Swing集成到统一流程 | ||
| 399 | -5. **✅ 文档规范**: 统一管理，中文命名，清晰索引 | ||
| 400 | -6. **✅ 代码质量**: 无Linter错误，统一编码规范 | ||
| 401 | - | ||
| 402 | ---- | ||
| 403 | - | ||
| 404 | -## 📝 后续建议 | ||
| 405 | - | ||
| 406 | -### 短期优化 | ||
| 407 | - | ||
| 408 | -1. **监控与告警** | ||
| 409 | - - 添加任务执行时间监控 | ||
| 410 | - - 映射文件过期检测 | ||
| 411 | - - 自动重新获取机制 | ||
| 412 | - | ||
| 413 | -2. **性能优化** | ||
| 414 | - - Session文件增量更新 | ||
| 415 | - - 映射文件分批加载 | ||
| 416 | - - 并行任务执行 | ||
| 417 | - | ||
| 418 | -### 长期规划 | ||
| 419 | - | ||
| 420 | -1. **分布式支持** | ||
| 421 | - - 多机协同计算 | ||
| 422 | - - 数据分片处理 | ||
| 423 | - | ||
| 424 | -2. **实时更新** | ||
| 425 | - - 在线学习机制 | ||
| 426 | - - 增量索引更新 | ||
| 427 | - | ||
| 428 | -3. **A/B测试框架** | ||
| 429 | - - 多版本算法对比 | ||
| 430 | - - 效果评估系统 | ||
| 431 | - | ||
| 432 | ---- | ||
| 433 | - | ||
| 434 | -## 📞 相关文档 | ||
| 435 | - | ||
| 436 | -- **快速开始**: [doc/快速开始.md](./快速开始.md) | ||
| 437 | -- **详细指南**: [doc/Swing算法使用指南.md](./Swing算法使用指南.md) | ||
| 438 | -- **故障排查**: [doc/故障排查指南.md](./故障排查指南.md) | ||
| 439 | -- **文档索引**: [doc/README.md](./README.md) | ||
| 440 | - | ||
| 441 | ---- | ||
| 442 | - | ||
| 443 | -**改进完成时间**: 2024-10-17 | ||
| 444 | -**状态**: ✅ 已完成并测试通过 | ||
| 445 | - |
| @@ -0,0 +1,711 @@ | @@ -0,0 +1,711 @@ | ||
| 1 | +# 推荐系统离线任务详细设计文档 | ||
| 2 | + | ||
| 3 | +## 📋 文档说明 | ||
| 4 | + | ||
| 5 | +本文档是推荐系统离线任务的详细设计文档，包含系统架构、功能模块、实现细节和使用指南。 | ||
| 6 | + | ||
| 7 | +**最后更新**: 2024-10-17 | ||
| 8 | +**版本**: v1.1 | ||
| 9 | +**状态**: ✅ 已完成并可用 | ||
| 10 | + | ||
| 11 | +--- | ||
| 12 | + | ||
| 13 | +## 📦 项目概述 | ||
| 14 | + | ||
| 15 | +推荐系统离线任务负责生成各类推荐索引，包括商品相似度索引（i2i）和兴趣点聚合索引，为在线推荐系统提供数据支撑。 | ||
| 16 | + | ||
| 17 | +### 核心功能 | ||
| 18 | + | ||
| 19 | +1. **i2i相似度索引**（4种算法） | ||
| 20 | + - Swing算法（C++高性能版 + Python版） | ||
| 21 | + - Session Word2Vec | ||
| 22 | + - DeepWalk | ||
| 23 | + - Content-based（内容相似度） | ||
| 24 | + | ||
| 25 | +2. **兴趣点聚合索引**（11个维度） | ||
| 26 | + - 7个单维度：platform、client_platform、supplier、category_level1-4 | ||
| 27 | + - 4个组合维度：platform_client、platform_category2、platform_category3、client_category2 | ||
| 28 | + - 3种列表类型：hot（热门）、cart（加购）、new（新品）、global（全局） | ||
| 29 | + | ||
| 30 | +### 技术特点 | ||
| 31 | + | ||
| 32 | +- ✅ **完整性**: 行为相似 + 内容相似，短期热门 + 长期稳定 | ||
| 33 | +- ✅ **灵活性**: 支持4级分类查询，支持多维度组合 | ||
| 34 | +- ✅ **可扩展性**: 易于添加新维度和新算法 | ||
| 35 | +- ✅ **高性能**: C++ Swing算法性能比Python快10-100倍 | ||
| 36 | + | ||
| 37 | +--- | ||
| 38 | + | ||
| 39 | +## 🏗️ 系统架构 | ||
| 40 | + | ||
| 41 | +### 目录结构 | ||
| 42 | + | ||
| 43 | +``` | ||
| 44 | +offline_tasks/ | ||
| 45 | +├── scripts/ # Python脚本 | ||
| 46 | +│ ├── fetch_item_attributes.py # 前置任务：获取商品属性 | ||
| 47 | +│ ├── generate_session.py # 前置任务：生成session | ||
| 48 | +│ ├── i2i_swing.py # Python Swing算法 | ||
| 49 | +│ ├── i2i_session_w2v.py # Session W2V | ||
| 50 | +│ ├── i2i_deepwalk.py # DeepWalk | ||
| 51 | +│ ├── i2i_content_similar.py # 内容相似度 | ||
| 52 | +│ ├── interest_aggregation.py # 兴趣聚合 | ||
| 53 | +│ ├── load_index_to_redis.py # 加载到Redis | ||
| 54 | +│ ├── add_names_to_swing.py # 添加商品名 | ||
| 55 | +│ └── debug_utils.py # Debug工具 | ||
| 56 | +├── collaboration/ # C++ Swing算法 | ||
| 57 | +│ ├── src/ # C++源码 | ||
| 58 | +│ ├── run.sh # 执行脚本 | ||
| 59 | +│ └── output/ # 输出目录 | ||
| 60 | +├── config/ | ||
| 61 | +│ └── offline_config.py # 配置文件 | ||
| 62 | +├── doc/ # 文档目录 | ||
| 63 | +│ ├── 详细设计文档.md # 本文档 | ||
| 64 | +│ ├── 离线索引数据规范.md # 数据输出规范 | ||
| 65 | +│ └── Redis数据规范.md # Redis存储规范 | ||
| 66 | +├── output/ # 输出文件 | ||
| 67 | +├── logs/ # 日志文件 | ||
| 68 | +├── run.sh # ⭐ 主执行脚本 | ||
| 69 | +├── run_all.py # Python版本执行脚本 | ||
| 70 | +└── README.md | ||
| 71 | +``` | ||
| 72 | + | ||
| 73 | +### 执行流程 | ||
| 74 | + | ||
| 75 | +``` | ||
| 76 | +1. 环境准备 | ||
| 77 | + └─ 清理旧进程、创建必要目录 | ||
| 78 | + | ||
| 79 | +2. 前置任务 | ||
| 80 | + ├─ fetch_item_attributes.py → 商品属性映射（避免重复查询数据库） | ||
| 81 | + ├─ generate_session.py → 用户session文件 | ||
| 82 | + └─ collaboration/run.sh → C++ Swing (高性能版本) | ||
| 83 | + | ||
| 84 | +3. i2i算法任务 | ||
| 85 | + ├─ i2i_swing.py → Python Swing (支持日期维度) | ||
| 86 | + ├─ i2i_session_w2v.py → Session W2V | ||
| 87 | + ├─ i2i_deepwalk.py → DeepWalk | ||
| 88 | + └─ i2i_content_similar.py → 内容相似度 | ||
| 89 | + | ||
| 90 | +4. 兴趣聚合 | ||
| 91 | + └─ interest_aggregation.py → 多维度聚合 | ||
| 92 | + | ||
| 93 | +5. 加载Redis | ||
| 94 | + └─ load_index_to_redis.py → 导入Redis | ||
| 95 | + | ||
| 96 | +6. 完成 | ||
| 97 | + └─ 输出结果文件列表 | ||
| 98 | +``` | ||
| 99 | + | ||
| 100 | +--- | ||
| 101 | + | ||
| 102 | +## 🎯 功能模块详解 | ||
| 103 | + | ||
| 104 | +### 1. i2i相似度索引 | ||
| 105 | + | ||
| 106 | +#### 1.1 Swing算法 | ||
| 107 | + | ||
| 108 | +**两个版本：** | ||
| 109 | + | ||
| 110 | +**C++高性能版本** | ||
| 111 | +- 文件位置: `offline_tasks/collaboration/` | ||
| 112 | +- 性能: 比Python快10-100倍 | ||
| 113 | +- 适用场景: 生产环境，海量数据（>50,000商品） | ||
| 114 | +- 输出格式: `item_id \t similar_id1:score1,similar_id2:score2,...` | ||
| 115 | +- 分数特点: 原始Swing分数（未归一化） | ||
| 116 | + | ||
| 117 | +**Python标准版本** | ||
| 118 | +- 文件: `scripts/i2i_swing.py` | ||
| 119 | +- 性能: 适中，易于调试 | ||
| 120 | +- 适用场景: 开发测试，需要高级特性（时间衰减、日期维度） | ||
| 121 | +- 输出格式: `item_id \t item_name \t similar_id1:score1,...` | ||
| 122 | +- 分数特点: 归一化到0-1区间 | ||
| 123 | + | ||
| 124 | +**参数配置：** | ||
| 125 | +```bash | ||
| 126 | +# C++ Swing | ||
| 127 | +ALPHA=0.7 # Swing alpha参数（0.5-1.0） | ||
| 128 | +THRESHOLD1=1 # 交互强度阈值1 | ||
| 129 | +THRESHOLD2=3 # 交互强度阈值2 | ||
| 130 | +THREAD_NUM=4 # 线程数 | ||
| 131 | + | ||
| 132 | +# Python Swing | ||
| 133 | +--lookback_days 730 # 回看天数 | ||
| 134 | +--use_daily_session # 启用日期维度（同时考虑用户整体行为和单日行为） | ||
| 135 | +--time_decay # 启用时间衰减 | ||
| 136 | +--debug # Debug模式 | ||
| 137 | +``` | ||
| 138 | + | ||
| 139 | +#### 1.2 Session Word2Vec | ||
| 140 | + | ||
| 141 | +基于用户会话序列的商品相似度计算，捕捉用户浏览顺序关系。 | ||
| 142 | + | ||
| 143 | +**特点：** | ||
| 144 | +- 基于Word2Vec算法 | ||
| 145 | +- 考虑商品在会话中的顺序 | ||
| 146 | +- 适合"看了又看"场景 | ||
| 147 | + | ||
| 148 | +**参数：** | ||
| 149 | +```bash | ||
| 150 | +python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model | ||
| 151 | +``` | ||
| 152 | + | ||
| 153 | +#### 1.3 DeepWalk | ||
| 154 | + | ||
| 155 | +基于图随机游走的商品相似度计算，发现商品间的深层关系。 | ||
| 156 | + | ||
| 157 | +**特点：** | ||
| 158 | +- 构建商品关系图 | ||
| 159 | +- 随机游走生成序列 | ||
| 160 | +- 发现间接关联 | ||
| 161 | + | ||
| 162 | +**参数：** | ||
| 163 | +```bash | ||
| 164 | +python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph | ||
| 165 | +``` | ||
| 166 | + | ||
| 167 | +#### 1.4 Content-based 内容相似度 | ||
| 168 | + | ||
| 169 | +基于商品属性（分类、供应商等）计算相似度。 | ||
| 170 | + | ||
| 171 | +**三种方法：** | ||
| 172 | +- TF-IDF方法: 基于商品名称文本 | ||
| 173 | +- 分类方法: 基于商品分类层级 | ||
| 174 | +- 混合方法: 综合多种特征（推荐） | ||
| 175 | + | ||
| 176 | +**参数：** | ||
| 177 | +```bash | ||
| 178 | +python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid | ||
| 179 | +``` | ||
| 180 | + | ||
| 181 | +### 2. 兴趣点聚合索引 | ||
| 182 | + | ||
| 183 | +根据不同维度聚合热门商品，支持个性化推荐。 | ||
| 184 | + | ||
| 185 | +#### 支持的维度 | ||
| 186 | + | ||
| 187 | +**单维度（7个）：** | ||
| 188 | +- `platform`: 业务平台（pc, h5, app等） | ||
| 189 | +- `client_platform`: 客户端平台（iOS, Android, Web等） | ||
| 190 | +- `supplier`: 供应商 | ||
| 191 | +- `category_level1`: 一级分类 | ||
| 192 | +- `category_level2`: 二级分类 | ||
| 193 | +- `category_level3`: 三级分类 | ||
| 194 | +- `category_level4`: 四级分类 | ||
| 195 | + | ||
| 196 | +**组合维度（4个）：** | ||
| 197 | +- `platform_client`: 平台+客户端 | ||
| 198 | +- `platform_category2`: 平台+二级分类 | ||
| 199 | +- `platform_category3`: 平台+三级分类 | ||
| 200 | +- `client_category2`: 客户端+二级分类 | ||
| 201 | + | ||
| 202 | +#### 列表类型 | ||
| 203 | + | ||
| 204 | +- **hot**: 热门商品（最近N天高交互） | ||
| 205 | +- **cart**: 加购商品（高加购率） | ||
| 206 | +- **new**: 新品（最近90天上架） | ||
| 207 | +- **global**: 全局热门 | ||
| 208 | + | ||
| 209 | +**参数：** | ||
| 210 | +```bash | ||
| 211 | +python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 | ||
| 212 | +``` | ||
| 213 | + | ||
| 214 | +### 3. 前置任务 | ||
| 215 | + | ||
| 216 | +#### 3.1 商品属性获取 | ||
| 217 | + | ||
| 218 | +**问题**: 多个脚本需要商品名称，重复查询数据库效率低。 | ||
| 219 | + | ||
| 220 | +**解决方案**: 前置任务一次性获取，保存到本地文件。 | ||
| 221 | + | ||
| 222 | +```bash | ||
| 223 | +python3 scripts/fetch_item_attributes.py | ||
| 224 | +``` | ||
| 225 | + | ||
| 226 | +**输出**: | ||
| 227 | +- `output/item_attributes_mappings.json`: 商品ID->名称映射 | ||
| 228 | +- `output/item_attributes_stats.txt`: 统计信息 | ||
| 229 | + | ||
| 230 | +**效果**: 减少80-90%的数据库查询次数 | ||
| 231 | + | ||
| 232 | +#### 3.2 Session文件生成 | ||
| 233 | + | ||
| 234 | +从数据库提取用户行为数据，生成session文件供算法使用。 | ||
| 235 | + | ||
| 236 | +```bash | ||
| 237 | +python3 scripts/generate_session.py --lookback_days 730 --format both | ||
| 238 | +``` | ||
| 239 | + | ||
| 240 | +**输出格式：** | ||
| 241 | +- `session.txt.YYYYMMDD`: 标准格式（包含uid） | ||
| 242 | +- `session.txt.YYYYMMDD.cpp`: C++格式（纯json） | ||
| 243 | + | ||
| 244 | +**行为权重：** | ||
| 245 | +- purchase: 10.0（购买） | ||
| 246 | +- contactFactory: 5.0（联系厂家） | ||
| 247 | +- addToCart: 3.0（加入购物车） | ||
| 248 | +- addToPool: 2.0（加入询价池） | ||
| 249 | + | ||
| 250 | +--- | ||
| 251 | + | ||
| 252 | +## 🚀 使用指南 | ||
| 253 | + | ||
| 254 | +### 快速开始（3步） | ||
| 255 | + | ||
| 256 | +#### 步骤1: 安装依赖 | ||
| 257 | +```bash | ||
| 258 | +cd /home/tw/recommendation/offline_tasks | ||
| 259 | +bash install.sh | ||
| 260 | +``` | ||
| 261 | + | ||
| 262 | +#### 步骤2: 测试连接 | ||
| 263 | +```bash | ||
| 264 | +python3 test_connection.py | ||
| 265 | +``` | ||
| 266 | + | ||
| 267 | +#### 步骤3: 运行任务 | ||
| 268 | +```bash | ||
| 269 | +# 小数据量测试（30天数据） | ||
| 270 | +python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10 | ||
| 271 | + | ||
| 272 | +# 完整任务（推荐使用run.sh） | ||
| 273 | +bash run.sh | ||
| 274 | +``` | ||
| 275 | + | ||
| 276 | +### 运行完整流程 | ||
| 277 | + | ||
| 278 | +**方式1: 使用run.sh（推荐）** | ||
| 279 | +```bash | ||
| 280 | +cd /home/tw/recommendation/offline_tasks | ||
| 281 | +bash run.sh | ||
| 282 | +``` | ||
| 283 | + | ||
| 284 | +这将自动执行： | ||
| 285 | +- 前置任务（商品属性、session生成） | ||
| 286 | +- C++ Swing算法 | ||
| 287 | +- Python算法（Swing、W2V、DeepWalk、内容相似度） | ||
| 288 | +- 兴趣聚合 | ||
| 289 | +- Redis加载 | ||
| 290 | + | ||
| 291 | +**方式2: 使用run_all.py（简化版）** | ||
| 292 | +```bash | ||
| 293 | +python3 run_all.py --debug | ||
| 294 | +``` | ||
| 295 | + | ||
| 296 | +不包括C++ Swing和Redis加载。 | ||
| 297 | + | ||
| 298 | +**方式3: 单独运行任务** | ||
| 299 | +```bash | ||
| 300 | +# 1. 前置任务 | ||
| 301 | +python3 scripts/fetch_item_attributes.py | ||
| 302 | +python3 scripts/generate_session.py --lookback_days 730 | ||
| 303 | + | ||
| 304 | +# 2. C++ Swing | ||
| 305 | +cd collaboration && bash run.sh && cd .. | ||
| 306 | + | ||
| 307 | +# 3. Python算法 | ||
| 308 | +python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug | ||
| 309 | +python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 | ||
| 310 | +python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 | ||
| 311 | +python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid | ||
| 312 | + | ||
| 313 | +# 4. 兴趣聚合 | ||
| 314 | +python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000 | ||
| 315 | + | ||
| 316 | +# 5. 加载到Redis | ||
| 317 | +python3 scripts/load_index_to_redis.py --redis-host localhost | ||
| 318 | +``` | ||
| 319 | + | ||
| 320 | +### 配置说明 | ||
| 321 | + | ||
| 322 | +主要配置在 `config/offline_config.py`： | ||
| 323 | + | ||
| 324 | +```python | ||
| 325 | +# 数据库配置 | ||
| 326 | +DB_CONFIG = { | ||
| 327 | + 'host': 'your_db_host', | ||
| 328 | + 'port': '9030', | ||
| 329 | + 'database': 'datacenter', | ||
| 330 | + 'username': 'readonly', | ||
| 331 | + 'password': 'your_password' | ||
| 332 | +} | ||
| 333 | + | ||
| 334 | +# Redis配置 | ||
| 335 | +REDIS_CONFIG = { | ||
| 336 | + 'host': 'your_redis_host', | ||
| 337 | + 'port': 6379, | ||
| 338 | + 'db': 0, | ||
| 339 | + 'password': None | ||
| 340 | +} | ||
| 341 | + | ||
| 342 | +# 时间配置 | ||
| 343 | +LOOKBACK_DAYS = 730 # 2年数据 | ||
| 344 | + | ||
| 345 | +# 行为权重 | ||
| 346 | +behavior_weights = { | ||
| 347 | + 'click': 1.0, | ||
| 348 | + 'addToCart': 3.0, | ||
| 349 | + 'contactFactory': 5.0, | ||
| 350 | + 'purchase': 10.0 | ||
| 351 | +} | ||
| 352 | + | ||
| 353 | +# 时间衰减 | ||
| 354 | +time_decay_factor = 0.95 # 每30天衰减5% | ||
| 355 | +``` | ||
| 356 | + | ||
| 357 | +### 查看输出结果 | ||
| 358 | + | ||
| 359 | +所有输出文件在 `output/` 目录： | ||
| 360 | + | ||
| 361 | +```bash | ||
| 362 | +cd /home/tw/recommendation/offline_tasks/output | ||
| 363 | +ls -lh | ||
| 364 | + | ||
| 365 | +# 查看i2i相似度 | ||
| 366 | +head -5 i2i_swing_20251016.txt | ||
| 367 | + | ||
| 368 | +# 查看兴趣点聚合 | ||
| 369 | +head -5 interest_aggregation_hot_20251016.txt | ||
| 370 | +``` | ||
| 371 | + | ||
| 372 | +### 查看日志 | ||
| 373 | + | ||
| 374 | +```bash | ||
| 375 | +cd /home/tw/recommendation/offline_tasks/logs | ||
| 376 | + | ||
| 377 | +# 主日志 | ||
| 378 | +tail -f run_all_20251016.log | ||
| 379 | + | ||
| 380 | +# 内存监控日志 | ||
| 381 | +tail -f memory_monitor.log | ||
| 382 | + | ||
| 383 | +# Debug日志 | ||
| 384 | +ls debug/ | ||
| 385 | +``` | ||
| 386 | + | ||
| 387 | +--- | ||
| 388 | + | ||
| 389 | +## 📊 输出数据示例 | ||
| 390 | + | ||
| 391 | +### i2i相似度索引 | ||
| 392 | + | ||
| 393 | +**C++ Swing（高性能版）：** | ||
| 394 | +``` | ||
| 395 | +# 文件: collaboration/output/swing_similar.txt | ||
| 396 | +3600052 2704531:0.00431593,2503886:0.00431593,3371410:0.00431593 | ||
| 397 | + | ||
| 398 | +# 可读版本: collaboration/output/swing_similar_readable.txt | ||
| 399 | +3600052:商品A 2704531:商品B:0.00431593,2503886:商品C:0.00431593 | ||
| 400 | +``` | ||
| 401 | + | ||
| 402 | +**Python Swing：** | ||
| 403 | +``` | ||
| 404 | +# 文件: output/i2i_swing_20251016.txt | ||
| 405 | +12345 商品A 23456:0.8523,34567:0.7842,45678:0.7234 | ||
| 406 | +``` | ||
| 407 | + | ||
| 408 | +### 兴趣点聚合索引 | ||
| 409 | + | ||
| 410 | +``` | ||
| 411 | +# 文件: output/interest_aggregation_hot_20251016.txt | ||
| 412 | +platform:pc 12345,23456,34567,45678,56789 | ||
| 413 | +category_level2:200 45678,56789,67890,78901,89012 | ||
| 414 | +platform_category2:pc_200 12345,23456,34567,45678 | ||
| 415 | +``` | ||
| 416 | + | ||
| 417 | +--- | ||
| 418 | + | ||
| 419 | +## 🎬 业务场景应用 | ||
| 420 | + | ||
| 421 | +### 场景1: 首页猜你喜欢 | ||
| 422 | + | ||
| 423 | +**使用索引：** | ||
| 424 | +```python | ||
| 425 | +# 基于平台 | ||
| 426 | +interest:hot:platform:pc | ||
| 427 | + | ||
| 428 | +# 基于分类偏好 | ||
| 429 | +interest:hot:category_level2:200 | ||
| 430 | + | ||
| 431 | +# 基于平台+分类 | ||
| 432 | +interest:hot:platform_category2:pc_200 | ||
| 433 | +``` | ||
| 434 | + | ||
| 435 | +### 场景2: 详情页相关推荐 | ||
| 436 | + | ||
| 437 | +**使用索引：** | ||
| 438 | +```python | ||
| 439 | +# 行为相似（C++ Swing，生产推荐） | ||
| 440 | +item:similar:swing_cpp:12345 | ||
| 441 | + | ||
| 442 | +# 行为相似（Python Swing） | ||
| 443 | +item:similar:swing:12345 | ||
| 444 | + | ||
| 445 | +# 内容相似 | ||
| 446 | +item:similar:content_hybrid:12345 | ||
| 447 | + | ||
| 448 | +# 融合推荐（多算法） | ||
| 449 | +swing_items = redis.get('item:similar:swing_cpp:12345') | ||
| 450 | +w2v_items = redis.get('item:similar:w2v:12345') | ||
| 451 | +content_items = redis.get('item:similar:content_hybrid:12345') | ||
| 452 | +# 融合多个算法结果... | ||
| 453 | +``` | ||
| 454 | + | ||
| 455 | +### 场景3: 搜索结果页推荐 | ||
| 456 | + | ||
| 457 | +**使用索引：** | ||
| 458 | +```python | ||
| 459 | +# 全局热门 | ||
| 460 | +interest:global:platform:pc | ||
| 461 | + | ||
| 462 | +# 分类相关 | ||
| 463 | +interest:global:category_level2:200 | ||
| 464 | +``` | ||
| 465 | + | ||
| 466 | +### 场景4: 供应商店铺页 | ||
| 467 | + | ||
| 468 | +**使用索引：** | ||
| 469 | +```python | ||
| 470 | +# 供应商热门 | ||
| 471 | +interest:hot:supplier:10001 | ||
| 472 | + | ||
| 473 | +# 供应商新品 | ||
| 474 | +interest:new:supplier:10001 | ||
| 475 | +``` | ||
| 476 | + | ||
| 477 | +--- | ||
| 478 | + | ||
| 479 | +## ⚙️ 参数调优建议 | ||
| 480 | + | ||
| 481 | +### Swing算法参数 | ||
| 482 | + | ||
| 483 | +**alpha (0.5-1.0)** | ||
| 484 | +- 越小：越关注用户共同行为的多样性 | ||
| 485 | +- 越大：越容易忽略用户重叠度 | ||
| 486 | +- B2B场景建议：0.5-0.7 | ||
| 487 | + | ||
| 488 | +**threshold1/threshold2** | ||
| 489 | +- threshold1: 筛选用户有效行为（建议1-3） | ||
| 490 | +- threshold2: 计算相似度阈值（建议3-5） | ||
| 491 | +- B2B低频场景可适当降低 | ||
| 492 | + | ||
| 493 | +**thread_num** | ||
| 494 | +- 根据CPU核心数设置 | ||
| 495 | +- 建议：4-8（普通服务器） | ||
| 496 | + | ||
| 497 | +### 数据范围参数 | ||
| 498 | + | ||
| 499 | +**lookback_days** | ||
| 500 | +- B2B低频场景：建议730天（2年） | ||
| 501 | +- B2C高频场景：建议30-90天 | ||
| 502 | +- 数据量大时可适当减少 | ||
| 503 | + | ||
| 504 | +**top_n** | ||
| 505 | +- i2i相似度：建议10-50 | ||
| 506 | +- 兴趣聚合：建议50-1000 | ||
| 507 | + | ||
| 508 | +--- | ||
| 509 | + | ||
| 510 | +## 🔧 故障排查 | ||
| 511 | + | ||
| 512 | +### 常见问题 | ||
| 513 | + | ||
| 514 | +**Q1: 任务运行时间太长** | ||
| 515 | +- 减少 `--lookback_days` 参数（如改为365天） | ||
| 516 | +- 减少 `--top_n` 参数 | ||
| 517 | +- 在更强大的机器上运行 | ||
| 518 | +- 使用C++ Swing代替Python Swing | ||
| 519 | + | ||
| 520 | +**Q2: 内存不足** | ||
| 521 | +- Swing算法特别消耗内存，可以先跳过 | ||
| 522 | +- 只运行DeepWalk或Session W2V | ||
| 523 | +- 对数据进行采样 | ||
| 524 | +- 调整C++代码中的max_session_list_len和max_sim_list_len | ||
| 525 | + | ||
| 526 | +**Q3: 数据库连接超时** | ||
| 527 | +- 检查数据库配置: `config/offline_config.py` | ||
| 528 | +- 测试连接: `python3 test_connection.py` | ||
| 529 | +- 检查网络和防火墙 | ||
| 530 | +- 增加SQL查询超时时间 | ||
| 531 | + | ||
| 532 | +**Q4: Session文件不存在** | ||
| 533 | +```bash | ||
| 534 | +# 重新生成session文件 | ||
| 535 | +python3 scripts/generate_session.py --lookback_days 730 | ||
| 536 | +``` | ||
| 537 | + | ||
| 538 | +**Q5: 编译失败（C++ Swing）** | ||
| 539 | +```bash | ||
| 540 | +# 检查编译器 | ||
| 541 | +g++ --version | ||
| 542 | + | ||
| 543 | +# 手动编译 | ||
| 544 | +cd collaboration | ||
| 545 | +make clean | ||
| 546 | +make | ||
| 547 | +``` | ||
| 548 | + | ||
| 549 | +**Q6: 结果为空** | ||
| 550 | +- 降低threshold参数 | ||
| 551 | +- 增加lookback_days | ||
| 552 | +- 检查数据量: `wc -l output/session.txt.*` | ||
| 553 | + | ||
| 554 | +### 查看错误日志 | ||
| 555 | + | ||
| 556 | +```bash | ||
| 557 | +# 查看最新日志 | ||
| 558 | +tail -100 logs/run_all_$(date +%Y%m%d).log | ||
| 559 | + | ||
| 560 | +# 查看特定任务日志 | ||
| 561 | +tail -100 logs/debug/i2i_swing_*.log | ||
| 562 | + | ||
| 563 | +# 搜索错误信息 | ||
| 564 | +grep -i "error" logs/run_all_*.log | ||
| 565 | +``` | ||
| 566 | + | ||
| 567 | +--- | ||
| 568 | + | ||
| 569 | +## 📈 性能参考 | ||
| 570 | + | ||
| 571 | +在标准配置（730天数据，top_n=50）下的预估运行时间： | ||
| 572 | + | ||
| 573 | +| 任务 | 数据量 | 预估时间 | 内存占用 | | ||
| 574 | +|------|--------|---------|---------| | ||
| 575 | +| C++ Swing | 100万条行为 | 30-120分钟 | 4-8GB | | ||
| 576 | +| Python Swing | 100万条行为 | 2-4小时 | 4-8GB | | ||
| 577 | +| Session W2V | 100万条行为 | 30-60分钟 | 2-4GB | | ||
| 578 | +| DeepWalk | 100万条行为 | 1-2小时 | 2-4GB | | ||
| 579 | +| 内容相似度 | 5万商品 | 10-30分钟 | 1-2GB | | ||
| 580 | +| 兴趣点聚合 | 100万条行为 | 30-60分钟 | 2-4GB | | ||
| 581 | + | ||
| 582 | +**总计**: 约4-8小时（取决于数据量和机器配置） | ||
| 583 | + | ||
| 584 | +--- | ||
| 585 | + | ||
| 586 | +## 🔄 定时任务设置 | ||
| 587 | + | ||
| 588 | +### 使用crontab | ||
| 589 | + | ||
| 590 | +```bash | ||
| 591 | +# 编辑crontab | ||
| 592 | +crontab -e | ||
| 593 | + | ||
| 594 | +# 每天凌晨2点运行（推荐） | ||
| 595 | +0 2 * * * cd /home/tw/recommendation/offline_tasks && bash run.sh >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 | ||
| 596 | + | ||
| 597 | +# 或者使用Python版本（不含C++ Swing和Redis加载） | ||
| 598 | +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 | ||
| 599 | +``` | ||
| 600 | + | ||
| 601 | +### 分任务调度 | ||
| 602 | + | ||
| 603 | +```bash | ||
| 604 | +# 每天凌晨2点运行i2i算法 | ||
| 605 | +0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_swing.py --lookback_days 730 | ||
| 606 | + | ||
| 607 | +# 每天凌晨4点运行兴趣聚合 | ||
| 608 | +0 4 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/interest_aggregation.py --lookback_days 730 | ||
| 609 | + | ||
| 610 | +# 每周日凌晨3点运行内容相似度（变化慢） | ||
| 611 | +0 3 * * 0 cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_content_similar.py --top_n 50 | ||
| 612 | +``` | ||
| 613 | + | ||
| 614 | +--- | ||
| 615 | + | ||
| 616 | +## 📊 数据量统计 | ||
| 617 | + | ||
| 618 | +### 索引数量估算 | ||
| 619 | + | ||
| 620 | +| 索引类型 | 索引数量 | 单条大小 | 总大小 | 更新频率 | | ||
| 621 | +|---------|---------|---------|--------|---------| | ||
| 622 | +| i2i_swing_cpp | ~50,000 | ~400B | ~20MB | 每天 | | ||
| 623 | +| i2i_swing | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 624 | +| i2i_session_w2v | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 625 | +| i2i_deepwalk | ~50,000 | ~500B | ~25MB | 每天 | | ||
| 626 | +| i2i_content | ~50,000 | ~500B | ~25MB | 每周 | | ||
| 627 | +| interest_hot | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 628 | +| interest_cart | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 629 | +| interest_new | ~5,000 | ~1KB | ~5MB | 每天 | | ||
| 630 | +| interest_global | ~10,000 | ~1KB | ~10MB | 每天 | | ||
| 631 | +| **总计** | **~295,000** | - | **~155MB** | - | | ||
| 632 | + | ||
| 633 | +### Redis内存占用 | ||
| 634 | + | ||
| 635 | +加载到Redis后的内存占用约 **180MB**（包含key开销） | ||
| 636 | + | ||
| 637 | +--- | ||
| 638 | + | ||
| 639 | +## 💡 核心优势 | ||
| 640 | + | ||
| 641 | +### 1. 完整性 | ||
| 642 | +- ✅ 行为相似 + 内容相似 | ||
| 643 | +- ✅ 短期热门 + 长期稳定 | ||
| 644 | +- ✅ 粗粒度 + 细粒度 | ||
| 645 | + | ||
| 646 | +### 2. 灵活性 | ||
| 647 | +- ✅ 支持4级分类查询 | ||
| 648 | +- ✅ 支持供应商维度 | ||
| 649 | +- ✅ 支持多维度组合 | ||
| 650 | + | ||
| 651 | +### 3. 可扩展性 | ||
| 652 | +- ✅ 易于添加新维度 | ||
| 653 | +- ✅ 易于添加新算法 | ||
| 654 | +- ✅ 配置化管理 | ||
| 655 | + | ||
| 656 | +### 4. 高性能 | ||
| 657 | +- ✅ C++ Swing高性能实现 | ||
| 658 | +- ✅ 前置任务减少数据库查询 | ||
| 659 | +- ✅ 多线程并行处理 | ||
| 660 | + | ||
| 661 | +### 5. 实用性 | ||
| 662 | +- ✅ 适配真实B2B数据 | ||
| 663 | +- ✅ 文档完善 | ||
| 664 | +- ✅ 易于维护 | ||
| 665 | + | ||
| 666 | +--- | ||
| 667 | + | ||
| 668 | +## 🎯 关键改进点总结 | ||
| 669 | + | ||
| 670 | +1. **✅ 性能优化**: 前置任务减少80-90%的数据库查询，C++ Swing提升10-100倍性能 | ||
| 671 | +2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离 | ||
| 672 | +3. **✅ 功能增强**: Swing算法支持日期维度，同时考虑用户整体和单日行为 | ||
| 673 | +4. **✅ 集成优化**: C++ Swing集成到统一流程，一键执行 | ||
| 674 | +5. **✅ 文档规范**: 统一管理，清晰索引 | ||
| 675 | +6. **✅ 代码质量**: 统一编码规范，完善错误处理 | ||
| 676 | + | ||
| 677 | +--- | ||
| 678 | + | ||
| 679 | +## 📝 相关文档 | ||
| 680 | + | ||
| 681 | +1. **离线索引数据规范** (`离线索引数据规范.md`) | ||
| 682 | + - 任务输出数据的详细格式说明 | ||
| 683 | + - 文件命名规范 | ||
| 684 | + - 数据质量检查 | ||
| 685 | + | ||
| 686 | +2. **Redis数据规范** (`Redis数据规范.md`) | ||
| 687 | + - Redis Key规范 | ||
| 688 | + - 数据加载流程 | ||
| 689 | + - 查询示例 | ||
| 690 | + | ||
| 691 | +3. **配置文件** (`config/offline_config.py`) | ||
| 692 | + - 数据库配置 | ||
| 693 | + - Redis配置 | ||
| 694 | + - 算法参数 | ||
| 695 | + | ||
| 696 | +--- | ||
| 697 | + | ||
| 698 | +## 📞 联系与支持 | ||
| 699 | + | ||
| 700 | +如有问题，请： | ||
| 701 | +1. 查看本文档的故障排查部分 | ||
| 702 | +2. 查看日志文件: `logs/` | ||
| 703 | +3. 查看相关文档: `doc/离线索引数据规范.md`、`doc/Redis数据规范.md` | ||
| 704 | +4. 联系开发团队 | ||
| 705 | + | ||
| 706 | +--- | ||
| 707 | + | ||
| 708 | +**文档版本**: v1.1 | ||
| 709 | +**最后更新**: 2024-10-17 | ||
| 710 | +**维护者**: 推荐系统团队 | ||
| 711 | + |
offline_tasks/doc/调试指南.md deleted
| @@ -1,332 +0,0 @@ | @@ -1,332 +0,0 @@ | ||
| 1 | -# Debug模式使用指南 | ||
| 2 | - | ||
| 3 | -## 🐛 Debug功能概述 | ||
| 4 | - | ||
| 5 | -Debug模式为所有离线任务提供： | ||
| 6 | -1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度 | ||
| 7 | -2. **明文索引文件** - ID后面带上对应的名称，方便检查效果 | ||
| 8 | -3. **数据采样展示** - 关键步骤的示例数据 | ||
| 9 | -4. **性能统计** - 每个步骤的耗时和资源使用 | ||
| 10 | - | ||
| 11 | -## 🚀 快速开始 | ||
| 12 | - | ||
| 13 | -### 1. 运行单个脚本（Debug模式） | ||
| 14 | - | ||
| 15 | -```bash | ||
| 16 | -cd /home/tw/recommendation/offline_tasks | ||
| 17 | - | ||
| 18 | -# Swing算法 - Debug模式 | ||
| 19 | -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug | ||
| 20 | - | ||
| 21 | -# 兴趣聚合 - Debug模式 | ||
| 22 | -python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug | ||
| 23 | - | ||
| 24 | -# 内容相似 - Debug模式 | ||
| 25 | -python3 scripts/i2i_content_similar.py --top_n 10 --debug | ||
| 26 | -``` | ||
| 27 | - | ||
| 28 | -### 2. 运行所有任务（Debug模式） | ||
| 29 | - | ||
| 30 | -```bash | ||
| 31 | -# 使用debug参数运行所有任务 | ||
| 32 | -python3 run_all.py --lookback_days 7 --top_n 10 --debug | ||
| 33 | -``` | ||
| 34 | - | ||
| 35 | -## 📊 Debug输出说明 | ||
| 36 | - | ||
| 37 | -### A. 日志输出 | ||
| 38 | - | ||
| 39 | -Debug模式下，日志会输出到两个地方： | ||
| 40 | -1. **控制台** - 实时查看进度 | ||
| 41 | -2. **Debug日志文件** - 完整保存 | ||
| 42 | - | ||
| 43 | -日志文件位置： | ||
| 44 | -``` | ||
| 45 | -offline_tasks/logs/debug/i2i_swing_20251016_193000.log | ||
| 46 | -offline_tasks/logs/debug/interest_aggregation_20251016_193500.log | ||
| 47 | -... | ||
| 48 | -``` | ||
| 49 | - | ||
| 50 | -### B. 日志内容示例 | ||
| 51 | - | ||
| 52 | -``` | ||
| 53 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 54 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数: | ||
| 55 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 56 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - alpha: 0.5 | ||
| 57 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - top_n: 10 | ||
| 58 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - lookback_days: 7 | ||
| 59 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - debug: True | ||
| 60 | -2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================ | ||
| 61 | - | ||
| 62 | -2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录 | ||
| 63 | - | ||
| 64 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ | ||
| 65 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息: | ||
| 66 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================ | ||
| 67 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234 | ||
| 68 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5 | ||
| 69 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name'] | ||
| 70 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - | ||
| 71 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型: | ||
| 72 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - user_id: object | ||
| 73 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_id: int64 | ||
| 74 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - event_type: object | ||
| 75 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - create_time: datetime64[ns] | ||
| 76 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - item_name: object | ||
| 77 | - | ||
| 78 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布: | ||
| 79 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToCart: 8520 (55.93%) | ||
| 80 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - contactFactory: 3456 (22.68%) | ||
| 81 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - purchase: 2134 (14.01%) | ||
| 82 | -2025-10-16 19:30:05 - i2i_swing - DEBUG - addToPool: 1124 (7.38%) | ||
| 83 | - | ||
| 84 | -2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345 | ||
| 85 | -2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%) | ||
| 86 | -2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%) | ||
| 87 | -... | ||
| 88 | -``` | ||
| 89 | - | ||
| 90 | -### C. 明文索引文件 | ||
| 91 | - | ||
| 92 | -Debug模式下，每个索引文件都会生成对应的明文文件： | ||
| 93 | - | ||
| 94 | -**原始索引文件** (`output/i2i_swing_20251016.txt`): | ||
| 95 | -``` | ||
| 96 | -12345 香蕉干 67890:0.8567,11223:0.7234,44556:0.6891 | ||
| 97 | -67890 芒果干 12345:0.8567,22334:0.7123,55667:0.6543 | ||
| 98 | -``` | ||
| 99 | - | ||
| 100 | -**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`): | ||
| 101 | -``` | ||
| 102 | -================================================================================ | ||
| 103 | -明文索引文件 | ||
| 104 | -生成时间: 2025-10-16 19:35:00 | ||
| 105 | -描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7) | ||
| 106 | -总索引数: 2345 | ||
| 107 | -================================================================================ | ||
| 108 | - | ||
| 109 | -[1] i2i:swing:12345(香蕉干) | ||
| 110 | --------------------------------------------------------------------------------- | ||
| 111 | - 1. ID:67890(芒果干) - Score:0.8567 | ||
| 112 | - 2. ID:11223(菠萝干) - Score:0.7234 | ||
| 113 | - 3. ID:44556(苹果干) - Score:0.6891 | ||
| 114 | - 4. ID:22334(木瓜干) - Score:0.6234 | ||
| 115 | - 5. ID:55667(草莓干) - Score:0.5891 | ||
| 116 | - | ||
| 117 | -[2] i2i:swing:67890(芒果干) | ||
| 118 | --------------------------------------------------------------------------------- | ||
| 119 | - 1. ID:12345(香蕉干) - Score:0.8567 | ||
| 120 | - 2. ID:22334(木瓜干) - Score:0.7123 | ||
| 121 | - 3. ID:55667(草莓干) - Score:0.6543 | ||
| 122 | - 4. ID:11223(菠萝干) - Score:0.6234 | ||
| 123 | - 5. ID:44556(苹果干) - Score:0.5891 | ||
| 124 | - | ||
| 125 | -... | ||
| 126 | - | ||
| 127 | -================================================================================ | ||
| 128 | -已输出 50/2345 个索引 | ||
| 129 | -================================================================================ | ||
| 130 | -``` | ||
| 131 | - | ||
| 132 | -## 📁 文件结构 | ||
| 133 | - | ||
| 134 | -Debug模式下的文件组织： | ||
| 135 | - | ||
| 136 | -``` | ||
| 137 | -offline_tasks/ | ||
| 138 | -├── output/ | ||
| 139 | -│ ├── i2i_swing_20251016.txt # 原始索引文件 | ||
| 140 | -│ ├── interest_aggregation_hot_20251016.txt | ||
| 141 | -│ └── debug/ # Debug明文文件目录 | ||
| 142 | -│ ├── i2i_swing_20251016_readable.txt # 明文索引 | ||
| 143 | -│ ├── interest_aggregation_hot_20251016_readable.txt | ||
| 144 | -│ └── ... | ||
| 145 | -└── logs/ | ||
| 146 | - ├── run_all_20251016.log # 主日志 | ||
| 147 | - └── debug/ # Debug详细日志目录 | ||
| 148 | - ├── i2i_swing_20251016_193000.log | ||
| 149 | - ├── interest_aggregation_20251016_193500.log | ||
| 150 | - └── ... | ||
| 151 | -``` | ||
| 152 | - | ||
| 153 | -## 🔍 使用场景 | ||
| 154 | - | ||
| 155 | -### 场景1：调试数据流程 | ||
| 156 | - | ||
| 157 | -```bash | ||
| 158 | -# 使用小数据量+debug模式快速验证 | ||
| 159 | -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug | ||
| 160 | - | ||
| 161 | -# 查看日志，检查： | ||
| 162 | -# - 数据加载是否正确 | ||
| 163 | -# - 行为类型分布是否合理 | ||
| 164 | -# - 用户/商品数量是否符合预期 | ||
| 165 | -``` | ||
| 166 | - | ||
| 167 | -### 场景2：检查推荐效果 | ||
| 168 | - | ||
| 169 | -```bash | ||
| 170 | -# 生成明文索引文件 | ||
| 171 | -python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug | ||
| 172 | - | ||
| 173 | -# 打开明文文件查看： | ||
| 174 | -cat output/debug/i2i_swing_20251016_readable.txt | less | ||
| 175 | - | ||
| 176 | -# 检查推荐是否合理，例如： | ||
| 177 | -# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理 | ||
| 178 | -# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数 | ||
| 179 | -``` | ||
| 180 | - | ||
| 181 | -### 场景3：性能调优 | ||
| 182 | - | ||
| 183 | -```bash | ||
| 184 | -# Debug模式查看各步骤耗时 | ||
| 185 | -python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时" | ||
| 186 | - | ||
| 187 | -# 输出示例： | ||
| 188 | -# 步骤1耗时: 2.34秒 | ||
| 189 | -# 步骤2耗时: 15.67秒 <- 瓶颈在这里 | ||
| 190 | -# 步骤3耗时: 1.23秒 | ||
| 191 | -# 总耗时: 19.24秒 | ||
| 192 | -``` | ||
| 193 | - | ||
| 194 | -### 场景4：参数调整 | ||
| 195 | - | ||
| 196 | -```bash | ||
| 197 | -# 测试不同alpha值的效果 | ||
| 198 | -python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1 | ||
| 199 | -python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1 | ||
| 200 | -python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1 | ||
| 201 | - | ||
| 202 | -# 对比明文文件，选择最佳参数 | ||
| 203 | -diff output/debug/i2i_swing_*_readable.txt | ||
| 204 | -``` | ||
| 205 | - | ||
| 206 | -## 💡 最佳实践 | ||
| 207 | - | ||
| 208 | -### 1. 开发调试阶段 | ||
| 209 | - | ||
| 210 | -```bash | ||
| 211 | -# 使用小数据量 + Debug模式 | ||
| 212 | -python3 run_all.py --lookback_days 3 --top_n 10 --debug | ||
| 213 | -``` | ||
| 214 | - | ||
| 215 | -- ✅ 快速验证流程 | ||
| 216 | -- ✅ 详细日志便于排错 | ||
| 217 | -- ✅ 明文文件检查效果 | ||
| 218 | - | ||
| 219 | -### 2. 参数调优阶段 | ||
| 220 | - | ||
| 221 | -```bash | ||
| 222 | -# 中等数据量 + Debug模式 | ||
| 223 | -python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug | ||
| 224 | -``` | ||
| 225 | - | ||
| 226 | -- ✅ 查看数据分布 | ||
| 227 | -- ✅ 评估推荐质量 | ||
| 228 | -- ✅ 调整算法参数 | ||
| 229 | - | ||
| 230 | -### 3. 生产运行阶段 | ||
| 231 | - | ||
| 232 | -```bash | ||
| 233 | -# 大数据量 + 正常模式（不加--debug） | ||
| 234 | -python3 run_all.py --lookback_days 730 --top_n 50 | ||
| 235 | -``` | ||
| 236 | - | ||
| 237 | -- ✅ 高效运行 | ||
| 238 | -- ✅ 只输出必要日志 | ||
| 239 | -- ✅ 节省磁盘空间 | ||
| 240 | - | ||
| 241 | -## 🛠️ Debug工具 | ||
| 242 | - | ||
| 243 | -### 查看实时日志 | ||
| 244 | - | ||
| 245 | -```bash | ||
| 246 | -# 实时查看debug日志 | ||
| 247 | -tail -f logs/debug/i2i_swing_*.log | ||
| 248 | - | ||
| 249 | -# 只看DEBUG级别 | ||
| 250 | -tail -f logs/debug/i2i_swing_*.log | grep "DEBUG" | ||
| 251 | - | ||
| 252 | -# 只看错误 | ||
| 253 | -tail -f logs/debug/i2i_swing_*.log | grep "ERROR" | ||
| 254 | -``` | ||
| 255 | - | ||
| 256 | -### 统计分析 | ||
| 257 | - | ||
| 258 | -```bash | ||
| 259 | -# 统计处理的数据量 | ||
| 260 | -grep "总行数" logs/debug/*.log | ||
| 261 | - | ||
| 262 | -# 统计生成的索引数 | ||
| 263 | -grep "总索引数" output/debug/*_readable.txt | ||
| 264 | - | ||
| 265 | -# 查看性能统计 | ||
| 266 | -grep "耗时" logs/debug/*.log | ||
| 267 | -``` | ||
| 268 | - | ||
| 269 | -### 快速检查 | ||
| 270 | - | ||
| 271 | -```bash | ||
| 272 | -# 检查前10个推荐 | ||
| 273 | -head -50 output/debug/i2i_swing_*_readable.txt | ||
| 274 | - | ||
| 275 | -# 搜索特定商品的推荐 | ||
| 276 | -grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10 | ||
| 277 | - | ||
| 278 | -# 统计推荐数量分布 | ||
| 279 | -grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -## ⚠️ 注意事项 | ||
| 283 | - | ||
| 284 | -1. **磁盘空间** | ||
| 285 | - - Debug日志和明文文件会占用较多空间 | ||
| 286 | - - 建议定期清理：`rm -rf logs/debug/* output/debug/*` | ||
| 287 | - | ||
| 288 | -2. **运行时间** | ||
| 289 | - - Debug模式会增加10-20%的运行时间 | ||
| 290 | - - 生产环境建议关闭debug | ||
| 291 | - | ||
| 292 | -3. **敏感信息** | ||
| 293 | - - 明文文件包含商品名称等信息 | ||
| 294 | - - 注意数据安全和隐私保护 | ||
| 295 | - | ||
| 296 | -4. **文件编码** | ||
| 297 | - - 明文文件使用UTF-8编码 | ||
| 298 | - - 确保查看工具支持中文显示 | ||
| 299 | - | ||
| 300 | -## 📖 相关命令 | ||
| 301 | - | ||
| 302 | -```bash | ||
| 303 | -# 查看帮助 | ||
| 304 | -python3 scripts/i2i_swing.py --help | ||
| 305 | -python3 run_all.py --help | ||
| 306 | - | ||
| 307 | -# 验证配置 | ||
| 308 | -python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)" | ||
| 309 | - | ||
| 310 | -# 测试debug工具 | ||
| 311 | -python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')" | ||
| 312 | -``` | ||
| 313 | - | ||
| 314 | -## ✅ 验证Debug功能 | ||
| 315 | - | ||
| 316 | -```bash | ||
| 317 | -# 快速测试 | ||
| 318 | -cd /home/tw/recommendation/offline_tasks | ||
| 319 | -python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug | ||
| 320 | - | ||
| 321 | -# 应该看到： | ||
| 322 | -# ✓ DEBUG级别日志输出 | ||
| 323 | -# ✓ 创建debug日志文件 | ||
| 324 | -# ✓ 生成明文索引文件 | ||
| 325 | -# ✓ 显示数据统计信息 | ||
| 326 | -``` | ||
| 327 | - | ||
| 328 | ---- | ||
| 329 | - | ||
| 330 | -**Debug模式**: 开发和调试的利器 | ||
| 331 | -**正常模式**: 生产环境的选择 | ||
| 332 | -**灵活切换**: 一个参数的事情 |
offline_tasks/doc/运行脚本指南.md deleted
| @@ -1,304 +0,0 @@ | @@ -1,304 +0,0 @@ | ||
| 1 | -# run.sh 运行脚本使用指南 | ||
| 2 | - | ||
| 3 | -## 概述 | ||
| 4 | - | ||
| 5 | -`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。 | ||
| 6 | - | ||
| 7 | -## 主要特性 | ||
| 8 | - | ||
| 9 | -### 1. 内存监控 | ||
| 10 | -- **警告阈值**: 25GB - 打印警告日志 | ||
| 11 | -- **强制终止阈值**: 30GB - 自动kill进程 | ||
| 12 | -- **检查频率**: 每10秒检查一次 | ||
| 13 | -- **日志文件**: `logs/memory_monitor.log` | ||
| 14 | - | ||
| 15 | -### 2. 任务流程 | ||
| 16 | -1. 清理旧进程和输出 | ||
| 17 | -2. 运行调试模式（小数据量测试） | ||
| 18 | -3. 运行生产模式（大数据量） | ||
| 19 | -4. 加载索引到Redis | ||
| 20 | - | ||
| 21 | -### 3. 错误处理 | ||
| 22 | -- 任何步骤失败会立即退出 | ||
| 23 | -- 显示详细的退出码 | ||
| 24 | -- 保存完整日志 | ||
| 25 | - | ||
| 26 | -## 使用方法 | ||
| 27 | - | ||
| 28 | -### 基本运行 | ||
| 29 | -```bash | ||
| 30 | -cd /home/tw/recommendation/offline_tasks | ||
| 31 | -./run.sh | ||
| 32 | -``` | ||
| 33 | - | ||
| 34 | -### 查看实时输出 | ||
| 35 | -```bash | ||
| 36 | -./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log | ||
| 37 | -``` | ||
| 38 | - | ||
| 39 | -### 后台运行 | ||
| 40 | -```bash | ||
| 41 | -nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 & | ||
| 42 | -``` | ||
| 43 | - | ||
| 44 | -## 内存监控说明 | ||
| 45 | - | ||
| 46 | -### 监控逻辑 | ||
| 47 | - | ||
| 48 | -```bash | ||
| 49 | -check_memory() { | ||
| 50 | - local pid=$1 | ||
| 51 | - local threshold_warn=25 # 25GB警告 | ||
| 52 | - local threshold_kill=30 # 30GB强制kill | ||
| 53 | - | ||
| 54 | - while 进程运行中; do | ||
| 55 | - 获取内存使用 | ||
| 56 | - | ||
| 57 | - if 内存 >= 30GB: | ||
| 58 | - 打印错误日志 | ||
| 59 | - 强制终止进程 | ||
| 60 | - break | ||
| 61 | - elif 内存 >= 25GB: | ||
| 62 | - 打印警告日志 | ||
| 63 | - | ||
| 64 | - sleep 10秒 | ||
| 65 | - done | ||
| 66 | -} | ||
| 67 | -``` | ||
| 68 | - | ||
| 69 | -### 日志格式 | ||
| 70 | - | ||
| 71 | -**警告日志**: | ||
| 72 | -``` | ||
| 73 | -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12345 | ||
| 74 | -``` | ||
| 75 | - | ||
| 76 | -**强制终止日志**: | ||
| 77 | -``` | ||
| 78 | -[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345 | ||
| 79 | -``` | ||
| 80 | - | ||
| 81 | -### 查看监控日志 | ||
| 82 | -```bash | ||
| 83 | -# 实时查看 | ||
| 84 | -tail -f logs/memory_monitor.log | ||
| 85 | - | ||
| 86 | -# 查看历史 | ||
| 87 | -cat logs/memory_monitor.log | ||
| 88 | -``` | ||
| 89 | - | ||
| 90 | -## 运行流程 | ||
| 91 | - | ||
| 92 | -### 步骤1: 调试模式 | ||
| 93 | -```bash | ||
| 94 | -python3 run_all.py --debug | ||
| 95 | -``` | ||
| 96 | -- 使用默认参数（见 `offline_config.py`） | ||
| 97 | -- 输出保存到 `output_debug/` | ||
| 98 | -- 启动内存监控 | ||
| 99 | - | ||
| 100 | -### 步骤2: 生产模式 | ||
| 101 | -```bash | ||
| 102 | -python3 run_all.py --debug | ||
| 103 | -``` | ||
| 104 | -- 生成完整索引 | ||
| 105 | -- 输出保存到 `output/` | ||
| 106 | -- 启动内存监控 | ||
| 107 | - | ||
| 108 | -### 步骤3: 加载Redis | ||
| 109 | -```bash | ||
| 110 | -python3 scripts/load_index_to_redis.py --redis-host localhost | ||
| 111 | -``` | ||
| 112 | -- 加载所有生成的索引 | ||
| 113 | -- 包括新增的内容相似索引 | ||
| 114 | - | ||
| 115 | -## 输出示例 | ||
| 116 | - | ||
| 117 | -``` | ||
| 118 | -====================================================================== | ||
| 119 | -开始运行离线任务 - 2025-10-17 14:00:00 | ||
| 120 | -内存监控: 警告阈值=25GB, 强制终止阈值=30GB | ||
| 121 | -====================================================================== | ||
| 122 | - | ||
| 123 | ->>> 步骤1: 调试模式运行（小数据量） | ||
| 124 | -调试任务 PID: 12345 | ||
| 125 | -✓ 调试模式完成 | ||
| 126 | - | ||
| 127 | ->>> 步骤2: 生产模式运行（大数据量） | ||
| 128 | -生产任务 PID: 12346 | ||
| 129 | -[2025-10-17 14:30:25] ⚠️ 内存警告！当前使用: 26.45GB (>= 25GB), PID=12346 | ||
| 130 | -✓ 生产模式完成 | ||
| 131 | - | ||
| 132 | ->>> 步骤3: 加载到Redis | ||
| 133 | -✓ Redis加载完成 | ||
| 134 | - | ||
| 135 | -====================================================================== | ||
| 136 | -所有任务完成 - 2025-10-17 16:30:00 | ||
| 137 | -====================================================================== | ||
| 138 | -``` | ||
| 139 | - | ||
| 140 | -## 自定义配置 | ||
| 141 | - | ||
| 142 | -### 修改内存阈值 | ||
| 143 | - | ||
| 144 | -编辑 `run.sh` 中的以下行： | ||
| 145 | -```bash | ||
| 146 | -local threshold_warn=25 # 修改警告阈值 | ||
| 147 | -local threshold_kill=30 # 修改强制kill阈值 | ||
| 148 | -``` | ||
| 149 | - | ||
| 150 | -### 修改检查频率 | ||
| 151 | - | ||
| 152 | -编辑 `run.sh` 中的以下行： | ||
| 153 | -```bash | ||
| 154 | -sleep 10 # 修改为其他秒数 | ||
| 155 | -``` | ||
| 156 | - | ||
| 157 | -### 跳过调试模式 | ||
| 158 | - | ||
| 159 | -注释掉步骤1相关代码： | ||
| 160 | -```bash | ||
| 161 | -# # 3. 调试模式运行（小数据量） | ||
| 162 | -# echo "" | ||
| 163 | -# echo ">>> 步骤1: 调试模式运行（小数据量）" | ||
| 164 | -# python3 run_all.py --debug & | ||
| 165 | -# ... | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -### 修改Redis配置 | ||
| 169 | - | ||
| 170 | -修改步骤3的参数： | ||
| 171 | -```bash | ||
| 172 | -python3 scripts/load_index_to_redis.py \ | ||
| 173 | - --redis-host your-redis-host \ | ||
| 174 | - --redis-port 6379 \ | ||
| 175 | - --redis-db 0 | ||
| 176 | -``` | ||
| 177 | - | ||
| 178 | -## 故障排查 | ||
| 179 | - | ||
| 180 | -### 内存持续超限 | ||
| 181 | - | ||
| 182 | -**原因**: | ||
| 183 | -- 数据量太大 | ||
| 184 | -- 内存泄漏 | ||
| 185 | -- 并发任务过多 | ||
| 186 | - | ||
| 187 | -**解决方案**: | ||
| 188 | -1. 增加内存阈值（临时方案） | ||
| 189 | -2. 优化代码减少内存占用 | ||
| 190 | -3. 分批处理数据 | ||
| 191 | -4. 使用增量更新 | ||
| 192 | - | ||
| 193 | -### 进程被意外终止 | ||
| 194 | - | ||
| 195 | -**检查日志**: | ||
| 196 | -```bash | ||
| 197 | -# 查看监控日志 | ||
| 198 | -cat logs/memory_monitor.log | ||
| 199 | - | ||
| 200 | -# 查看任务日志 | ||
| 201 | -ls -lht logs/ | ||
| 202 | -cat logs/run_all_*.log | ||
| 203 | -``` | ||
| 204 | - | ||
| 205 | -### 任务失败 | ||
| 206 | - | ||
| 207 | -**查看退出码**: | ||
| 208 | -- 0: 成功 | ||
| 209 | -- 1: 一般错误 | ||
| 210 | -- 137: 被kill信号终止（可能是内存超限） | ||
| 211 | -- 其他: 查看具体错误信息 | ||
| 212 | - | ||
| 213 | -## 监控建议 | ||
| 214 | - | ||
| 215 | -### 1. 添加系统监控 | ||
| 216 | -```bash | ||
| 217 | -# 安装监控工具 | ||
| 218 | -apt install htop iotop | ||
| 219 | - | ||
| 220 | -# 实时监控 | ||
| 221 | -htop -p $(pgrep -f run_all.py) | ||
| 222 | -``` | ||
| 223 | - | ||
| 224 | -### 2. 设置告警 | ||
| 225 | -```bash | ||
| 226 | -# 配置邮件告警 | ||
| 227 | -if [ $PROD_EXIT_CODE -ne 0 ]; then | ||
| 228 | - echo "任务失败" | mail -s "离线任务告警" admin@example.com | ||
| 229 | -fi | ||
| 230 | -``` | ||
| 231 | - | ||
| 232 | -### 3. 定时任务 | ||
| 233 | -```bash | ||
| 234 | -# 添加到crontab | ||
| 235 | -0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1 | ||
| 236 | -``` | ||
| 237 | - | ||
| 238 | -## 性能优化 | ||
| 239 | - | ||
| 240 | -### 内存优化建议 | ||
| 241 | - | ||
| 242 | -1. **分批处理** | ||
| 243 | - ```python | ||
| 244 | - # 在代码中使用batch处理 | ||
| 245 | - batch_size = 1000 | ||
| 246 | - for i in range(0, len(items), batch_size): | ||
| 247 | - batch = items[i:i+batch_size] | ||
| 248 | - process(batch) | ||
| 249 | - ``` | ||
| 250 | - | ||
| 251 | -2. **及时释放** | ||
| 252 | - ```python | ||
| 253 | - import gc | ||
| 254 | - del large_object | ||
| 255 | - gc.collect() | ||
| 256 | - ``` | ||
| 257 | - | ||
| 258 | -3. **使用生成器** | ||
| 259 | - ```python | ||
| 260 | - def process_items(): | ||
| 261 | - for item in items: | ||
| 262 | - yield process(item) | ||
| 263 | - ``` | ||
| 264 | - | ||
| 265 | -## 日志管理 | ||
| 266 | - | ||
| 267 | -### 日志文件 | ||
| 268 | -- `logs/memory_monitor.log` - 内存监控日志 | ||
| 269 | -- `logs/run_all_YYYYMMDD.log` - 任务运行日志 | ||
| 270 | -- `output/` - 生成的索引文件 | ||
| 271 | -- `output_debug/` - 调试模式输出 | ||
| 272 | - | ||
| 273 | -### 清理旧日志 | ||
| 274 | -```bash | ||
| 275 | -# 保留最近7天 | ||
| 276 | -find logs/ -name "*.log" -mtime +7 -delete | ||
| 277 | - | ||
| 278 | -# 压缩旧日志 | ||
| 279 | -find logs/ -name "*.log" -mtime +3 -exec gzip {} \; | ||
| 280 | -``` | ||
| 281 | - | ||
| 282 | -## 安全注意事项 | ||
| 283 | - | ||
| 284 | -1. **权限**: 确保脚本有执行权限 `chmod +x run.sh` | ||
| 285 | -2. **路径**: 使用绝对路径避免混淆 | ||
| 286 | -3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀 | ||
| 287 | -4. **备份**: 脚本会删除output目录，请提前备份重要数据 | ||
| 288 | - | ||
| 289 | -## 总结 | ||
| 290 | - | ||
| 291 | -`run.sh` 提供了： | ||
| 292 | -- ✅ 自动化运行流程 | ||
| 293 | -- ✅ 内存监控保护 | ||
| 294 | -- ✅ 详细日志记录 | ||
| 295 | -- ✅ 错误处理机制 | ||
| 296 | -- ✅ 进度显示 | ||
| 297 | - | ||
| 298 | -建议在生产环境使用前先在测试环境验证。 | ||
| 299 | - | ||
| 300 | ---- | ||
| 301 | - | ||
| 302 | -**更新时间**: 2025-10-17 | ||
| 303 | -**版本**: v2.0 | ||
| 304 | - |
offline_tasks/doc/项目重构说明-20241017.md deleted
| @@ -1,397 +0,0 @@ | @@ -1,397 +0,0 @@ | ||
| 1 | -# 项目重构说明 - 2024-10-17 | ||
| 2 | - | ||
| 3 | -## ✅ 完成的重构 | ||
| 4 | - | ||
| 5 | -### 1. 目录结构调整 | ||
| 6 | - | ||
| 7 | -**改动**: 将`collaboration`目录移入`offline_tasks` | ||
| 8 | - | ||
| 9 | -**之前**: | ||
| 10 | -``` | ||
| 11 | -recommendation/ | ||
| 12 | -├── offline_tasks/ | ||
| 13 | -│ ├── scripts/ | ||
| 14 | -│ └── ... | ||
| 15 | -└── collaboration/ # 外层目录 | ||
| 16 | - ├── src/ | ||
| 17 | - └── run.sh | ||
| 18 | -``` | ||
| 19 | - | ||
| 20 | -**之后**: | ||
| 21 | -``` | ||
| 22 | -recommendation/ | ||
| 23 | -└── offline_tasks/ | ||
| 24 | - ├── scripts/ | ||
| 25 | - ├── collaboration/ # 移入内部 | ||
| 26 | - │ ├── src/ | ||
| 27 | - │ └── run.sh | ||
| 28 | - └── ... | ||
| 29 | -``` | ||
| 30 | - | ||
| 31 | -**优势**: | ||
| 32 | -- ✅ 统一目录结构，所有离线任务在同一目录 | ||
| 33 | -- ✅ 简化路径配置 | ||
| 34 | -- ✅ 便于统一管理和部署 | ||
| 35 | - | ||
| 36 | ---- | ||
| 37 | - | ||
| 38 | -### 2. 执行脚本简化 | ||
| 39 | - | ||
| 40 | -**改动**: 主执行脚本从`run_all.py`改为`run.sh`，直接调用各个脚本 | ||
| 41 | - | ||
| 42 | -**之前的流程**: | ||
| 43 | -```python | ||
| 44 | -# run_all.py (Python实现) | ||
| 45 | -run_script('fetch_item_attributes.py') | ||
| 46 | -run_script('generate_session.py') | ||
| 47 | -run_cpp_swing() # 调用collaboration/run.sh | ||
| 48 | -run_script('i2i_swing.py') | ||
| 49 | -# ... | ||
| 50 | -``` | ||
| 51 | - | ||
| 52 | -**现在的流程**: | ||
| 53 | -```bash | ||
| 54 | -# run.sh (Shell实现) | ||
| 55 | -python3 scripts/fetch_item_attributes.py | ||
| 56 | -python3 scripts/generate_session.py | ||
| 57 | -cd collaboration && bash run.sh && cd .. | ||
| 58 | -python3 scripts/i2i_swing.py | ||
| 59 | -# ... | ||
| 60 | -``` | ||
| 61 | - | ||
| 62 | -**优势**: | ||
| 63 | -- ✅ 代码更简洁，减少抽象层 | ||
| 64 | -- ✅ 直接调用，易于理解和调试 | ||
| 65 | -- ✅ 内存监控、错误处理更灵活 | ||
| 66 | -- ✅ 配置参数集中在顶部，便于修改 | ||
| 67 | - | ||
| 68 | ---- | ||
| 69 | - | ||
| 70 | -### 3. 路径更新 | ||
| 71 | - | ||
| 72 | -所有相关路径已更新： | ||
| 73 | - | ||
| 74 | -**collaboration/run.sh**: | ||
| 75 | -- `SESSION_DATA_DIR="../offline_tasks/output"` → `"../output"` | ||
| 76 | -- `DEBUG_SCRIPT="../offline_tasks/scripts/..."` → `"../scripts/..."` | ||
| 77 | - | ||
| 78 | -**文档更新**: | ||
| 79 | -- ✅ `README.md` | ||
| 80 | -- ✅ `doc/离线索引数据规范.md` | ||
| 81 | -- ✅ `doc/Redis数据规范.md` | ||
| 82 | -- ✅ `doc/系统改进总结-20241017.md` | ||
| 83 | - | ||
| 84 | ---- | ||
| 85 | - | ||
| 86 | -## 📋 新的项目结构 | ||
| 87 | - | ||
| 88 | -``` | ||
| 89 | -offline_tasks/ | ||
| 90 | -├── scripts/ # Python脚本 | ||
| 91 | -│ ├── fetch_item_attributes.py # 前置：获取商品属性 | ||
| 92 | -│ ├── generate_session.py # 前置：生成session | ||
| 93 | -│ ├── i2i_swing.py # Python Swing | ||
| 94 | -│ ├── i2i_session_w2v.py # Session W2V | ||
| 95 | -│ ├── i2i_deepwalk.py # DeepWalk | ||
| 96 | -│ ├── i2i_content_similar.py # 内容相似度 | ||
| 97 | -│ ├── interest_aggregation.py # 兴趣聚合 | ||
| 98 | -│ ├── load_index_to_redis.py # 加载到Redis | ||
| 99 | -│ ├── add_names_to_swing.py # 添加商品名 | ||
| 100 | -│ └── debug_utils.py # Debug工具 | ||
| 101 | -├── collaboration/ # C++ Swing算法 | ||
| 102 | -│ ├── src/ | ||
| 103 | -│ │ ├── swing.cc # Swing实现 | ||
| 104 | -│ │ ├── swing_symmetric.cc # 对称Swing | ||
| 105 | -│ │ ├── icf_simple.cc # 简单协同 | ||
| 106 | -│ │ └── ucf.py # 用户协同 | ||
| 107 | -│ ├── bin/ # 编译后的二进制 | ||
| 108 | -│ ├── include/ # 头文件 | ||
| 109 | -│ ├── utils/ # 工具函数 | ||
| 110 | -│ ├── run.sh # C++ Swing执行脚本 | ||
| 111 | -│ ├── Makefile # 编译配置 | ||
| 112 | -│ └── output/ # 输出目录 | ||
| 113 | -├── config/ | ||
| 114 | -│ └── offline_config.py # 配置文件 | ||
| 115 | -├── doc/ # 文档中心 | ||
| 116 | -│ ├── README.md | ||
| 117 | -│ ├── 快速开始.md | ||
| 118 | -│ ├── Swing算法使用指南.md | ||
| 119 | -│ ├── 离线索引数据规范.md | ||
| 120 | -│ ├── Redis数据规范.md | ||
| 121 | -│ └── ... | ||
| 122 | -├── output/ # 输出文件 | ||
| 123 | -│ ├── item_attributes_mappings.json | ||
| 124 | -│ ├── session.txt.* | ||
| 125 | -│ └── *.txt | ||
| 126 | -├── logs/ # 日志文件 | ||
| 127 | -├── run.sh # ⭐ 主执行脚本（推荐） | ||
| 128 | -├── run_all.py # Python版本（保留但简化） | ||
| 129 | -└── README.md | ||
| 130 | -``` | ||
| 131 | - | ||
| 132 | ---- | ||
| 133 | - | ||
| 134 | -## 🚀 使用方式 | ||
| 135 | - | ||
| 136 | -### 主要方式：run.sh（推荐） | ||
| 137 | - | ||
| 138 | -```bash | ||
| 139 | -cd /home/tw/recommendation/offline_tasks | ||
| 140 | - | ||
| 141 | -# 直接运行（使用默认配置） | ||
| 142 | -bash run.sh | ||
| 143 | - | ||
| 144 | -# 修改配置后运行 | ||
| 145 | -# 编辑 run.sh 顶部的配置区域 | ||
| 146 | -vim run.sh | ||
| 147 | - | ||
| 148 | -# 查看帮助 | ||
| 149 | -cat run.sh | head -40 # 查看配置说明 | ||
| 150 | -``` | ||
| 151 | - | ||
| 152 | -**run.sh配置项**: | ||
| 153 | -```bash | ||
| 154 | -# 算法参数 | ||
| 155 | -LOOKBACK_DAYS=730 | ||
| 156 | -TOP_N=50 | ||
| 157 | -DEBUG_MODE="--debug" # 留空则不开启debug | ||
| 158 | - | ||
| 159 | -# Redis配置 | ||
| 160 | -REDIS_HOST="localhost" | ||
| 161 | -REDIS_PORT=6379 | ||
| 162 | - | ||
| 163 | -# 内存监控阈值 | ||
| 164 | -MEM_WARN_THRESHOLD=25 # GB | ||
| 165 | -MEM_KILL_THRESHOLD=35 # GB | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | -### 备用方式：run_all.py（简化版） | ||
| 169 | - | ||
| 170 | -```bash | ||
| 171 | -cd /home/tw/recommendation/offline_tasks | ||
| 172 | - | ||
| 173 | -# 运行（不包括C++ Swing和Redis加载） | ||
| 174 | -python3 run_all.py --debug | ||
| 175 | -``` | ||
| 176 | - | ||
| 177 | -**注意**: `run_all.py`已简化，只包含： | ||
| 178 | -- 前置任务（商品属性、session） | ||
| 179 | -- Python算法任务（Swing、W2V、DeepWalk等） | ||
| 180 | -- 不包括C++ Swing和Redis加载 | ||
| 181 | - | ||
| 182 | ---- | ||
| 183 | - | ||
| 184 | -## 📊 执行流程对比 | ||
| 185 | - | ||
| 186 | -### run.sh（完整流程） | ||
| 187 | - | ||
| 188 | -``` | ||
| 189 | -1. 环境准备 | ||
| 190 | - ├─ 清理旧进程 | ||
| 191 | - └─ 创建必要目录 | ||
| 192 | - | ||
| 193 | -2. 前置任务 | ||
| 194 | - ├─ fetch_item_attributes.py → 商品属性映射 | ||
| 195 | - ├─ generate_session.py → 用户session | ||
| 196 | - └─ collaboration/run.sh → C++ Swing (高性能) | ||
| 197 | - | ||
| 198 | -3. i2i算法任务 | ||
| 199 | - ├─ i2i_swing.py → Python Swing (日期维度) | ||
| 200 | - ├─ i2i_session_w2v.py → Session W2V | ||
| 201 | - ├─ i2i_deepwalk.py → DeepWalk | ||
| 202 | - └─ i2i_content_similar.py → 内容相似度 | ||
| 203 | - | ||
| 204 | -4. 兴趣聚合 | ||
| 205 | - └─ interest_aggregation.py → 多维度聚合 | ||
| 206 | - | ||
| 207 | -5. 加载Redis | ||
| 208 | - └─ load_index_to_redis.py → 导入Redis | ||
| 209 | - | ||
| 210 | -6. 完成 | ||
| 211 | - └─ 输出结果文件列表 | ||
| 212 | -``` | ||
| 213 | - | ||
| 214 | -### run_all.py（简化流程） | ||
| 215 | - | ||
| 216 | -``` | ||
| 217 | -1. 前置任务 | ||
| 218 | - ├─ fetch_item_attributes.py | ||
| 219 | - └─ generate_session.py | ||
| 220 | - | ||
| 221 | -2. i2i算法任务 | ||
| 222 | - ├─ i2i_swing.py | ||
| 223 | - ├─ i2i_session_w2v.py | ||
| 224 | - ├─ i2i_deepwalk.py | ||
| 225 | - └─ i2i_content_similar.py | ||
| 226 | - | ||
| 227 | -3. 兴趣聚合 | ||
| 228 | - └─ interest_aggregation.py | ||
| 229 | -``` | ||
| 230 | - | ||
| 231 | ---- | ||
| 232 | - | ||
| 233 | -## 💡 关键改进 | ||
| 234 | - | ||
| 235 | -### 1. 代码简化 | ||
| 236 | - | ||
| 237 | -**删除的冗余代码**: | ||
| 238 | -- `run_all.py`中的`run_cpp_swing()`函数（45行） | ||
| 239 | -- 复杂的子进程调用和错误处理 | ||
| 240 | - | ||
| 241 | -**简化效果**: | ||
| 242 | -- run.sh: 直接调用，清晰明了 | ||
| 243 | -- run_all.py: 从270行简化到211行 | ||
| 244 | - | ||
| 245 | -### 2. 灵活性提升 | ||
| 246 | - | ||
| 247 | -**run.sh的优势**: | ||
| 248 | -```bash | ||
| 249 | -# 内存监控（自动） | ||
| 250 | -check_memory $pid "$task_name" & | ||
| 251 | - | ||
| 252 | -# 任务函数（统一） | ||
| 253 | -run_task "任务名" "python3 scripts/xxx.py" | ||
| 254 | - | ||
| 255 | -# 配置集中（顶部） | ||
| 256 | -LOOKBACK_DAYS=730 | ||
| 257 | -DEBUG_MODE="--debug" | ||
| 258 | -``` | ||
| 259 | - | ||
| 260 | -### 3. 错误处理 | ||
| 261 | - | ||
| 262 | -**之前**: | ||
| 263 | -- Python捕获异常，日志分散 | ||
| 264 | -- 失败后需要手动排查 | ||
| 265 | - | ||
| 266 | -**现在**: | ||
| 267 | -- Shell直接显示错误 | ||
| 268 | -- 内存监控自动处理OOM | ||
| 269 | -- 任务失败继续执行后续任务 | ||
| 270 | - | ||
| 271 | ---- | ||
| 272 | - | ||
| 273 | -## 🔧 常见操作 | ||
| 274 | - | ||
| 275 | -### 修改算法参数 | ||
| 276 | - | ||
| 277 | -```bash | ||
| 278 | -# 编辑 run.sh | ||
| 279 | -vim run.sh | ||
| 280 | - | ||
| 281 | -# 修改这些参数 | ||
| 282 | -LOOKBACK_DAYS=365 # 回看天数 | ||
| 283 | -TOP_N=100 # 推荐数量 | ||
| 284 | -DEBUG_MODE="" # 关闭debug | ||
| 285 | -``` | ||
| 286 | - | ||
| 287 | -### 只运行特定任务 | ||
| 288 | - | ||
| 289 | -```bash | ||
| 290 | -cd /home/tw/recommendation/offline_tasks | ||
| 291 | - | ||
| 292 | -# 只运行C++ Swing | ||
| 293 | -cd collaboration && bash run.sh && cd .. | ||
| 294 | - | ||
| 295 | -# 只运行Python Swing | ||
| 296 | -python3 scripts/i2i_swing.py --lookback_days 730 --debug | ||
| 297 | - | ||
| 298 | -# 只加载Redis | ||
| 299 | -python3 scripts/load_index_to_redis.py --redis-host localhost | ||
| 300 | -``` | ||
| 301 | - | ||
| 302 | -### 查看日志 | ||
| 303 | - | ||
| 304 | -```bash | ||
| 305 | -# 主日志 | ||
| 306 | -tail -f logs/run_all_$(date +%Y%m%d).log | ||
| 307 | - | ||
| 308 | -# 内存监控日志 | ||
| 309 | -tail -f logs/memory_monitor.log | ||
| 310 | - | ||
| 311 | -# Debug日志 | ||
| 312 | -ls logs/debug/ | ||
| 313 | -``` | ||
| 314 | - | ||
| 315 | ---- | ||
| 316 | - | ||
| 317 | -## 📝 迁移指南 | ||
| 318 | - | ||
| 319 | -如果你之前使用`python3 run_all.py`，现在改用`bash run.sh`： | ||
| 320 | - | ||
| 321 | -### 命令对应关系 | ||
| 322 | - | ||
| 323 | -| 之前 | 现在 | 说明 | | ||
| 324 | -|------|------|------| | ||
| 325 | -| `python3 run_all.py` | `bash run.sh` | 完整流程 | | ||
| 326 | -| `python3 run_all.py --debug` | `bash run.sh` | run.sh默认开启debug | | ||
| 327 | -| 无对应命令 | `bash run.sh` | 现在包含Redis加载 | | ||
| 328 | - | ||
| 329 | -### 定时任务更新 | ||
| 330 | - | ||
| 331 | -**旧的crontab**: | ||
| 332 | -```cron | ||
| 333 | -0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py | ||
| 334 | -``` | ||
| 335 | - | ||
| 336 | -**新的crontab**: | ||
| 337 | -```cron | ||
| 338 | -0 3 * * * cd /home/tw/recommendation/offline_tasks && bash run.sh >> logs/cron_$(date +\%Y\%m\%d).log 2>&1 | ||
| 339 | -``` | ||
| 340 | - | ||
| 341 | ---- | ||
| 342 | - | ||
| 343 | -## ⚠️ 注意事项 | ||
| 344 | - | ||
| 345 | -1. **路径依赖**: | ||
| 346 | - - 确保在`offline_tasks`目录下执行`bash run.sh` | ||
| 347 | - - 不要在其他目录执行 | ||
| 348 | - | ||
| 349 | -2. **内存监控**: | ||
| 350 | - - 默认阈值：警告25GB，终止35GB | ||
| 351 | - - 根据服务器配置调整`MEM_WARN_THRESHOLD`和`MEM_KILL_THRESHOLD` | ||
| 352 | - | ||
| 353 | -3. **并行执行**: | ||
| 354 | - - 不建议同时运行多个`run.sh`实例 | ||
| 355 | - - 脚本会自动清理旧进程 | ||
| 356 | - | ||
| 357 | -4. **失败处理**: | ||
| 358 | - - 单个任务失败不会终止整体流程 | ||
| 359 | - - 查看日志确认失败原因 | ||
| 360 | - | ||
| 361 | ---- | ||
| 362 | - | ||
| 363 | -## 🎯 总结 | ||
| 364 | - | ||
| 365 | -### 改进前后对比 | ||
| 366 | - | ||
| 367 | -| 方面 | 改进前 | 改进后 | | ||
| 368 | -|------|--------|--------| | ||
| 369 | -| **目录结构** | collaboration在外层 | 统一在offline_tasks内 | | ||
| 370 | -| **主执行脚本** | run_all.py (Python) | run.sh (Shell) | | ||
| 371 | -| **代码复杂度** | 270行，多层抽象 | 214行，直接调用 | | ||
| 372 | -| **配置方式** | 参数分散 | 集中在顶部 | | ||
| 373 | -| **内存监控** | 无 | 自动监控+自动终止 | | ||
| 374 | -| **错误处理** | Python异常捕获 | Shell直接显示 | | ||
| 375 | -| **包含任务** | 不含Redis加载 | 含完整流程 | | ||
| 376 | - | ||
| 377 | -### 核心改进 | ||
| 378 | - | ||
| 379 | -1. ✅ **结构简化**: collaboration目录移入，统一管理 | ||
| 380 | -2. ✅ **代码简化**: 去除冗余抽象，直接调用脚本 | ||
| 381 | -3. ✅ **功能增强**: 添加内存监控、统一任务管理 | ||
| 382 | -4. ✅ **易用性**: 配置集中、日志清晰、错误明确 | ||
| 383 | - | ||
| 384 | ---- | ||
| 385 | - | ||
| 386 | -## 📚 相关文档 | ||
| 387 | - | ||
| 388 | -- [快速开始](./快速开始.md) | ||
| 389 | -- [运行脚本指南](./运行脚本指南.md) | ||
| 390 | -- [故障排查指南](./故障排查指南.md) | ||
| 391 | -- [系统改进总结](./系统改进总结-20241017.md) | ||
| 392 | - | ||
| 393 | ---- | ||
| 394 | - | ||
| 395 | -**更新时间**: 2024-10-17 | ||
| 396 | -**状态**: ✅ 已完成并测试 | ||
| 397 | - |