跳到内容

使用 GuideLLM 评估 Speculator 模型

使用 vLLM 和 GuideLLM 评估 speculator 模型，并提取接受长度指标。

快速入门

1. 安装依赖项 

bash setup.sh  # or: bash setup.sh --use-uv for faster installation

2. 使用预配置模型运行评估 

# Llama-3.1-8B EAGLE3 on math_reasoning dataset
./run_evaluation.sh -c configs/llama-3.1-8b-eagle3.env

# Llama-3.3-70B EAGLE3 on math_reasoning dataset
./run_evaluation.sh -c configs/llama-3.3-70b-eagle3.env

# GPT-OSS-20B EAGLE3 on math_reasoning dataset
./run_evaluation.sh -c configs/gpt-oss-20b-eagle3.env

# Qwen3-8B EAGLE3 on math_reasoning dataset
./run_evaluation.sh -c configs/qwen3-8b-eagle3.env

# Qwen3-32B EAGLE3 on math_reasoning dataset
./run_evaluation.sh -c configs/qwen3-32b-eagle3.env

或使用自定义参数运行 

./run_evaluation.sh \
  -m "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3" \
  -d "emulated"

结果将保存在一个带时间戳的目录中，例如 eval_results_20251203_165432/。

架构

此框架由模块化脚本组成，组织在一个清晰的目录结构中

eval-guidellm/
├── run_evaluation.sh              # Main controller
├── configs/                       # Pre-configured evaluations
│   ├── llama-3.1-8b-eagle3.env    # Llama-3.1-8B
│   ├── llama-3.3-70b-eagle3.env   # Llama-3.3-70B
│   ├── gpt-oss-20b-eagle3.env     # GPT-OSS-20B
│   ├── qwen3-8b-eagle3.env        # Qwen3-8B
│   └── qwen3-32b-eagle3.env       # Qwen3-32B
├── scripts/                       # Utility scripts
│   ├── vllm_serve.sh
│   ├── vllm_stop.sh
│   ├── run_guidellm.sh
│   └── parse_logs.py
└── setup.sh                       # Install dependencies

配置

预配置模型

该框架包含常见模型的配置

# Llama-3.1-8B EAGLE3 on math_reasoning
./run_evaluation.sh -c configs/llama-3.1-8b-eagle3.env

# Llama-3.3-70B EAGLE3 on math_reasoning
./run_evaluation.sh -c configs/llama-3.3-70b-eagle3.env

# GPT-OSS-20B EAGLE3 on math_reasoning
./run_evaluation.sh -c configs/gpt-oss-20b-eagle3.env

# Qwen3-8B EAGLE3 on math_reasoning
./run_evaluation.sh -c configs/qwen3-8b-eagle3.env

# Qwen3-32B EAGLE3 on math_reasoning
./run_evaluation.sh -c configs/qwen3-32b-eagle3.env

命令行用法

./run_evaluation.sh -m MODEL -d DATASET [OPTIONS]

Required:
  -m MODEL      Speculator model (e.g., "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3")
  -d DATASET    Dataset for benchmarking (see Dataset Options below)

Optional:
  -c FILE       Config file to use (e.g., configs/llama-eagle3.env)
  -o DIR        Output directory (default: eval_results_TIMESTAMP)

创建自定义配置

在 configs/ 中创建一个新的配置文件

# configs/my-model.env
MODEL="my-org/my-model"
DATASET="RedHatAI/speculator_benchmarks:math_reasoning.jsonl"
TENSOR_PARALLEL_SIZE=2
GPU_MEMORY_UTILIZATION=0.8
PORT=8000
HEALTH_CHECK_TIMEOUT=300

# Sampling parameters
TEMPERATURE=0.6
TOP_P=0.95
TOP_K=20

OUTPUT_DIR="eval_results_$(date +%Y%m%d_%H%M%S)"

然后运行

./run_evaluation.sh -c configs/my-model.env

配置选项

选项 描述 默认值
MODEL Speculator 模型路径或 HuggingFace ID (必需)
DATASET 用于基准测试的数据集（模拟、HF 数据集或文件路径） (必需)
TENSOR_PARALLEL_SIZE 用于张量并行的 GPU 数量 2
GPU_MEMORY_UTILIZATION 用于使用的 GPU 内存比例 0.8
PORT 服务器端口 8000
HEALTH_CHECK_TIMEOUT 服务器启动超时时间（秒） 300
TEMPERATURE 采样温度 0.6
TOP_P Top-p（nucleus）采样参数 0.95
TOP_K Top-k 采样参数 20
OUTPUT_DIR 输出目录 eval_results_TIMESTAMP

数据集选项

