offline tasks: mem optimize

tangwang
1 parent 5b61955e
Showing 45 changed files with 3338 additions and 4079 deletions Show diff stats
offline_tasks/B2B_LOW_FREQUENCY_OPTIMIZATION.md
offline_tasks/CHANGES_SUMMARY.md
offline_tasks/CONTENT_SIMILARITY_UPDATE.md
offline_tasks/CURRENT_STATUS.md
offline_tasks/DELIVERY.md
offline_tasks/FIELD_MAPPING.md
offline_tasks/FINAL_SUMMARY.md
offline_tasks/FINAL_UPDATE.md
offline_tasks/FIX_NAME_MAPPING.md
offline_tasks/LATEST_UPDATES.md
offline_tasks/MEMORY_MONITORING_UPDATE.md
offline_tasks/PROJECT_SUMMARY.md
offline_tasks/QUICKSTART_NEW.md
offline_tasks/QUICK_DEBUG_SUMMARY.md
offline_tasks/STRUCTURE.md
offline_tasks/UPDATE_CONFIG_GUIDE.md
offline_tasks/config/offline_config.py
offline_tasks/COMPLETE_INDEX_LIST.md -> offline_tasks/doc/COMPLETE_INDEX_LIST.md
offline_tasks/DATABASE_SETUP.md -> offline_tasks/doc/DATABASE_SETUP.md
offline_tasks/DEBUG_GUIDE.md -> offline_tasks/doc/DEBUG_GUIDE.md
@@ -1,223 +0,0 @@
-# B2B低频场景优化总结
-
-## 📋 优化背景
-
-B2B场景的特点：
-- ✅ 用户行为频次**非常低**
-- ✅ 行为间隔时间**可能很长**
-- ✅ 历史行为**依然重要**，不应过度衰减
-
-## ✅ 已完成的优化
-
-### 1. **i2i_session_w2v.py** - Session分割策略优化
-
-#### 修改前（基于时间间隔）
-```python
-# 问题：B2B场景下，用户可能几个月才有一次行为
-# 基于30分钟间隔分割session不合适
-session_gap_minutes = 30
-if (current_time - last_time).total_seconds() / 60 > session_gap_minutes:
-    # 新session
-```
-
-#### 修改后（固定长度分块）
-```python
-# 参考: graphembedding/session_w2v/prepare_data.py
-# 按固定长度分块，不考虑时间间隔
-max_session_length = 50  # 最大会话长度
-min_session_length = 2   # 最小会话长度
-
-# 按用户行为序列分块
-user_sessions = [
-    item_sequence[i:i + max_session_length] 
-    for i in range(0, len(item_sequence), max_session_length)
-]
-```
-
-**优势：**
-- 不依赖时间间隔，适合低频场景
-- 逻辑简化，性能更好
-- 保留用户行为的顺序信息
-
-**新增参数：**
-```bash
---max_session_length 50   # 最大会话长度
---min_session_length 2    # 最小会话长度（过滤太短的序列）
-```
-
----
-
-### 2. **i2i_swing.py** - 关闭时间衰减
-
-#### 修改前
-```python
---time_decay  # 默认True，开启时间衰减
-# 30天前权重: 0.95
-# 60天前权重: 0.90
-# 180天前权重: 0.74 (衰减过快)
-```
-
-#### 修改后
-```python
---time_decay  # 默认False，关闭时间衰减
-# 所有历史行为权重相同，更适合低频场景
-```
-
-**原因：**
-在B2B低频场景下，6个月前的行为可能依然很有价值，不应该被大幅衰减。
-
----
-
-### 3. **interest_aggregation.py** - 关闭时间衰减
-
-#### 修改内容
-```python
-# 热门商品索引 - 关闭时间衰减
-list_type_indices['hot'] = aggregate_by_dimensions(
-    df_hot, behavior_weights, time_decay=False  # 改为False
-)
-
-# 加购商品索引 - 关闭时间衰减
-list_type_indices['cart'] = aggregate_by_dimensions(
-    df_cart, behavior_weights, time_decay=False  # 改为False
-)
-
-# 全局索引 - 关闭时间衰减
-global_aggregations = aggregate_by_dimensions(
-    df, behavior_weights, time_decay=False  # 改为False
-)
-
-# 新品索引 - 本来就不用时间衰减（保持不变）
-list_type_indices['new'] = aggregate_by_dimensions(
-    df_new, behavior_weights, time_decay=False
-)
-```
-
----
-
-## 🚀 使用方法
-
-### Session W2V（已自动优化）
-```bash
-# 使用新的固定长度分块策略
-python3 scripts/i2i_session_w2v.py \
-    --lookback_days 365 \
-    --max_session_length 50 \
-    --min_session_length 2 \
-    --top_n 50 \
-    --debug
-```
-
-### Swing算法（默认已关闭时间衰减）
-```bash
-# 默认不使用时间衰减，适合B2B场景
-python3 scripts/i2i_swing.py \
-    --lookback_days 365 \
-    --top_n 50 \
-    --debug
-
-# 如果需要开启时间衰减（不推荐）
-python3 scripts/i2i_swing.py \
-    --lookback_days 365 \
-    --time_decay \
-    --decay_factor 0.99  # 更缓慢的衰减
-```
-
-### 兴趣聚合（已自动优化）
-```bash
-# 已默认关闭时间衰减
-python3 scripts/interest_aggregation.py \
-    --lookback_days 365 \
-    --top_n 100 \
-    --debug
-```
-
-### 运行所有任务
-```bash
-cd /home/tw/recommendation/offline_tasks
-
-# 使用更长的回溯天数，适合低频场景
-python3 run_all.py --lookback_days 365 --top_n 50 --debug
-```
-
----
-
-## 📊 其他索引（无需修改）
-
-### i2i_deepwalk.py
-- ✅ 不涉及session分割
-- ✅ 不使用时间衰减
-- ✅ 无需修改
-
-### i2i_content_similar.py
-- ✅ 基于商品属性的相似度
-- ✅ 不涉及时间因素
-- ✅ 无需修改
-
----
-
-## 💡 建议的配置调整
-
-### 1. 增加回溯天数
-```python
-# offline_tasks/config/offline_config.py
-DEFAULT_LOOKBACK_DAYS = 365  # 从默认值改为365天
-```
-
-### 2. 如果需要重新启用时间衰减（特殊场景）
-```bash
-# Swing算法
-python3 scripts/i2i_swing.py --time_decay --decay_factor 0.99
-
-# 修改interest_aggregation.py中的hard-coded值
-# 将 time_decay=False 改回 time_decay=True
-```
-
----
-
-## ✨ 优化效果
-
-### 预期改进
-1. **Session W2V**: 
-   - 不再因为时间间隔过长而丢失用户行为序列
-   - 能够更好地捕捉低频用户的行为模式
-
-2. **Swing算法**:
-   - 历史行为不会因时间衰减而被低估
-   - 在数据稀疏的情况下充分利用所有历史数据
-
-3. **兴趣聚合**:
-   - 长期累积的用户偏好得到保留
-   - 推荐结果更稳定
-
-### 需要监控的指标
-- [ ] Session数量变化
-- [ ] 相似物品覆盖率
-- [ ] 推荐效果指标（CTR、转化率等）
-
----
-
-## 📝 回滚方法
-
-如果需要恢复之前的逻辑：
-
-```bash
-# 1. 恢复i2i_swing.py的时间衰减
-git diff offline_tasks/scripts/i2i_swing.py
-# 将 default=False 改回 default=True
-
-# 2. 恢复interest_aggregation.py的时间衰减  
-git diff offline_tasks/scripts/interest_aggregation.py
-# 将所有 time_decay=False 改回 time_decay=True
-
-# 3. 恢复i2i_session_w2v.py的时间分割
-git diff offline_tasks/scripts/i2i_session_w2v.py
-# 恢复基于时间间隔的session分割逻辑
-```
-
----
-
-**修改时间**: 2025-10-16  
-**适用场景**: B2B低频交易场景  
-**核心原则**: 在低频场景下，所有历史数据都很宝贵，不要过度衰减
-
@@ -1,326 +0,0 @@
-# 离线任务更新总结
-
-## 更新日期
-2025-10-17
-
-## 更新内容
-
-### 1. 重构内容相似索引 (`i2i_content_similar.py`)
-
-#### 变化
-- **从**: 基于数据库商品属性计算（TF-IDF + 余弦相似度）
-- **到**: 基于Elasticsearch向量计算（KNN查询）
-
-#### 简化
-- **移除**: 所有命令行参数（`--method`, `--top_n`, `--output`, `--debug`）
-- **保留**: 无参数，配置内置在代码中
-- **生成**: 两份索引文件（名称向量 + 图片向量）
-
-### 2. 简化运行脚本 (`run_all.py`)
-
-#### 移除的参数
-- `--skip-i2i` - 跳过i2i任务
-- `--skip-interest` - 跳过兴趣聚合
-- `--only-swing` - 只运行Swing
-- `--only-w2v` - 只运行W2V
-- `--only-deepwalk` - 只运行DeepWalk
-- `--only-content` - 只运行内容相似
-- `--only-interest` - 只运行兴趣聚合
-- `--lookback_days` - 回看天数
-- `--top_n` - Top N数量
-
-#### 保留的参数
-- `--debug` - 调试模式（唯一参数）
-
-#### 使用
-```bash
-# 之前
-python run_all.py --lookback_days 30 --top_n 50 --skip-interest
-
-# 现在
-python run_all.py
-# 或者
-python run_all.py --debug
-```
-
-### 3. 更新Redis数据规范 (`REDIS_DATA_SPEC.md`)
-
-#### 新增索引
-- `i2i_content_name`: 基于名称向量的相似索引
-- `i2i_content_pic`: 基于图片向量的相似索引
-
-#### 更新统计
-- Key数量: 245,000 → 270,000
-- 总内存: ~135MB → ~160MB
-
-### 4. 更新索引加载器 (`load_index_to_redis.py`)
-
-#### 更新
-- 添加 `content_name` 到i2i索引类型列表
-- 添加 `content_pic` 到i2i索引类型列表
-- 自动加载两个新的内容相似索引
-
-### 5. 更新依赖 (`requirements.txt`)
-
-#### 新增
-```
-elasticsearch>=8.0.0
-```
-
-### 6. 新增文档
-
-#### ES向量相似度说明 (`ES_VECTOR_SIMILARITY.md`)
-- ES配置说明
-- 工作流程详解
-- 性能说明和优化建议
-- 故障排查指南
-
-#### 更新说明 (`CONTENT_SIMILARITY_UPDATE.md`)
-- 更新概述
-- 主要变化
-- 使用指南
-- 技术细节
-- 性能说明
-- 与其他算法对比
-
-#### 本文档 (`CHANGES_SUMMARY.md`)
-- 所有变更的简要总结
-
-### 7. 新增测试脚本 (`test_es_connection.py`)
-
-测试ES连接和向量查询功能：
-- 测试ES连接
-- 测试索引是否存在
-- 测试向量字段映射
-- 测试查询商品向量
-- 测试KNN向量查询
-
-## 文件清单
-
-### 修改的文件
-1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写
-2. ✅ `offline_tasks/run_all.py` - 简化参数
-3. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 更新规范
-4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 添加新索引类型
-5. ✅ `requirements.txt` - 添加elasticsearch依赖
-
-### 新增的文件
-6. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - ES向量说明
-7. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 更新说明
-8. ✅ `offline_tasks/CHANGES_SUMMARY.md` - 本文档
-9. ✅ `offline_tasks/scripts/test_es_connection.py` - ES测试脚本
-
-## 使用指南
-
-### 1. 安装依赖
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. 测试ES连接
-
-```bash
-cd /home/tw/recommendation/offline_tasks
-python scripts/test_es_connection.py
-```
-
-### 3. 运行内容相似索引生成
-
-```bash
-# 单独运行
-python scripts/i2i_content_similar.py
-
-# 或通过run_all运行所有任务
-python run_all.py
-```
-
-### 4. 加载到Redis
-
-```bash
-python scripts/load_index_to_redis.py
-```
-
-## 输出文件
-
-### 新增的输出文件
-- `output/i2i_content_name_YYYYMMDD.txt` - 名称向量相似索引
-- `output/i2i_content_pic_YYYYMMDD.txt` - 图片向量相似索引
-
-### 文件格式
-```
-item_id \t item_name \t similar_id1:score1,similar_id2:score2,...
-```
-
-### 示例
-```
-3302275    香蕉干    3302276:0.9234,3302277:0.8756,3302278:0.8432
-```
-
-## Redis Keys
-
-### 新增的Key格式
-```
-item:similar:content_name:{item_id}
-item:similar:content_pic:{item_id}
-```
-
-### Value格式
-```json
-[[similar_id1,score1],[similar_id2,score2],...]
-```
-
-### 查询示例
-```python
-import redis
-import json
-
-r = redis.Redis(host='localhost', port=6379, db=0)
-
-# 名称向量相似
-similar = json.loads(r.get('item:similar:content_name:3302275'))
-# 返回: [[3302276, 0.9234], [3302277, 0.8756], ...]
-
-# 图片向量相似
-similar = json.loads(r.get('item:similar:content_pic:3302275'))
-# 返回: [[4503826, 0.8123], [4503827, 0.7856], ...]
-```
-
-## 性能指标
-
-### 内容相似索引生成
-- 活跃商品: ~50,000
-- 运行时间: 50-60分钟
-- 内存占用: < 2GB
-
-### Redis存储
-- 新增Keys: ~100,000 (两份索引各50,000)
-- 新增内存: ~50MB
-- TTL: 30天
-
-## 兼容性
-
-### 向后兼容
-- ✅ 其他i2i算法（Swing, W2V, DeepWalk）不受影响
-- ✅ 兴趣聚合算法不受影响
-- ✅ Redis加载器向后兼容
-- ✅ 在线查询API不受影响
-
-### 不兼容的变化
-- ❌ `i2i_content_similar.py` 命令行参数全部改变
-- ❌ 旧的 `i2i_content_hybrid_*.txt` 文件不再生成
-
-## 迁移指南
-
-### 如果之前使用了内容相似索引
-
-1. **更新脚本调用**
-   ```bash
-   # 旧版本
-   python i2i_content_similar.py --top_n 50 --method hybrid
-   
-   # 新版本
-   python i2i_content_similar.py  # 无需参数
-   ```
-
-2. **更新Redis Key**
-   ```python
-   # 旧版本
-   r.get('item:similar:content:{item_id}')
-   
-   # 新版本（两个选择）
-   r.get('item:similar:content_name:{item_id}')  # 名称相似
-   r.get('item:similar:content_pic:{item_id}')   # 图片相似
-   ```
-
-3. **更新在线API**
-   - 如果API使用了 `content` 算法，需要更新为 `content_name` 或 `content_pic`
-   - 建议支持两种算法，让前端选择或混合使用
-
-## 技术栈
-
-### 新增技术
-- **Elasticsearch**: 向量存储和KNN查询
-- **KNN算法**: 基于向量的相似度计算
-
-### ES配置
-```python
-ES_CONFIG = {
-    'host': 'http://localhost:9200',
-    'index_name': 'spu',
-    'username': 'essa',
-    'password': '4hOaLaf41y2VuI8y'
-}
-```
-
-### 向量字段
-- `embedding_name_zh`: 名称文本向量 (1024维, dot_product)
-- `embedding_pic_h14.vector`: 图片向量 (1024维, dot_product)
-
-## 优势
-
-### 相比旧版本
-1. **更简单**: 无需参数配置
-2. **更快**: ES KNN查询比TF-IDF快
-3. **更准**: 深度学习向量比手工特征准
-4. **更多维度**: 名称 + 图片两个维度
-
-### 使用场景
-- **名称向量**: 语义相似推荐（同类但不同品牌）
-- **图片向量**: 视觉相似推荐（外观相似商品）
-
-## 注意事项
-
-1. **ES依赖**: 需要Elasticsearch服务可用
-2. **向量数据**: 需要ES中有向量数据
-3. **网络延迟**: ES查询受网络影响
-4. **首次运行**: 可能较慢，建议先测试连接
-
-## 故障排查
-
-### ES连接失败
-```bash
-# 检查ES是否可访问
-curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200
-
-# 运行测试脚本
-python scripts/test_es_connection.py
-```
-
-### 向量字段不存在
-```bash
-# 检查ES mapping
-curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200/spu/_mapping
-```
-
-### 查询超时
-- 增加 `request_timeout` 参数
-- 检查网络连接
-- 减少 `KNN_CANDIDATES` 参数
-
-## 后续优化
-
-1. **批量查询**: 使用 `_mget` 批量获取向量
-2. **并发处理**: 多线程提高查询效率
-3. **增量更新**: 只处理变化的商品
-4. **缓存向量**: 避免重复查询ES
-5. **监控告警**: 添加性能监控和异常告警
-
-## 相关文档
-
-- `ES_VECTOR_SIMILARITY.md` - ES向量详细说明
-- `CONTENT_SIMILARITY_UPDATE.md` - 更新详细说明
-- `REDIS_DATA_SPEC.md` - Redis数据规范
-- `README.md` - 项目概述
-
-## 总结
-
-本次更新大幅简化了内容相似索引的使用，从基于属性的相似度改为基于深度学习向量的相似度，提供了更准确和多维度的相似商品推荐。同时简化了参数配置，降低了使用和维护成本。
-
----
-
-**变更**: 9个文件（5个修改，4个新增）  
-**影响**: 内容相似索引生成和使用方式  
-**破坏性**: 中等（API兼容，但参数和Key格式改变）  
-**优先级**: 高（建议尽快更新）
-
@@ -1,243 +0,0 @@
-# 内容相似索引更新说明
-
-## 📋 更新概述
-
-重构了 `i2i_content_similar.py`，从基于数据库属性计算改为基于Elasticsearch向量计算，生成两份内容相似索引。
-
-## 🔄 主要变化
-
-### 1. 算法改变
-
-**之前 (旧版本):**
-- 基于商品属性（分类、供应商、包装等）
-- 使用TF-IDF + 余弦相似度
-- 提供 `--method` 参数选择: tfidf / category / hybrid
-- 复杂的参数配置
-
-**现在 (新版本):**
-- 基于Elasticsearch的向量相似度
-- 使用KNN向量查询
-- **无需任何参数，开箱即用**
-- 自动生成两份索引
-
-### 2. 生成的索引
-
-| 索引名称 | 向量来源 | 文件名 | Redis Key | TTL |
-|---------|---------|--------|-----------|-----|
-| **名称向量相似** | `embedding_name_zh` | `i2i_content_name_YYYYMMDD.txt` | `item:similar:content_name:{item_id}` | 30天 |
-| **图片向量相似** | `embedding_pic_h14` | `i2i_content_pic_YYYYMMDD.txt` | `item:similar:content_pic:{item_id}` | 30天 |
-
-### 3. 参数简化
-
-**之前:**
-```bash
-python i2i_content_similar.py --top_n 50 --method hybrid --debug
-```
-
-**现在:**
-```bash
-python i2i_content_similar.py
-# 就这么简单！无需任何参数
-```
-
-所有配置都在代码中预设好：
-- `TOP_N = 50`: 返回前50个相似商品
-- `KNN_K = 100`: KNN查询返回100个候选
-- `KNN_CANDIDATES = 200`: 候选池大小200
-
-## 📝 更新的文件
-
-### 核心代码
-1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写
-   - 连接Elasticsearch
-   - 查询最近1年活跃商品
-   - 获取向量并计算相似度
-   - 生成两份索引
-
-### 配置文档
-2. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 更新Redis数据规范
-   - 添加 `i2i_content_name` 规范
-   - 添加 `i2i_content_pic` 规范
-   - 更新内存占用估算（270,000 keys, ~160MB）
-
-### 调度脚本
-3. ✅ `offline_tasks/run_all.py` - 简化参数
-   - 移除 `--only-*` 参数
-   - 移除 `--skip-*` 参数
-   - 移除 `--lookback_days` 和 `--top_n` 参数
-   - 只保留 `--debug` 参数
-   - 添加内容相似任务
-
-4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 更新加载逻辑
-   - 添加 `content_name` 和 `content_pic` 到索引类型列表
-
-### 新增文档
-5. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - ES向量相似度说明
-   - ES配置说明
-   - 工作流程详解
-   - 性能说明和优化建议
-   - 故障排查指南
-
-6. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 本文档
-
-## 🚀 使用指南
-
-### 安装依赖
-
-需要安装Elasticsearch客户端：
-```bash
-pip install elasticsearch
-```
-
-### 配置ES连接
-
-在 `i2i_content_similar.py` 中修改ES配置（如需要）：
-```python
-ES_CONFIG = {
-    'host': 'http://localhost:9200',
-    'index_name': 'spu',
-    'username': 'essa',
-    'password': '4hOaLaf41y2VuI8y'
-}
-```
-
-### 运行脚本
-
-#### 单独运行
-```bash
-cd /home/tw/recommendation/offline_tasks
-python scripts/i2i_content_similar.py
-```
-
-#### 通过run_all运行
-```bash
-python run_all.py
-```
-
-### 加载到Redis
-```bash
-python scripts/load_index_to_redis.py --date 20251017
-```
-
-## 📊 输出示例
-
-### 文件格式
-```
-3302275    香蕉干    3302276:0.9234,3302277:0.8756,3302278:0.8432
-```
-
-### Redis存储
-```python
-# 名称向量相似
-GET item:similar:content_name:3302275
-# 返回: [[3302276,0.9234],[3302277,0.8756],[3302278,0.8432]]
-
-# 图片向量相似
-GET item:similar:content_pic:3302275
-# 返回: [[4503826,0.8123],[4503827,0.7856],[4503828,0.7645]]
-```
-
-## 🔍 技术细节
-
-### 数据源
-
-1. **活跃商品列表**
-   - 来源: 数据库 `sensors_events` 表
-   - 条件: 最近1年内有行为记录
-   - 行为类型: click, contactFactory, addToPool, addToCart, purchase
-
-2. **向量数据**
-   - 来源: Elasticsearch `spu` 索引
-   - 字段:
-     - `embedding_name_zh`: 名称文本向量 (1024维)
-     - `embedding_pic_h14.vector`: 图片向量 (1024维)
-     - `name_zh`: 商品中文名称
-
-### ES查询
-
-#### 1. 获取商品向量
-```json
-{
-  "query": {
-    "term": {"_id": "商品ID"}
-  },
-  "_source": {
-    "includes": ["_id", "name_zh", "embedding_name_zh", "embedding_pic_h14"]
-  }
-}
-```
-
-#### 2. KNN相似度查询
-```json
-{
-  "knn": {
-    "field": "embedding_name_zh",
-    "query_vector": [向量],
-    "k": 100,
-    "num_candidates": 200
-  },
-  "_source": ["_id", "name_zh"],
-  "size": 100
-}
-```
-
-## ⚡ 性能说明
-
-### 运行时间
-- 活跃商品数: ~50,000
-- 向量查询: ~50,000次 × 10ms = 8-10分钟
-- KNN查询: ~50,000次 × 50ms = 40-50分钟
-- **总计: 约50-60分钟**
-
-### 优化建议
-1. 批量查询: 使用 `_mget` 批量获取向量
-2. 并发处理: 多线程/异步IO
-3. 增量更新: 只处理变化的商品
-4. 缓存向量: 避免重复查询
-
-## 🆚 与其他算法对比
-
-| 算法 | 数据源 | 计算方式 | 特点 | 更新频率 |
-|-----|-------|---------|------|---------|
-| **Swing** | 用户行为 | 共现关系 | 捕获真实交互 | 每天 |
-| **W2V** | 用户会话 | 序列学习 | 捕获序列关系 | 每天 |
-| **DeepWalk** | 行为图 | 图游走 | 发现深层关联 | 每天 |
-| **名称向量** | ES向量 | KNN查询 | 语义相似 | 每周 |
-| **图片向量** | ES向量 | KNN查询 | 视觉相似 | 每周 |
-
-## 📋 待办事项
-
-- [x] 重写 `i2i_content_similar.py`
-- [x] 更新 `REDIS_DATA_SPEC.md`
-- [x] 简化 `run_all.py` 参数
-- [x] 更新 `load_index_to_redis.py`
-- [x] 编写技术文档
-- [ ] 添加单元测试
-- [ ] 性能优化（批量查询）
-- [ ] 添加监控和告警
-
-## ⚠️ 注意事项
-
-1. **ES连接**: 确保能访问ES服务器
-2. **向量缺失**: 部分商品可能没有向量，会被跳过
-3. **网络延迟**: ES查询受网络影响，建议内网部署
-4. **内存占用**: 处理大量商品时注意内存使用
-5. **依赖安装**: 需要安装 `elasticsearch` Python包
-
-## 🔗 相关文档
-
-- `ES_VECTOR_SIMILARITY.md` - ES向量相似度详细说明
-- `REDIS_DATA_SPEC.md` - Redis数据规范
-- `OFFLINE_INDEX_SPEC.md` - 离线索引规范
-- `QUICKSTART.md` - 快速开始指南
-
-## 📞 联系方式
-
-如有问题或建议，请联系开发团队。
-
----
-
-**更新日期**: 2025-10-17  
-**版本**: v2.0  
-**作者**: AI Assistant
-
@@ -1,229 +0,0 @@
-# 当前状态说明
-
-## ✅ 已完成并可用的功能
-
-### 1. i2i 行为相似算法（100%可用）
-- ✅ **Swing算法** - 已适配实际数据库字段
-- ✅ **Session W2V** - 已适配实际数据库字段  
-- ✅ **DeepWalk** - 已适配实际数据库字段
-
-**使用的字段**（已验证存在）：
-- `sensors_events.anonymous_id`
-- `sensors_events.item_id`
-- `sensors_events.event`
-- `sensors_events.create_time`
-- `prd_goods_sku.id`
-- `prd_goods_sku.name`
-
-**输出格式**：
-```
-item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
-```
-
-**运行命令**：
-```bash
-# 单独运行
-python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50
-python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50
-python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50
-```
-
----
-
-### 2. 兴趣点聚合（部分可用）
-
-#### 已适配的维度：
-✅ **business_platform** - 业务平台维度
-```
-platform:pc → item_id1:score1,item_id2:score2,...
-platform:mobile → ...
-```
-
-✅ **client_platform** - 客户端平台维度
-```
-client_platform:web → item_id1:score1,item_id2:score2,...
-client_platform:app → ...
-```
-
-✅ **platform_client** - 组合维度
-```
-platform_client:pc_web → item_id1:score1,item_id2:score2,...
-```
-
-#### 已适配的列表类型：
-✅ **hot** - 热门商品（基于最近180天）
-✅ **cart** - 加购商品
-✅ **new** - 新品（基于create_time）
-
-**运行命令**：
-```bash
-python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000
-```
-
----
-
-## ⚠️ 原计划但未实现的功能（因字段不存在）
-
-### sensors_events 表缺失字段：
-- ❌ `country` - 国家/销售区域
-- ❌ `customer_type` - 客户类型
-
-### prd_goods_sku 表缺失字段：
-- ❌ `category_level2_id` - 二级分类
-- ❌ `category_level3_id` - 三级分类
-
-### 影响的索引：
-- ❌ country:{country}
-- ❌ customer_type:{type}
-- ❌ category_level2:{cat_id}
-- ❌ category_level3:{cat_id}
-- ❌ 相关的组合维度索引
-
----
-
-## 📊 业务场景映射（更新后）
-
-### 场景1: 首页猜你喜欢
-**可用索引**：
-```python
-# 按平台推荐
-interest:hot:platform:pc
-interest:hot:platform:mobile
-
-# 按客户端平台推荐
-interest:hot:client_platform:web
-interest:hot:client_platform:app
-
-# 组合维度
-interest:hot:platform_client:pc_web
-```
-
-### 场景2: 详情页大家都在看
-**可用索引**：
-```python
-# i2i相似度（完全可用）
-i2i:swing:{item_id}
-i2i:session_w2v:{item_id}
-i2i:deepwalk:{item_id}
-```
-
-### 场景3: 搜索结果页推荐
-**可用索引**：
-```python
-# 按平台的全局推荐
-interest:global:platform:pc
-interest:global:client_platform:web
-
-# 或使用 page_type（需要扩展）
-interest:global:page_type:search
-```
-
----
-
-## 🎯 当前可用的完整索引列表
-
-### i2i索引（完全可用）
-```
-i2i:swing:{item_id}
-i2i:session_w2v:{item_id}
-i2i:deepwalk:{item_id}
-```
-
-### 兴趣点聚合索引（部分可用）
-
-**单维度**：
-```
-platform:{business_platform}           # 如：platform:pc
-client_platform:{client_platform}      # 如：client_platform:web
-```
-
-**组合维度**：
-```
-platform_client:{platform}_{client}    # 如：platform_client:pc_web
-```
-
-**列表类型前缀**：
-```
-interest:hot:...
-interest:cart:...
-interest:new:...
-interest:global:...
-```
-
-**完整示例**：
-```
-interest:hot:platform:pc
-interest:hot:client_platform:web
-interest:hot:platform_client:pc_web
-interest:cart:platform:mobile
-interest:new:client_platform:app
-interest:global:platform:pc
-```
-
----
-
-## 🚀 快速运行
-
-### 测试i2i功能（完全可用）
-```bash
-cd /home/tw/recommendation/offline_tasks
-
-# 运行Swing算法（小数据量测试）
-python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10
-
-# 查看输出
-head -n 5 output/i2i_swing_*.txt
-```
-
-### 测试兴趣点聚合（部分可用）
-```bash
-# 运行兴趣点聚合（小数据量测试）
-python3 scripts/interest_aggregation.py --lookback_days 30 --top_n 100
-
-# 查看输出
-head -n 10 output/interest_aggregation_hot_*.txt
-grep "^platform:" output/interest_aggregation_hot_*.txt | head -5
-```
-
-### 运行所有可用任务
-```bash
-# 运行全部
-python3 run_all.py --lookback_days 730 --top_n 50
-
-# 查看日志
-tail -f logs/run_all_*.log
-```
-
----
-
-## 💡 建议
-
-### 短期建议（立即可用）
-1. **优先使用 i2i 功能** - 这部分功能完整且经过验证
-2. **使用现有平台维度** - platform 和 client_platform 可以满足基本需求
-3. **测试小数据量** - 先用30天数据测试，确认无误后再用完整数据
-
-### 中期建议（需要扩展）
-1. **添加更多维度** - 可以考虑使用 `page_type`、`item_type` 等现有字段
-2. **关联其他表** - 如果其他表有分类信息，可以通过 JOIN 获取
-3. **解析JSON字段** - `__properties` 可能包含额外信息
-
-### 长期建议（需要数据支持）
-1. **补充用户特征字段** - 在 sensors_events 表中添加 country、customer_type 字段
-2. **补充商品分类字段** - 在 prd_goods_sku 表或关联表中添加分类信息
-3. **建立用户画像表** - 单独维护用户属性信息
-
----
-
-## 📞 文档索引
-
-- **FIELD_MAPPING.md** - 字段映射详细说明
-- **DATABASE_SETUP.md** - 数据库配置指南
-- **TROUBLESHOOTING.md** - 故障排除
-- **CHANGELOG.md** - 更新日志
-- **README.md** - 完整文档
-
----
-
-**更新时间**: 2025-10-16  
-**状态**: i2i功能完全可用，兴趣点聚合部分可用
@@ -1,335 +0,0 @@
-# 推荐系统离线任务 - 交付文档
-
-## 📋 项目概述
-
-根据您的需求，已完成推荐系统的离线任务部分构建，包括：
-
-1. **i2i 行为相似索引**：实现了3种算法（Swing、Session W2V、DeepWalk）
-2. **兴趣点聚合索引**：支持多维度（平台、国家、客户类型、分类）和多列表类型（热门、加购、新品）
-
-## ✅ 已完成的工作
-
-### 1. 核心功能实现
-
-#### 1.1 i2i 行为相似算法（参考 item_sim.py 改写）
-
-| 算法 | 文件 | 状态 | 说明 |
-|------|------|------|------|
-| **Swing** | `scripts/i2i_swing.py` | ✅ 完成 | 改写自collaboration/swing.cc，适配现有数据格式 |
-| **Session W2V** | `scripts/i2i_session_w2v.py` | ✅ 完成 | 改写自graphembedding/session_w2v，支持用户会话序列 |
-| **DeepWalk** | `scripts/i2i_deepwalk.py` | ✅ 完成 | 改写自graphembedding/deepwalk，支持图随机游走 |
-
-**特性**：
-- ✅ 适配真实数据库（SelectDB）
-- ✅ 支持时间衰减（2年数据，权重衰减）
-- ✅ 支持行为权重（click/addToCart/contactFactory/purchase等）
-- ✅ 输出格式与 item_sim.py 一致
-
-#### 1.2 兴趣点聚合索引
-
-| 维度类型 | 示例 | 状态 |
-|---------|------|------|
-| 平台 | platform:PC | ✅ 完成 |
-| 国家/销售区域 | country:US | ✅ 完成 |
-| 客户类型 | customer_type:retailer | ✅ 完成 |
-| 二级分类 | category_level2:100 | ✅ 完成 |
-| 三级分类 | category_level3:200 | ✅ 完成 |
-| 组合维度 | platform_country:PC_US | ✅ 完成 |
-
-| 列表类型 | 说明 | 状态 |
-|---------|------|------|
-| **热门** (hot) | 最近180天高交互商品 | ✅ 完成 |
-| **加购** (cart) | 基于加购行为 | ✅ 完成 |
-| **新品** (new) | 最近90天上架商品 | ✅ 完成 |
-| **全局** (global) | 所有数据综合 | ✅ 完成 |
-
-**特性**：
-- ✅ 时间衰减（最近2年，权重随时间衰减）
-- ✅ 多维度组合支持
-- ✅ 可配置的top N输出
-
-### 2. 基础设施
-
-| 组件 | 文件 | 状态 | 说明 |
-|------|------|------|------|
-| 数据库连接 | `db_service.py` | ✅ 完成 | 统一的数据库连接服务 |
-| 配置管理 | `config/offline_config.py` | ✅ 完成 | 集中的配置管理 |
-| 统一调度 | `run_all.py` | ✅ 完成 | 一键运行所有任务 |
-| Redis加载 | `scripts/load_index_to_redis.py` | ✅ 完成 | 索引加载到Redis |
-| 连接测试 | `test_connection.py` | ✅ 完成 | 验证环境配置 |
-| 查询示例 | `example_query_redis.py` | ✅ 完成 | 演示如何使用索引 |
-
-### 3. 文档
-
-| 文档 | 文件 | 状态 | 说明 |
-|------|------|------|------|
-| 详细文档 | `README.md` | ✅ 完成 | 完整的使用说明 |
-| 快速开始 | `QUICKSTART.md` | ✅ 完成 | 快速上手指南 |
-| 项目总结 | `PROJECT_SUMMARY.md` | ✅ 完成 | 技术架构和原理 |
-| 目录结构 | `STRUCTURE.md` | ✅ 完成 | 目录和数据流说明 |
-| 安装脚本 | `install.sh` | ✅ 完成 | 自动化安装 |
-| 依赖清单 | `requirements.txt` | ✅ 完成 | Python依赖包 |
-
-## 📁 交付文件清单
-
-```
-/home/tw/recommendation/
-├── db_service.py                              # 数据库连接服务
-├── requirements.txt                            # 依赖包清单
-│
-└── offline_tasks/                              # 离线任务主目录
-    ├── config/
-    │   └── offline_config.py                  # 配置文件
-    │
-    ├── scripts/                                # 核心算法脚本
-    │   ├── i2i_swing.py                       # ✅ Swing算法
-    │   ├── i2i_session_w2v.py                 # ✅ Session W2V
-    │   ├── i2i_deepwalk.py                    # ✅ DeepWalk
-    │   ├── interest_aggregation.py            # ✅ 兴趣点聚合
-    │   └── load_index_to_redis.py             # ✅ Redis加载
-    │
-    ├── output/                                 # 输出目录（运行后生成）
-    ├── logs/                                   # 日志目录（运行后生成）
-    │
-    ├── run_all.py                              # ✅ 统一调度脚本
-    ├── install.sh                              # ✅ 安装脚本
-    ├── test_connection.py                      # ✅ 连接测试
-    ├── example_query_redis.py                  # ✅ 查询示例
-    │
-    └── 文档/
-        ├── README.md                           # ✅ 详细文档
-        ├── QUICKSTART.md                       # ✅ 快速开始
-        ├── PROJECT_SUMMARY.md                  # ✅ 项目总结
-        ├── STRUCTURE.md                        # ✅ 目录结构
-        └── DELIVERY.md                         # ✅ 本文档
-```
-
-## 🚀 快速开始
-
-### 步骤1: 安装依赖
-
-```bash
-cd /home/tw/recommendation/offline_tasks
-bash install.sh
-```
-
-### 步骤2: 配置数据库
-
-编辑 `config/offline_config.py`，确保数据库连接信息正确。
-
-### 步骤3: 测试连接
-
-```bash
-python3 test_connection.py
-```
-
-### 步骤4: 运行离线任务
-
-```bash
-# 运行所有任务
-python3 run_all.py --lookback_days 730 --top_n 50
-
-# 或者运行单个任务
-python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50
-python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000
-```
-
-### 步骤5: 加载索引到Redis
-
-```bash
-python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379
-```
-
-### 步骤6: 查询验证
-
-```bash
-python3 example_query_redis.py
-```
-
-## 📊 数据格式说明
-
-### i2i索引格式
-```
-item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
-```
-
-**示例**：
-```
-123456	商品A	234567:0.8523,345678:0.7842,456789:0.7234
-```
-
-### 兴趣点聚合索引格式
-```
-dimension_key \t item_id1:score1,item_id2:score2,...
-```
-
-**示例**：
-```
-platform:PC	12345:98.52,23456:87.34,34567:76.89
-country:US	45678:156.23,56789:142.87,67890:128.45
-platform_country:PC_US	78901:234.56,89012:198.76,90123:187.23
-```
-
-## 🎯 业务场景对应
-
-根据您提供的业务场景，索引使用方式如下：
-
-### 1. 首页猜你喜欢
-**使用索引**：兴趣点聚合 (hot + global)
-
-```python
-# 获取用户特征
-platform = user.platform  # PC/Mobile
-country = user.country    # US/UK/CN...
-customer_type = user.customer_type  # retailer/wholesaler...
-
-# 查询多个维度的热门商品
-hot_items_1 = redis.get(f"interest:hot:platform_country:{platform}_{country}")
-hot_items_2 = redis.get(f"interest:hot:customer_type:{customer_type}")
-hot_items_3 = redis.get(f"interest:global:country:{country}")
-
-# 融合多个结果
-recommended_items = merge_and_rerank(hot_items_1, hot_items_2, hot_items_3)
-```
-
-### 2. 详情页的大家都在看
-**使用索引**：i2i 行为相似
-
-```python
-# 当前浏览的商品ID
-current_item_id = "123456"
-
-# 查询相似商品（可以组合多个算法）
-similar_swing = redis.get(f"i2i:swing:{current_item_id}")
-similar_w2v = redis.get(f"i2i:session_w2v:{current_item_id}")
-similar_deepwalk = redis.get(f"i2i:deepwalk:{current_item_id}")
-
-# 融合结果
-recommended_items = merge_i2i_results(similar_swing, similar_w2v, similar_deepwalk)
-```
-
-### 3. 搜索结果页底部的供应商推荐
-**使用索引**：兴趣点聚合 (按分类)
-
-```python
-# 用户搜索的分类
-category_level2 = search_query.category_level2
-
-# 查询该分类下的推荐商品
-items = redis.get(f"interest:global:category_level2:{category_level2}")
-
-# 结合用户特征进行个性化排序
-personalized_items = personalize_ranking(items, user_profile)
-```
-
-## ⚙️ 配置参数说明
-
-### 关键配置（config/offline_config.py）
-
-```python
-# 时间范围
-LOOKBACK_DAYS = 730        # 回溯天数（2年）
-RECENT_DAYS = 180          # 热门商品统计天数
-NEW_DAYS = 90              # 新品定义天数
-
-# 时间衰减
-time_decay_factor = 0.95   # 每30天衰减5%
-
-# 行为权重
-behavior_weights = {
-    'click': 1.0,           # 点击
-    'addToPool': 2.0,       # 加入询盘池
-    'addToCart': 3.0,       # 加入购物车
-    'contactFactory': 5.0,  # 联系工厂
-    'purchase': 10.0        # 购买
-}
-
-# 输出数量
-i2i_top_n = 50             # 每个商品的相似商品数
-interest_top_n = 1000      # 每个维度的推荐商品数
-```
-
-## 📈 性能参考
-
-基于100万条用户行为数据的预估：
-
-| 任务 | 预估时间 | 内存占用 | 输出大小 |
-|------|---------|---------|---------|
-| Swing算法 | 2-4小时 | 4-8GB | ~50MB |
-| Session W2V | 30-60分钟 | 2-4GB | ~30MB |
-| DeepWalk | 1-2小时 | 2-4GB | ~40MB |
-| 兴趣点聚合 | 30-60分钟 | 2-4GB | ~100MB |
-| **总计** | **5-8小时** | **8-16GB** | **~220MB** |
-
-## 🔧 定时任务设置
-
-建议使用crontab设置每天运行：
-
-```bash
-# 编辑crontab
-crontab -e
-
-# 添加以下行（每天凌晨2点运行）
-0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py >> logs/cron.log 2>&1
-
-# 凌晨6点加载到Redis
-0 6 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 scripts/load_index_to_redis.py >> logs/load_redis.log 2>&1
-```
-
-## 🐛 常见问题
-
-### Q1: 数据库连接失败
-**解决方案**：
-1. 检查 `config/offline_config.py` 中的数据库配置
-2. 运行 `python3 test_connection.py` 测试连接
-3. 确认网络连接和防火墙设置
-
-### Q2: 任务运行时间过长
-**解决方案**：
-1. 减少 `--lookback_days` 参数（如改为365天）
-2. 使用 `--only-xxx` 参数只运行特定任务
-3. 考虑使用C++版本的Swing算法（性能提升10倍）
-
-### Q3: 内存不足
-**解决方案**：
-1. 先运行DeepWalk或Session W2V（内存占用较小）
-2. 使用 `--skip-i2i` 跳过Swing算法
-3. 分批处理数据
-
-## 📚 参考文档
-
-- **README.md**: 完整的功能说明和使用指南
-- **QUICKSTART.md**: 快速上手步骤
-- **PROJECT_SUMMARY.md**: 技术架构和算法原理
-- **STRUCTURE.md**: 项目结构和数据流向
-
-## ✨ 技术亮点
-
-1. **适配真实数据**：参考 item_sim.py，完全适配现有数据库结构
-2. **多算法支持**：实现了3种主流i2i算法，可以融合使用
-3. **多维度聚合**：支持单维度和组合维度，灵活满足不同场景
-4. **时间衰减**：考虑时间因素，近期行为权重更高
-5. **行为加权**：不同行为类型赋予不同权重，购买权重最高
-6. **统一调度**：一键运行所有任务，自动化程度高
-7. **配置灵活**：所有参数可配置，便于调优
-8. **文档完善**：提供了完整的使用文档和示例代码
-
-## 🎉 交付状态
-
-**状态**: ✅ 已完成
-
-所有功能已实现并测试通过，可以直接使用。建议先在测试环境运行验证，确认无误后再部署到生产环境。
-
-## 📞 后续支持
-
-如有问题，请查看：
-1. 日志文件：`logs/` 目录下的日志
-2. 文档：各个 `.md` 文档
-3. 示例代码：`example_query_redis.py`
-
----
-
-**交付日期**: 2025-10-16  
-**版本**: v1.0  
-**状态**: 已完成 ✅
-
@@ -1,172 +0,0 @@
-# 数据库字段映射说明
-
-## 实际表结构
-
-根据检查结果，实际的表结构如下：
-
-### sensors_events 表（用户行为事件表）
-
-| 代码中使用的字段 | 实际字段名 | 说明 |
-|----------------|-----------|------|
-| `user_id` | `anonymous_id` | 匿名用户ID |
-| `item_id` | `item_id` | 商品ID |
-| `event_type` | `event` | 事件类型 |
-| `create_time` | `create_time` | 创建时间 |
-| `platform` | `business_platform` | 业务平台 |
-| `client_platform` | `client_platform` | 客户端平台 |
-
-**不存在的字段**：
-- ❌ `country` - 国家字段（原计划支持，但表中不存在）
-- ❌ `customer_type` - 客户类型字段（原计划支持，但表中不存在）
-
-**其他可用字段**：
-- `ip` - IP地址
-- `item_type` - 商品类型
-- `location_src` - 位置来源
-- `search_content` - 搜索内容
-- `page_type` - 页面类型
-- `session_id` - 会话ID
-
-### prd_goods_sku 表（商品SKU表）
-
-| 代码中使用的字段 | 实际字段名 | 说明 |
-|----------------|-----------|------|
-| `item_id` | `id` | 商品ID |
-| `item_name` | `name` | 商品名称 |
-| `item_create_time` | `create_time` | 商品创建时间 |
-
-**不存在的字段**：
-- ❌ `category_level2_id` - 二级分类ID
-- ❌ `category_level3_id` - 三级分类ID
-
-**其他可用字段**：
-- `goods_id` - 关联商品主表ID
-- `buyer_id` - 买家ID
-- `factory_no` - 工厂编号
-- `package_type_name` - 包装类型名称
-- `on_sell_time` - 上架时间
-- `price_base` - 基础价格
-
-## 当前支持的维度
-
-基于实际表结构，当前代码支持以下维度：
-
-### 单维度
-1. ✅ `platform` - 业务平台（business_platform）
-2. ✅ `client_platform` - 客户端平台
-3. ❌ `country` - 国家（字段不存在）
-4. ❌ `customer_type` - 客户类型（字段不存在）
-5. ❌ `category_level2` - 二级分类（字段不存在）
-6. ❌ `category_level3` - 三级分类（字段不存在）
-
-### 组合维度
-1. ✅ `platform_client` - 业务平台 + 客户端平台
-
-### 列表类型
-1. ✅ `hot` - 热门商品
-2. ✅ `cart` - 加购商品
-3. ✅ `new` - 新品
-
-## 如何扩展更多维度
-
-### 方案1: 使用现有字段
-
-可以考虑使用表中已有的其他字段来扩展维度：
-
-```python
-# 在 interest_aggregation.py 的 SQL 查询中添加
-sql_query = f"""
-SELECT 
-    ...
-    se.page_type,           # 页面类型
-    se.item_type,           # 商品类型
-    pgs.package_type_name,  # 包装类型
-    ...
-"""
-
-# 在聚合函数中添加新维度
-if pd.notna(row.get('page_type')):
-    key = f"page_type:{row['page_type']}"
-    aggregations[key][item_id] += weight
-
-if pd.notna(row.get('item_type')):
-    key = f"item_type:{row['item_type']}"
-    aggregations[key][item_id] += weight
-```
-
-### 方案2: 关联其他表获取分类信息
-
-如果分类信息在其他表中，可以通过 JOIN 获取：
-
-```python
-sql_query = f"""
-SELECT 
-    se.anonymous_id AS user_id,
-    se.item_id,
-    ...
-    gc.category_level2_id,
-    gc.category_level3_id
-FROM 
-    sensors_events se
-LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id
-LEFT JOIN goods_category gc ON pgs.goods_id = gc.goods_id  # 假设有这个表
-...
-"""
-```
-
-### 方案3: 从 JSON 字段提取
-
-如果 `__properties` 字段包含额外信息，可以解析JSON：
-
-```python
-# 在查询中
-sql_query = f"""
-SELECT 
-    ...
-    se.__properties as properties_json
-...
-"""
-
-# 在处理时
-import json
-props = json.loads(row.get('properties_json', '{}'))
-if 'country' in props:
-    key = f"country:{props['country']}"
-    aggregations[key][item_id] += weight
-```
-
-## 推荐的实际使用维度
-
-基于现有字段，建议使用以下维度组合：
-
-1. **业务平台维度** - `platform:{business_platform}`
-   - 示例：platform:pc, platform:mobile
-   
-2. **客户端平台维度** - `client_platform:{client_platform}`
-   - 示例：client_platform:web, client_platform:app
-
-3. **页面类型维度** - `page_type:{page_type}` （需添加）
-   - 示例：page_type:detail, page_type:list
-
-4. **商品类型维度** - `item_type:{item_type}` （需添加）
-   - 示例：item_type:normal, item_type:special
-
-## 更新后的输出示例
-
-```
-# 实际可用的索引键
-platform:pc                          → 12345:98.5,23456:87.3,...
-platform:mobile                      → 34567:76.2,45678:65.1,...
-client_platform:web                  → 56789:54.3,67890:43.2,...
-client_platform:app                  → 78901:32.1,89012:21.0,...
-platform_client:pc_web               → 90123:123.4,01234:112.3,...
-```
-
-## 总结
-
-1. **已实现**: 基于 `business_platform` 和 `client_platform` 的索引
-2. **未实现**: country、customer_type、分类相关索引（因字段不存在）
-3. **可扩展**: page_type、item_type 等其他维度
-
-如需支持更多维度，请参考上述方案进行扩展。
-
@@ -1,269 +0,0 @@
-# 内容相似索引重构 - 最终总结
-
-## ✅ 已完成的工作
-
-### 1. 核心功能实现
-
-#### 重写 `i2i_content_similar.py`
-- ✅ 从数据库属性计算 → ES向量计算
-- ✅ 生成两份索引：名称向量 + 图片向量
-- ✅ 移除所有命令行参数，配置内置
-- ✅ **加入 `on_sell_days_boost` 提权** ⭐新增
-  - 取值范围：0.9~1.1
-  - 自动应用到所有相似度分数
-  - 异常值保护，默认1.0
-
-#### 提权逻辑
-```python
-# KNN查询获取基础分数
-base_score = knn_result['_score']
-
-# 获取上架天数提权值
-boost = knn_result['_source']['on_sell_days_boost']  # 0.9~1.1
-
-# 应用提权
-final_score = base_score * boost
-```
-
-### 2. 简化运行脚本
-
-#### `run_all.py` 参数简化
-- ❌ 移除：`--skip-i2i`, `--skip-interest`, `--only-*`, `--lookback_days`, `--top_n`
-- ✅ 保留：`--debug` (唯一参数)
-- ✅ 添加：内容相似任务
-
-#### 使用方式
-```bash
-# 之前（复杂）
-python run_all.py --lookback_days 30 --top_n 50 --skip-interest --only-content
-
-# 现在（简单）
-python run_all.py
-```
-
-### 3. 更新配置和文档
-
-#### 修改的文件
-1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写，加入提权
-2. ✅ `offline_tasks/run_all.py` - 简化参数
-3. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 新增2个索引规范
-4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 支持新索引
-5. ✅ `requirements.txt` - 添加elasticsearch依赖
-
-#### 新增的文件
-6. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - 技术文档
-7. ✅ `offline_tasks/scripts/test_es_connection.py` - 测试工具
-8. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 更新说明
-9. ✅ `offline_tasks/CHANGES_SUMMARY.md` - 变更总结
-10. ✅ `offline_tasks/QUICKSTART_NEW.md` - 快速开始
-11. ✅ `offline_tasks/FINAL_SUMMARY.md` - 本文档
-
-### 4. 测试工具增强
-
-#### `test_es_connection.py` 功能
-- ✅ 测试ES连接
-- ✅ 测试索引存在
-- ✅ 测试字段映射（包含 `on_sell_days_boost`）
-- ✅ 测试向量查询
-- ✅ 测试KNN查询
-- ✅ **显示提权计算过程** ⭐新增
-  ```
-  基础分数: 0.8523, 提权: 1.05, 最终分数: 0.8949
-  ```
-
-## 📊 生成的索引
-
-### 索引文件
-| 文件名 | 向量类型 | Redis Key | 提权 | TTL |
-|-------|---------|-----------|------|-----|
-| `i2i_content_name_YYYYMMDD.txt` | 名称向量 | `item:similar:content_name:{id}` | ✅ | 30天 |
-| `i2i_content_pic_YYYYMMDD.txt` | 图片向量 | `item:similar:content_pic:{id}` | ✅ | 30天 |
-
-### 文件格式
-```
-item_id \t item_name \t similar_id1:boosted_score1,similar_id2:boosted_score2,...
-```
-
-### 示例（分数已包含提权）
-```
-3302275    香蕉干    3302276:0.9686,3302277:0.9182,3302278:0.8849
-                    ↑ 已应用on_sell_days_boost提权
-```
-
-## 🔍 技术细节
-
-### ES查询字段
-```python
-_source = [
-    "_id",                  # 商品ID
-    "name_zh",              # 中文名称
-    "on_sell_days_boost"    # 提权值 ⭐
-]
-```
-
-### 提权处理
-```python
-# 1. 获取提权值
-boost = hit['_source'].get('on_sell_days_boost', 1.0)
-
-# 2. 范围验证（0.9~1.1）
-if boost is None or boost < 0.9 or boost > 1.1:
-    boost = 1.0  # 异常值使用默认值
-
-# 3. 应用提权
-final_score = base_score * boost
-```
-
-### 提权说明
-- **> 1.0**: 提权（新品、热门商品）
-- **= 1.0**: 不提权（正常商品）
-- **< 1.0**: 降权（长尾商品）
-
-## 🚀 使用指南
-
-### 1. 安装依赖
-```bash
-pip install -r requirements.txt
-# 新增: elasticsearch>=8.0.0
-```
-
-### 2. 测试ES连接（含提权测试）
-```bash
-python scripts/test_es_connection.py
-```
-
-输出示例：
-```
-✓ 找到商品 3302275
-  名称: 香蕉干
-  上架天数提权: 1.05
-
-✓ 名称向量KNN查询成功
-    1. ID: 3302276, 名称: 香蕉片
-        基础分数: 0.9220, 提权: 1.05, 最终分数: 0.9681
-    2. ID: 3302277, 名称: 芒果干
-        基础分数: 0.8746, 提权: 1.05, 最终分数: 0.9183
-```
-
-### 3. 运行生成
-```bash
-# 单独运行
-python scripts/i2i_content_similar.py
-
-# 或全部运行
-python run_all.py
-```
-
-### 4. 加载到Redis
-```bash
-python scripts/load_index_to_redis.py
-```
-
-### 5. 查询使用
-```python
-import redis
-import json
-
-r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)
-
-# 获取名称向量相似（分数已含提权）
-similar = json.loads(r.get('item:similar:content_name:3302275'))
-# 返回: [[3302276, 0.9686], [3302277, 0.9182], ...]
-#           ↑ 分数已应用on_sell_days_boost
-
-# 获取图片向量相似（分数已含提权）
-similar = json.loads(r.get('item:similar:content_pic:3302275'))
-# 返回: [[4503826, 0.8523], [4503827, 0.8245], ...]
-#           ↑ 分数已应用on_sell_days_boost
-```
-
-## 🎯 核心改进
-
-### 1. 简化使用
-- **无参数**: `i2i_content_similar.py` 无需任何参数
-- **无选择**: `run_all.py` 自动运行所有任务
-- **易维护**: 配置集中在代码中
-
-### 2. 更强大
-- **深度学习**: 基于ES向量，比TF-IDF更准确
-- **多维度**: 名称 + 图片两个维度
-- **智能提权**: 自动应用上架天数提权 ⭐
-- **更快**: ES KNN查询性能优秀
-
-### 3. 提权优势
-- **动态调整**: 根据商品上架天数动态提权
-- **平滑过渡**: 0.9~1.1小范围提权，避免剧烈变化
-- **异常保护**: 自动处理缺失或异常值
-- **透明计算**: 测试工具显示提权过程
-
-## 📈 性能指标
-
-| 指标 | 值 |
-|-----|---|
-| 活跃商品数 | ~50,000 |
-| 运行时间 | 50-60分钟 |
-| Redis Keys | +100,000 |
-| Redis内存 | +50MB |
-| 提权开销 | 可忽略（简单乘法） |
-
-## ⚠️ 重要说明
-
-### 提权应用
-- ✅ 所有相似度分数都已应用提权
-- ✅ 输出文件中的分数是最终分数
-- ✅ Redis中存储的分数是最终分数
-- ✅ 无需在应用层再次应用提权
-
-### 向后兼容
-- ✅ 其他i2i算法不受影响
-- ✅ Redis加载器向后兼容
-- ❌ 命令行参数全部改变
-- ❌ Redis Key格式改变
-
-### 迁移建议
-1. 更新API调用，使用新的Redis Key
-2. 无需修改分数处理逻辑（已含提权）
-3. 建议同时支持两种向量算法
-
-## 📚 文档导航
-
-| 文档 | 说明 |
-|------|------|
-| `QUICKSTART_NEW.md` | 5分钟快速开始 |
-| `ES_VECTOR_SIMILARITY.md` | ES向量技术详解 |
-| `CONTENT_SIMILARITY_UPDATE.md` | 完整更新说明 |
-| `CHANGES_SUMMARY.md` | 所有变更总结 |
-| `FINAL_SUMMARY.md` | 本文档 |
-
-## 🎉 总结
-
-本次重构实现了三大目标：
-
-1. **简化使用** ✅
-   - 移除复杂参数
-   - 一键运行所有任务
-
-2. **提升能力** ✅
-   - 深度学习向量
-   - 多维度相似度
-   - 智能上架天数提权 ⭐
-
-3. **易于维护** ✅
-   - 代码清晰简洁
-   - 文档完整详细
-   - 测试工具完善
-
-### 关键特性
-
-- **🚀 无参数运行**: `python scripts/i2i_content_similar.py`
-- **🎯 智能提权**: 自动应用 `on_sell_days_boost` (0.9~1.1)
-- **🔍 双向量**: 名称语义 + 图片视觉
-- **📊 高性能**: ES KNN查询快速准确
-- **🛡️ 异常保护**: 提权值验证和默认值处理
-
----
-
-**重构完成时间**: 2025-10-17  
-**影响范围**: 内容相似索引生成和使用  
-**状态**: ✅ 已完成，可投入使用
-
@@ -1,301 +0,0 @@
-# 最终更新说明
-
-## 📅 更新日期：2025-10-16
-
-## ✅ 已完成的功能（完整版）
-
-### 1. i2i 相似度索引（4种算法）
-
-#### 1.1 行为相似（3种）
-基于用户行为计算商品相似度：
-
-| 算法 | 文件 | 特点 | 状态 |
-|------|------|------|------|
-| **Swing** | `i2i_swing.py` | 基于用户共同行为，效果最好 | ✅ 已完成 |
-| **Session W2V** | `i2i_session_w2v.py` | 基于会话序列，捕获序列关系 | ✅ 已完成 |
-| **DeepWalk** | `i2i_deepwalk.py` | 基于图游走，发现深层关系 | ✅ 已完成 |
-
-#### 1.2 内容相似（新增）
-基于商品属性计算商品相似度：
-
-| 算法 | 文件 | 特点 | 状态 |
-|------|------|------|------|
-| **Content-based** | `i2i_content_similar.py` | 基于分类、供应商、属性等 | ✅ 新增完成 |
-
-**支持的方法**：
-- `tfidf` - 基于TF-IDF的文本相似度
-- `category` - 基于分类的相似度
-- `hybrid` - 混合方法（推荐）
-
-**使用的特征**：
-- 商品分类（一级到四级）
-- 供应商信息
-- 包装类型和包装方式
-- 商品名称关键词
-
-**运行命令**：
-```bash
-# 使用混合方法（推荐）
-python3 scripts/i2i_content_similar.py --top_n 50 --method hybrid
-
-# 只使用TF-IDF
-python3 scripts/i2i_content_similar.py --top_n 50 --method tfidf
-
-# 只使用分类
-python3 scripts/i2i_content_similar.py --top_n 50 --method category
-```
-
----
-
-### 2. 兴趣点聚合索引（已完善）
-
-#### 支持的维度（从2个扩展到7个）
-
-**单维度**：
-1. ✅ `platform` - 业务平台
-2. ✅ `client_platform` - 客户端平台
-3. ✅ `supplier` - 供应商
-4. ✅ `category_level1` - 一级分类
-5. ✅ `category_level2` - 二级分类
-6. ✅ `category_level3` - 三级分类
-7. ✅ `category_level4` - 四级分类
-
-**组合维度**：
-1. ✅ `platform_client` - 业务平台 + 客户端平台
-2. ✅ `platform_category2` - 平台 + 二级分类
-3. ✅ `platform_category3` - 平台 + 三级分类
-4. ✅ `client_category2` - 客户端平台 + 二级分类
-
-**列表类型**：
-1. ✅ `hot` - 热门商品
-2. ✅ `cart` - 加购商品
-3. ✅ `new` - 新品
-
----
-
-## 🎯 完整的索引输出
-
-### i2i索引（4种）
-```
-# 行为相似
-i2i:swing:{item_id}
-i2i:session_w2v:{item_id}
-i2i:deepwalk:{item_id}
-
-# 内容相似（新增）
-i2i:content_hybrid:{item_id}
-i2i:content_tfidf:{item_id}
-i2i:content_category:{item_id}
-```
-
-### 兴趣点聚合索引（大幅扩展）
-
-**单维度示例**：
-```
-interest:hot:platform:pc
-interest:hot:client_platform:web
-interest:hot:supplier:10001
-interest:hot:category_level1:100
-interest:hot:category_level2:200
-interest:hot:category_level3:300
-interest:hot:category_level4:400
-```
-
-**组合维度示例**：
-```
-interest:hot:platform_client:pc_web
-interest:hot:platform_category2:pc_200
-interest:hot:platform_category3:mobile_300
-interest:hot:client_category2:web_200
-```
-
-**列表类型示例**：
-```
-interest:hot:category_level2:200
-interest:cart:category_level3:300
-interest:new:supplier:10001
-interest:global:platform_category2:pc_200
-```
-
----
-
-## 📊 业务场景应用（更新）
-
-### 场景1: 首页猜你喜欢
-```python
-# 1. 基于平台推荐
-items_1 = redis.get("interest:hot:platform:pc")
-
-# 2. 基于用户常购分类推荐
-items_2 = redis.get("interest:hot:category_level2:200")
-
-# 3. 基于平台+分类组合
-items_3 = redis.get("interest:hot:platform_category2:pc_200")
-
-# 融合多个维度
-recommended = merge_and_personalize(items_1, items_2, items_3)
-```
-
-### 场景2: 详情页大家都在看
-```python
-item_id = "12345"
-
-# 1. 行为相似（用户行为）
-similar_behavior = redis.get(f"i2i:swing:{item_id}")
-
-# 2. 内容相似（商品属性）
-similar_content = redis.get(f"i2i:content_hybrid:{item_id}")
-
-# 3. 融合推荐
-recommended = merge_i2i(similar_behavior, similar_content, weight1=0.6, weight2=0.4)
-```
-
-### 场景3: 分类页推荐
-```python
-category_id = "200"
-
-# 1. 该分类的热门商品
-hot_items = redis.get(f"interest:hot:category_level2:{category_id}")
-
-# 2. 该分类的新品
-new_items = redis.get(f"interest:new:category_level2:{category_id}")
-
-# 3. 组合展示
-display(hot_items, new_items)
-```
-
-### 场景4: 供应商页推荐
-```python
-supplier_id = "10001"
-
-# 该供应商的热门商品
-hot_items = redis.get(f"interest:hot:supplier:{supplier_id}")
-```
-
----
-
-## 🚀 运行所有任务
-
-```bash
-cd /home/tw/recommendation/offline_tasks
-
-# 运行全部任务（包括新增的内容相似）
-python3 run_all.py --lookback_days 730 --top_n 50
-
-# 只运行内容相似
-python3 run_all.py --only-content --top_n 50
-
-# 跳过内容相似，只运行其他
-python3 run_all.py --skip-content --lookback_days 730 --top_n 50
-```
-
----
-
-## 📈 性能参考（更新）
-
-| 任务 | 数据依赖 | 预估时间 | 内存占用 |
-|------|---------|---------|---------|
-| Swing | 用户行为（730天） | 2-4小时 | 4-8GB |
-| Session W2V | 用户行为（730天） | 30-60分钟 | 2-4GB |
-| DeepWalk | 用户行为（730天） | 1-2小时 | 2-4GB |
-| **Content-based** | **商品属性（全量）** | **10-30分钟** | **2-4GB** |
-| 兴趣点聚合 | 用户行为（730天） | 30-60分钟 | 2-4GB |
-
-**总计**：约6-10小时
-
----
-
-## 📝 数据表依赖关系
-
-### i2i 行为相似
-- `sensors_events` - 用户行为事件
-- `prd_goods_sku` - 商品SKU信息
-
-### i2i 内容相似（新增）
-- `prd_goods_sku` - 商品SKU信息
-- `prd_goods` - 商品主表
-- `sup_supplier` - 供应商信息
-- `prd_category` - 分类信息（层级结构）
-- `prd_goods_sku_attribute` - 商品属性
-- `prd_option` - 属性选项
-- `prd_attribute` - 属性定义
-
-### 兴趣点聚合（已完善）
-- `sensors_events` - 用户行为事件
-- `prd_goods_sku` - 商品SKU信息
-- `prd_goods` - 商品主表
-- `prd_category` - 分类信息（新增）
-
----
-
-## 🔄 与原有代码的对比
-
-### 原计划维度（文档中）
-- ❌ 国家/销售区域（字段不存在）
-- ❌ 客户类型（字段不存在）
-- ⚠️ 二级分类（原以为不存在，现已支持）
-- ⚠️ 三级分类（原以为不存在，现已支持）
-
-### 实际实现维度（完善后）
-- ✅ 业务平台
-- ✅ 客户端平台
-- ✅ 供应商（新增）
-- ✅ 一级分类（新增）
-- ✅ 二级分类（新增支持）
-- ✅ 三级分类（新增支持）
-- ✅ 四级分类（新增）
-
----
-
-## 💡 优势总结
-
-### 1. 内容相似的优势
-- ✅ **冷启动友好**：新商品立即可用
-- ✅ **不依赖行为数据**：商品上架即可生成相似推荐
-- ✅ **可解释性强**：基于分类、属性等明确特征
-- ✅ **计算快速**：只需要商品属性数据
-
-### 2. 多维度聚合的优势
-- ✅ **分类粒度丰富**：支持4级分类
-- ✅ **供应商维度**：支持供应商页推荐
-- ✅ **组合查询**：支持平台+分类等组合维度
-- ✅ **灵活性高**：可根据需要查询不同粒度
-
-### 3. 算法融合的优势
-- ✅ **行为 + 内容**：可以融合4种i2i算法
-- ✅ **短期 + 长期**：热门、新品等不同时效性
-- ✅ **粗粒度 + 细粒度**：一级到四级分类
-
----
-
-## 🎉 完成状态
-
-**✅ 全部完成！**
-
-1. ✅ i2i 行为相似（3种算法）
-2. ✅ i2i 内容相似（1种算法，3种方法）
-3. ✅ 兴趣点聚合（7个单维度 + 4个组合维度 + 3种列表类型）
-4. ✅ 统一调度脚本
-5. ✅ Redis加载工具
-6. ✅ 完整文档
-
----
-
-## 📚 相关文档
-
-- **CURRENT_STATUS.md** - 当前功能状态
-- **FIELD_MAPPING.md** - 字段映射说明
-- **DATABASE_SETUP.md** - 数据库配置
-- **TROUBLESHOOTING.md** - 故障排除
-- **README.md** - 完整文档
-
----
-
-**更新版本**: v1.1  
-**更新日期**: 2025-10-16  
-**主要变化**: 
-- 新增内容相似算法
-- 完善分类维度支持（1-4级）
-- 新增供应商维度
-- 扩展组合维度查询
-
@@ -1,186 +0,0 @@
-# 商品名称映射问题修复
-
-## 问题描述
-
-在Debug模式生成的明文文件中，商品名称显示为"Unknown"：
-
-```
-[7] i2i:swing:3667845
---------------------------------------------------------------------------------
-  1. ID:3588590(Unknown) - Score:0.2857
-  2. ID:3623446(Unknown) - Score:...
-```
-
-## 根本原因
-
-数据类型不匹配导致名称映射失败：
-
-1. **fetch_name_mappings()** 从数据库获取的映射，key是**字符串类型**：
-   ```python
-   mappings['item'] = dict(zip(df['id'].astype(str), df['name']))
-   # 结果: {'12345': '香蕉干', '67890': '芒果干', ...}
-   ```
-
-2. **item_name_map** 从DataFrame创建的映射，key是**整数类型**：
-   ```python
-   item_name_map = dict(zip(df['item_id'].unique(), ...))
-   # 结果: {12345: '香蕉干', 67890: '芒果干', ...}
-   ```
-
-3. **更新操作失败**：
-   ```python
-   name_mappings['item'].update(item_name_map)
-   # int类型的key和str类型的key不匹配，实际上没有更新成功
-   ```
-
-4. **查询时找不到**：
-   ```python
-   name = name_mappings.get('item', {}).get(str(item_id), 'Unknown')
-   # 将int的item_id转为str查询，但dict中只有int类型的key，所以返回'Unknown'
-   ```
-
-## 修复方案
-
-### 方法1：统一转为字符串（已采用）
-
-```python
-# 修改前
-item_name_map = dict(zip(df['item_id'].unique(), df.groupby('item_id')['item_name'].first()))
-
-# 修改后（key转为字符串）
-item_name_map = dict(zip(df['item_id'].unique().astype(str), df.groupby('item_id')['item_name'].first()))
-```
-
-### 方法2：update时转换（备选）
-
-```python
-# 转换key类型后再更新
-name_mappings['item'].update({str(k): v for k, v in item_name_map.items()})
-```
-
-## 验证修复
-
-修复后运行debug模式：
-
-```bash
-cd /home/tw/recommendation/offline_tasks
-python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
-```
-
-检查明文文件：
-
-```bash
-more output/debug/i2i_swing_*_readable.txt
-```
-
-应该看到：
-
-```
-[7] i2i:swing:3667845(商品名称)
---------------------------------------------------------------------------------
-  1. ID:3588590(香蕉干) - Score:0.2857
-  2. ID:3623446(芒果干) - Score:0.2143
-```
-
-## 数据库字段确认
-
-正确的查询关系：
-
-```sql
-SELECT 
-    pgs.id as 'sku_id',
-    pgs.name as '商品名称',
-    ss.name as '供应商名称',
-    pc_1.name as '一级类目',
-    pc_2.name as '二级类目'
-FROM prd_goods_sku pgs
-LEFT JOIN sup_supplier ss ON pgs.supplier_id = ss.id
-LEFT JOIN prd_category pc_1 ON ...
-```
-
-## 其他脚本
-
-这个问题也可能存在于其他脚本，需要同样修复：
-- ✅ i2i_swing.py (已修复)
-- ⚠️ i2i_session_w2v.py (如果有debug功能需要检查)
-- ⚠️ i2i_deepwalk.py (如果有debug功能需要检查)
-- ⚠️ i2i_content_similar.py (如果有debug功能需要检查)
-- ⚠️ interest_aggregation.py (如果有debug功能需要检查)
-
-## 预防措施
-
-为避免类似问题，建议：
-
-1. **统一数据类型约定**：
-   - 所有ID映射的key统一使用字符串类型
-   - 在debug_utils.py中明确文档说明
-
-2. **添加类型检查**：
-   ```python
-   def safe_update_mapping(target_dict, source_dict):
-       """安全更新映射，自动转换key类型"""
-       for k, v in source_dict.items():
-           target_dict[str(k)] = v
-   ```
-
-3. **添加调试日志**：
-   ```python
-   if debug:
-       logger.debug(f"更新前: {len(name_mappings['item'])} 个名称")
-       name_mappings['item'].update(item_name_map)
-       logger.debug(f"更新后: {len(name_mappings['item'])} 个名称")
-   ```
-
----
-
-**状态**: ✅ 已修复  
-**影响范围**: i2i_swing.py  
-**修复时间**: 2025-10-16
-
-## 补充修复 - 主输出文件
-
-问题同样存在于主输出文件中：
-
-```
-1070176 Unknown 2786217:0.4000
-2786217 Unknown 1070176:0.4000
-```
-
-### 原因
-
-主输出代码中使用整数item_id作为key查询：
-
-```python
-for item_id, sims in result.items():
-    item_name = item_name_map.get(item_id, 'Unknown')  # item_id是int，但map的key是str
-```
-
-### 修复
-
-统一转换为字符串：
-
-```python
-for item_id, sims in result.items():
-    item_name = item_name_map.get(str(item_id), 'Unknown')  # 转换为字符串查询
-```
-
-### 验证
-
-```bash
-# 重新运行
-python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10
-
-# 检查输出
-more output/i2i_swing_20251016.txt
-```
-
-应该看到：
-```
-1070176	商品名称A	2786217:0.4000
-2786217	商品名称B	1070176:0.4000
-```
-
----
-
-**更新时间**: 2025-10-16 20:30  
-**状态**: ✅ 完全修复
@@ -1,155 +0,0 @@
-# 最新更新 (2025-10-17)
-
-## 🎉 本次更新内容
-
-### 1. ✅ ES向量相似度 + on_sell_days_boost提权
-
-#### 功能
-- 基于Elasticsearch向量计算相似度（名称向量 + 图片向量）
-- 自动应用 `on_sell_days_boost` 提权（0.9~1.1）
-- 无需任何命令行参数，开箱即用
-
-#### 使用
-```bash
-python scripts/i2i_content_similar.py
-```
-
-### 2. ✅ 代码规范：统一使用 logger
-
-#### 变更
-- 移除所有 `print` 语句
-- 统一使用 `logger` 记录日志
-- 更好的日志级别控制
-
-### 3. ✅ run.sh 内存监控
-
-#### 功能
-- **25GB警告**: 打印警告日志，继续运行
-- **30GB终止**: 强制kill进程，防止OOM
-- **每10秒检查**: 实时监控内存使用
-- **详细日志**: `logs/memory_monitor.log`
-
-#### 使用
-```bash
-./run.sh
-```
-
-## 📋 快速开始
-
-### 1. 测试ES连接和向量
-```bash
-python scripts/test_es_connection.py
-```
-
-### 2. 测试内存监控
-```bash
-./test_memory_monitor.sh
-```
-
-### 3. 运行所有任务（含监控）
-```bash
-./run.sh
-```
-
-### 4. 查看监控日志
-```bash
-tail -f logs/memory_monitor.log
-```
-
-## 📊 生成的索引
-
-| 索引文件 | Redis Key | 提权 | TTL |
-|---------|-----------|------|-----|
-| `i2i_content_name_YYYYMMDD.txt` | `item:similar:content_name:{id}` | ✅ | 30天 |
-| `i2i_content_pic_YYYYMMDD.txt` | `item:similar:content_pic:{id}` | ✅ | 30天 |
-
-## 📚 文档
-
-| 文档 | 说明 |
-|------|------|
-| `QUICKSTART_NEW.md` | 5分钟快速开始 |
-| `ES_VECTOR_SIMILARITY.md` | ES向量技术详解 |
-| `RUN_SCRIPT_GUIDE.md` | 运行脚本使用指南 |
-| `MEMORY_MONITORING_UPDATE.md` | 内存监控详细说明 |
-| `FINAL_SUMMARY.md` | 完整更新总结 |
-
-## 🔍 关键特性
-
-### ES向量相似度
-```python
-# 自动应用提权
-base_score = knn_result['_score']
-boost = knn_result['on_sell_days_boost']  # 0.9~1.1
-final_score = base_score * boost
-```
-
-### 内存监控
-```bash
-# 自动监控每个任务
-python3 run_all.py &
-PID=$!
-check_memory $PID &  # 后台监控
-
-# 日志输出
-[2025-10-17 15:20:15] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB)
-[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB, 强制终止
-```
-
-## ⚠️ 重要说明
-
-### 向量相似度
-- ✅ 分数已包含 `on_sell_days_boost` 提权
-- ✅ 输出到文件和Redis的都是最终分数
-- ✅ 应用层无需再次应用提权
-
-### 内存监控
-- ⚠️ 默认阈值：25GB警告，30GB终止
-- ⚠️ 可在 `run.sh` 中修改阈值
-- ⚠️ 监控日志保存在 `logs/memory_monitor.log`
-
-### run_all.py 简化
-- ❌ 移除了所有 `--only-*`, `--skip-*` 参数
-- ✅ 只保留 `--debug` 参数
-- ✅ 配置集中在 `offline_config.py`
-
-## 🚀 一键运行
-
-```bash
-# 完整流程（含内存监控）
-cd /home/tw/recommendation/offline_tasks
-./run.sh
-
-# 输出:
-# ======================================================================
-# 开始运行离线任务 - 2025-10-17 14:00:00
-# 内存监控: 警告阈值=25GB, 强制终止阈值=30GB
-# ======================================================================
-# 
-# >>> 步骤1: 调试模式运行（小数据量）
-# ✓ 调试模式完成
-# 
-# >>> 步骤2: 生产模式运行（大数据量）
-# ✓ 生产模式完成
-# 
-# >>> 步骤3: 加载到Redis
-# ✓ Redis加载完成
-# 
-# ======================================================================
-# 所有任务完成 - 2025-10-17 16:30:00
-# ======================================================================
-```
-
-## 🎯 核心改进
-
-1. **更智能**: ES向量 + 上架天数提权
-2. **更简单**: 无需参数，一键运行
-3. **更安全**: 内存监控保护系统
-4. **更规范**: 统一使用logger
-5. **更完整**: 详细文档和测试工具
-
----
-
-**更新日期**: 2025-10-17  
-**版本**: v2.1  
-**状态**: ✅ 已完成，可投入使用
-
@@ -1,376 +0,0 @@
-# 内存监控功能更新
-
-## 更新日期
-2025-10-17
-
-## 更新内容
-
-### 1. ✅ 代码规范：移除 print，统一使用 logger
-
-#### 检查结果
-- ✅ `i2i_content_similar.py` - 已全部使用 logger
-- ✅ `test_es_connection.py` - print用于测试工具输出（符合预期）
-- ✅ 所有核心代码已使用 logger
-
-### 2. ✅ run.sh 添加内存监控功能
-
-#### 核心功能
-
-**内存监控函数**:
-```bash
-check_memory() {
-    local pid=$1
-    local threshold_warn=25  # 25GB警告阈值
-    local threshold_kill=30  # 30GB强制kill阈值
-    
-    while kill -0 $pid 2>/dev/null; do
-        获取进程内存使用（MB）
-        转换为GB
-        
-        if 内存 >= 30GB:
-            打印错误日志到终端和文件
-            强制kill进程
-            break
-        elif 内存 >= 25GB:
-            打印警告日志到终端和文件
-        
-        sleep 10秒检查一次
-    done
-}
-```
-
-#### 监控特性
-
-| 特性 | 说明 |
-|------|------|
-| **警告阈值** | 25GB - 打印警告但继续运行 |
-| **终止阈值** | 30GB - 强制kill进程 |
-| **检查频率** | 每10秒检查一次 |
-| **日志输出** | 终端 + `logs/memory_monitor.log` |
-| **自动清理** | 任务完成后自动终止监控 |
-
-#### 日志格式
-
-**警告日志**:
-```
-[2025-10-17 14:30:25] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12345
-```
-
-**强制终止日志**:
-```
-[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345
-```
-
-### 3. ✅ 增强的运行流程
-
-#### 更新后的执行流程
-
-```bash
-#!/bin/bash
-
-1. 定义内存监控函数
-2. 清理旧进程和输出
-3. 创建logs目录
-4. 显示开始信息（包含监控阈值）
-
-# 调试模式
-5. 启动调试任务（后台）
-6. 启动内存监控（后台）
-7. 等待任务完成
-8. 终止监控进程
-9. 检查退出码
-
-# 生产模式
-10. 启动生产任务（后台）
-11. 启动内存监控（后台）
-12. 等待任务完成
-13. 终止监控进程
-14. 检查退出码
-
-# 加载Redis
-15. 加载索引到Redis
-16. 检查退出码
-
-17. 显示完成信息
-```
-
-### 4. ✅ 新增文件
-
-| 文件 | 说明 |
-|------|------|
-| `run.sh` | 更新：添加内存监控 |
-| `RUN_SCRIPT_GUIDE.md` | 新增：运行脚本使用指南 |
-| `test_memory_monitor.sh` | 新增：内存监控测试脚本 |
-| `MEMORY_MONITORING_UPDATE.md` | 新增：本文档 |
-
-## 使用指南
-
-### 基本使用
-
-```bash
-# 1. 运行脚本（自动监控内存）
-cd /home/tw/recommendation/offline_tasks
-./run.sh
-
-# 2. 查看监控日志
-tail -f logs/memory_monitor.log
-
-# 3. 查看系统内存
-free -h
-```
-
-### 测试监控功能
-
-```bash
-# 运行测试脚本
-./test_memory_monitor.sh
-```
-
-### 自定义阈值
-
-编辑 `run.sh` 第8-9行：
-```bash
-local threshold_warn=25  # 修改警告阈值
-local threshold_kill=30  # 修改强制kill阈值
-```
-
-## 技术细节
-
-### 内存获取
-
-```bash
-# 获取进程内存（RSS，单位KB）
-ps -p $pid -o rss=
-
-# 转换为MB
-mem_mb=$(ps -p $pid -o rss= | awk '{print int($1/1024)}')
-
-# 转换为GB
-mem_gb=$(echo "scale=2; $mem_mb/1024" | bc)
-```
-
-### 进程检查
-
-```bash
-# 检查进程是否存在
-kill -0 $pid 2>/dev/null
-
-# 返回值:
-# 0 - 进程存在
-# 非0 - 进程不存在
-```
-
-### 强制终止
-
-```bash
-# 发送SIGKILL信号
-kill -9 $pid
-
-# 特点:
-# - 立即终止，不可捕获
-# - 不执行清理代码
-# - 确保进程被终止
-```
-
-## 输出示例
-
-### 正常运行（内存未超限）
-
-```
-======================================================================
-开始运行离线任务 - 2025-10-17 14:00:00
-内存监控: 警告阈值=25GB, 强制终止阈值=30GB
-======================================================================
-
->>> 步骤1: 调试模式运行（小数据量）
-调试任务 PID: 12345
-✓ 调试模式完成
-
->>> 步骤2: 生产模式运行（大数据量）
-生产任务 PID: 12346
-✓ 生产模式完成
-
->>> 步骤3: 加载到Redis
-✓ Redis加载完成
-
-======================================================================
-所有任务完成 - 2025-10-17 16:30:00
-======================================================================
-```
-
-### 内存警告（25GB-30GB）
-
-```
->>> 步骤2: 生产模式运行（大数据量）
-生产任务 PID: 12346
-[2025-10-17 15:20:15] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12346
-[2025-10-17 15:22:30] ⚠️  内存警告！当前使用: 27.80GB (>= 25GB), PID=12346
-[2025-10-17 15:24:45] ⚠️  内存警告！当前使用: 28.95GB (>= 25GB), PID=12346
-✓ 生产模式完成
-```
-
-### 内存超限（>=30GB）
-
-```
->>> 步骤2: 生产模式运行（大数据量）
-生产任务 PID: 12346
-[2025-10-17 15:20:15] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12346
-[2025-10-17 15:22:30] ⚠️  内存警告！当前使用: 28.80GB (>= 25GB), PID=12346
-[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12346
-✗ 生产模式失败，退出码: 137
-```
-
-## 监控日志示例
-
-`logs/memory_monitor.log`:
-```
-[2025-10-17 15:20:15] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12346
-[2025-10-17 15:22:30] ⚠️  内存警告！当前使用: 28.80GB (>= 25GB), PID=12346
-[2025-10-17 15:24:45] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12346
-```
-
-## 故障处理
-
-### 内存持续增长
-
-**现象**: 警告日志频繁出现，内存持续增长
-
-**原因**:
-- 数据量过大
-- 内存泄漏
-- 批处理大小不合理
-
-**解决方案**:
-1. 减小批处理大小
-2. 增加垃圾回收频率
-3. 优化算法减少内存占用
-4. 考虑分批运行
-
-### 进程被误杀
-
-**现象**: 任务未完成就被终止
-
-**原因**:
-- 阈值设置过低
-- 系统其他进程占用内存
-
-**解决方案**:
-1. 提高阈值（修改 run.sh）
-2. 优化代码减少内存使用
-3. 关闭不必要的系统进程
-
-### 监控不生效
-
-**检查清单**:
-- [ ] `bc` 命令是否安装：`which bc`
-- [ ] 脚本是否有执行权限：`ls -l run.sh`
-- [ ] logs目录是否存在：`ls -ld logs/`
-- [ ] 进程是否在后台运行：`ps aux | grep run_all`
-
-## 性能影响
-
-### 监控开销
-
-| 项目 | 影响 |
-|------|------|
-| CPU | < 0.1% (每10秒运行一次ps命令) |
-| 内存 | < 10MB (监控脚本本身) |
-| 磁盘I/O | 极小 (仅写日志) |
-
-### 建议
-
-- ✅ 检查频率10秒合理，不建议小于5秒
-- ✅ 警告阈值25GB为系统总内存的合理比例
-- ✅ 终止阈值30GB留有5GB缓冲空间
-- ⚠️ 根据实际情况调整阈值
-
-## 最佳实践
-
-### 1. 定期查看日志
-```bash
-# 每天检查
-cat logs/memory_monitor.log
-
-# 统计警告次数
-grep "⚠️" logs/memory_monitor.log | wc -l
-
-# 统计终止次数
-grep "❌" logs/memory_monitor.log | wc -l
-```
-
-### 2. 设置定时任务
-```bash
-# 每周一凌晨2点运行
-0 2 * * 1 /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1
-```
-
-### 3. 配置告警
-```bash
-# 在 run.sh 末尾添加
-if grep -q "❌" logs/memory_monitor.log; then
-    echo "内存超限告警" | mail -s "[告警] 离线任务内存超限" admin@example.com
-fi
-```
-
-### 4. 监控系统资源
-```bash
-# 安装监控工具
-apt install htop sysstat
-
-# 实时监控
-htop -p $(pgrep -f run_all.py)
-
-# 查看历史
-sar -r 1 10  # 内存使用情况
-```
-
-## 对比
-
-### 更新前
-```bash
-# 无内存监控
-python3 run_all.py --lookback_days 730 --top_n 50
-
-# 问题:
-# - 内存可能无限增长
-# - OOM导致系统崩溃
-# - 无法及时发现问题
-```
-
-### 更新后
-```bash
-# 自动内存监控
-./run.sh
-
-# 优势:
-# ✅ 25GB警告提醒
-# ✅ 30GB自动终止
-# ✅ 详细日志记录
-# ✅ 保护系统稳定
-```
-
-## 总结
-
-本次更新实现了：
-
-1. ✅ **代码规范化**: 统一使用logger，移除print
-2. ✅ **内存监控**: 25GB警告，30GB强制终止
-3. ✅ **自动化运行**: 集成监控到运行流程
-4. ✅ **日志记录**: 详细的监控日志
-5. ✅ **测试工具**: 提供测试脚本验证功能
-6. ✅ **完整文档**: 使用指南和故障处理
-
-### 核心价值
-
-- 🛡️ **保护系统**: 防止内存溢出导致系统崩溃
-- 📊 **实时监控**: 每10秒检查一次内存使用
-- 🔔 **及时告警**: 25GB警告，30GB终止
-- 📝 **日志完整**: 所有监控事件都有记录
-- 🔧 **易于调整**: 阈值和频率可轻松修改
-
----
-
-**更新完成时间**: 2025-10-17  
-**状态**: ✅ 已完成，可投入使用  
-**建议**: 先在测试环境验证后再用于生产
-
@@ -1,276 +0,0 @@
-# 推荐系统离线任务 - 项目总结
-
-## 项目概述
-
-本项目实现了一个完整的推荐系统离线任务框架，用于生成各种推荐索引。主要包括两大模块：
-
-1. **i2i 行为相似索引**：基于用户行为计算物品之间的相似度
-2. **兴趣点聚合索引**：按多维度聚合用户行为，生成不同场景的推荐列表
-
-## 技术架构
-
-### 数据来源
-- 数据库：SelectDB（兼容MySQL协议）
-- 主要表：
-  - `sensors_events`：用户行为事件表
-  - `prd_goods_sku`：商品SKU表
-
-### 算法实现
-
-#### 1. i2i 行为相似算法
-
-| 算法 | 原理 | 优势 | 适用场景 |
-|------|------|------|---------|
-| **Swing** | 基于用户共同行为的物品相似度，考虑用户重叠度 | 效果好，能发现深层关系 | 详情页推荐、相关商品 |
-| **Session W2V** | 基于用户会话序列训练Word2Vec | 能捕获序列关系 | 下一个可能感兴趣的商品 |
-| **DeepWalk** | 基于图随机游走训练Word2Vec | 能发现图结构特征 | 发现潜在关联商品 |
-
-#### 2. 兴趣点聚合
-
-**维度分类：**
-
-- **单维度**：
-  - 平台（PC/Mobile/App）
-  - 国家/销售区域
-  - 客户类型（零售商/批发商等）
-  - 二级分类
-  - 三级分类
-
-- **组合维度**：
-  - 平台 + 国家
-  - 平台 + 客户类型
-  - 国家 + 客户类型
-  - 平台 + 国家 + 客户类型
-
-**列表类型：**
-
-- **hot（热门）**：基于最近180天的高交互商品
-- **cart（加购）**：基于加购行为的高频商品
-- **new（新品）**：基于商品创建时间的新品
-- **global（全局）**：基于所有数据的综合排序
-
-## 核心特性
-
-### 1. 时间衰减
-- 使用指数衰减模型，越近期的行为权重越高
-- 衰减因子：0.95（每30天衰减一次）
-- 公式：`weight = decay_factor ^ (days / 30)`
-
-### 2. 行为权重
-不同行为类型赋予不同权重：
-
-| 行为类型 | 权重 | 说明 |
-|---------|------|------|
-| click | 1.0 | 点击 |
-| addToPool | 2.0 | 加入询盘池 |
-| addToCart | 3.0 | 加入购物车 |
-| contactFactory | 5.0 | 联系工厂 |
-| purchase | 10.0 | 购买 |
-
-### 3. 可配置参数
-所有参数集中在 `config/offline_config.py`，便于调整优化。
-
-## 文件清单
-
-### 核心代码
-
-```
-/home/tw/recommendation/
-├── db_service.py                              # 数据库连接服务
-├── requirements.txt                            # Python依赖包
-└── offline_tasks/
-    ├── config/
-    │   └── offline_config.py                  # 配置文件
-    ├── scripts/
-    │   ├── i2i_swing.py                       # Swing算法
-    │   ├── i2i_session_w2v.py                 # Session W2V算法
-    │   ├── i2i_deepwalk.py                    # DeepWalk算法
-    │   ├── interest_aggregation.py            # 兴趣点聚合
-    │   └── load_index_to_redis.py             # 加载索引到Redis
-    ├── run_all.py                              # 统一调度脚本
-    ├── test_connection.py                      # 连接测试脚本
-    ├── example_query_redis.py                  # Redis查询示例
-    ├── README.md                               # 详细文档
-    ├── QUICKSTART.md                           # 快速启动指南
-    └── PROJECT_SUMMARY.md                      # 本文档
-```
-
-### 输出目录
-
-```
-offline_tasks/
-├── output/                                     # 索引输出目录
-│   ├── i2i_swing_YYYYMMDD.txt
-│   ├── i2i_session_w2v_YYYYMMDD.txt
-│   ├── i2i_deepwalk_YYYYMMDD.txt
-│   ├── session_w2v_model_YYYYMMDD.model       # W2V模型
-│   ├── deepwalk_model_YYYYMMDD.model          # DeepWalk模型
-│   ├── item_graph_YYYYMMDD.txt                # 物品图结构
-│   ├── interest_aggregation_hot_YYYYMMDD.txt
-│   ├── interest_aggregation_cart_YYYYMMDD.txt
-│   ├── interest_aggregation_new_YYYYMMDD.txt
-│   └── interest_aggregation_global_YYYYMMDD.txt
-└── logs/                                       # 日志目录
-    ├── run_all_YYYYMMDD.log
-    └── ...
-```
-
-## 使用流程
-
-### 1. 环境准备
-```bash
-pip install -r requirements.txt
-```
-
-### 2. 测试连接
-```bash
-cd offline_tasks
-python test_connection.py
-```
-
-### 3. 运行离线任务
-```bash
-python run_all.py --lookback_days 730 --top_n 50
-```
-
-### 4. 加载索引到Redis
-```bash
-python scripts/load_index_to_redis.py --expire-days 7
-```
-
-### 5. 查询示例
-```bash
-python example_query_redis.py
-```
-
-## 数据格式
-
-### i2i索引格式
-```
-item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
-```
-
-示例：
-```
-123456 \t 商品A \t 234567:0.8523,345678:0.7842,456789:0.7234
-```
-
-### 兴趣点聚合索引格式
-```
-dimension_key \t item_id1:score1,item_id2:score2,...
-```
-
-示例：
-```
-platform:PC \t 12345:98.52,23456:87.34,34567:76.89
-country:US \t 45678:156.23,56789:142.87,67890:128.45
-platform_country:PC_US \t 78901:234.56,89012:198.76,90123:187.23
-```
-
-## 在线推荐场景
-
-### 场景1：详情页 - 大家都在看
-```
-用户浏览商品ID: 123456
-查询: i2i:swing:123456
-返回: 该商品的相似商品列表
-```
-
-### 场景2：首页 - 猜你喜欢
-```
-用户特征: PC端, 美国, 零售商
-组合查询:
-1. interest:hot:platform_country:PC_US
-2. interest:cart:customer_type:retailer
-3. 结合用户历史行为的i2i
-```
-
-### 场景3：搜索结果页 - 供应商推荐
-```
-用户搜索: 二级分类100
-查询: interest:global:category_level2:100
-返回: 该分类下的热门商品
-```
-
-## 性能指标
-
-### 数据量参考（730天数据）
-- 用户行为记录：约100万-1000万条
-- 商品数量：约10万-50万个
-- 生成索引：约5万-20万条
-
-### 运行时间（参考值）
-- Swing算法：2-4小时
-- Session W2V：30-60分钟
-- DeepWalk：1-2小时
-- 兴趣点聚合：30-60分钟
-- 总计：约5-8小时
-
-### 资源占用
-- CPU：8-16核
-- 内存：8-16GB
-- 磁盘：输出文件约500MB-2GB
-
-## 优化建议
-
-### 1. 算法层面
-- **Swing算法**：可以使用C++版本（已有实现），性能提升10倍
-- **并行化**：将不同算法分配到不同机器并行运行
-- **增量更新**：对于变化不大的索引，考虑增量更新
-
-### 2. 工程层面
-- **分布式计算**：使用Spark/Flink处理大规模数据
-- **缓存中间结果**：避免重复计算
-- **数据采样**：调试阶段使用采样数据
-
-### 3. 业务层面
-- **A/B测试**：对比不同算法的效果
-- **融合策略**：组合多个算法的结果
-- **实时更新**：结合实时计算补充离线索引
-
-## 后续扩展
-
-### 1. 新增算法
-- ItemCF（物品协同过滤）
-- Node2Vec（带权重的图游走）
-- Graph Neural Network（图神经网络）
-
-### 2. 新增维度
-- 价格区间
-- 品牌
-- 标签组合
-- 用户画像更多维度
-
-### 3. 实时化
-- 实时更新热门商品
-- 实时更新新品列表
-- 实时i2i相似度计算
-
-### 4. 个性化
-- 结合用户画像的个性化排序
-- 多目标优化（点击率、转化率、GMV）
-- 强化学习排序
-
-## 维护说明
-
-### 定期检查
-- 每周检查日志，确保任务正常运行
-- 每月检查索引质量，调整参数
-- 每季度评估算法效果，优化策略
-
-### 监控指标
-- 任务执行成功率
-- 索引生成数量
-- Redis命中率
-- 推荐点击率/转化率
-
-## 联系方式
-
-如有问题或建议，请联系推荐系统团队。
-
----
-
-**文档版本**: v1.0  
-**最后更新**: 2025-10-16  
-**作者**: 推荐系统团队
-
@@ -1,321 +0,0 @@
-# 快速开始 - 新版本
-
-## 🚀 5分钟快速上手
-
-### 1. 安装依赖
-
-```bash
-cd /home/tw/recommendation
-pip install -r requirements.txt
-```
-
-**新增依赖**: `elasticsearch>=8.0.0`
-
-### 2. 测试ES连接
-
-```bash
-cd offline_tasks
-python scripts/test_es_connection.py
-```
-
-如果看到 ✓ 表示测试通过。
-
-### 3. 运行所有任务
-
-```bash
-python run_all.py
-```
-
-就这么简单！不需要任何参数。
-
-### 4. 加载到Redis
-
-```bash
-python scripts/load_index_to_redis.py
-```
-
-## 📋 运行单个任务
-
-### i2i相似索引
-
-```bash
-# Swing算法
-python scripts/i2i_swing.py --lookback_days 30 --top_n 50 --time_decay
-
-# Session W2V
-python scripts/i2i_session_w2v.py --lookback_days 30 --top_n 50 --save_model
-
-# DeepWalk
-python scripts/i2i_deepwalk.py --lookback_days 30 --top_n 50 --save_model
-
-# 内容相似（ES向量）- 无需参数！
-python scripts/i2i_content_similar.py
-```
-
-### 兴趣聚合
-
-```bash
-python scripts/interest_aggregation.py --lookback_days 30 --top_n 1000
-```
-
-## 🎯 主要变化
-
-### 简化！简化！简化！
-
-#### 之前 (v1.0)
-```bash
-python run_all.py \
-  --lookback_days 30 \
-  --top_n 50 \
-  --skip-interest \
-  --only-content \
-  --debug
-```
-
-#### 现在 (v2.0)
-```bash
-python run_all.py
-# 或
-python run_all.py --debug  # 启用debug模式
-```
-
-### 内容相似索引
-
-#### 之前
-- 1个索引: `i2i_content_hybrid_*.txt`
-- 基于: 商品属性（分类、供应商等）
-- 参数: `--method hybrid --top_n 50`
-
-#### 现在
-- **2个索引**: 
-  - `i2i_content_name_*.txt` (名称向量)
-  - `i2i_content_pic_*.txt` (图片向量)
-- 基于: Elasticsearch深度学习向量
-- 参数: **无需参数！**
-
-## 📊 输出文件
-
-### 文件位置
-```
-offline_tasks/output/
-├── i2i_swing_20251017.txt          # Swing相似索引
-├── i2i_session_w2v_20251017.txt    # Session W2V相似索引
-├── i2i_deepwalk_20251017.txt       # DeepWalk相似索引
-├── i2i_content_name_20251017.txt   # 名称向量相似索引 ⭐新
-├── i2i_content_pic_20251017.txt    # 图片向量相似索引 ⭐新
-├── interest_aggregation_hot_20251017.txt    # 热门商品
-├── interest_aggregation_cart_20251017.txt   # 加购商品
-├── interest_aggregation_new_20251017.txt    # 新品
-└── interest_aggregation_global_20251017.txt # 全局热门
-```
-
-### 文件格式
-```
-item_id \t item_name \t similar_id1:score1,similar_id2:score2,...
-```
-
-## 🔍 查询示例
-
-### Python查询
-
-```python
-import redis
-import json
-
-# 连接Redis
-r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)
-
-# 1. 获取Swing相似商品
-similar = json.loads(r.get('item:similar:swing:123456'))
-# 返回: [[234567, 0.8523], [345678, 0.7842], ...]
-
-# 2. 获取名称向量相似商品 ⭐新
-similar = json.loads(r.get('item:similar:content_name:123456'))
-# 返回: [[234567, 0.9234], [345678, 0.8756], ...]
-
-# 3. 获取图片向量相似商品 ⭐新
-similar = json.loads(r.get('item:similar:content_pic:123456'))
-# 返回: [[567890, 0.8123], [678901, 0.7856], ...]
-
-# 4. 获取热门商品
-hot_items = json.loads(r.get('interest:hot:platform:PC'))
-# 返回: [123456, 234567, 345678, ...]
-```
-
-### Redis CLI查询
-
-```bash
-# 连接Redis
-redis-cli
-
-# 查看Swing相似商品
-GET item:similar:swing:123456
-
-# 查看名称向量相似商品 ⭐新
-GET item:similar:content_name:123456
-
-# 查看图片向量相似商品 ⭐新
-GET item:similar:content_pic:123456
-
-# 查看热门商品
-GET interest:hot:platform:PC
-```
-
-## ⚙️ 配置说明
-
-### ES配置 (i2i_content_similar.py)
-
-```python
-ES_CONFIG = {
-    'host': 'http://localhost:9200',
-    'index_name': 'spu',
-    'username': 'essa',
-    'password': '4hOaLaf41y2VuI8y'
-}
-```
-
-### 算法参数 (i2i_content_similar.py)
-
-```python
-TOP_N = 50          # 每个商品返回50个相似商品
-KNN_K = 100         # KNN查询返回100个候选
-KNN_CANDIDATES = 200  # 候选池大小200
-```
-
-### 全局配置 (offline_config.py)
-
-```python
-DEFAULT_LOOKBACK_DAYS = 30    # 回看天数
-DEFAULT_I2I_TOP_N = 50        # i2i Top N
-DEFAULT_INTEREST_TOP_N = 1000 # 兴趣聚合 Top N
-```
-
-## 🔧 故障排查
-
-### ES连接失败
-
-```bash
-# 1. 检查ES是否运行
-curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200
-
-# 2. 运行测试脚本
-python scripts/test_es_connection.py
-
-# 3. 检查配置
-# 编辑 scripts/i2i_content_similar.py 中的 ES_CONFIG
-```
-
-### 商品ID不存在
-
-测试脚本默认使用 `item_id = "3302275"`，如果不存在：
-
-```python
-# 编辑 test_es_connection.py
-test_item_id = "你的商品ID"
-```
-
-### Redis连接失败
-
-```bash
-# 检查Redis配置
-cat offline_tasks/config/offline_config.py | grep REDIS
-
-# 测试Redis连接
-redis-cli ping
-```
-
-### 文件不存在
-
-```bash
-# 检查output目录
-ls -lh offline_tasks/output/
-
-# 查看最新生成的文件
-ls -lht offline_tasks/output/ | head -10
-```
-
-## 📚 详细文档
-
-- **ES向量相似度**: `scripts/ES_VECTOR_SIMILARITY.md`
-- **更新说明**: `CONTENT_SIMILARITY_UPDATE.md`
-- **变更总结**: `CHANGES_SUMMARY.md`
-- **Redis规范**: `REDIS_DATA_SPEC.md`
-
-## 🎓 学习路径
-
-### 新用户
-1. 阅读本文档 ✓
-2. 运行 `test_es_connection.py`
-3. 运行 `run_all.py`
-4. 查看 `output/` 目录
-5. 加载到Redis并查询
-
-### 进阶使用
-1. 阅读 `ES_VECTOR_SIMILARITY.md`
-2. 了解向量相似度原理
-3. 优化ES查询性能
-4. 自定义算法参数
-
-### 开发者
-1. 阅读 `CONTENT_SIMILARITY_UPDATE.md`
-2. 了解技术架构
-3. 阅读源代码注释
-4. 贡献代码改进
-
-## 🚨 注意事项
-
-### ⚠️ 破坏性变化
-
-1. **i2i_content_similar.py 参数全部改变**
-   - 旧: `--method`, `--top_n`, `--debug`
-   - 新: 无参数
-
-2. **Redis Key格式改变**
-   - 旧: `item:similar:content:{item_id}`
-   - 新: `item:similar:content_name:{item_id}` 和 `item:similar:content_pic:{item_id}`
-
-3. **输出文件改变**
-   - 旧: `i2i_content_hybrid_*.txt`
-   - 新: `i2i_content_name_*.txt` 和 `i2i_content_pic_*.txt`
-
-### ✅ 向后兼容
-
-- Swing、W2V、DeepWalk 算法不受影响
-- 兴趣聚合不受影响
-- Redis加载器向后兼容
-- 其他i2i索引继续工作
-
-## 💡 最佳实践
-
-### 运行频率
-- **行为相似** (Swing, W2V, DeepWalk): 每天
-- **内容相似** (名称向量, 图片向量): 每周
-- **兴趣聚合**: 每天
-
-### Redis TTL
-- **行为相似**: 7天
-- **内容相似**: 30天
-- **兴趣聚合**: 3-7天
-
-### 性能优化
-1. 使用 `--debug` 模式调试
-2. 先用小数据集测试
-3. 定期清理过期数据
-4. 监控ES查询性能
-
-## 🎉 总结
-
-新版本大幅简化了使用，主要改进：
-
-1. ✅ **无需参数**: `run_all.py` 和 `i2i_content_similar.py` 无需参数
-2. ✅ **更强大**: 基于深度学习向量，更准确
-3. ✅ **多维度**: 名称 + 图片两个维度
-4. ✅ **更快**: ES KNN查询性能优秀
-5. ✅ **易维护**: 代码简洁，配置清晰
-
-开始使用新版本，享受更简单、更强大的推荐系统！
-
----
-
-**问题反馈**: 如有问题请查看详细文档或联系开发团队
-
@@ -1,128 +0,0 @@
-# Debug功能快速总结
-
-## ✅ 已完成的工作
-
-### 1. 核心组件
-
-| 组件 | 状态 | 说明 |
-|------|------|------|
-| `debug_utils.py` | ✅ | Debug工具库（369行） |
-| `offline_config.py` | ✅ | 新增DEBUG_CONFIG |
-| `i2i_swing.py` | ✅ | 完整debug支持 |
-| `run_all.py` | ✅ | 支持--debug参数传递 |
-
-### 2. Debug功能特性
-
-#### A. 详细日志输出
-```python
-# 自动记录：
-- 算法参数
-- 数据统计（行数、列数、类型、缺失值）
-- 处理进度（每N条显示）
-- 每个步骤的耗时
-- 数据分布（行为类型、用户数、商品数）
-- 中间结果采样
-```
-
-#### B. 明文索引文件
-```
-原始: 12345\t香蕉干\t67890:0.8567,11223:0.7234
-明文: [1] i2i:swing:12345(香蕉干)
-        1. ID:67890(芒果干) - Score:0.8567
-        2. ID:11223(菠萝干) - Score:0.7234
-```
-
-#### C. 日志文件
-```
-offline_tasks/logs/debug/i2i_swing_20251016_193000.log
-offline_tasks/output/debug/i2i_swing_20251016_readable.txt
-```
-
-## 🚀 使用方法
-
-### 单个脚本
-```bash
-# i2i_swing.py 已支持debug
-python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
-```
-
-### 所有任务
-```bash
-# run_all.py 已支持debug参数传递
-python3 run_all.py --lookback_days 7 --top_n 10 --debug
-```
-
-## 📊 输出示例
-
-### 控制台输出
-```
-2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
-2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数:
-2025-10-16 19:30:00 - i2i_swing - DEBUG -   alpha: 0.5
-2025-10-16 19:30:00 - i2i_swing - DEBUG -   top_n: 10
-2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录
-2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234
-2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布:
-2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToCart: 8520 (55.93%)
-2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345
-```
-
-### 明文文件示例
-```
-================================================================================
-明文索引文件
-生成时间: 2025-10-16 19:35:00
-描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7)
-总索引数: 2345
-================================================================================
-
-[1] i2i:swing:12345(香蕉干)
---------------------------------------------------------------------------------
-  1. ID:67890(芒果干) - Score:0.8567
-  2. ID:11223(菠萝干) - Score:0.7234
-  3. ID:44556(苹果干) - Score:0.6891
-```
-
-## 🔧 Debug工具函数
-
-| 函数 | 功能 |
-|------|------|
-| `setup_debug_logger()` | 设置debug日志 |
-| `log_dataframe_info()` | 记录DataFrame详情 |
-| `log_dict_stats()` | 记录字典统计 |
-| `save_readable_index()` | 保存明文索引 |
-| `fetch_name_mappings()` | 获取ID到名称映射 |
-| `log_algorithm_params()` | 记录算法参数 |
-| `log_processing_step()` | 记录处理步骤 |
-
-## 📝 待完成
-
-需要为以下脚本添加debug支持（使用相同模式）：
-- [ ] i2i_session_w2v.py
-- [ ] i2i_deepwalk.py
-- [ ] i2i_content_similar.py
-- [ ] interest_aggregation.py
-
-## 💡 快速测试
-
-```bash
-# 1. 测试debug工具
-cd /home/tw/recommendation/offline_tasks
-python3 -c "from scripts.debug_utils import *; print('✓ Debug utils OK')"
-
-# 2. 测试i2i_swing debug模式
-python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug
-
-# 3. 查看输出
-ls -lh logs/debug/
-ls -lh output/debug/
-```
-
-## 📖 完整文档
-
-详细使用指南：`DEBUG_GUIDE.md`
-
----
-
-**状态**: 🚧 进行中 (i2i_swing.py完成，其他脚本待更新)  
-**下一步**: 批量更新其他4个脚本的debug支持
@@ -1,303 +0,0 @@
-# 项目目录结构
-
-```
-/home/tw/recommendation/
-│
-├── db_service.py                    # 数据库连接服务（共享模块）
-├── requirements.txt                 # Python依赖包列表
-│
-├── offline_tasks/                   # 【离线任务主目录】
-│   │
-│   ├── config/                      # 配置目录
-│   │   └── offline_config.py       # 离线任务配置文件
-│   │                                  - 数据库配置
-│   │                                  - Redis配置
-│   │                                  - 算法参数配置
-│   │                                  - 时间配置
-│   │
-│   ├── scripts/                     # 脚本目录
-│   │   ├── i2i_swing.py            # Swing算法实现
-│   │   │                              输出: i2i_swing_YYYYMMDD.txt
-│   │   │
-│   │   ├── i2i_session_w2v.py      # Session Word2Vec算法
-│   │   │                              输出: i2i_session_w2v_YYYYMMDD.txt
-│   │   │                                   session_w2v_model_YYYYMMDD.model
-│   │   │
-│   │   ├── i2i_deepwalk.py         # DeepWalk算法
-│   │   │                              输出: i2i_deepwalk_YYYYMMDD.txt
-│   │   │                                   deepwalk_model_YYYYMMDD.model
-│   │   │                                   item_graph_YYYYMMDD.txt
-│   │   │
-│   │   ├── interest_aggregation.py # 兴趣点聚合索引生成
-│   │   │                              输出: interest_aggregation_hot_YYYYMMDD.txt
-│   │   │                                   interest_aggregation_cart_YYYYMMDD.txt
-│   │   │                                   interest_aggregation_new_YYYYMMDD.txt
-│   │   │                                   interest_aggregation_global_YYYYMMDD.txt
-│   │   │
-│   │   └── load_index_to_redis.py  # 索引加载到Redis
-│   │
-│   ├── output/                      # 输出目录（自动创建）
-│   │   ├── i2i_swing_*.txt         # Swing算法输出
-│   │   ├── i2i_session_w2v_*.txt   # Session W2V输出
-│   │   ├── i2i_deepwalk_*.txt      # DeepWalk输出
-│   │   ├── interest_aggregation_*  # 兴趣点聚合输出
-│   │   ├── *.model                 # 训练的模型文件
-│   │   └── item_graph_*.txt        # 物品图结构
-│   │
-│   ├── logs/                        # 日志目录（自动创建）
-│   │   ├── run_all_*.log           # 总调度日志
-│   │   ├── load_redis.log          # Redis加载日志
-│   │   └── cron.log                # 定时任务日志
-│   │
-│   ├── run_all.py                   # 【主调度脚本】
-│   │                                  统一运行所有离线任务
-│   │
-│   ├── install.sh                   # 安装脚本
-│   │                                  自动安装依赖和初始化
-│   │
-│   ├── test_connection.py           # 连接测试脚本
-│   │                                  测试数据库和Redis连接
-│   │
-│   ├── example_query_redis.py       # Redis查询示例
-│   │                                  演示如何查询索引
-│   │
-│   ├── README.md                    # 详细文档
-│   ├── QUICKSTART.md                # 快速开始指南
-│   ├── PROJECT_SUMMARY.md           # 项目总结
-│   └── STRUCTURE.md                 # 本文档
-│
-├── item_sim.py                      # 原有的物品相似度脚本（参考）
-├── hot/                             # 原有的热门商品模块（参考）
-├── collaboration/                   # 原有的协同过滤模块（参考）
-└── graphembedding/                  # 原有的图嵌入模块（参考）
-```
-
-## 数据流向图
-
-```
-┌─────────────────┐
-│   数据源         │
-│  (SelectDB)     │
-└────────┬────────┘
-         │
-         │ SQL查询
-         │
-         ▼
-┌─────────────────────────────────────────────────────────┐
-│                    离线任务处理                          │
-│                                                          │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
-│  │ Swing算法    │  │ Session W2V  │  │ DeepWalk算法 │  │
-│  │              │  │              │  │              │  │
-│  │ 用户行为共现  │  │ 会话序列     │  │ 图随机游走   │  │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
-│         │                 │                 │           │
-│         └─────────────────┴─────────────────┘           │
-│                           │                              │
-│                           │ i2i相似度索引                │
-│                           ▼                              │
-│                  ┌─────────────────┐                     │
-│                  │  输出文件(.txt) │                     │
-│                  └─────────────────┘                     │
-│                                                          │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │           兴趣点聚合                              │   │
-│  │                                                   │   │
-│  │  按维度分组: 平台/国家/客户类型/分类              │   │
-│  │  按类型分组: 热门/加购/新品/全局                  │   │
-│  │  时间衰减 + 行为权重                              │   │
-│  └────────────────────┬─────────────────────────────┘   │
-│                       │                                  │
-│                       │ 多维度索引                       │
-│                       ▼                                  │
-│              ┌─────────────────┐                         │
-│              │  输出文件(.txt) │                         │
-│              └─────────────────┘                         │
-└─────────────────────────────────────────────────────────┘
-                       │
-                       │ 加载
-                       ▼
-              ┌─────────────────┐
-              │     Redis        │
-              │   (在线索引)     │
-              └────────┬────────┘
-                       │
-                       │ 查询
-                       ▼
-              ┌─────────────────┐
-              │   在线推荐服务   │
-              │                  │
-              │ - 详情页推荐     │
-              │ - 首页推荐       │
-              │ - 搜索推荐       │
-              └──────────────────┘
-```
-
-## 核心模块说明
-
-### 1. 配置模块
-**文件**: `config/offline_config.py`
-
-**职责**:
-- 数据库连接配置
-- Redis连接配置
-- 算法超参数配置
-- 行为权重配置
-- 时间范围配置
-
-### 2. i2i相似度模块
-
-#### 2.1 Swing算法
-**文件**: `scripts/i2i_swing.py`
-
-**输入**: 用户行为数据（user_id, item_id, event_type, create_time）
-
-**核心逻辑**:
-```python
-# 对于物品i和j，计算它们的Swing相似度
-for user_u in common_users:
-    for user_v in common_users:
-        common_items = items_u ∩ items_v
-        sim(i, j) += 1 / (alpha + |common_items|)
-```
-
-**输出**: `i2i_swing_YYYYMMDD.txt`
-```
-item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
-```
-
-#### 2.2 Session Word2Vec
-**文件**: `scripts/i2i_session_w2v.py`
-
-**输入**: 用户会话序列
-
-**核心逻辑**:
-1. 按时间间隔切分用户会话
-2. 训练Word2Vec模型
-3. 计算物品向量相似度
-
-**输出**: 
-- `i2i_session_w2v_YYYYMMDD.txt`
-- `session_w2v_model_YYYYMMDD.model`
-
-#### 2.3 DeepWalk
-**文件**: `scripts/i2i_deepwalk.py`
-
-**输入**: 用户-物品交互数据
-
-**核心逻辑**:
-1. 构建物品共现图
-2. 执行随机游走生成序列
-3. 训练Word2Vec模型
-4. 计算物品向量相似度
-
-**输出**:
-- `i2i_deepwalk_YYYYMMDD.txt`
-- `deepwalk_model_YYYYMMDD.model`
-- `item_graph_YYYYMMDD.txt`
-
-### 3. 兴趣点聚合模块
-**文件**: `scripts/interest_aggregation.py`
-
-**输入**: 用户行为数据 + 用户特征
-
-**核心逻辑**:
-```python
-# 按维度聚合
-for each behavior:
-    weight = behavior_weight * time_weight
-    aggregations[dimension_key][item_id] += weight
-
-# 排序并输出top N
-for dimension_key, items in aggregations:
-    output top_n items sorted by weight
-```
-
-**维度组合**:
-- 单维度: platform, country, customer_type, category_level2, category_level3
-- 组合维度: platform_country, platform_customer, country_customer, platform_country_customer
-
-**列表类型**:
-- hot: 最近180天高交互
-- cart: 加购行为
-- new: 新品（最近90天上架）
-- global: 全局（所有数据）
-
-**输出**: 
-- `interest_aggregation_hot_YYYYMMDD.txt`
-- `interest_aggregation_cart_YYYYMMDD.txt`
-- `interest_aggregation_new_YYYYMMDD.txt`
-- `interest_aggregation_global_YYYYMMDD.txt`
-
-### 4. Redis加载模块
-**文件**: `scripts/load_index_to_redis.py`
-
-**职责**: 将生成的索引文件加载到Redis
-
-**Redis Key格式**:
-- i2i索引: `i2i:{algorithm}:{item_id}`
-- 兴趣点索引: `interest:{list_type}:{dimension_key}`
-
-**示例**:
-```
-i2i:swing:123456 -> "234567:0.8523,345678:0.7842,..."
-interest:hot:platform:PC -> "12345:98.52,23456:87.34,..."
-```
-
-### 5. 统一调度模块
-**文件**: `run_all.py`
-
-**职责**: 按顺序运行所有离线任务
-
-**执行流程**:
-1. 运行Swing算法
-2. 运行Session W2V
-3. 运行DeepWalk
-4. 运行兴趣点聚合
-5. 记录日志和统计
-
-## 使用场景映射
-
-| 业务场景 | 使用的索引 | Redis Key示例 |
-|---------|-----------|--------------|
-| 详情页 - 大家都在看 | i2i相似度 | `i2i:swing:{item_id}` |
-| 首页 - 猜你喜欢 | 兴趣点聚合 | `interest:hot:platform_country:{platform}_{country}` |
-| 搜索 - 相关推荐 | 兴趣点聚合 + i2i | `interest:global:category_level2:{cat_id}` |
-| 购物车 - 可能喜欢 | 兴趣点聚合(cart) | `interest:cart:customer_type:{type}` |
-| 新品推荐 | 兴趣点聚合(new) | `interest:new:platform:{platform}` |
-
-## 配置调优参数
-
-### 时间相关
-- `LOOKBACK_DAYS`: 730 (2年)
-- `RECENT_DAYS`: 180 (热门商品统计)
-- `NEW_DAYS`: 90 (新品定义)
-- `decay_factor`: 0.95 (时间衰减)
-
-### 算法相关
-- Swing `alpha`: 0.5
-- W2V `vector_size`: 128
-- W2V `window_size`: 5
-- DeepWalk `num_walks`: 10
-- DeepWalk `walk_length`: 40
-
-### 输出相关
-- i2i `top_n`: 50
-- 兴趣点 `top_n`: 1000
-
-## 性能优化要点
-
-1. **Swing算法**: 使用C++版本可提升10倍性能
-2. **并行化**: 将不同算法分配到不同机器
-3. **增量更新**: 只更新变化的部分
-4. **数据采样**: 调试时使用采样数据
-5. **批量加载**: Redis使用pipeline批量加载
-
-## 监控指标
-
-- 任务执行时间
-- 生成索引数量
-- Redis内存占用
-- 推荐点击率
-- 推荐转化率
-
@@ -1,205 +0,0 @@
-# 配置参数调整指南
-
-## 📝 概述
-
-所有默认参数现在都集中在配置文件中，便于统一管理和调整。
-
-## 🎯 主要默认参数
-
-### 在 `config/offline_config.py` 中配置：
-
-```python
-# 时间配置
-DEFAULT_LOOKBACK_DAYS = 30    # 默认回看天数
-DEFAULT_RECENT_DAYS = 7       # 默认最近天数
-
-# i2i算法参数
-DEFAULT_I2I_TOP_N = 50        # 默认返回Top N个相似商品
-
-# 兴趣聚合参数
-DEFAULT_INTEREST_TOP_N = 1000  # 默认每个key返回Top N个商品
-```
-
-## 🔧 调试与生产切换
-
-### 调试阶段（当前配置）
-
-```python
-DEFAULT_LOOKBACK_DAYS = 30    # 30天数据，快速验证
-DEFAULT_RECENT_DAYS = 7       # 7天最近数据
-DEFAULT_I2I_TOP_N = 50        # Top 50
-DEFAULT_INTEREST_TOP_N = 1000 # Top 1000
-```
-
-**预估运行时间**：30-60分钟  
-**内存占用**：2-4GB
-
-### 生产环境配置
-
-```python
-DEFAULT_LOOKBACK_DAYS = 730   # 2年历史数据，更准确
-DEFAULT_RECENT_DAYS = 180     # 半年最近数据
-DEFAULT_I2I_TOP_N = 50        # Top 50
-DEFAULT_INTEREST_TOP_N = 1000 # Top 1000
-```
-
-**预估运行时间**：6-10小时  
-**内存占用**：8-16GB
-
-## 🚀 使用方式
-
-### 1. 使用默认配置运行
-
-```bash
-# 使用配置文件中的默认值（当前为30天）
-python3 run_all.py
-```
-
-### 2. 临时覆盖默认值
-
-```bash
-# 临时使用不同的参数，不修改配置文件
-python3 run_all.py --lookback_days 7 --top_n 20
-```
-
-### 3. 修改配置文件（推荐）
-
-编辑 `config/offline_config.py`：
-
-```python
-# 调试完成后，改为生产配置
-DEFAULT_LOOKBACK_DAYS = 730
-DEFAULT_RECENT_DAYS = 180
-```
-
-然后运行：
-
-```bash
-python3 run_all.py
-```
-
-## 📊 各脚本的默认参数
-
-所有脚本都会从配置文件读取默认值：
-
-| 脚本 | 参数 | 默认值 | 来源 |
-|------|------|--------|------|
-| `i2i_swing.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` |
-| `i2i_swing.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` |
-| `i2i_session_w2v.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` |
-| `i2i_session_w2v.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` |
-| `i2i_deepwalk.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` |
-| `i2i_deepwalk.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` |
-| `i2i_content_similar.py` | `--top_n` | 50 | `DEFAULT_I2I_TOP_N` |
-| `interest_aggregation.py` | `--lookback_days` | 30 | `DEFAULT_LOOKBACK_DAYS` |
-| `interest_aggregation.py` | `--top_n` | 1000 | `DEFAULT_INTEREST_TOP_N` |
-
-## 💡 调试建议
-
-### 第一次运行（验证流程）
-
-```bash
-# 使用最小数据量快速验证
-python3 run_all.py --lookback_days 7 --top_n 10
-```
-
-### 第二次运行（调试参数）
-
-```python
-# 修改配置文件为30天
-DEFAULT_LOOKBACK_DAYS = 30
-```
-
-```bash
-python3 run_all.py
-```
-
-### 第三次运行（生产环境）
-
-```python
-# 修改配置文件为730天
-DEFAULT_LOOKBACK_DAYS = 730
-DEFAULT_RECENT_DAYS = 180
-```
-
-```bash
-python3 run_all.py
-```
-
-## 🔍 其他可调整的配置
-
-### i2i算法详细配置
-
-在 `offline_config.py` 的 `I2I_CONFIG` 中：
-
-```python
-I2I_CONFIG = {
-    'swing': {
-        'alpha': 0.5,           # swing算法的alpha参数
-        'threshold1': 0.5,      # 交互强度阈值1
-        'threshold2': 0.5,      # 交互强度阈值2
-        'max_sim_list_len': 300,  # 最大相似列表长度
-        'top_n': 50,            # 输出top N个相似商品
-    },
-    # ...其他算法配置
-}
-```
-
-### 兴趣聚合详细配置
-
-```python
-INTEREST_AGGREGATION_CONFIG = {
-    'top_n': 1000,              # 每个key生成前N个商品
-    'time_decay_factor': 0.95,  # 时间衰减因子（每30天）
-    'min_interaction_count': 2,  # 最小交互次数
-    
-    'behavior_weights': {
-        'click': 1.0,
-        'addToCart': 3.0,
-        'addToPool': 2.0,
-        'contactFactory': 5.0,
-        'purchase': 10.0,
-    },
-}
-```
-
-## 📌 注意事项
-
-1. **调试优先**：先用小数据量（7-30天）验证流程
-2. **逐步扩大**：确认无误后再增加到生产数据量
-3. **监控资源**：注意内存和磁盘空间使用情况
-4. **保存配置**：在配置文件中注释记录不同场景的参数值
-
-## 🎯 快速切换环境
-
-创建不同的配置副本：
-
-```bash
-# 备份当前配置
-cp config/offline_config.py config/offline_config_debug.py
-cp config/offline_config.py config/offline_config_prod.py
-
-# 使用不同配置
-cp config/offline_config_debug.py config/offline_config.py  # 调试模式
-cp config/offline_config_prod.py config/offline_config.py   # 生产模式
-```
-
-## ✅ 验证配置
-
-查看当前默认值：
-
-```bash
-python3 -c "from config.offline_config import *; print(f'LOOKBACK_DAYS: {DEFAULT_LOOKBACK_DAYS}')"
-```
-
-查看帮助信息：
-
-```bash
-python3 run_all.py --help
-```
-
----
-
-**配置文件位置**: `config/offline_config.py`  
-**当前默认配置**: 30天调试模式  
-**建议**: 调试通过后修改为730天生产模式
@@ -28,7 +28,7 @@ os.makedirs(LOG_DIR, exist_ok=True)
 # ============================================================================
  
 # 时间配置（建议先用小数值调试，确认无误后再改为大数值）
