# 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
  **状态**: ✅ 已完成