Torrent — Expert-Aware Multi-Batch MoE Pipeline

Torrent 是一个独立的 Python 包，实现了面向 CPU-PCIe-GPU offloading 场景的 MoE 推理加速。 核心算法来源于论文 "Klotski: An Expert-Aware Multi-Batch Pipeline for MoE LLM Inference"（arXiv:2502.06888）， 集成目标模型为 Qwen3-30B-A3B + EAGLE-3 Speculative Decoding。

核心创新

专家感知多 batch 流水线（n-batch Pipeline）

将 n 个并发序列的专家 I/O 合并：每个专家权重从 CPU→GPU 只传输一次，服务 n 个序列中所有路由到该专家的 token。

期望唯一专家数（均匀独立路由，$E=128, k=8$）：

$$E_{unique}(n) = E \cdot \left(1 - \left(1 - \frac{k}{E}\right)^n\right)$$

per-token 专家 I/O 时间相对于 $n=1$ 的理论加速：

（参数：$t_{io}=0.387\text{ms/expert}$, $t_{attn}=0.024\text{ms/seq}$, $L=48$）

其他关键技术

• CorrelationTable：在线学习专家路由模式，预取下一层热专家
• AsyncLoader：双 CUDA stream（io_stream + compute_stream）重叠 I/O 与计算
• ExpertExecutor：热专家优先 + 就绪优先排序，最小化 intra-layer bubble
• HardwareProfiler + ConstraintSolver：自动测量 6 个硬件时延参数，求解最优 n

安装

快速安装

# 1. 先安装 speculators（vllm-project 生态）
pip install speculators

# 2. 安装 srep-moe
git clone https://github.com/yourorg/srep-moe
cd srep-moe
pip install -e .

依赖

快速开始

1. 端到端验证（无需真实模型权重）

python demo.py               # 纯 CPU 玩具模型验证
python demo.py --gpu         # GPU 验证
python demo.py --large       # 更大配置

2. 真实 Qwen3-30B 推理

# 硬件测量
python run_qwen3_moe.py --mode profile

# 理论性能表（不加载模型）
python run_qwen3_moe.py --mode theory

# Torrent 单序列推理
python run_qwen3_moe.py --mode torrent --n 4 --max_new_tokens 64

# N-batch 并发推理
python run_qwen3_moe.py --mode nbatch --n 8 --max_new_tokens 32

# N-batch sweep
python run_qwen3_moe.py --mode sweep --max_new_tokens 16

3. 玩具模型 benchmark

# 与 baseline 对比（玩具 MoE）
python benchmark/run_torrent.py --compare --n 4

# n 值扫描
python benchmark/run_torrent.py --sweep

# 单独跑 baseline
python benchmark/run_baseline.py --steps 20

项目结构

srep-moe/
├── pyproject.toml              # 包配置（pip install srep-moe）
├── src/torrent/                # 核心包
│   ├── __init__.py             # 统一导出
│   ├── nbatch_engine.py        # TorrentNBatchEngine（n-batch 并发推理）
│   ├── planner/
│   │   ├── hardware_profiler.py  # 测量 6 个硬件时延参数
│   │   └── constraint_solver.py  # 求解最优 n（论文 Algorithm 2）
│   ├── prefetch/
│   │   ├── correlation_table.py  # 路由模式在线学习
│   │   └── async_loader.py       # 双 CUDA stream 异步加载
│   ├── runtime/
│   │   ├── memory_manager.py     # 三级存储（GPU/CPU/Disk）
│   │   ├── expert_executor.py    # 热优先 + 就绪优先执行
│   │   └── pipeline.py           # TorrentPipeline / TorrentConfig
│   ├── metrics/
│   │   └── collector.py          # 吞吐/时延/bubble 指标
│   └── models/
│       └── __init__.py           # Qwen3MoE 集成（FP8 反量化 + patch）
├── models/
│   └── moe_model.py            # MoEModelWrapper（Mixtral offloading）
├── benchmark/
│   ├── run_baseline.py         # 串行整层预取 baseline
│   └── run_torrent.py          # Torrent multi-batch benchmark
├── demo.py                     # 端到端验证脚本
├── run_qwen3_moe.py            # Qwen3-30B 真实推理入口
└── experiments/
    └── qwen3_moe_eagle3/       # 实验记录与复现脚本

与 speculators 的关系

典型部署：先用 speculators 训练/导出 EAGLE-3 草稿头；再用 srep-moe 在 CPU-PCIe-GPU 环境运行联合推理。

论文复现验证

参考

• 论文：arXiv:2502.06888 "Klotski: An Expert-Aware Multi-Batch Pipeline..."
• speculators：github.com/vllm-project/speculators
• Qwen3-30B-A3B：huggingface.co/Qwen/Qwen3-30B-A3B-Instruct-2507-FP8