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