@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/mlops/evaluation/lm-evaluation-harness/references/distributed-eval.md

@@ -0,0 +1,519 @@
+# 分布式评估
+
+使用数据并行（data parallelism）和 tensor/pipeline parallelism 跨多个 GPU 运行评估的指南。
+
+## 概览
+
+分布式评估通过以下方式加速基准测试：
+- **Data Parallelism**：跨 GPU 划分评估样本（每个 GPU 都有完整的模型副本）
+- **Tensor Parallelism**：跨 GPU 划分模型权重（适用于大模型）
+- **Pipeline Parallelism**：跨 GPU 划分模型层（适用于超大模型）
+
+**何时使用**：
+- Data Parallel：模型可以装入单个 GPU，且希望加快评估速度
+- Tensor/Pipeline Parallel：模型太大，无法装入单个 GPU
+
+## HuggingFace Models (`hf`)
+
+### Data Parallelism（推荐）
+
+每个 GPU 加载完整的模型副本并处理一部分评估数据。
+
+**单节点（8 个 GPU）**：
+```bash
+accelerate launch --multi_gpu --num_processes 8 \
+  -m lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf,dtype=bfloat16 \
+  --tasks mmlu,gsm8k,hellaswag \
+  --batch_size 16
+```
+
+**加速比**：接近线性（8 个 GPU = 约 8 倍速度）
+
+**显存**：每个 GPU 都需要完整的模型（7B 模型 ≈ 14GB × 8 = 总共 112GB）
+
+### Tensor Parallelism（模型分片）
+
+将无法装入单个 GPU 的大模型的权重划分到多个 GPU 上。
+
+**不使用 accelerate 启动器**：
+```bash
+lm_eval --model hf \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    parallelize=True,\
+    dtype=bfloat16 \
+  --tasks mmlu,gsm8k \
+  --batch_size 8
+```
+
+**使用 8 个 GPU 时**：70B 模型 (140GB) / 8 = 每个 GPU 17.5GB ✅
+
+**高级分片**：
+```bash
+lm_eval --model hf \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    parallelize=True,\
+    device_map_option=auto,\
+    max_memory_per_gpu=40GB,\
+    max_cpu_memory=100GB,\
+    dtype=bfloat16 \
+  --tasks mmlu
+```
+
+**选项**：
+- `device_map_option`: `"auto"`（默认）、`"balanced"`、`"balanced_low_0"`
+- `max_memory_per_gpu`: 每个 GPU 的最大显存（例如：`"40GB"`）
+- `max_cpu_memory`: 用于 offloading 的最大 CPU 内存
+- `offload_folder`: 磁盘 offloading 目录
+
+### 结合 Data 与 Tensor Parallelism
+
+将两者结合用于超大型模型。
+
+**示例：在 16 个 GPU 上运行 70B 模型（2 个副本，每个 8 个 GPU）**：
+```bash
+accelerate launch --multi_gpu --num_processes 2 \
+  -m lm_eval --model hf \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    parallelize=True,\
+    dtype=bfloat16 \
+  --tasks mmlu \
+  --batch_size 8
+```
+
+**结果**：通过 data parallelism 实现 2 倍加速，并通过 tensor parallelism 成功运行 70B 模型
+
+### 使用 `accelerate config` 进行配置
+
+创建 `~/.cache/huggingface/accelerate/default_config.yaml`：
+```yaml
+compute_environment: LOCAL_MACHINE
+distributed_type: MULTI_GPU
+num_machines: 1
+num_processes: 8
+gpu_ids: all
+mixed_precision: bf16
+```
+
+**然后运行**：
+```bash
+accelerate launch -m lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu
+```
+
+## vLLM Models (`vllm`)
+
+vLLM 提供了高度优化的分布式推理。
+
+### Tensor Parallelism
+
+**单节点（4 个 GPU）**：
+```bash
+lm_eval --model vllm \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    tensor_parallel_size=4,\
+    dtype=auto,\
+    gpu_memory_utilization=0.9 \
+  --tasks mmlu,gsm8k \
+  --batch_size auto
+```
+
+**显存**：70B 模型拆分到 4 个 GPU 上 = 每个 GPU 约 35GB
+
+### Data Parallelism
+
+**多个模型副本**：
+```bash
+lm_eval --model vllm \
+  --model_args \
+    pretrained=meta-llama/Llama-2-7b-hf,\
+    data_parallel_size=4,\
+    dtype=auto,\
+    gpu_memory_utilization=0.8 \
+  --tasks hellaswag,arc_challenge \
+  --batch_size auto
+```
+
+**结果**：4 个模型副本 = 4 倍吞吐量
+
+### 结合 Tensor 与 Data Parallelism
+
+**示例：8 个 GPU = 4 TP × 2 DP**：
+```bash
+lm_eval --model vllm \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    tensor_parallel_size=4,\
+    data_parallel_size=2,\
+    dtype=auto,\
+    gpu_memory_utilization=0.85 \
+  --tasks mmlu \
+  --batch_size auto
+```
+
+**结果**：成功运行 70B 模型 (TP=4)，获得 2 倍加速 (DP=2)
+
+### 多节点 vLLM
+
+vLLM 原生不支持多节点。请使用 Ray：
+
+```bash
+# 启动 Ray 集群
+ray start --head --port=6379
+
+# 运行评估
+lm_eval --model vllm \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    tensor_parallel_size=8,\
+    dtype=auto \
+  --tasks mmlu
+```
+
+## NVIDIA NeMo Models (`nemo_lm`)
+
+### Data Replication
+
+**8 个 GPU 上运行 8 个副本**：
+```bash
+torchrun --nproc-per-node=8 --no-python \
+  lm_eval --model nemo_lm \
+  --model_args \
+    path=/path/to/model.nemo,\
+    devices=8 \
+  --tasks hellaswag,arc_challenge \
+  --batch_size 32
+```
+
+**加速比**：接近线性（8 倍速度）
+
+### Tensor Parallelism
+
+**4 路 tensor parallelism**：
+```bash
+torchrun --nproc-per-node=4 --no-python \
+  lm_eval --model nemo_lm \
+  --model_args \
+    path=/path/to/70b_model.nemo,\
+    devices=4,\
+    tensor_model_parallel_size=4 \
+  --tasks mmlu,gsm8k \
+  --batch_size 16
+```
+
+### Pipeline Parallelism
+
+**在 4 个 GPU 上进行 2 TP × 2 PP**：
+```bash
+torchrun --nproc-per-node=4 --no-python \
+  lm_eval --model nemo_lm \
+  --model_args \
+    path=/path/to/model.nemo,\
+    devices=4,\
+    tensor_model_parallel_size=2,\
+    pipeline_model_parallel_size=2 \
+  --tasks mmlu \
+  --batch_size 8
+```
+
+**限制条件**：`devices = TP × PP`
+
+### 多节点 NeMo
+
+目前 lm-evaluation-harness 尚不支持。
+
+## SGLang Models (`sglang`)
+
+### Tensor Parallelism
+
+```bash
+lm_eval --model sglang \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    tp_size=4,\
+    dtype=auto \
+  --tasks gsm8k \
+  --batch_size auto
+```
+
+### Data Parallelism（已弃用）
+
+**注意**：SGLang 正在弃用 data parallelism。请改用 tensor parallelism。
+
+```bash
+lm_eval --model sglang \
+  --model_args \
+    pretrained=meta-llama/Llama-2-7b-hf,\
+    dp_size=4,\
+    dtype=auto \
+  --tasks mmlu
+```
+
+## 性能比较
+
+### 70B 模型评估（MMLU，5-shot）
+
+| 方法 | GPUs | 时间 | 显存/GPU | 备注 |
+|--------|------|------|------------|-------|
+| HF (无并行) | 1 | 8 小时 | 140GB (OOM) | 无法装入 |
+| HF (TP=8) | 8 | 2 小时 | 17.5GB | 较慢，可装入 |
+| HF (DP=8) | 8 | 1 小时 | 140GB (OOM) | 无法装入 |
+| vLLM (TP=4) | 4 | 30 分钟 | 35GB | 很快！ |
+| vLLM (TP=4, DP=2) | 8 | 15 分钟 | 35GB | 最快 |
+
+### 7B 模型评估（多任务）
+
+| 方法 | GPUs | 时间 | 加速比 |
+|--------|------|------|---------|
+| HF (单 GPU) | 1 | 4 小时 | 1× |
+| HF (DP=4) | 4 | 1 小时 | 4× |
+| HF (DP=8) | 8 | 30 分钟 | 8× |
+| vLLM (DP=8) | 8 | 15 分钟 | 16× |
+
+**结论**：在推理方面，vLLM 明显快于 HuggingFace。
+
+## 选择并行策略
+
+### 决策树
+
+```
+模型可以装入单个 GPU？
+├─ 是：使用 data parallelism
+│   ├─ HF: accelerate launch --multi_gpu --num_processes N
+│   └─ vLLM: data_parallel_size=N (最快)
+│
+└─ 否：使用 tensor/pipeline parallelism
+    ├─ 模型 < 70B:
+    │   └─ vLLM: tensor_parallel_size=4
+    ├─ 模型 70-175B:
+    │   ├─ vLLM: tensor_parallel_size=8
+    │   └─ 或 HF: parallelize=True
+    └─ 模型 > 175B:
+        └─ 联系框架作者
+```
+
+### 显存估算
+
+**经验法则**：
+```
+显存 (GB) = 参数量 (B) × 精度 (bytes) × 1.2 (开销)
+```
+
+**示例**：
+- 7B FP16: 7 × 2 × 1.2 = 16.8GB ✅ 可装入 A100 40GB
+- 13B FP16: 13 × 2 × 1.2 = 31.2GB ✅ 可装入 A100 40GB
+- 70B FP16: 70 × 2 × 1.2 = 168GB ❌ 需要 TP=4 或 TP=8
+- 70B BF16: 70 × 2 × 1.2 = 168GB (与 FP16 相同)
+
+**使用 tensor parallelism 时**：
+```
+每个 GPU 的显存 = 总显存 / TP
+```
+
+- 4 个 GPU 上运行 70B：168GB / 4 = 每个 GPU 42GB ✅
+- 8 个 GPU 上运行 70B：168GB / 8 = 每个 GPU 21GB ✅
+
+## 多节点评估
+
+### 结合 SLURM 使用 HuggingFace
+
+**提交作业**：
+```bash
+#!/bin/bash
+#SBATCH --nodes=4
+#SBATCH --gpus-per-node=8
+#SBATCH --ntasks-per-node=1
+
+srun accelerate launch --multi_gpu \
+  --num_processes $((SLURM_NNODES * 8)) \
+  -m lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu,gsm8k,hellaswag \
+  --batch_size 16
+```
+
+**提交**：
+```bash
+sbatch eval_job.sh
+```
+
+### 手动多节点配置
+
+**在每个节点上运行**：
+```bash
+accelerate launch \
+  --multi_gpu \
+  --num_machines 4 \
+  --num_processes 32 \
+  --main_process_ip $MASTER_IP \
+  --main_process_port 29500 \
+  --machine_rank $NODE_RANK \
+  -m lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu
+```
+
+**环境变量**：
+- `MASTER_IP`: rank 0 节点的 IP
+- `NODE_RANK`: 每个节点对应的 0, 1, 2, 3
+
+## 最佳实践
+
+### 1. 从小规模开始
+
+先在小样本上进行测试：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-70b-hf,parallelize=True \
+  --tasks mmlu \
+  --limit 100  # 仅测试 100 个样本
+```
+
+### 2. 监控 GPU 用法
+
+```bash
+# 终端 1：运行评估
+lm_eval --model hf ...
+
+# 终端 2：监控
+watch -n 1 nvidia-smi
+```
+
+需要注意：
+- GPU 利用率 > 90%
+- 显存使用量稳定
+- 所有 GPU 均处于活跃状态
+
+### 3. 优化 Batch Size
+
+```bash
+# 自动 batch size（推荐）
+--batch_size auto
+
+# 或手动调优
+--batch_size 16  # 从这里开始
+--batch_size 32  # 如果显存允许则增加
+```
+
+### 4. 使用混合精度
+
+```bash
+--model_args dtype=bfloat16  # 速度更快，显存占用更少
+```
+
+### 5. 检查通信
+
+对于 data parallelism，请检查网络带宽：
+```bash
+# 应该能看到 InfiniBand 或高速网络
+nvidia-smi topo -m
+```
+
+## 故障排查
+
+### "CUDA out of memory"
+
+**解决方案**：
+1. 增加 tensor parallelism：
+   ```bash
+   --model_args tensor_parallel_size=8  # 原先是 4
+   ```
+
+2. 减小 batch size：
+   ```bash
+   --batch_size 4  # 原先是 16
+   ```
+
+3. 降低精度：
+   ```bash
+   --model_args dtype=int8  # 量化
+   ```
+
+### "NCCL error" 或挂起
+
+**检查**：
+1. 所有 GPU 是否可见：`nvidia-smi`
+2. 是否安装了 NCCL：`python -c "import torch; print(torch.cuda.nccl.version())"`
+3. 节点间的网络连接是否正常
+
+**修复**：
+```bash
+export NCCL_DEBUG=INFO  # 启用调试日志
+export NCCL_IB_DISABLE=0  # 如果可用，使用 InfiniBand
+```
+
+### 评估速度缓慢
+
+**可能的原因**：
+1. **数据加载瓶颈**：对数据集进行预处理
+2. **GPU 利用率低**：增加 batch size
+3. **通信开销**：降低并行度
+
+**性能分析**：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu \
+  --limit 100 \
+  --log_samples  # 检查耗时
+```
+
+### GPU 负载不平衡
+
+**症状**：GPU 0 的利用率达到 100%，而其他 GPU 为 50%
+
+**解决方案**：使用 `device_map_option=balanced`：
+```bash
+--model_args parallelize=True,device_map_option=balanced
+```
+
+## 示例 Configurations
+
+### 小型模型 (7B) - 快速评估
+
+```bash
+# 8 张 A100，data parallel
+accelerate launch --multi_gpu --num_processes 8 \
+  -m lm_eval --model hf \
+  --model_args \
+    pretrained=meta-llama/Llama-2-7b-hf,\
+    dtype=bfloat16 \
+  --tasks mmlu,gsm8k,hellaswag,arc_challenge \
+  --num_fewshot 5 \
+  --batch_size 32
+
+# 时间：约 30 分钟
+```
+
+### 大型模型 (70B) - vLLM
+
+```bash
+# 8 张 H100，tensor parallel
+lm_eval --model vllm \
+  --model_args \
+    pretrained=meta-llama/Llama-2-70b-hf,\
+    tensor_parallel_size=8,\
+    dtype=auto,\
+    gpu_memory_utilization=0.9 \
+  --tasks mmlu,gsm8k,humaneval \
+  --num_fewshot 5 \
+  --batch_size auto
+
+# 时间：约 1 小时
+```
+
+### 超大型模型 (175B+)
+
+**需要专门的设置 - 请联系框架维护者**
+
+## 参考资料
+
+- HuggingFace Accelerate: https://huggingface.co/docs/accelerate/
+- vLLM 文档: https://docs.vllm.ai/
+- NeMo 文档: https://docs.nvidia.com/nemo-framework/
+- lm-eval 分布式指南: `docs/model_guide.md`