该框架支持五种类型的数据集输入

  1. 内置数据集：emulated（包含在 guidellm 中）

  2. 例如：DATASET="emulated"

  3. HuggingFace 数据集（所有文件）：org/dataset-name

  4. 使用 HuggingFace CLI 自动下载
  5. 对数据集中所有 .jsonl 文件运行基准测试

  6. 例如：DATASET="RedHatAI/speculator_benchmarks"

  7. HuggingFace 数据集（特定文件）：org/dataset-name:filename.jsonl

  8. 下载数据集并仅使用指定的文件
  9. 使用冒号（:）分隔数据集和文件名

  10. 例如：DATASET="RedHatAI/speculator_benchmarks:math_reasoning.jsonl"

  11. 本地目录：包含 .jsonl 文件的文件夹路径

  12. 对目录中所有 .jsonl 文件运行基准测试
  13. 结果将以特定于数据集的文件名保存

  14. 例如：DATASET="./my_datasets/"

  15. 本地文件：单个 .jsonl 文件的路径

  16. 对该特定文件运行基准测试
  17. 例如：DATASET="./my_data.jsonl"

高级用法

手动工作流程

用于调试或对同一服务器运行多个基准测试

# Terminal 1: Start server
./scripts/vllm_serve.sh \
  -m "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3" \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.8 \
  --log-file server.log \
  --pid-file server.pid

# Terminal 2: Run benchmarks
./scripts/run_guidellm.sh -d "dataset1.jsonl" --output-file results1.json
./scripts/run_guidellm.sh -d "dataset2.jsonl" --output-file results2.json

# Parse acceptance metrics
python scripts/parse_logs.py server.log -o acceptance_stats.txt

# Terminal 1: Stop server
./scripts/vllm_stop.sh --pid-file server.pid

输出文件

所有结果都保存在带时间戳的输出目录中。

单个数据集

eval_results_20251203_165432/
├── vllm_server.log          # vLLM server output (used for parsing)
├── guidellm_output.log      # GuideLLM benchmark progress
├── guidellm_results.json    # GuideLLM performance metrics
└── acceptance_analysis.txt  # Acceptance length statistics

多个数据集（目录或 HuggingFace）

使用目录或包含多个 .jsonl 文件的 HuggingFace 数据集时

eval_results_20251203_165432/
├── vllm_server.log                    # vLLM server output (all benchmarks)
├── guidellm_output_dataset1.log       # Benchmark progress for dataset1
├── guidellm_output_dataset2.log       # Benchmark progress for dataset2
├── guidellm_results_dataset1.json     # Performance metrics for dataset1
├── guidellm_results_dataset2.json     # Performance metrics for dataset2
└── acceptance_analysis.txt            # Combined acceptance statistics

接受率指标

acceptance_analysis.txt 包含：-加权接受率：按草稿标记加权的每位置接受率-条件接受率：在接受第 N-1 位的情况下接受第 N 位的概率

这些指标有助于评估投机解码的有效性。

示例

使用预配置模型

./run_evaluation.sh -c configs/llama-3.1-8b-eagle3.env
./run_evaluation.sh -c configs/llama-3.3-70b-eagle3.env
./run_evaluation.sh -c configs/gpt-oss-20b-eagle3.env
./run_evaluation.sh -c configs/qwen3-8b-eagle3.env
./run_evaluation.sh -c configs/qwen3-32b-eagle3.env

使用模拟数据集进行快速测试

./run_evaluation.sh \
  -m "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3" \
  -d "emulated"

HuggingFace 数据集（特定文件）

./run_evaluation.sh \
  -m "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3" \
  -d "RedHatAI/speculator_benchmarks:math_reasoning.jsonl"

HuggingFace 数据集（所有文件）

./run_evaluation.sh \
  -m "RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3" \
  -d "RedHatAI/speculator_benchmarks"

本地文件或目录

# Single file
./run_evaluation.sh -m MODEL -d "./my_data.jsonl"

# All .jsonl files in directory
./run_evaluation.sh -m MODEL -d "./my_datasets/"

故障排除

服务器未启动 

tail -n 50 eval_results_*/vllm_server.log  # Check logs
nvidia-smi                                  # Verify GPU availability

数据集未找到 

hf download DATASET --repo-type dataset  # Test HF dataset download
./run_evaluation.sh -m MODEL -d emulated # Use built-in dataset

服务器清理 

./scripts/vllm_stop.sh                   # Graceful shutdown
pkill -9 -f "vllm serve"                 # Force kill if needed

依赖项

必需：Python 3.9+，vLLM，GuideLLM，HuggingFace CLI，curl

bash setup.sh              # Install with pip
bash setup.sh --use-uv     # Install with uv (faster)