Swing算法使用指南.md 8.21 KB
Edit Raw Blame History


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文件。
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算法。
cd /home/tw/recommendation/collaboration

# 直接运行（使用默认配置）
bash run.sh

# 或者给脚本添加执行权限后运行
chmod +x run.sh
./run.sh


配置说明（修改run.sh中的参数）：
# 数据路径配置
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环境，修改此处


脚本执行流程：


编译C++程序（swing, icf_simple, swing_symmetric）
查找当天日期的session文件
运行Swing算法计算物品相似度
合并多线程输出结果
自动调用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文件（可选）
如果需要为其他文件生成可读版本：
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算法参数

alpha (0.5-1.0)


越小：越关注用户共同行为的多样性
越大：越容忽略用户重叠度
建议：0.5-0.7（B2B场景）

threshold1 (1-5)


用于筛选用户的有效行为
建议：1-3（低频场景可用1）

threshold2 (1-10)


用于计算相似度的行为强度阈值
建议：3-5（需要较强的交互信号）

thread_num (1-20)


根据CPU核心数设置
建议：4-8（普通服务器）


数据范围参数

lookback_days


B2B低频场景：建议730天（2年）
B2C高频场景：建议30-90天
数据量大时可适当减少


完整示例
# 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


解决方法：
cd /home/tw/recommendation/offline_tasks
python3 scripts/generate_session.py

问题2: 编译失败
编译失败，退出


解决方法：
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万商品）：


增加线程数
THREAD_NUM=8  # 或更多

分批处理


可以将session文件按用户分片
分别运行Swing算法
最后合并结果

调整max_session_list_len


修改 src/swing.cc 中的 max_session_list_len
限制每个用户的最大行为数


内存优化
如果遇到内存不足：


减少 max_sim_list_len（默认300）
减少 max_session_list_len（默认100）
分批处理数据

集成到定时任务
# 添加到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算法原理
离线任务配置
Debug工具使用

常见问题
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