# 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`