-DEFAULT_LOOKBACK_DAYS = 730    # 默认回看天数（调试用30天，生产可改为730天）
+DEFAULT_LOOKBACK_DAYS = 400    # 默认回看天数（调试用30天，生产可改为730天）
 DEFAULT_RECENT_DAYS = 180       # 默认最近天数（调试用7天，生产可改为180天）
  
 # i2i算法默认参数
@@ -0,0 +1,79 @@
+# 推荐系统离线任务文档中心
+
+本目录包含推荐系统所有重要文档。
+
+## 📚 文档目录
+
+### 快速开始
+
+- **[从这里开始.md](./从这里开始.md)** - 新手入门指南，了解项目结构和基本概念
+- **[快速开始.md](./快速开始.md)** - 快速运行离线任务的步骤
+- **[Swing快速开始.md](../collaboration/Swing快速开始.md)** - C++ Swing算法快速使用指南
+
+### 使用指南
+
+- **[Swing算法使用指南.md](./Swing算法使用指南.md)** - 详细的Swing算法使用文档
+- **[运行脚本指南.md](./运行脚本指南.md)** - 所有离线任务脚本的使用说明
+- **[调试指南.md](./调试指南.md)** - Debug模式和日志使用说明
+
+### 数据规范
+
+- **[离线索引数据规范.md](./离线索引数据规范.md)** - 所有离线索引的格式和说明
+- **[Redis数据规范.md](./Redis数据规范.md)** - Redis中数据的key格式和结构
+- **[完整索引列表.md](./完整索引列表.md)** - 系统中所有索引的完整清单
+
+### 配置说明
+
+- **[数据库配置说明.md](./数据库配置说明.md)** - 数据库连接和表结构说明
+- **配置文件**: `../config/offline_config.py` - 所有可配置参数
+
+### 实现总结
+
+- **[Swing实现总结.md](./Swing实现总结.md)** - C++ Swing集成实现的完整说明
+
+### 维护文档
+
+- **[故障排查指南.md](./故障排查指南.md)** - 常见问题和解决方案
+- **[更新日志.md](./更新日志.md)** - 系统更新历史
+
+## 📂 相关文档
+
+### 其他模块文档
+
+- **Collaboration模块**: `../collaboration/README.md` - C++ 协同过滤算法
+- **GraphEmbedding模块**: 
+  - Session W2V: `../graphembedding/session_w2v/README.md`
+  - DeepWalk: `../graphembedding/deepwalk/README.md`
+- **Hot模块**: `../hot/README.md` - 热门商品推荐
+
+### 项目README
+
+- **项目根目录**: `../../README.md` - 项目总览
+- **离线任务**: `../README.md` - 离线任务模块说明
+
+## 🎯 文档使用建议
+
+### 新用户
+
+1. 先阅读 **[从这里开始.md](./从这里开始.md)** 了解整体架构
+2. 然后看 **[快速开始.md](./快速开始.md)** 快速运行系统
+3. 需要时查阅具体的使用指南和数据规范
+
+### 开发人员
+
+1. 查看 **[运行脚本指南.md](./运行脚本指南.md)** 了解所有脚本
+2. 参考 **[调试指南.md](./调试指南.md)** 进行调试
+3. 遵循 **数据规范** 文档进行开发
+
+### 运维人员
+
+1. 配置前先看 **[数据库配置说明.md](./数据库配置说明.md)**
+2. 遇到问题查看 **[故障排查指南.md](./故障排查指南.md)**
+3. 了解 **[Redis数据规范.md](./Redis数据规范.md)** 便于维护
+
+## 📝 文档更新
+
+所有文档由项目维护者更新。如有疑问或发现错误，请联系团队。
+
+**最后更新**: 2024-10-17
+
@@ -0,0 +1,306 @@
+# Redis数据灌入规范
+
+## 📋 数据灌入概述
+
+将离线生成的推荐索引加载到Redis，供在线系统实时查询使用。
+
+## 🔑 Redis Key规范
+
+### 通用规则
+```
+{namespace}:{function}:{algorithm}:{identifier}
+```
+
+- `namespace`: 业务命名空间（item, user, interest等）
+- `function`: 功能类型（similar, feature, hot等）
+- `algorithm`: 算法名称（swing, w2v, deepwalk等）
+- `identifier`: 具体标识（item_id, dimension_key等）
+
+## 📊 数据灌入规范表
+
+| 模块名称 | 源数据地址 | 格式描述 | RedisKey模板 | RedisValue格式 | TTL |
+|---------|-----------|---------|-------------|---------------|-----|
+| **i2i_swing** | `output/i2i_swing_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:swing:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
+| **i2i_session_w2v** | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:w2v:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
+| **i2i_deepwalk** | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:deepwalk:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
+| **i2i_content_name** | `output/i2i_content_name_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_name:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 |
+| **i2i_content_pic** | `output/i2i_content_pic_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_pic:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 |
+| **interest_hot** | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:hot:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
+| **interest_cart** | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:cart:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
+| **interest_new** | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:new:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
+| **interest_global** | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:global:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 7天 |
+
+## 📝 详细说明
+
+### 1. i2i相似度索引
+
+#### 源数据格式
+```
+12345	香蕉干	67890:0.8567,11223:0.7234,44556:0.6891
+```
+
+#### Redis存储
+
+**Key**: `item:similar:swing:12345`
+
+**Value** (JSON格式):
+```json
+[[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]
+```
+
+**Value** (序列化后):
+```python
+import json
+value = json.dumps([[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]])
+# 存储: "[[67890,0.8567],[11223,0.7234],[44556,0.6891]]"
+```
+
+#### 查询示例
+```python
+import redis
+import json
+
+r = redis.Redis(host='localhost', port=6379, db=0)
+
+# 获取商品12345的相似商品（Swing算法）
+similar_items = json.loads(r.get('item:similar:swing:12345'))
+# 返回: [[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]
+
+# 获取Top5相似商品
+top_5 = similar_items[:5]
+```
+
+### 2. 兴趣点聚合索引
+
+#### 源数据格式
+```
+platform:pc	12345,67890,11223,44556,22334
+category_level2:200	67890,12345,22334,55667,11223
+```
+
+#### Redis存储
+
+**Key**: `interest:hot:platform:pc`
+
+**Value** (JSON格式):
+```json
+[12345, 67890, 11223, 44556, 22334]
+```
+
+**Value** (序列化后):
+```python
+import json
+value = json.dumps([12345, 67890, 11223, 44556, 22334])
+# 存储: "[12345,67890,11223,44556,22334]"
+```
+
+#### 查询示例
+```python
+import redis
+import json
+
+r = redis.Redis(host='localhost', port=6379, db=0)
+
+# 获取PC平台的热门商品
+hot_items = json.loads(r.get('interest:hot:platform:pc'))
+# 返回: [12345, 67890, 11223, 44556, 22334]
+
+# 获取Top10热门商品
+top_10 = hot_items[:10]
+```
+
+## 🔄 数据加载流程
+
+### 1. 加载i2i索引
+
+```python
+def load_i2i_index(file_path, algorithm_name, redis_client, expire_seconds=604800):
+    """
+    加载i2i相似度索引到Redis
+    
+    Args:
+        file_path: 索引文件路径
+        algorithm_name: 算法名称（swing, w2v, deepwalk, content）
+        redis_client: Redis客户端
+        expire_seconds: 过期时间（秒），默认7天
+    """
+    import json
+    
+    count = 0
+    with open(file_path, 'r', encoding='utf-8') as f:
+        for line in f:
+            parts = line.strip().split('\t')
+            if len(parts) < 3:
+                continue
+            
+            item_id = parts[0]
+            similar_str = parts[2]  # similar_id1:score1,similar_id2:score2,...
+            
+            # 解析相似商品
+            similar_items = []
+            for pair in similar_str.split(','):
+                if ':' in pair:
+                    sim_id, score = pair.split(':')
+                    similar_items.append([int(sim_id), float(score)])
+            
+            # 存储到Redis
+            redis_key = f"item:similar:{algorithm_name}:{item_id}"
+            redis_value = json.dumps(similar_items)
+            
+            redis_client.set(redis_key, redis_value)
+            redis_client.expire(redis_key, expire_seconds)
+            
+            count += 1
+    
+    return count
+```
+
+### 2. 加载兴趣聚合索引
+
+```python
+def load_interest_index(file_path, list_type, redis_client, expire_seconds=259200):
+    """
+    加载兴趣点聚合索引到Redis
+    
+    Args:
+        file_path: 索引文件路径
+        list_type: 列表类型（hot, cart, new, global）
+        redis_client: Redis客户端
+        expire_seconds: 过期时间（秒），默认3天
+    """
+    import json
+    
+    count = 0
+    with open(file_path, 'r', encoding='utf-8') as f:
+        for line in f:
+            parts = line.strip().split('\t')
+            if len(parts) != 2:
+                continue
+            
+            dimension_key = parts[0]  # platform:pc
+            item_ids_str = parts[1]   # 12345,67890,11223,...
+            
+            # 解析商品ID列表
+            item_ids = [int(item_id) for item_id in item_ids_str.split(',')]
+            
+            # 存储到Redis
+            redis_key = f"interest:{list_type}:{dimension_key}"
+            redis_value = json.dumps(item_ids)
+            
+            redis_client.set(redis_key, redis_value)
+            redis_client.expire(redis_key, expire_seconds)
+            
+            count += 1
+    
+    return count
+```
+
+## 🚀 快速加载命令
+
+### 加载所有索引
+```bash
+cd /home/tw/recommendation/offline_tasks
+
+# 加载所有索引（使用今天的数据）
+python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379
+
+# 加载指定日期的索引
+python3 scripts/load_index_to_redis.py --date 20251016 --redis-host localhost
+
+# 只加载i2i索引
+python3 scripts/load_index_to_redis.py --load-i2i --redis-host localhost
+
+# 只加载兴趣聚合索引
+python3 scripts/load_index_to_redis.py --load-interest --redis-host localhost
+```
+
+### 验证数据
+```bash
+# 连接Redis
+redis-cli
+
+# 检查key数量
+DBSIZE
+
+# 查看某个商品的相似推荐
+GET item:similar:swing:12345
+
+# 查看平台热门商品
+GET interest:hot:platform:pc
+
+# 查看所有i2i相关的key
+KEYS item:similar:*
+
+# 查看所有interest相关的key
+KEYS interest:*
+
+# 检查key的过期时间
+TTL item:similar:swing:12345
+```
+
+## 📊 数据统计
+
+### Redis内存占用估算
+
+| 索引类型 | Key数量 | 单条Value大小 | 总内存 |
+|---------|--------|-------------|--------|
+| i2i_swing | 50,000 | ~500B | ~25MB |
+| i2i_w2v | 50,000 | ~500B | ~25MB |
+| i2i_deepwalk | 50,000 | ~500B | ~25MB |
+| i2i_content_name | 50,000 | ~500B | ~25MB |
+| i2i_content_pic | 50,000 | ~500B | ~25MB |
+| interest_hot | 10,000 | ~1KB | ~10MB |
+| interest_cart | 10,000 | ~1KB | ~10MB |
+| interest_new | 5,000 | ~1KB | ~5MB |
+| interest_global | 10,000 | ~1KB | ~10MB |
+| **总计** | **270,000** | - | **~160MB** |
+
+### 过期策略
+
+| 索引类型 | TTL | 原因 |
+|---------|-----|------|
+| i2i行为相似 | 7天 | 用户行为变化快，需要频繁更新 |
+| i2i内容相似 | 30天 | 商品属性变化慢，可以保留更久 |
+| 热门/加购 | 3天 | 热度变化快，需要及时更新 |
+| 新品 | 3天 | 新品概念有时效性 |
+| 全局热门 | 7天 | 相对稳定，可以保留更久 |
+
+## ⚠️ 注意事项
+
+1. **原子性**: 使用Pipeline批量写入，提高性能
+2. **过期时间**: 合理设置TTL，避免过期数据
+3. **内存管理**: 定期清理过期key，监控内存使用
+4. **数据版本**: 使用日期标记，支持数据回滚
+5. **容错处理**: 加载失败时不影响线上服务
+6. **监控告警**: 监控加载成功率、Redis内存、查询延迟
+
+## 🔍 监控指标
+
+### 数据质量指标
+```python
+# 检查加载成功率
+total_keys = redis_client.dbsize()
+expected_keys = 245000
+success_rate = total_keys / expected_keys * 100
+
+# 检查数据完整性
+sample_keys = [
+    'item:similar:swing:12345',
+    'interest:hot:platform:pc'
+]
+for key in sample_keys:
+    if not redis_client.exists(key):
+        print(f"Missing key: {key}")
+```
+
+### 性能指标
+- 加载耗时: < 5分钟
+- 内存占用: < 200MB
+- 查询延迟: < 1ms
+- 成功率: > 99%
+
+## 🔗 相关文档
+
+- **离线索引规范**: `OFFLINE_INDEX_SPEC.md`
+- **API接口文档**: `RECOMMENDATION_API.md`
+- **运维手册**: `OPERATIONS.md`
@@ -0,0 +1,375 @@
+# Swing算法实现总结
+
+## 完成的任务
+
+本次实现完成了以下功能：
+
+### 1. Session生成脚本 ✓
+
+**文件**: `offline_tasks/scripts/generate_session.py`
+
+**功能**:
+- 从数据库提取用户行为数据
+- 聚合用户session（按商品维度累加权重）
+- 支持两种输出格式：
+  - 标准格式：`uid \t {"item_id":score,...}`
+  - C++格式：`{"item_id":score,...}` （每行一个用户）
+
+**主要参数**:
+- `--lookback_days`: 回看天数（默认730天）
+- `--format`: 输出格式（standard/cpp/both）
+- `--output`: 输出文件路径
+- `--debug`: 启用debug模式
+
+**使用示例**:
+```bash
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/generate_session.py --lookback_days 730 --format both
+```
+
+### 2. Swing运行脚本 ✓
+
+**文件**: `collaboration/run.sh`
+
+**改进内容**:
+- ✓ 适配新的数据路径（`../offline_tasks/output/`）
+- ✓ 自动检测session文件格式（带uid或纯json）
+- ✓ 增加配置区域，便于修改参数
+- ✓ 添加错误检查和友好的输出信息
+- ✓ 自动调用debug脚本生成可读文件
+- ✓ 支持自定义Python环境
+
+**配置项**:
+```bash
+SESSION_DATA_DIR="../offline_tasks/output"  # session文件目录
+ALPHA=0.7          # Swing alpha参数
+THRESHOLD1=1       # 交互强度阈值1
+THRESHOLD2=3       # 交互强度阈值2
+THREAD_NUM=4       # 线程数
+SHOW_PROGRESS=1    # 显示进度
+PYTHON_CMD="python3"  # Python命令
+```
+
+**执行流程**:
+1. 编译C++程序
+2. 查找session文件
+3. 运行Swing算法（多线程）
+4. 合并结果
+5. 生成可读版本（自动调用debug脚本）
+
+### 3. Debug脚本 ✓
+
+**文件**: `offline_tasks/scripts/add_names_to_swing.py`
+
+**功能**:
+- 读取Swing算法输出结果
+- 从数据库获取商品名称映射
+- 生成可读版本：`item_id:name \t similar_id1:name1:score1,...`
+
+**使用示例**:
+```bash
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/add_names_to_swing.py \
+    ../collaboration/output/swing_similar.txt \
+    ../collaboration/output/swing_similar_readable.txt \
+    --debug
+```
+
+### 4. 使用文档 ✓
+
+**文件**:
+- `offline_tasks/SWING_USAGE.md` - 完整使用指南
+- `collaboration/QUICKSTART.md` - 快速开始指南
+
+**包含内容**:
+- 详细的使用步骤
+- 参数说明和调优建议
+- 故障排查指南
+- 性能优化建议
+- 完整示例
+
+## 数据流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  步骤1: 生成Session文件                                      │
+│  generate_session.py                                        │
+│  ↓                                                          │
+│  数据库 → 用户行为数据 → 聚合权重 → session.txt.YYYYMMDD    │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  步骤2: 运行Swing算法                                        │
+│  collaboration/run.sh                                       │
+│  ↓                                                          │
+│  session文件 → C++ Swing → sim_matrx.* → swing_similar.txt │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  步骤3: 生成Debug文件                                        │
+│  add_names_to_swing.py (自动调用)                           │
+│  ↓                                                          │
+│  swing_similar.txt → 添加商品名 → swing_similar_readable.txt│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 文件格式说明
+
+### Session文件格式
+
+**标准格式** (`session.txt.YYYYMMDD`):
+```
+user_id1	{"123":10.0,"456":5.0,"789":3.0}
+user_id2	{"123":8.0,"999":12.0}
+```
+
+**C++格式** (`session.txt.YYYYMMDD.cpp`):
+```
+{"123":10.0,"456":5.0,"789":3.0}
+{"123":8.0,"999":12.0}
+```
+
+### Swing结果格式
+
+**原始格式** (`swing_similar.txt`):
+```
+12345	67890:0.8523,23456:0.7234,34567:0.6891
+```
+
+**可读格式** (`swing_similar_readable.txt`):
+```
+12345:iPhone 15 Pro	67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234
+```
+
+## 行为权重配置
+
+当前配置（在`generate_session.py`中）:
+
+| 行为类型 | 权重 | 说明 |
+|---------|------|------|
+| purchase | 10.0 | 购买行为（最强信号） |
+| contactFactory | 5.0 | 联系厂家 |
+| addToCart | 3.0 | 加入购物车 |
+| addToPool | 2.0 | 加入询价池 |
+
+## 快速开始
+
+```bash
+# 1. 生成session文件（730天数据）
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/generate_session.py --lookback_days 730
+
+# 2. 运行Swing算法
+cd /home/tw/recommendation/collaboration
+bash run.sh
+
+# 3. 查看结果
+cat output/swing_similar_readable.txt | head -20
+```
+
+## 项目结构
+
+```
+recommendation/
+├── offline_tasks/
+│   ├── scripts/
+│   │   ├── generate_session.py          # 新增：生成session
+│   │   ├── add_names_to_swing.py        # 新增：添加商品名
+│   │   ├── i2i_swing.py                 # 已有：Python版Swing
+│   │   └── debug_utils.py               # 已有：Debug工具
+│   ├── config/
+│   │   └── offline_config.py            # 配置文件
+│   ├── output/
+│   │   ├── session.txt.YYYYMMDD         # 生成的session文件
+│   │   └── session.txt.YYYYMMDD.cpp     # C++格式session
+│   ├── SWING_USAGE.md                   # 新增：详细使用文档
+│   └── ...
+├── collaboration/
+│   ├── run.sh                           # 修改：适配新数据格式
+│   ├── QUICKSTART.md                    # 新增：快速开始
+│   ├── src/
+│   │   ├── swing.cc                     # C++ Swing实现
+│   │   ├── swing_symmetric.cc           # 对称Swing
+│   │   ├── icf_simple.cc                # 简单协同过滤
+│   │   └── ucf.py                       # 用户协同
+│   ├── bin/                             # 编译后的可执行文件
+│   ├── output_YYYYMMDD/                 # 输出目录
+│   │   ├── sim_matrx.*                  # 多线程输出
+│   │   ├── swing_similar.txt            # 合并结果
+│   │   └── swing_similar_readable.txt   # 可读结果
+│   └── output -> output_YYYYMMDD        # 软链接
+└── SWING_IMPLEMENTATION_SUMMARY.md      # 本文档
+```
+
+## 参数调优建议
+
+### 针对B2B低频场景
+
+```bash
+# Session生成
+--lookback_days 730    # 2年数据（B2B交互频次低）
+
+# Swing算法
+ALPHA=0.5-0.7         # 关注用户共同行为的多样性
+THRESHOLD1=1          # 低阈值，保留更多数据
+THRESHOLD2=3          # 中等阈值，过滤噪音
+THREAD_NUM=4-8        # 根据服务器配置
+```
+
+### 针对大数据量场景
+
+```bash
+# 增加线程数
+THREAD_NUM=8
+
+# 修改C++代码参数
+max_sim_list_len=300      # 相似列表长度
+max_session_list_len=100  # session截断长度
+```
+
+## 与现有系统集成
+
+### 1. 定时任务
+
+```bash
+# 每天凌晨2点运行
+0 2 * * * cd /home/tw/recommendation/offline_tasks && \
+          python3 scripts/generate_session.py && \
+          cd ../collaboration && bash run.sh
+```
+
+### 2. 结果导入Redis
+
+可使用现有的 `load_index_to_redis.py` 脚本导入结果。
+
+### 3. 与Python版Swing对比
+
+- **C++版本**（本次实现）：性能更好，适合大数据量
+- **Python版本**（`i2i_swing.py`）：易于调试，支持时间衰减
+
+可以运行两个版本对比效果：
+```bash
+# Python版本
+python3 offline_tasks/scripts/i2i_swing.py --debug
+
+# C++版本
+cd collaboration && bash run.sh
+```
+
+## 测试验证
+
+### 1. 小数据量测试
+
+```bash
+# 生成小范围数据（30天）
+python3 scripts/generate_session.py --lookback_days 30
+
+# 运行Swing
+cd ../collaboration
+bash run.sh
+```
+
+### 2. 查看结果质量
+
+```bash
+# 查看可读版本前100行
+head -100 output/swing_similar_readable.txt
+
+# 检查相似度分布
+cat output/swing_similar.txt | awk -F'\t' '{print NF-1}' | sort -n | uniq -c
+```
+
+### 3. 性能测试
+
+```bash
+# 记录运行时间
+time bash run.sh
+```
+
+## 故障排查
+
+### 常见问题
+
+1. **Session文件不存在**
+   - 先运行 `generate_session.py`
+
+2. **编译失败**
+   - 检查g++版本：`g++ --version`
+   - 手动编译：`cd collaboration && make`
+
+3. **数据库连接失败**
+   - 检查配置：`offline_tasks/config/offline_config.py`
+   - 测试连接：`python3 offline_tasks/test_connection.py`
+
+4. **结果为空**
+   - 降低threshold参数
+   - 增加lookback_days
+   - 检查数据量：`wc -l output/session.txt.*`
+
+详细故障排查参见：`offline_tasks/SWING_USAGE.md`
+
+## 后续优化方向
+
+1. **性能优化**
+   - 支持分布式计算
+   - 增量更新机制
+   - 结果缓存
+
+2. **功能增强**
+   - 支持多种相似度算法
+   - 在线实时更新
+   - A/B测试框架
+
+3. **可观测性**
+   - 添加监控指标
+   - 结果质量评估
+   - 自动报警
+
+## 相关文档
+
+- **详细使用指南**: `offline_tasks/SWING_USAGE.md`
+- **快速开始**: `collaboration/QUICKSTART.md`
+- **配置说明**: `offline_tasks/config/offline_config.py`
+- **Debug工具**: `offline_tasks/scripts/debug_utils.py`
+- **Swing算法原理**: `collaboration/README.md`
+
+## 维护说明
+
+### 代码维护
+
+- **Session生成**: `offline_tasks/scripts/generate_session.py`
+- **Swing执行**: `collaboration/run.sh`
+- **Debug脚本**: `offline_tasks/scripts/add_names_to_swing.py`
+
+### 配置维护
+
+- **数据库配置**: `offline_tasks/config/offline_config.py`
+- **行为权重**: `generate_session.py` 中的 `behavior_weights`
+- **Swing参数**: `collaboration/run.sh` 中的配置区域
+
+### 日志查看
+
+```bash
+# Session生成日志
+ls offline_tasks/logs/debug/generate_session_*.log
+
+# Swing运行日志
+ls collaboration/logs/
+```
+
+## 总结
+
+本次实现完成了一套完整的C++ Swing算法工作流：
+
+1. ✓ **前置任务**：Session文件生成（`generate_session.py`）
+2. ✓ **核心算法**：C++ Swing执行（改进的`run.sh`）
+3. ✓ **后处理**：Debug文件生成（`add_names_to_swing.py`）
+4. ✓ **文档完善**：详细使用指南和快速开始
+
+所有脚本都支持debug模式，便于调试和监控。整体流程自动化程度高，只需一条命令即可完成全流程。
+
+---
+
+**实现时间**: 2024-10-17
+**状态**: ✅ 已完成
+
@@ -0,0 +1,322 @@
+# Swing算法使用指南
+
+本文档介绍如何使用C++版本的Swing算法进行物品相似度计算。
+
+## 目录结构
+
+```
+recommendation/
+├── offline_tasks/
+│   ├── scripts/
+│   │   ├── generate_session.py      # 生成用户session文件
+│   │   └── add_names_to_swing.py    # 给结果添加商品名称
+│   └── output/
+│       └── session.txt.YYYYMMDD     # 生成的session文件
+└── collaboration/
+    ├── run.sh                        # Swing算法执行脚本
+    ├── src/
+    │   ├── swing.cc                  # Swing算法实现
+    │   └── ucf.py                    # 用户协同过滤
+    └── output_YYYYMMDD/
+        ├── swing_similar.txt         # Swing结果（ID格式）
+        └── swing_similar_readable.txt # Swing结果（带商品名）
+```
+
+## 使用流程
+
+### 步骤1: 生成Session文件
+
+首先需要从数据库提取用户行为数据，生成session文件。
+
+```bash
+cd /home/tw/recommendation/offline_tasks
+
+# 基本用法（使用默认参数：730天数据）
+python3 scripts/generate_session.py
+
+# 指定回看天数
+python3 scripts/generate_session.py --lookback_days 365
+
+# 启用debug模式查看详细信息
+python3 scripts/generate_session.py --lookback_days 730 --debug
+
+# 指定输出文件路径
+python3 scripts/generate_session.py --output output/session.txt.20241017
+
+# 选择输出格式
+python3 scripts/generate_session.py --format both    # 同时生成两种格式（默认）
+python3 scripts/generate_session.py --format standard  # uid \t json 格式
+python3 scripts/generate_session.py --format cpp      # 纯json格式（.cpp后缀）
+```
+
+**输出文件格式：**
+
+- `session.txt.YYYYMMDD` - 标准格式（包含uid）：
+  ```
+  uid1 \t {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0}
+  uid2 \t {"item_id4":15.0,"item_id5":8.0}
+  ```
+
+- `session.txt.YYYYMMDD.cpp` - C++格式（纯json）：
+  ```
+  {"item_id1":10.0,"item_id2":5.0,"item_id3":3.0}
+  {"item_id4":15.0,"item_id5":8.0}
+  ```
+
+**行为权重配置：**
+- `purchase`: 10.0（购买）
+- `contactFactory`: 5.0（联系厂家）
+- `addToCart`: 3.0（加入购物车）
+- `addToPool`: 2.0（加入询价池）
+
+### 步骤2: 运行Swing算法
+
+session文件生成后，运行C++版本的Swing算法。
+
+```bash
+cd /home/tw/recommendation/collaboration
+
+# 直接运行（使用默认配置）
+bash run.sh
+
+# 或者给脚本添加执行权限后运行
+chmod +x run.sh
+./run.sh
+```
+
+**配置说明（修改run.sh中的参数）：**
+
+```bash
+# 数据路径配置
+SESSION_DATA_DIR="../offline_tasks/output"  # session文件目录
+
+# Swing算法参数
+ALPHA=0.7          # Swing算法的alpha参数（越小越关注用户共同行为）
+THRESHOLD1=1       # 交互强度阈值1（用于筛选用户行为）
+THRESHOLD2=3       # 交互强度阈值2（用于计算相似度）
+THREAD_NUM=4       # 线程数（根据CPU核心数调整）
+SHOW_PROGRESS=1    # 是否显示进度 (0/1)
+
+# Python环境
+PYTHON_CMD="python3"  # 如需使用特定Python环境，修改此处
+```
+
+**脚本执行流程：**
+
+1. 编译C++程序（swing, icf_simple, swing_symmetric）
+2. 查找当天日期的session文件
+3. 运行Swing算法计算物品相似度
+4. 合并多线程输出结果
+5. 自动调用debug脚本生成可读版本
+
+### 步骤3: 查看结果
+
+运行完成后，结果文件位于 `collaboration/output_YYYYMMDD/` 目录：
+
+**1. swing_similar.txt** - 原始结果（ID格式）
+```
+12345 \t 67890:0.8523,23456:0.7234,34567:0.6891
+```
+格式：`item_id \t similar_item_id1:score1,similar_item_id2:score2,...`
+
+**2. swing_similar_readable.txt** - 可读结果（带商品名）
+```
+12345:iPhone 15 Pro \t 67890:iPhone 15:0.8523,23456:iPhone 14 Pro:0.7234
+```
+格式：`item_id:item_name \t similar_item_id1:name1:score1,similar_item_id2:name2:score2,...`
+
+### 步骤4: 单独生成Debug文件（可选）
+
+如果需要为其他文件生成可读版本：
+
+```bash
+cd /home/tw/recommendation/offline_tasks
+
+# 基本用法
+python3 scripts/add_names_to_swing.py collaboration/output/swing_similar.txt
+
+# 指定输出文件
+python3 scripts/add_names_to_swing.py \
+    collaboration/output/swing_similar.txt \
+    collaboration/output/my_readable.txt
+
+# 启用debug模式
+python3 scripts/add_names_to_swing.py \
+    collaboration/output/swing_similar.txt \
+    --debug
+```
+
+## 参数调优建议
+
+### Swing算法参数
+
+1. **alpha (0.5-1.0)**
+   - 越小：越关注用户共同行为的多样性
+   - 越大：越容忽略用户重叠度
+   - 建议：0.5-0.7（B2B场景）
+
+2. **threshold1 (1-5)**
+   - 用于筛选用户的有效行为
+   - 建议：1-3（低频场景可用1）
+
+3. **threshold2 (1-10)**
+   - 用于计算相似度的行为强度阈值
+   - 建议：3-5（需要较强的交互信号）
+
+4. **thread_num (1-20)**
+   - 根据CPU核心数设置
+   - 建议：4-8（普通服务器）
+
+### 数据范围参数
+
+1. **lookback_days**
+   - B2B低频场景：建议730天（2年）
+   - B2C高频场景：建议30-90天
+   - 数据量大时可适当减少
+
+## 完整示例
+
+```bash
+# 1. 生成session文件（730天数据）
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/generate_session.py --lookback_days 730 --debug
+
+# 2. 检查生成的文件
+ls -lh output/session.txt.*
+# 应该看到：
+# session.txt.20241017
+# session.txt.20241017.cpp
+
+# 3. 运行Swing算法
+cd /home/tw/recommendation/collaboration
+bash run.sh
+
+# 4. 查看结果
+ls -lh output/swing_similar*
+cat output/swing_similar_readable.txt | head -20
+```
+
+## 故障排查
+
+### 问题1: Session文件不存在
+
+```
+错误: Session文件不存在: ../offline_tasks/output/session.txt.20241017.cpp
+```
+
+**解决方法：**
+```bash
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/generate_session.py
+```
+
+### 问题2: 编译失败
+
+```
+编译失败，退出
+```
+
+**解决方法：**
+```bash
+cd /home/tw/recommendation/collaboration
+# 检查编译器
+g++ --version
+
+# 手动编译
+make clean
+make
+
+# 检查依赖
+ls include/
+ls utils/
+```
+
+### 问题3: 数据库连接失败
+
+```
+获取数据失败: Connection refused
+```
+
+**解决方法：**
+- 检查数据库配置：`offline_tasks/config/offline_config.py`
+- 测试连接：`python3 offline_tasks/test_connection.py`
+- 确认网络和防火墙设置
+
+### 问题4: 结果为空
+
+**可能原因：**
+- threshold1/threshold2设置过高，过滤掉了所有数据
+- 数据量太少，用户和商品交集不足
+
+**解决方法：**
+- 降低threshold参数（如threshold1=0.5, threshold2=1）
+- 增加lookback_days
+- 检查数据量：`wc -l output/session.txt.*`
+
+## 性能优化
+
+### 大数据量场景
+
+如果数据量很大（>100万用户，>10万商品）：
+
+1. **增加线程数**
+   ```bash
+   THREAD_NUM=8  # 或更多
+   ```
+
+2. **分批处理**
+   - 可以将session文件按用户分片
+   - 分别运行Swing算法
+   - 最后合并结果
+
+3. **调整max_session_list_len**
+   - 修改 `src/swing.cc` 中的 `max_session_list_len`
+   - 限制每个用户的最大行为数
+
+### 内存优化
+
+如果遇到内存不足：
+
+1. 减少 `max_sim_list_len`（默认300）
+2. 减少 `max_session_list_len`（默认100）
+3. 分批处理数据
+
+## 集成到定时任务
+
+```bash
+# 添加到crontab
+crontab -e
+
+# 每天凌晨2点运行
+0 2 * * * cd /home/tw/recommendation/offline_tasks && python3 scripts/generate_session.py && cd ../collaboration && bash run.sh >> logs/swing_$(date +\%Y\%m\%d).log 2>&1
+```
+
+## 相关文档
+
+- [Swing算法原理](./collaboration/README.md)
+- [离线任务配置](./offline_tasks/config/offline_config.py)
+- [Debug工具使用](./offline_tasks/scripts/debug_utils.py)
+
+## 常见问题
+
+**Q: session文件格式选择哪个？**
+A: run.sh会自动检测格式。建议使用 `--format both` 生成两种格式。
+
+**Q: Swing算法运行多久？**
+A: 取决于数据量和线程数。通常：
+- 1万商品：1-5分钟
+- 10万商品：10-30分钟
+- 数据量大时建议使用多线程
+
+**Q: 如何调整相似商品数量？**
+A: 修改 `src/swing.cc` 中的 `max_sim_list_len` 参数（默认300）。
+
+**Q: 能否使用Python版本的Swing？**
+A: 可以，使用 `offline_tasks/scripts/i2i_swing.py`。但C++版本性能更好。
+
+## 联系支持
+
+如有问题，请参考：
+- 项目README: `/home/tw/recommendation/README.md`
+- 故障排查: `/home/tw/recommendation/offline_tasks/TROUBLESHOOTING.md`
+
@@ -0,0 +1,350 @@
+# 完整索引清单
+
+## 📋 所有可用的推荐索引
+
+### 1. i2i 相似度索引
+
+#### 1.1 行为相似索引（3种）
+
+**Swing算法**：
+```
+i2i:swing:{item_id}
+```
+示例：`i2i:swing:12345`
+
+**Session Word2Vec**：
+```
+i2i:session_w2v:{item_id}
+```
+示例：`i2i:session_w2v:12345`
+
+**DeepWalk**：
+```
+i2i:deepwalk:{item_id}
+```
+示例：`i2i:deepwalk:12345`
+
+#### 1.2 内容相似索引（3种方法）
+
+**混合方法（推荐）**：
+```
+i2i:content_hybrid:{item_id}
+```
+示例：`i2i:content_hybrid:12345`
+
+**TF-IDF方法**：
+```
+i2i:content_tfidf:{item_id}
+```
+示例：`i2i:content_tfidf:12345`
+
+**分类方法**：
+```
+i2i:content_category:{item_id}
+```
+示例：`i2i:content_category:12345`
+
+---
+
+### 2. 兴趣点聚合索引
+
+格式：`interest:{list_type}:{dimension}:{value}`
+
+#### 2.1 列表类型（list_type）
+
+- `hot` - 热门商品
+- `cart` - 加购商品
+- `new` - 新品
+- `global` - 全局（所有数据）
+
+#### 2.2 单维度索引
+
+##### 业务平台（platform）
+```
+interest:hot:platform:pc
+interest:hot:platform:mobile
+interest:cart:platform:pc
+interest:new:platform:mobile
+interest:global:platform:pc
+```
+
+##### 客户端平台（client_platform）
+```
+interest:hot:client_platform:web
+interest:hot:client_platform:app
+interest:cart:client_platform:web
+interest:new:client_platform:app
+interest:global:client_platform:web
+```
+
+##### 供应商（supplier）
+```
+interest:hot:supplier:10001
+interest:hot:supplier:10002
+interest:cart:supplier:10001
+interest:new:supplier:10002
+interest:global:supplier:10001
+```
+
+##### 一级分类（category_level1）
+```
+interest:hot:category_level1:100
+interest:cart:category_level1:100
+interest:new:category_level1:100
+interest:global:category_level1:100
+```
+
+##### 二级分类（category_level2）
+```
+interest:hot:category_level2:200
+interest:cart:category_level2:200
+interest:new:category_level2:200
+interest:global:category_level2:200
+```
+
+##### 三级分类（category_level3）
+```
+interest:hot:category_level3:300
+interest:cart:category_level3:300
+interest:new:category_level3:300
+interest:global:category_level3:300
+```
+
+##### 四级分类（category_level4）
+```
+interest:hot:category_level4:400
+interest:cart:category_level4:400
+interest:new:category_level4:400
+interest:global:category_level4:400
+```
+
+#### 2.3 组合维度索引
+
+##### 平台 + 客户端
+```
+interest:hot:platform_client:pc_web
+interest:hot:platform_client:pc_app
+interest:hot:platform_client:mobile_web
+interest:hot:platform_client:mobile_app
+```
+
+##### 平台 + 二级分类
+```
+interest:hot:platform_category2:pc_200
+interest:hot:platform_category2:mobile_200
+interest:cart:platform_category2:pc_200
+interest:new:platform_category2:mobile_200
+```
+
+##### 平台 + 三级分类
+```
+interest:hot:platform_category3:pc_300
+interest:hot:platform_category3:mobile_300
+interest:cart:platform_category3:pc_300
+interest:new:platform_category3:mobile_300
+```
+
+##### 客户端平台 + 二级分类
+```
+interest:hot:client_category2:web_200
+interest:hot:client_category2:app_200
+interest:cart:client_category2:web_200
+interest:new:client_category2:app_200
+```
+
+---
+
+## 🎯 按业务场景的索引使用
+
+### 场景1: 首页个性化推荐
+
+**方案A: 基于平台**
+```python
+key = f"interest:hot:platform:{user_platform}"
+# 示例：interest:hot:platform:pc
+```
+
+**方案B: 基于分类偏好**
+```python
+key = f"interest:hot:category_level2:{user_favorite_category}"
+# 示例：interest:hot:category_level2:200
+```
+
+**方案C: 基于平台+分类**
+```python
+key = f"interest:hot:platform_category2:{user_platform}_{category_id}"
+# 示例：interest:hot:platform_category2:pc_200
+```
+
+### 场景2: 详情页相关推荐
+
+**方案A: 行为相似**
+```python
+key = f"i2i:swing:{current_item_id}"
+# 示例：i2i:swing:12345
+```
+
+**方案B: 内容相似**
+```python
+key = f"i2i:content_hybrid:{current_item_id}"
+# 示例：i2i:content_hybrid:12345
+```
+
+**方案C: 融合推荐**
+```python
+behavior_similar = redis.get(f"i2i:swing:{item_id}")
+content_similar = redis.get(f"i2i:content_hybrid:{item_id}")
+# 融合两种结果
+```
+
+### 场景3: 分类页推荐
+
+**方案A: 该分类热门**
+```python
+key = f"interest:hot:category_level2:{category_id}"
+# 示例：interest:hot:category_level2:200
+```
+
+**方案B: 该分类新品**
+```python
+key = f"interest:new:category_level2:{category_id}"
+# 示例：interest:new:category_level2:200
+```
+
+**方案C: 该分类+平台**
+```python
+key = f"interest:hot:platform_category2:{platform}_{category_id}"
+# 示例：interest:hot:platform_category2:pc_200
+```
+
+### 场景4: 供应商店铺页
+
+**方案A: 供应商热门商品**
+```python
+key = f"interest:hot:supplier:{supplier_id}"
+# 示例：interest:hot:supplier:10001
+```
+
+**方案B: 供应商新品**
+```python
+key = f"interest:new:supplier:{supplier_id}"
+# 示例：interest:new:supplier:10001
+```
+
+### 场景5: 搜索结果页推荐
+
+**方案A: 全局热门**
+```python
+key = "interest:global:platform:pc"
+```
+
+**方案B: 分类相关**
+```python
+key = f"interest:global:category_level2:{search_category}"
+# 示例：interest:global:category_level2:200
+```
+
+---
+
+## 📊 索引数量统计
+
+### i2i索引
+- 行为相似：3种算法 × 商品数量
+- 内容相似：3种方法 × 商品数量
+- **总计**：6 × 商品数量
+
+### 兴趣点聚合索引
+
+**单维度**：
+- platform: 2-10个
+- client_platform: 2-5个
+- supplier: 100-1000个
+- category_level1: 10-50个
+- category_level2: 50-200个
+- category_level3: 200-1000个
+- category_level4: 1000-5000个
+
+**组合维度**：
+- platform_client: 4-50个
+- platform_category2: 100-2000个
+- platform_category3: 400-10000个
+- client_category2: 100-1000个
+
+**列表类型**：每个维度 × 4种类型（hot/cart/new/global）
+
+**预估总数**：10000-50000条索引
+
+---
+
+## 🔍 查询示例代码
+
+### Python示例
+
+```python
+import redis
+
+# 连接Redis
+r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)
+
+# 1. 查询商品的相似商品
+item_id = "12345"
+similar_items = r.get(f"i2i:swing:{item_id}")
+if similar_items:
+    items = similar_items.split(',')
+    for item in items[:5]:  # 取前5个
+        item_id, score = item.split(':')
+        print(f"商品ID: {item_id}, 相似度: {score}")
+
+# 2. 查询分类热门商品
+category_id = "200"
+hot_items = r.get(f"interest:hot:category_level2:{category_id}")
+if hot_items:
+    items = hot_items.split(',')
+    for item in items[:10]:  # 取前10个
+        item_id, score = item.split(':')
+        print(f"商品ID: {item_id}, 得分: {score}")
+
+# 3. 查询平台+分类组合
+platform = "pc"
+category_id = "200"
+key = f"interest:hot:platform_category2:{platform}_{category_id}"
+items = r.get(key)
+```
+
+### Redis命令行示例
+
+```bash
+# 查询商品相似度
+redis-cli GET "i2i:swing:12345"
+
+# 查询分类热门
+redis-cli GET "interest:hot:category_level2:200"
+
+# 查询供应商商品
+redis-cli GET "interest:hot:supplier:10001"
+
+# 模糊查询所有热门索引
+redis-cli KEYS "interest:hot:*"
+
+# 查看某个分类的所有类型
+redis-cli KEYS "interest:*:category_level2:200"
+```
+
+---
+
+## 📝 注意事项
+
+1. **索引命名规范**：严格遵循 `type:subtype:dimension:value` 格式
+2. **值的格式**：`item_id1:score1,item_id2:score2,...`
+3. **过期时间**：建议设置7天过期
+4. **更新频率**：建议每天更新一次
+5. **查询优先级**：
+   - 优先使用细粒度索引（如四级分类）
+   - 粗粒度索引作为后备（如一级分类）
+   - 融合多个索引结果
+
+---
+
+**版本**: v1.1  
+**生成日期**: 2025-10-16  
+**索引总数**: 约10000-50000条
@@ -0,0 +1,217 @@
+# 故障排除指南
+
+## 常见问题及解决方案
+
+### 1. 数据库字段错误
+
+#### 问题：
+```
+pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'")
+```
+
+#### 原因：
+数据库表结构与代码中使用的字段名不匹配。
+
+#### 解决方案：
+1. 查看 `DATABASE_SETUP.md` 了解如何配置字段
+2. 修改对应脚本中的SQL查询，使用实际存在的字段名
+3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过
+
+#### 已修复的字段：
+- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的
+- ✅ 基础功能不依赖分类字段
+
+---
+
+### 2. 连接超时
+
+#### 问题：
+```
+pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...")
+```
+
+#### 解决方案：
+1. 检查数据库配置：`config/offline_config.py`
+2. 确认网络连接和防火墙设置
+3. 运行测试：`python3 test_connection.py`
+
+---
+
+### 3. 内存不足
+
+#### 问题：
+程序运行时内存占用过高或被杀死。
+
+#### 解决方案：
+1. 减少回溯天数：`--lookback_days 365`（从730改为365）
+2. 减少输出数量：`--top_n 20`（从50改为20）
+3. 先运行单个算法：
+   ```bash
+   python3 scripts/i2i_session_w2v.py  # 内存占用较小
+   ```
+4. 跳过Swing算法（内存占用最大）：
+   ```bash
+   python3 run_all.py --skip-i2i
+   ```
+
+---
+
+### 4. 运行时间过长
+
+#### 解决方案：
+1. 减少数据量：`--lookback_days 180`
+2. 只运行特定算法：
+   ```bash
+   python3 run_all.py --only-w2v
+   ```
+3. 考虑使用C++版本的Swing（性能提升10倍）
+
+---
+
+### 5. 依赖包安装失败
+
+#### 解决方案：
+```bash
+# 单独安装失败的包
+pip3 install pandas sqlalchemy pymysql gensim numpy
+
+# 或使用国内镜像
+pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+---
+
+### 6. Redis连接失败
+
+#### 问题：
+```
+redis.exceptions.ConnectionError: Error connecting to Redis
+```
+
+#### 解决方案：
+1. Redis是可选的，只影响索引加载功能
+2. 如果不需要Redis，可以跳过：
+   ```bash
+   python3 run_all.py  # 只运行离线任务，不加载到Redis
+   ```
+3. 如果需要Redis，确认Redis已安装并运行：
+   ```bash
+   redis-cli ping  # 应该返回 PONG
+   ```
+
+---
+
+### 7. 输出文件为空
+
+#### 可能原因：
+1. 数据量太少（没有满足最小阈值）
+2. 时间范围内没有数据
+3. SQL查询条件过于严格
+
+#### 解决方案：
+1. 检查日志：`tail -f logs/run_all_*.log`
+2. 调整参数：
+   - 增加时间范围：`--lookback_days 1000`
+   - 减少阈值：修改配置文件中的 `min_interaction_count`
+3. 检查数据库中是否有数据：
+   ```python
+   # 运行简单查询测试
+   python3 test_connection.py
+   ```
+
+---
+
+### 8. 权限问题
+
+#### 问题：
+```
+PermissionError: [Errno 13] Permission denied
+```
+
+#### 解决方案：
+```bash
+# 给脚本添加执行权限
+chmod +x install.sh run_all.py
+
+# 确保有写入权限
+chmod 755 output/ logs/
+```
+
+---
+
+### 9. Python版本问题
+
+#### 要求：
+Python 3.7+
+
+#### 检查版本：
+```bash
+python3 --version
+```
+
+#### 如果版本过低，需要升级Python
+
+---
+
+### 10. 编码问题
+
+#### 问题：
+```
+UnicodeDecodeError: 'utf-8' codec can't decode byte...
+```
+
+#### 解决方案：
+确保所有文件使用UTF-8编码，特别是配置文件和输出文件。
+
+---
+
+## 调试技巧
+
+### 1. 查看详细日志
+```bash
+tail -f logs/run_all_*.log
+```
+
+### 2. 运行单个任务（便于调试）
+```bash
+python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10
+```
+
+### 3. 使用较小的数据量测试
+```bash
+python3 run_all.py --lookback_days 30 --top_n 10
+```
+
+### 4. 检查中间结果
+```bash
+ls -lh output/
+head -n 20 output/i2i_swing_*.txt
+```
+
+---
+
+## 获取支持
+
+如果以上方法都无法解决问题：
+
+1. **查看文档**：
+   - `README.md` - 详细说明
+   - `DATABASE_SETUP.md` - 数据库配置
+   - `QUICKSTART.md` - 快速开始
+
+2. **查看日志**：
+   - `logs/` 目录下的所有日志文件
+
+3. **简化测试**：
+   - 先运行 `test_connection.py`
+   - 再运行单个脚本
+   - 使用小数据量测试
+
+4. **记录错误信息**：
+   - 完整的错误堆栈
+   - 使用的命令
+   - 配置文件内容
+
+---
+
+**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。
@@ -0,0 +1,179 @@
+# 数据库字段配置说明
+
+## 问题说明
+
+如果运行时遇到类似 `Unknown column 'xxx'` 的错误，说明数据库表结构与代码中使用的字段名不匹配。
+
+## 已适配的基础字段
+
+当前代码已经适配了以下基础字段（参考 `item_sim.py`）：
+
+### sensors_events 表
+- `anonymous_id` - 用户ID
+- `item_id` - 商品ID  
+- `event` - 事件类型
+- `create_time` - 创建时间
+- `platform` - 平台（可选）
+- `country` - 国家（可选）
+- `customer_type` - 客户类型（可选）
+
+### prd_goods_sku 表
+- `id` - 商品ID
+- `name` - 商品名称
+- `create_time` - 创建时间（用于判断新品）
+
+## 可选字段配置
+
+如果您的数据库表包含以下字段，可以在SQL查询中添加它们以支持更多维度：
+
+### 分类字段（可选）
+- `category_level1_id` - 一级分类ID
+- `category_level2_id` - 二级分类ID
+- `category_level3_id` - 三级分类ID
+
+## 如何添加分类字段支持
+
+如果您的数据库有分类字段，可以按以下步骤启用：
+
+### 步骤1: 修改 SQL 查询
+
+编辑 `scripts/interest_aggregation.py`，找到 SQL 查询部分，添加分类字段：
+
+```python
+sql_query = f"""
+SELECT 
+    se.anonymous_id AS user_id,
+    se.item_id,
+    se.event AS event_type,
+    se.create_time,
+    pgs.name AS item_name,
+    pgs.create_time AS item_create_time,
+    pgs.category_level2_id,    # 添加这一行
+    pgs.category_level3_id,    # 添加这一行
+    se.platform,
+    se.country,
+    se.customer_type
+FROM 
+    sensors_events se
+LEFT JOIN prd_goods_sku pgs ON se.item_id = pgs.id
+...
+"""
+```
+
+### 步骤2: 修改聚合逻辑
+
+在 `aggregate_by_dimensions` 函数中，字段检查已经做好了，如果字段存在会自动使用：
+
+```python
+# 维度4: 二级分类 (category_level2) - 如果字段存在
+if 'category_level2_id' in row and pd.notna(row.get('category_level2_id')):
+    key = f"category_level2:{row['category_level2_id']}"
+    aggregations[key][item_id] += weight
+```
+
+这段代码会自动检测字段是否存在，如果存在就使用，不存在就跳过。
+
+## 查看实际表结构
+
+运行以下命令查看您的数据库表结构：
+
+```python
+# 创建一个简单的脚本查看表结构
+import pandas as pd
+from db_service import create_db_connection
+from offline_tasks.config.offline_config import DB_CONFIG
+
+engine = create_db_connection(
+    DB_CONFIG['host'],
+    DB_CONFIG['port'],
+    DB_CONFIG['database'],
+    DB_CONFIG['username'],
+    DB_CONFIG['password']
+)
+
+# 查看 prd_goods_sku 表结构
+df = pd.read_sql("SELECT * FROM prd_goods_sku LIMIT 1", engine)
+print("prd_goods_sku 字段列表:")
+for col in df.columns:
+    print(f"  - {col}")
+
+# 查看 sensors_events 表结构  
+df = pd.read_sql("SELECT * FROM sensors_events LIMIT 1", engine)
+print("\nsensors_events 字段列表:")
+for col in df.columns:
+    print(f"  - {col}")
+```
+
+## 常见字段名映射
+
+如果您的数据库使用不同的字段名，需要在SQL查询中做映射：
+
+| 代码中的字段 | 可能的实际字段名 | 修改方式 |
+|-------------|----------------|---------|
+| `category_level2_id` | `cat2_id`, `category2`, `second_category` | `pgs.cat2_id AS category_level2_id` |
+| `category_level3_id` | `cat3_id`, `category3`, `third_category` | `pgs.cat3_id AS category_level3_id` |
+| `anonymous_id` | `user_id`, `uid`, `visitor_id` | `se.user_id AS anonymous_id` |
+| `customer_type` | `client_type`, `buyer_type` | `se.client_type AS customer_type` |
+
+## 完整示例
+
+假设您的表结构是：
+- `prd_goods_sku` 有字段：`id`, `title`, `cat2`, `cat3`, `add_time`
+- `sensors_events` 有字段：`uid`, `goods_id`, `action`, `time`
+
+则需要修改SQL为：
+
+```python
+sql_query = f"""
+SELECT 
+    se.uid AS user_id,
+    se.goods_id AS item_id,
+    se.action AS event_type,
+    se.time AS create_time,
+    pgs.title AS item_name,
+    pgs.add_time AS item_create_time,
+    pgs.cat2 AS category_level2_id,
+    pgs.cat3 AS category_level3_id
+FROM 
+    sensors_events se
+LEFT JOIN prd_goods_sku pgs ON se.goods_id = pgs.id
+...
+"""
+```
+
+## 最小化配置
+
+如果只想先测试基本功能，可以只使用最基础的字段：
+
+### i2i 算法只需要：
+- `anonymous_id` / `user_id`
+- `item_id`  
+- `event` / `event_type`
+- `create_time`
+- `name` (商品名称)
+
+### 兴趣点聚合至少需要：
+- 以上i2i的字段
+- 至少一个维度字段（如 `platform` 或 `country`）
+
+## 测试连接
+
+修改后，运行测试脚本验证：
+
+```bash
+cd /home/tw/recommendation/offline_tasks
+python3 test_connection.py
+```
+
+## 获取帮助
+
+如果仍有问题，请：
+1. 查看日志文件：`logs/run_all_*.log`
+2. 运行单个脚本测试，便于调试
+3. 使用 `--help` 参数查看命令行选项
+
+```bash
+python3 scripts/i2i_swing.py --help
+python3 scripts/interest_aggregation.py --help
+```
+
@@ -0,0 +1,197 @@
+# 离线索引产出规范
+
+## 📋 索引任务列表
+
+| 模块名称 | 任务命令 | 调度频次 | 输出数据 | 格式和示例 |
+|---------|---------|---------|---------|-----------|
+| **i2i_swing** | `python3 scripts/i2i_swing.py` | 每天 | `output/i2i_swing_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
+| **i2i_session_w2v** | `python3 scripts/i2i_session_w2v.py` | 每天 | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
+| **i2i_deepwalk** | `python3 scripts/i2i_deepwalk.py` | 每天 | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
+| **i2i_content** | `python3 scripts/i2i_content_similar.py` | 每周 | `output/i2i_content_hybrid_YYYYMMDD.txt` | `item_id \t item_name \t similar_id1:score1,similar_id2:score2,...` |
+| **interest_hot** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
+| **interest_cart** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
+| **interest_new** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
+| **interest_global** | `python3 scripts/interest_aggregation.py` | 每天 | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key \t item_id1,item_id2,item_id3,...` |
+
+## 📊 详细格式说明
+
+### 1. i2i相似度索引
+
+#### 输出格式
+```
+item_id \t item_name \t similar_id1:score1,similar_id2:score2,...
+```
+
+#### 示例
+```
+12345	香蕉干	67890:0.8567,11223:0.7234,44556:0.6891
+67890	芒果干	12345:0.8567,22334:0.7123,55667:0.6543
+```
+
+#### 字段说明
+- `item_id`: 商品SKU ID
+- `item_name`: 商品名称
+- `similar_id`: 相似商品ID
+- `score`: 相似度分数（0-1之间，越大越相似）
+
+#### 算法差异
+| 算法 | 特点 | 适用场景 |
+|------|------|---------|
+| **Swing** | 基于用户共同行为，发现购买关联 | 详情页"大家都在看" |
+| **Session W2V** | 基于会话序列，捕捉浏览顺序 | 详情页"看了又看" |
+| **DeepWalk** | 基于图结构，发现深层关系 | 详情页"相关推荐" |
+| **Content** | 基于商品属性，类目相似 | 冷启动商品推荐 |
+
+### 2. 兴趣点聚合索引
+
+#### 输出格式
+```
+dimension_key \t item_id1,item_id2,item_id3,...
+```
+
+#### 示例
+```
+platform:pc	12345,67890,11223,44556,22334
+category_level2:200	67890,12345,22334,55667,11223
+platform_category2:pc_200	12345,67890,22334,11223,55667
+supplier:10001	12345,44556,22334,67890,11223
+```
+
+#### 维度说明
+
+**单维度（7个）**
+- `platform:{platform_id}` - 业务平台（pc, h5, app等）
+- `client_platform:{client}` - 客户端平台（iOS, Android, Web等）
+- `supplier:{supplier_id}` - 供应商
+- `category_level1:{cat_id}` - 一级分类
+- `category_level2:{cat_id}` - 二级分类
+- `category_level3:{cat_id}` - 三级分类
+- `category_level4:{cat_id}` - 四级分类
+
+**组合维度（4个）**
+- `platform_client:{platform}_{client}` - 平台+客户端
+- `platform_category2:{platform}_{cat_id}` - 平台+二级分类
+- `platform_category3:{platform}_{cat_id}` - 平台+三级分类
+- `client_category2:{client}_{cat_id}` - 客户端+二级分类
+
+#### 列表类型说明
+
+| 类型 | 文件名 | 计算逻辑 | 适用场景 |
+|------|--------|---------|---------|
+| **hot** | `interest_aggregation_hot_YYYYMMDD.txt` | 最近N天的高频交互商品 | 首页"热门推荐" |
+| **cart** | `interest_aggregation_cart_YYYYMMDD.txt` | 高加购率商品 | 首页"热门加购" |
+| **new** | `interest_aggregation_new_YYYYMMDD.txt` | 最近上架的新品 | 首页"新品推荐" |
+| **global** | `interest_aggregation_global_YYYYMMDD.txt` | 全局热门商品 | 首页"猜你喜欢" |
+
+## 🔄 调度建议
+
+### 每日调度（数据量大，变化快）
+```bash
+# 每天凌晨3点执行
+0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py --lookback_days 730 --top_n 50
+```
+
+### 每周调度（数据量小，变化慢）
+```bash
+# 每周日凌晨4点执行
+0 4 * * 0 cd /home/tw/recommendation/offline_tasks && python3 scripts/i2i_content_similar.py --top_n 50
+```
+
+## 📁 文件命名规范
+
+### 标准格式
+```
+{algorithm_name}_{date}.txt
+```
+
+### 示例
+```
+i2i_swing_20251016.txt
+i2i_session_w2v_20251016.txt
+interest_aggregation_hot_20251016.txt
+```
+
+### Debug文件（开发调试用）
+```
+output/debug/{algorithm_name}_{date}_readable.txt
+logs/debug/{algorithm_name}_{date}_{time}.log
+```
+
+## 📈 数据量估算
+
+| 索引类型 | 索引数量 | 单条大小 | 总大小 | 更新频率 |
+|---------|---------|---------|--------|---------|
+| i2i_swing | ~50,000 | ~500B | ~25MB | 每天 |
+| i2i_session_w2v | ~50,000 | ~500B | ~25MB | 每天 |
+| i2i_deepwalk | ~50,000 | ~500B | ~25MB | 每天 |
+| i2i_content | ~50,000 | ~500B | ~25MB | 每周 |
+| interest_hot | ~10,000 | ~1KB | ~10MB | 每天 |
+| interest_cart | ~10,000 | ~1KB | ~10MB | 每天 |
+| interest_new | ~5,000 | ~1KB | ~5MB | 每天 |
+| interest_global | ~10,000 | ~1KB | ~10MB | 每天 |
+| **总计** | **~245,000** | - | **~135MB** | - |
+
+## 🎯 质量检查
+
+### 数据完整性检查
+```bash
+# 检查文件是否生成
+ls -lh output/*_$(date +%Y%m%d).txt
+
+# 检查行数
+wc -l output/*_$(date +%Y%m%d).txt
+
+# 检查格式
+head -5 output/i2i_swing_$(date +%Y%m%d).txt
+```
+
+### 数据质量指标
+
+**i2i索引质量**
+- 覆盖率：有推荐的商品数 / 总商品数 > 80%
+- 推荐数量：每个商品推荐10-50个相似商品
+- 分数范围：相似度分数在0.01-1.0之间
+
+**兴趣聚合质量**
+- 覆盖率：有数据的维度数 / 总维度数 > 60%
+- 推荐数量：每个维度推荐50-1000个商品
+- 商品去重：同一商品在列表中只出现一次
+
+## 🔍 查询示例
+
+### 查看特定商品的相似推荐
+```bash
+# 查看商品12345的相似商品
+grep "^12345\t" output/i2i_swing_20251016.txt
+```
+
+### 查看特定维度的热门商品
+```bash
+# 查看PC平台的热门商品
+grep "^platform:pc\t" output/interest_aggregation_hot_20251016.txt
+```
+
+### 统计索引数量
+```bash
+# 统计各类型索引数量
+for file in output/*_20251016.txt; do
+    echo "$file: $(wc -l < $file) 条"
+done
+```
+
+## ⚠️ 注意事项
+
+1. **文件编码**: 所有文件使用UTF-8编码
+2. **分隔符**: 使用Tab（\t）分隔字段
+3. **商品ID**: 使用数字类型，不带引号
+4. **分数精度**: 相似度分数保留4位小数
+5. **排序规则**: 相似商品按分数降序排列
+6. **去重**: 确保推荐列表中没有重复商品
+7. **有效性**: 推荐的商品必须是在售状态
+
+## 🔗 相关文档
+
+- **Redis数据规范**: `REDIS_DATA_SPEC.md`
+- **API接口文档**: `RECOMMENDATION_API.md`
+- **Debug指南**: `DEBUG_GUIDE.md`
+- **配置说明**: `UPDATE_CONFIG_GUIDE.md`
@@ -0,0 +1,366 @@
+# 推荐系统离线任务改进总结
+
+**日期**: 2024-10-17  
+**改进内容**: 前置任务优化、文档整理、算法增强
+
+---
+
+## ✅ 完成的改进
+
+### 1. 前置任务：商品属性获取
+
+**问题**: 多个脚本都需要获取ID->名称映射，导致重复查询数据库，效率低下。
+
+**解决方案**:
+- ✅ 创建 `fetch_item_attributes.py` 作为前置任务
+- ✅ 一次性从数据库获取所有ID->名称映射
+- ✅ 保存到本地JSON文件 (`item_attributes_mappings.json`)
+- ✅ 后续任务直接加载本地文件，避免重复查询
+
+**新增文件**:
+```
+offline_tasks/scripts/fetch_item_attributes.py
+offline_tasks/output/item_attributes_mappings.json
+offline_tasks/output/item_attributes_stats.txt
+```
+
+**修改文件**:
+```
+offline_tasks/scripts/debug_utils.py
+  - 新增 load_name_mappings_from_file() 函数
+  - fetch_name_mappings() 标记为已弃用
+
+offline_tasks/scripts/add_names_to_swing.py
+  - 改用 load_name_mappings_from_file()
+  - 移除数据库连接代码
+
+offline_tasks/scripts/i2i_swing.py
+  - 改用 load_name_mappings_from_file()
+  - Debug模式加载本地映射
+
+offline_tasks/run_all.py
+  - 添加前置任务1: fetch_item_attributes
+  - 添加前置任务2: generate_session
+  - 调整任务执行顺序
+```
+
+**效果**:
+- ⚡ 大幅减少数据库查询次数
+- 🚀 提升整体任务执行速度
+- 💾 统一的映射数据源，避免不一致
+
+---
+
+### 2. Session文件生成前置化
+
+**改进**: 将session文件生成作为独立的前置任务
+
+**新增任务流程**:
+```
+run_all.py 执行顺序:
+1. fetch_item_attributes.py   → 获取商品属性
+2. generate_session.py         → 生成用户session文件
+3. i2i_swing.py               → Swing算法
+4. i2i_session_w2v.py         → Session W2V
+5. i2i_deepwalk.py            → DeepWalk
+6. i2i_content_similar.py     → 内容相似度
+7. interest_aggregation.py    → 兴趣聚合
+```
+
+**好处**:
+- 📦 Session文件可复用于多个任务
+- 🔄 C++版Swing算法可直接使用session文件
+- 🎯 数据准备与算法执行解耦
+
+---
+
+### 3. Swing算法增强：支持日期维度
+
+**功能**: i2i_swing.py 现在支持 uid+日期 作为额外的session维度
+
+**实现方式**:
+```python
+# 数据duplicate：
+# 1. 原始数据：uid -> items
+# 2. 日期数据：uid_YYYYMMDD -> items
+# 3. 合并后输入Swing算法
+
+# 新增参数
+--use_daily_session        # 启用日期维度（默认开启）
+--no_daily_session         # 禁用日期维度
+```
+
+**示例**:
+```bash
+# 使用日期维度（默认）
+python3 scripts/i2i_swing.py --lookback_days 730 --debug
+
+# 禁用日期维度
+python3 scripts/i2i_swing.py --lookback_days 730 --no_daily_session
+```
+
+**效果**:
+- 📈 同时考虑用户整体行为和单日行为
+- 🎯 更精准的物品相似度计算
+- 🔍 捕获用户短期和长期兴趣
+
+**原理**:
+```
+原始数据:
+  user_A -> [item1, item2, item3]  (跨多天的行为)
+
+Duplicate后:
+  user_A -> [item1, item2, item3]       # 原始session
+  user_A_20241015 -> [item1]            # 10月15日session
+  user_A_20241016 -> [item2, item3]     # 10月16日session
+
+算法同时考虑：
+- 用户整体偏好（跨时间）
+- 用户单日集中行为（同一天购买的商品更相关）
+```
+
+---
+
+### 4. 文档整理与规范化
+
+**问题**: 文档散乱，临时记录太多，命名不规范。
+
+**解决方案**:
+
+#### 4.1 创建统一文档中心
+```
+offline_tasks/doc/
+├── README.md                    # 文档索引
+├── 从这里开始.md
+├── 快速开始.md
+├── Swing算法使用指南.md
+├── 运行脚本指南.md
+├── 调试指南.md
+├── 离线索引数据规范.md
+├── Redis数据规范.md
+├── 完整索引列表.md
+├── 数据库配置说明.md
+├── 故障排查指南.md
+├── 更新日志.md
+└── Swing实现总结.md
+```
+
+#### 4.2 删除临时文档
+```
+已删除的临时文档（offline_tasks/）:
+- MEMORY_MONITORING_UPDATE.md
+- LATEST_UPDATES.md
+- CONTENT_SIMILARITY_UPDATE.md
+- QUICKSTART_NEW.md
+- CHANGES_SUMMARY.md
+- B2B_LOW_FREQUENCY_OPTIMIZATION.md
+- FIX_NAME_MAPPING.md
+- QUICK_DEBUG_SUMMARY.md
+- UPDATE_CONFIG_GUIDE.md
+- FINAL_UPDATE.md
+- FINAL_SUMMARY.md
+- CURRENT_STATUS.md
+- DELIVERY.md
+- PROJECT_SUMMARY.md
+- STRUCTURE.md
+- FIELD_MAPPING.md
+
+已删除的临时文档（根目录）:
+- DEBUG_IMPLEMENTATION_SUMMARY.md
+- CONFIG_CHANGES_SUMMARY.md
+- OFFLINE_TASKS_SUMMARY.md
+- OFFLINE_TASKS_README.md
+- tables_structure.md
+```
+
+#### 4.3 文档命名规范
+- ✅ 所有重要文档使用中文名
+- ✅ 统一放在 `doc/` 目录
+- ✅ 创建 `doc/README.md` 索引
+- ✅ collaboration目录下的文档同步规范
+
+---
+
+## 📊 改进效果对比
+
+### 数据库查询优化
+
+**改进前**:
+```
+每次运行任务:
+  1. i2i_swing.py        → 查询商品名称
+  2. add_names_to_swing  → 查询商品名称
+  3. 其他debug任务       → 重复查询
+  
+总查询次数: 5-10次（取决于任务数）
+```
+
+**改进后**:
+```
+每次运行任务:
+  1. fetch_item_attributes.py  → 查询1次，保存文件
+  2. 所有后续任务              → 加载本地文件
+  
+总查询次数: 1次
+```
+
+**性能提升**: 减少 80-90% 的数据库查询
+
+### Session文件生成
+
+**改进前**:
+```
+- i2i_swing.py 内部查询数据库
+- C++ Swing需要手动准备数据
+```
+
+**改进后**:
+```
+- generate_session.py 统一生成
+- 支持两种格式（标准/C++）
+- 所有算法可复用
+```
+
+### 文档管理
+
+**改进前**:
+- 30+ 散乱的Markdown文件
+- 无明确分类和索引
+- 大量临时记录
+
+**改进后**:
+- 13个核心文档
+- 统一在 doc/ 目录
+- 清晰的索引和分类
+
+---
+
+## 🚀 使用指南
+
+### 运行完整流程
+
+```bash
+cd /home/tw/recommendation/offline_tasks
+
+# 方式1: 运行全部任务（推荐）
+python3 run_all.py --debug
+
+# 方式2: 分步运行
+# 步骤1: 获取商品属性
+python3 scripts/fetch_item_attributes.py
+
+# 步骤2: 生成session文件
+python3 scripts/generate_session.py --lookback_days 730
+
+# 步骤3: 运行Swing算法（启用日期维度）
+python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug
+```
+
+### C++ Swing算法
+
+```bash
+cd /home/tw/recommendation/collaboration
+
+# session文件自动生成后，运行Swing
+bash run.sh
+```
+
+### 查看文档
+
+```bash
+cd /home/tw/recommendation/offline_tasks/doc
+
+# 查看文档索引
+cat README.md
+
+# 快速开始
+cat 快速开始.md
+
+# 详细使用指南
+cat Swing算法使用指南.md
+```
+
+---
+
+## 📁 文件结构
+
+```
+recommendation/
+├── offline_tasks/
+│   ├── scripts/
+│   │   ├── fetch_item_attributes.py      # 新增：前置任务
+│   │   ├── generate_session.py           # 已有：session生成
+│   │   ├── add_names_to_swing.py         # 修改：使用本地映射
+│   │   ├── i2i_swing.py                  # 修改：支持日期维度
+│   │   └── debug_utils.py                # 修改：添加加载函数
+│   ├── doc/                              # 新增：文档中心
+│   │   ├── README.md
+│   │   ├── 快速开始.md
+│   │   ├── Swing算法使用指南.md
+│   │   └── ...
+│   ├── output/
+│   │   ├── item_attributes_mappings.json # 新增：映射文件
+│   │   ├── item_attributes_stats.txt     # 新增：统计信息
+│   │   └── session.txt.YYYYMMDD          # session文件
+│   ├── run_all.py                        # 修改：添加前置任务
+│   └── README.md
+└── collaboration/
+    ├── run.sh                             # 已修改：适配session
+    ├── Swing快速开始.md                   # 重命名
+    └── ...
+```
+
+---
+
+## 🎯 核心改进点总结
+
+1. **✅ 性能优化**: 减少80-90%的数据库查询
+2. **✅ 架构优化**: 前置任务解耦，数据准备与算法分离
+3. **✅ 功能增强**: Swing算法支持日期维度
+4. **✅ 文档规范**: 统一管理，中文命名，清晰索引
+5. **✅ 代码质量**: 无Linter错误，统一编码规范
+
+---
+
+## 📝 后续建议
+
+### 短期优化
+
+1. **监控与告警**
+   - 添加任务执行时间监控
+   - 映射文件过期检测
+   - 自动重新获取机制
+
+2. **性能优化**
+   - Session文件增量更新
+   - 映射文件分批加载
+   - 并行任务执行
+
+### 长期规划
+
+1. **分布式支持**
+   - 多机协同计算
+   - 数据分片处理
+   
+2. **实时更新**
+   - 在线学习机制
+   - 增量索引更新
+
+3. **A/B测试框架**
+   - 多版本算法对比
+   - 效果评估系统
+
+---
+
+## 📞 相关文档
+
+- **快速开始**: [doc/快速开始.md](./快速开始.md)
+- **详细指南**: [doc/Swing算法使用指南.md](./Swing算法使用指南.md)
+- **故障排查**: [doc/故障排查指南.md](./故障排查指南.md)
+- **文档索引**: [doc/README.md](./README.md)
+
+---
+
+**改进完成时间**: 2024-10-17  
+**状态**: ✅ 已完成并测试通过
+
@@ -0,0 +1,332 @@
+# Debug模式使用指南
+
+## 🐛 Debug功能概述
+
+Debug模式为所有离线任务提供：
+1. **详细的DEBUG级别日志** - 显示数据流向、统计信息、处理进度
+2. **明文索引文件** - ID后面带上对应的名称，方便检查效果
+3. **数据采样展示** - 关键步骤的示例数据
+4. **性能统计** - 每个步骤的耗时和资源使用
+
+## 🚀 快速开始
+
+### 1. 运行单个脚本（Debug模式）
+
+```bash
+cd /home/tw/recommendation/offline_tasks
+
+# Swing算法 - Debug模式
+python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
+
+# 兴趣聚合 - Debug模式  
+python3 scripts/interest_aggregation.py --lookback_days 7 --top_n 100 --debug
+
+# 内容相似 - Debug模式
+python3 scripts/i2i_content_similar.py --top_n 10 --debug
+```
+
+### 2. 运行所有任务（Debug模式）
+
+```bash
+# 使用debug参数运行所有任务
+python3 run_all.py --lookback_days 7 --top_n 10 --debug
+```
+
+## 📊 Debug输出说明
+
+### A. 日志输出
+
+Debug模式下，日志会输出到两个地方：
+1. **控制台** - 实时查看进度
+2. **Debug日志文件** - 完整保存
+
+日志文件位置：
+```
+offline_tasks/logs/debug/i2i_swing_20251016_193000.log
+offline_tasks/logs/debug/interest_aggregation_20251016_193500.log
+...
+```
+
+### B. 日志内容示例
+
+```
+2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
+2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数:
+2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
+2025-10-16 19:30:00 - i2i_swing - DEBUG -   alpha: 0.5
+2025-10-16 19:30:00 - i2i_swing - DEBUG -   top_n: 10
+2025-10-16 19:30:00 - i2i_swing - DEBUG -   lookback_days: 7
+2025-10-16 19:30:00 - i2i_swing - DEBUG -   debug: True
+2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
+
+2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录
+
+2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 用户行为数据 信息:
+2025-10-16 19:30:05 - i2i_swing - DEBUG - ============================================================
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 总列数: 5
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 列名: ['user_id', 'item_id', 'event_type', 'create_time', 'item_name']
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 数据类型:
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   user_id: object
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   item_id: int64
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   event_type: object
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   create_time: datetime64[ns]
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   item_name: object
+
+2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布:
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToCart: 8520 (55.93%)
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   contactFactory: 3456 (22.68%)
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   purchase: 2134 (14.01%)
+2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToPool: 1124 (7.38%)
+
+2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345
+2025-10-16 19:30:15 - i2i_swing - DEBUG - 已处理 50/2345 个商品 (2.1%)
+2025-10-16 19:30:20 - i2i_swing - DEBUG - 已处理 100/2345 个商品 (4.3%)
+...
+```
+
+### C. 明文索引文件
+
+Debug模式下，每个索引文件都会生成对应的明文文件：
+
+**原始索引文件** (`output/i2i_swing_20251016.txt`):
+```
+12345	香蕉干	67890:0.8567,11223:0.7234,44556:0.6891
+67890	芒果干	12345:0.8567,22334:0.7123,55667:0.6543
+```
+
+**明文索引文件** (`output/debug/i2i_swing_20251016_readable.txt`):
+```
+================================================================================
+明文索引文件
+生成时间: 2025-10-16 19:35:00
+描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7)
+总索引数: 2345
+================================================================================
+
+[1] i2i:swing:12345(香蕉干)
+--------------------------------------------------------------------------------
+  1. ID:67890(芒果干) - Score:0.8567
+  2. ID:11223(菠萝干) - Score:0.7234
+  3. ID:44556(苹果干) - Score:0.6891
+  4. ID:22334(木瓜干) - Score:0.6234
+  5. ID:55667(草莓干) - Score:0.5891
+
+[2] i2i:swing:67890(芒果干)
+--------------------------------------------------------------------------------
+  1. ID:12345(香蕉干) - Score:0.8567
+  2. ID:22334(木瓜干) - Score:0.7123
+  3. ID:55667(草莓干) - Score:0.6543
+  4. ID:11223(菠萝干) - Score:0.6234
+  5. ID:44556(苹果干) - Score:0.5891
+
+...
+
+================================================================================
+已输出 50/2345 个索引
+================================================================================
+```
+
+## 📁 文件结构
+
+Debug模式下的文件组织：
+
+```
+offline_tasks/
+├── output/
+│   ├── i2i_swing_20251016.txt              # 原始索引文件
+│   ├── interest_aggregation_hot_20251016.txt
+│   └── debug/                               # Debug明文文件目录
+│       ├── i2i_swing_20251016_readable.txt  # 明文索引
+│       ├── interest_aggregation_hot_20251016_readable.txt
+│       └── ...
+└── logs/
+    ├── run_all_20251016.log                 # 主日志
+    └── debug/                               # Debug详细日志目录
+        ├── i2i_swing_20251016_193000.log
+        ├── interest_aggregation_20251016_193500.log
+        └── ...
+```
+
+## 🔍 使用场景
+
+### 场景1：调试数据流程
+
+```bash
+# 使用小数据量+debug模式快速验证
+python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug
+
+# 查看日志，检查：
+# - 数据加载是否正确
+# - 行为类型分布是否合理
+# - 用户/商品数量是否符合预期
+```
+
+### 场景2：检查推荐效果
+
+```bash
+# 生成明文索引文件
+python3 scripts/i2i_swing.py --lookback_days 7 --top_n 20 --debug
+
+# 打开明文文件查看：
+cat output/debug/i2i_swing_20251016_readable.txt | less
+
+# 检查推荐是否合理，例如：
+# - 香蕉干 -> 芒果干、菠萝干 ✓ 合理
+# - 电脑 -> 香蕉干 ✗ 不合理，需要调整参数
+```
+
+### 场景3：性能调优
+
+```bash
+# Debug模式查看各步骤耗时
+python3 scripts/i2i_swing.py --debug 2>&1 | grep "耗时"
+
+# 输出示例：
+# 步骤1耗时: 2.34秒
+# 步骤2耗时: 15.67秒  <- 瓶颈在这里
+# 步骤3耗时: 1.23秒
+# 总耗时: 19.24秒
+```
+
+### 场景4：参数调整
+
+```bash
+# 测试不同alpha值的效果
+python3 scripts/i2i_swing.py --alpha 0.3 --debug > alpha_0.3.log 2>&1
+python3 scripts/i2i_swing.py --alpha 0.5 --debug > alpha_0.5.log 2>&1
+python3 scripts/i2i_swing.py --alpha 0.7 --debug > alpha_0.7.log 2>&1
+
+# 对比明文文件，选择最佳参数
+diff output/debug/i2i_swing_*_readable.txt
+```
+
+## 💡 最佳实践
+
+### 1. 开发调试阶段
+
+```bash
+# 使用小数据量 + Debug模式
+python3 run_all.py --lookback_days 3 --top_n 10 --debug
+```
+
+- ✅ 快速验证流程
+- ✅ 详细日志便于排错
+- ✅ 明文文件检查效果
+
+### 2. 参数调优阶段
+
+```bash
+# 中等数据量 + Debug模式
+python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug
+```
+
+- ✅ 查看数据分布
+- ✅ 评估推荐质量
+- ✅ 调整算法参数
+
+### 3. 生产运行阶段
+
+```bash
+# 大数据量 + 正常模式（不加--debug）
+python3 run_all.py --lookback_days 730 --top_n 50
+```
+
+- ✅ 高效运行
+- ✅ 只输出必要日志
+- ✅ 节省磁盘空间
+
+## 🛠️ Debug工具
+
+### 查看实时日志
+
+```bash
+# 实时查看debug日志
+tail -f logs/debug/i2i_swing_*.log
+
+# 只看DEBUG级别
+tail -f logs/debug/i2i_swing_*.log | grep "DEBUG"
+
+# 只看错误
+tail -f logs/debug/i2i_swing_*.log | grep "ERROR"
+```
+
+### 统计分析
+
+```bash
+# 统计处理的数据量
+grep "总行数" logs/debug/*.log
+
+# 统计生成的索引数
+grep "总索引数" output/debug/*_readable.txt
+
+# 查看性能统计
+grep "耗时" logs/debug/*.log
+```
+
+### 快速检查
+
+```bash
+# 检查前10个推荐
+head -50 output/debug/i2i_swing_*_readable.txt
+
+# 搜索特定商品的推荐
+grep "香蕉干" output/debug/i2i_swing_*_readable.txt -A 10
+
+# 统计推荐数量分布
+grep "Score:" output/debug/i2i_swing_*_readable.txt | wc -l
+```
+
+## ⚠️ 注意事项
+
+1. **磁盘空间**
+   - Debug日志和明文文件会占用较多空间
+   - 建议定期清理：`rm -rf logs/debug/* output/debug/*`
+
+2. **运行时间**
+   - Debug模式会增加10-20%的运行时间
+   - 生产环境建议关闭debug
+
+3. **敏感信息**
+   - 明文文件包含商品名称等信息
+   - 注意数据安全和隐私保护
+
+4. **文件编码**
+   - 明文文件使用UTF-8编码
+   - 确保查看工具支持中文显示
+
+## 📖 相关命令
+
+```bash
+# 查看帮助
+python3 scripts/i2i_swing.py --help
+python3 run_all.py --help
+
+# 验证配置
+python3 -c "from config.offline_config import DEBUG_CONFIG; print(DEBUG_CONFIG)"
+
+# 测试debug工具
+python3 -c "from scripts.debug_utils import *; print('Debug utils loaded OK')"
+```
+
+## ✅ 验证Debug功能
+
+```bash
+# 快速测试
+cd /home/tw/recommendation/offline_tasks
+python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug
+
+# 应该看到：
+# ✓ DEBUG级别日志输出
+# ✓ 创建debug日志文件
+# ✓ 生成明文索引文件
+# ✓ 显示数据统计信息
+```
+
+---
+
+**Debug模式**: 开发和调试的利器  
+**正常模式**: 生产环境的选择  
+**灵活切换**: 一个参数的事情
@@ -0,0 +1,304 @@
+# run.sh 运行脚本使用指南
+
+## 概述
+
+`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。
+
+## 主要特性
+
+### 1. 内存监控
+- **警告阈值**: 25GB - 打印警告日志
+- **强制终止阈值**: 30GB - 自动kill进程
+- **检查频率**: 每10秒检查一次
+- **日志文件**: `logs/memory_monitor.log`
+
+### 2. 任务流程
+1. 清理旧进程和输出
+2. 运行调试模式（小数据量测试）
+3. 运行生产模式（大数据量）
+4. 加载索引到Redis
+
+### 3. 错误处理
+- 任何步骤失败会立即退出
+- 显示详细的退出码
+- 保存完整日志
+
+## 使用方法
+
+### 基本运行
+```bash
+cd /home/tw/recommendation/offline_tasks
+./run.sh
+```
+
+### 查看实时输出
+```bash
+./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log
+```
+
+### 后台运行
+```bash
+nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 &
+```
+
+## 内存监控说明
+
+### 监控逻辑
+
+```bash
+check_memory() {
+    local pid=$1
+    local threshold_warn=25  # 25GB警告
+    local threshold_kill=30  # 30GB强制kill
+    
+    while 进程运行中; do
+        获取内存使用
+        
+        if 内存 >= 30GB:
+            打印错误日志
+            强制终止进程
+            break
+        elif 内存 >= 25GB:
+            打印警告日志
+        
+        sleep 10秒
+    done
+}
+```
+
+### 日志格式
+
+**警告日志**:
+```
+[2025-10-17 14:30:25] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12345
+```
+
+**强制终止日志**:
+```
+[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345
+```
+
+### 查看监控日志
+```bash
+# 实时查看
+tail -f logs/memory_monitor.log
+
+# 查看历史
+cat logs/memory_monitor.log
+```
+
+## 运行流程
+
+### 步骤1: 调试模式
+```bash
+python3 run_all.py --debug
+```
+- 使用默认参数（见 `offline_config.py`）
+- 输出保存到 `output_debug/`
+- 启动内存监控
+
+### 步骤2: 生产模式
+```bash
+python3 run_all.py --debug
+```
+- 生成完整索引
+- 输出保存到 `output/`
+- 启动内存监控
+
+### 步骤3: 加载Redis
+```bash
+python3 scripts/load_index_to_redis.py --redis-host localhost
+```
+- 加载所有生成的索引
+- 包括新增的内容相似索引
+
+## 输出示例
+
+```
+======================================================================
+开始运行离线任务 - 2025-10-17 14:00:00
+内存监控: 警告阈值=25GB, 强制终止阈值=30GB
+======================================================================
+
+>>> 步骤1: 调试模式运行（小数据量）
+调试任务 PID: 12345
+✓ 调试模式完成
+
+>>> 步骤2: 生产模式运行（大数据量）
+生产任务 PID: 12346
+[2025-10-17 14:30:25] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12346
+✓ 生产模式完成
+
+>>> 步骤3: 加载到Redis
+✓ Redis加载完成
+
+======================================================================
+所有任务完成 - 2025-10-17 16:30:00
+======================================================================
+```
+
+## 自定义配置
+
+### 修改内存阈值
+
+编辑 `run.sh` 中的以下行：
+```bash
+local threshold_warn=25  # 修改警告阈值
+local threshold_kill=30  # 修改强制kill阈值
+```
+
+### 修改检查频率
+
+编辑 `run.sh` 中的以下行：
+```bash
+sleep 10  # 修改为其他秒数
+```
+
+### 跳过调试模式
+
+注释掉步骤1相关代码：
+```bash
+# # 3. 调试模式运行（小数据量）
+# echo ""
+# echo ">>> 步骤1: 调试模式运行（小数据量）"
+# python3 run_all.py --debug &
+# ...
+```
+
+### 修改Redis配置
+
+修改步骤3的参数：
+```bash
+python3 scripts/load_index_to_redis.py \
+  --redis-host your-redis-host \
+  --redis-port 6379 \
+  --redis-db 0
+```
+
+## 故障排查
+
+### 内存持续超限
+
+**原因**:
+- 数据量太大
+- 内存泄漏
+- 并发任务过多
+
+**解决方案**:
+1. 增加内存阈值（临时方案）
+2. 优化代码减少内存占用
+3. 分批处理数据
+4. 使用增量更新
+
+### 进程被意外终止
+
+**检查日志**:
+```bash
+# 查看监控日志
+cat logs/memory_monitor.log
+
+# 查看任务日志
+ls -lht logs/
+cat logs/run_all_*.log
+```
+
+### 任务失败
+
+**查看退出码**:
+- 0: 成功
+- 1: 一般错误
+- 137: 被kill信号终止（可能是内存超限）
+- 其他: 查看具体错误信息
+
+## 监控建议
+
+### 1. 添加系统监控
+```bash
+# 安装监控工具
+apt install htop iotop
+
+# 实时监控
+htop -p $(pgrep -f run_all.py)
+```
+
+### 2. 设置告警
+```bash
+# 配置邮件告警
+if [ $PROD_EXIT_CODE -ne 0 ]; then
+    echo "任务失败" | mail -s "离线任务告警" admin@example.com
+fi
+```
+
+### 3. 定时任务
+```bash
+# 添加到crontab
+0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1
+```
+
+## 性能优化
+
+### 内存优化建议
+
+1. **分批处理**
+   ```python
+   # 在代码中使用batch处理
+   batch_size = 1000
+   for i in range(0, len(items), batch_size):
+       batch = items[i:i+batch_size]
+       process(batch)
+   ```
+
+2. **及时释放**
+   ```python
+   import gc
+   del large_object
+   gc.collect()
+   ```
+
+3. **使用生成器**
+   ```python
+   def process_items():
+       for item in items:
+           yield process(item)
+   ```
+
+## 日志管理
+
+### 日志文件
+- `logs/memory_monitor.log` - 内存监控日志
+- `logs/run_all_YYYYMMDD.log` - 任务运行日志
+- `output/` - 生成的索引文件
+- `output_debug/` - 调试模式输出
+
+### 清理旧日志
+```bash
+# 保留最近7天
+find logs/ -name "*.log" -mtime +7 -delete
+
+# 压缩旧日志
+find logs/ -name "*.log" -mtime +3 -exec gzip {} \;
+```
+
+## 安全注意事项
+
+1. **权限**: 确保脚本有执行权限 `chmod +x run.sh`
+2. **路径**: 使用绝对路径避免混淆
+3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀
+4. **备份**: 脚本会删除output目录，请提前备份重要数据
+
+## 总结
+
+`run.sh` 提供了：
+- ✅ 自动化运行流程
+- ✅ 内存监控保护
+- ✅ 详细日志记录
+- ✅ 错误处理机制
+- ✅ 进度显示
+
+建议在生产环境使用前先在测试环境验证。
+
+---
+
+**更新时间**: 2025-10-17  
+**版本**: v2.0
+
@@ -29,12 +29,6 @@ check_memory() {
     done
 }
  
-# # 查看配置指南
-# cat UPDATE_CONFIG_GUIDE.md
-
-# 2. 测试连接
-# python3 test_connection.py
-
 # 清理旧进程
 ps -ef|grep run_all.py | awk '{print $2}' | xargs kill -9 2>/dev/null
 ps -ef|grep recommendation | awk '{print $2}' | xargs kill -9 2>/dev/null
@@ -50,7 +44,8 @@ echo &quot;======================================================================&quot;
  
 echo ""
 echo ">>>  run_all.py"
-python3 run_all.py --debug
+# python3 run_all.py --lookback_days 400 --top_n 50 --debug &
+python3 run_all.py --debug &
 PID_PROD=$!
 echo "生产任务 PID: $PID_PROD"
  
@@ -95,6 +95,35 @@ def main():
     success_count = 0
     total_count = 0
  
+    # 前置任务1: 获取item基础属性
+    logger.info("\n" + "="*80)
+    logger.info("前置任务1: 获取商品基础属性（ID->名称映射）")
+    logger.info("="*80)
+    total_count += 1
+    script_args = []
+    if args.debug:
+        script_args.append('--debug')
+    if run_script('fetch_item_attributes.py', script_args):
+        success_count += 1
+    else:
+        logger.error("获取商品属性失败，后续任务可能无法生成可读文件")
+    
+    # 前置任务2: 生成session文件
+    logger.info("\n" + "="*80)
+    logger.info("前置任务2: 生成用户行为Session文件")
+    logger.info("="*80)
+    total_count += 1
+    script_args = [
+        '--lookback_days', str(DEFAULT_LOOKBACK_DAYS),
+        '--format', 'both'
+    ]
+    if args.debug:
+        script_args.append('--debug')
+    if run_script('generate_session.py', script_args):
+        success_count += 1
+    else:
+        logger.error("生成session文件失败")
+    
     # i2i 行为相似任务
     logger.info("\n" + "="*80)
     logger.info("Task 1: Running Swing algorithm for i2i similarity")
@@ -9,9 +9,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(
  
 import argparse
 from datetime import datetime
-from db_service import create_db_connection
-from offline_tasks.config.offline_config import DB_CONFIG
-from offline_tasks.scripts.debug_utils import setup_debug_logger, fetch_name_mappings
+from offline_tasks.scripts.debug_utils import setup_debug_logger, load_name_mappings_from_file
  
  
 def add_names_to_swing_result(input_file, output_file, name_mappings, logger=None, debug=False):
@@ -110,20 +108,16 @@ def main():
         logger.error(f"输入文件不存在: {args.input_file}")
         return
  
-    # 创建数据库连接
-    logger.info("连接数据库...")
-    engine = create_db_connection(
-        DB_CONFIG['host'],
-        DB_CONFIG['port'],
-        DB_CONFIG['database'],
-        DB_CONFIG['username'],
-        DB_CONFIG['password']
-    )
+    # 从本地文件加载名称映射
+    logger.info("加载ID到名称的映射...")
+    name_mappings = load_name_mappings_from_file(debug=args.debug)
+    
+    if not name_mappings or not name_mappings.get('item'):
+        logger.error("映射文件为空或加载失败")
+        logger.error("请先运行: python3 scripts/fetch_item_attributes.py")
+        return
  
-    # 获取名称映射
-    logger.info("获取ID到名称的映射...")
-    name_mappings = fetch_name_mappings(engine, debug=args.debug)
-    logger.info(f"获取到 {len(name_mappings['item'])} 个商品名称")
+    logger.info(f"加载了 {len(name_mappings['item'])} 个商品名称")
  
     # 处理文件
     add_names_to_swing_result(
@@ -255,9 +255,60 @@ def format_key_with_name(key, name_mappings):
     return ':'.join(formatted_parts)
  
  
+def load_name_mappings_from_file(mappings_file=None, debug=False):
+    """
+    从本地文件加载ID到名称的映射（推荐使用）
+    避免重复查询数据库，提高性能
+    
+    Args:
+        mappings_file: 映射文件路径（如果为None，使用默认路径）
+        debug: 是否输出debug信息
+    
+    Returns:
+        name_mappings字典
+    """
+    if mappings_file is None:
+        # 默认路径
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        mappings_file = os.path.join(base_dir, 'output', 'item_attributes_mappings.json')
+    
+    if not os.path.exists(mappings_file):
+        if debug:
+            print(f"✗ 映射文件不存在: {mappings_file}")
+            print(f"  请先运行 fetch_item_attributes.py 生成映射文件")
+        return {
+            'item': {},
+            'category': {},
+            'platform': {},
+            'supplier': {},
+            'client_platform': {}
+        }
+    
+    try:
+        with open(mappings_file, 'r', encoding='utf-8') as f:
+            mappings = json.load(f)
+        
+        if debug:
+            print(f"✓ 从文件加载映射: {mappings_file}")
+            for key, value in mappings.items():
+                print(f"  {key}: {len(value)} 个映射")
+        
+        return mappings
+    except Exception as e:
+        if debug:
+            print(f"✗ 加载映射文件失败: {e}")
+        return {
+            'item': {},
+            'category': {},
+            'platform': {},
+            'supplier': {},
+            'client_platform': {}
+        }
+
+
 def fetch_name_mappings(engine, debug=False):
     """
-    从数据库获取ID到名称的映射
+    从数据库获取ID到名称的映射（已弃用，建议使用load_name_mappings_from_file）
  
     Args:
         engine: 数据库连接
@@ -268,6 +319,10 @@ def fetch_name_mappings(engine, debug=False):
     """
     import pandas as pd
  
+    if debug:
+        print("⚠️  警告: 使用fetch_name_mappings直接查询数据库")
+        print("   建议使用load_name_mappings_from_file加载本地映射文件")
+    
     mappings = {
         'item': {},
         'category': {},
@@ -0,0 +1,179 @@
+"""
+获取商品基础属性（前置任务）
+从数据库获取ID->名称的映射，保存到本地文件供其他任务使用
+避免每个任务重复查询数据库
+"""
+import sys
+import os
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+import pandas as pd
+import json
+import argparse
+from datetime import datetime
+from db_service import create_db_connection
+from offline_tasks.config.offline_config import DB_CONFIG, OUTPUT_DIR
+from offline_tasks.scripts.debug_utils import setup_debug_logger
+
+
+def fetch_and_save_mappings(engine, output_dir, logger=None, debug=False):
+    """
+    从数据库获取各种ID->名称映射并保存
+    
+    Args:
+        engine: 数据库连接
+        output_dir: 输出目录
+        logger: 日志记录器
+        debug: 是否开启debug模式
+    
+    Returns:
+        mappings字典和输出文件路径
+    """
+    if logger:
+        logger.info("开始获取ID到名称的映射...")
+    
+    mappings = {
+        'item': {},
+        'category': {},
+        'platform': {},
+        'supplier': {},
+        'client_platform': {}
+    }
+    
+    stats = {}
+    
+    # 1. 获取商品名称
+    try:
+        if logger:
+            logger.info("获取商品名称...")
+        query = "SELECT id, name FROM prd_goods_sku WHERE status IN (2,4,5) LIMIT 5000000"
+        df = pd.read_sql(query, engine)
+        mappings['item'] = dict(zip(df['id'].astype(str), df['name']))
+        stats['item'] = len(mappings['item'])
+        if logger:
+            logger.info(f"✓ 获取到 {stats['item']} 个商品名称")
+    except Exception as e:
+        if logger:
+            logger.error(f"✗ 获取商品名称失败: {e}")
+        stats['item'] = 0
+    
+    # 2. 获取分类名称
+    try:
+        if logger:
+            logger.info("获取分类名称...")
+        query = "SELECT id, name FROM prd_category LIMIT 100000"
+        df = pd.read_sql(query, engine)
+        mappings['category'] = dict(zip(df['id'].astype(str), df['name']))
+        stats['category'] = len(mappings['category'])
+        if logger:
+            logger.info(f"✓ 获取到 {stats['category']} 个分类名称")
+    except Exception as e:
+        if logger:
+            logger.error(f"✗ 获取分类名称失败: {e}")
+        stats['category'] = 0
+    
+    # 3. 获取供应商名称
+    try:
+        if logger:
+            logger.info("获取供应商名称...")
+        query = "SELECT id, name FROM sup_supplier LIMIT 100000"
+        df = pd.read_sql(query, engine)
+        mappings['supplier'] = dict(zip(df['id'].astype(str), df['name']))
+        stats['supplier'] = len(mappings['supplier'])
+        if logger:
+            logger.info(f"✓ 获取到 {stats['supplier']} 个供应商名称")
+    except Exception as e:
+        if logger:
+            logger.error(f"✗ 获取供应商名称失败: {e}")
+        stats['supplier'] = 0
+    
+    # 4. 平台名称（硬编码）
+    mappings['platform'] = {
+        'pc': 'PC端',
+        'h5': 'H5移动端',
+        'app': 'APP',
+        'miniprogram': '小程序',
+        'wechat': '微信'
+    }
+    stats['platform'] = len(mappings['platform'])
+    
+    # 5. 客户端平台（硬编码）
+    mappings['client_platform'] = {
+        'iOS': 'iOS',
+        'Android': 'Android',
+        'Web': 'Web',
+        'H5': 'H5'
+    }
+    stats['client_platform'] = len(mappings['client_platform'])
+    
+    # 保存到文件
+    os.makedirs(output_dir, exist_ok=True)
+    output_file = os.path.join(output_dir, 'item_attributes_mappings.json')
+    
+    if logger:
+        logger.info(f"保存映射到: {output_file}")
+    
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(mappings, f, ensure_ascii=False, indent=2)
+    
+    # 保存统计信息
+    stats_file = os.path.join(output_dir, 'item_attributes_stats.txt')
+    with open(stats_file, 'w', encoding='utf-8') as f:
+        f.write(f"商品属性映射统计信息\n")
+        f.write(f"生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+        f.write(f"=" * 60 + "\n")
+        for key, count in stats.items():
+            f.write(f"{key}: {count}\n")
+        f.write(f"=" * 60 + "\n")
+        f.write(f"总计: {sum(stats.values())}\n")
+    
+    if logger:
+        logger.info(f"统计信息已保存到: {stats_file}")
+        logger.info(f"总计获取 {sum(stats.values())} 个映射")
+    
+    return mappings, output_file
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Fetch item attributes and save mappings')
+    parser.add_argument('--output_dir', type=str, default=OUTPUT_DIR,
+                       help='Output directory for mappings file')
+    parser.add_argument('--debug', action='store_true',
+                       help='Enable debug mode with detailed logging')
+    
+    args = parser.parse_args()
+    
+    # 设置日志
+    logger = setup_debug_logger('fetch_item_attributes', debug=args.debug)
+    
+    logger.info("="*60)
+    logger.info("商品属性获取任务（前置任务）")
+    logger.info("="*60)
+    
+    # 创建数据库连接
+    logger.info("连接数据库...")
+    engine = create_db_connection(
+        DB_CONFIG['host'],
+        DB_CONFIG['port'],
+        DB_CONFIG['database'],
+        DB_CONFIG['username'],
+        DB_CONFIG['password']
+    )
+    
+    # 获取并保存映射
+    mappings, output_file = fetch_and_save_mappings(
+        engine,
+        args.output_dir,
+        logger=logger,
+        debug=args.debug
+    )
+    
+    logger.info("="*60)
+    logger.info("✓ 商品属性获取完成！")
+    logger.info(f"映射文件: {output_file}")
+    logger.info("="*60)
+
+
+if __name__ == '__main__':
+    main()
+
@@ -20,7 +20,7 @@ from offline_tasks.config.offline_config import (
 )
 from offline_tasks.scripts.debug_utils import (
     setup_debug_logger, log_dataframe_info, log_dict_stats,
-    save_readable_index, fetch_name_mappings, log_algorithm_params,
+    save_readable_index, load_name_mappings_from_file, log_algorithm_params,
     log_processing_step
 )
  
@@ -51,7 +51,7 @@ def calculate_time_weight(event_time, reference_time, decay_factor=0.95, days_un
     return weight
  
  
-def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=None, debug=False):
+def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, use_daily_session=True, logger=None, debug=False):
     """
     Swing算法实现
  
@@ -60,6 +60,7 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No
         alpha: Swing算法的alpha参数
         time_decay: 是否使用时间衰减
         decay_factor: 时间衰减因子
+        use_daily_session: 是否同时使用uid+日期作为session维度
         logger: 日志记录器
         debug: 是否开启debug模式
  
@@ -68,7 +69,7 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No
     """
     start_time = datetime.now()
     if logger:
-        logger.debug(f"开始Swing算法计算，参数: alpha={alpha}, time_decay={time_decay}")
+        logger.debug(f"开始Swing算法计算，参数: alpha={alpha}, time_decay={time_decay}, use_daily_session={use_daily_session}")
  
     # 如果使用时间衰减，计算时间权重
     reference_time = datetime.now()
@@ -82,6 +83,27 @@ def swing_algorithm(df, alpha=0.5, time_decay=True, decay_factor=0.95, logger=No
         if logger and debug:
             logger.debug(f"时间权重统计: min={df['time_weight'].min():.4f}, max={df['time_weight'].max():.4f}, avg={df['time_weight'].mean():.4f}")
  
+    # 如果启用daily_session，duplicate数据：添加uid+date作为新的uid
+    if use_daily_session and 'create_time' in df.columns:
+        if logger:
+            logger.info("启用日期维度：duplicate数据，添加uid+日期作为新的session")
+        
+        # 创建原始数据副本
+        df_original = df.copy()
+        
+        # 创建uid+date版本
+        df_daily = df.copy()
+        df_daily['date'] = pd.to_datetime(df_daily['create_time']).dt.strftime('%Y%m%d')
+        df_daily['user_id'] = df_daily['user_id'].astype(str) + '_' + df_daily['date']
+        
+        # 合并两份数据
+        df = pd.concat([df_original, df_daily], ignore_index=True)
+        
+        if logger:
+            logger.info(f"原始数据: {len(df_original)} 条")
+            logger.info(f"日期维度数据: {len(df_daily)} 条")
+            logger.info(f"合并后总数据: {len(df)} 条")
+    
     # 构建用户-物品倒排索引
     if logger:
         log_processing_step(logger, "步骤1: 构建用户-物品倒排索引")
@@ -201,6 +223,10 @@ def main():
                        help='Use time decay for behavior weights (default: False for B2B low-frequency scenarios)')
     parser.add_argument('--decay_factor', type=float, default=0.95,
                        help='Time decay factor')
+    parser.add_argument('--use_daily_session', action='store_true', default=True,
+                       help='Use uid+date as additional session dimension (default: True)')
+    parser.add_argument('--no_daily_session', action='store_false', dest='use_daily_session',
+                       help='Disable uid+date session dimension')
     parser.add_argument('--output', type=str, default=None,
                        help='Output file path')
     parser.add_argument('--debug', action='store_true',
@@ -218,6 +244,7 @@ def main():
         'lookback_days': args.lookback_days,
         'time_decay': args.time_decay,
         'decay_factor': args.decay_factor,
+        'use_daily_session': args.use_daily_session,
         'debug': args.debug
     })
  
@@ -299,6 +326,7 @@ def main():
         alpha=args.alpha,
         time_decay=args.time_decay,
         decay_factor=args.decay_factor,
+        use_daily_session=args.use_daily_session,
         logger=logger,
         debug=args.debug
     )
@@ -333,9 +361,9 @@ def main():
     if args.debug:
         logger.info("Debug模式：生成明文索引文件...")
         try:
-            # 获取名称映射
-            logger.debug("获取ID到名称的映射...")
-            name_mappings = fetch_name_mappings(engine, debug=True)
+            # 从本地文件加载名称映射
+            logger.debug("加载ID到名称的映射...")
+            name_mappings = load_name_mappings_from_file(debug=True)
  
             # 准备索引数据（合并已有的item_name_map）
             # item_name_map的key已经是str类型，可以直接更新