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