面向真实世界大模型推理优化的SLO感知基准测试与评估平台

概述

GuideLLM 是一个用于评估语言模型在实际工作负载和配置下表现的平台。它能够模拟与 OpenAI 兼容及 vLLM 原生服务器的端到端交互，生成反映生产环境使用情况的工作负载模式，并输出详细的报告，帮助团队理解系统行为、资源需求以及运行上限。GuideLLM 支持真实和合成数据集、多模态输入以及灵活的执行配置文件，为工程和机器学习团队提供了一套一致的框架，以评估模型行为、优化部署并规划容量，从而适应系统的持续演进。

为什么选择 GuideLLM？

GuideLLM 能够在类生产环境中清晰地展示 LLM 部署时的性能、效率和可靠性。

• 捕捉完整的延迟和 token 级别的统计信息，用于 SLO 驱动的评估，包括 TTFT、ITL 和端到端行为的完整分布。
• 生成逼真且可配置的流量模式，涵盖同步、并发和基于速率的模式，支持可重复的扫描测试以识别安全的运行范围。
• 同时支持真实和合成的多模态数据集，在一个框架内实现受控实验和生产风格的评估。
• 生成标准化且可导出的报告，用于仪表盘、分析和回归跟踪，确保跨团队和工作流的一致性。
• 提供高吞吐量、可扩展的基准测试能力，支持多进程、多线程、异步执行，并配备灵活的 CLI/API，便于定制或快速上手。

比较

许多工具仅对端点进行基准测试，而非模型本身，因此会忽略对大语言模型至关重要的细节。GuideLLM 专注于 LLM 特有的工作负载，能够测量 TTFT、ITL、输出分布以及由数据集驱动的差异性。它采用标准的 Python 接口和 HuggingFace 数据集，而非自定义格式或仅用于研究的流水线，因而能无缝融入日常工程任务。此外，GuideLLM 在性能方面也经过精心设计，支持高频率的负载生成和精确的调度，远超简单的脚本或示例基准测试。下表突显了这种方法与其他选项相比的优势。

工具	CLI	API	高性能	全面指标	数据模态	数据来源	配置文件	后端	端点	输出类型
GuideLLM	✅	✅	✅	✅	文本、图像、音频、视频	HuggingFace、文件、合成数据、自定义数据	同步、并发、吞吐量、恒定、泊松、扫描	OpenAI 兼容	/completions, /chat/completions, /audio/translation, /audio/transcription	控制台、JSON、CSV、HTML
inference-perf	✅	❌	✅	❌	文本	合成数据、特定数据集	并发、恒定、泊松、扫描	OpenAI 兼容	/completions, /chat/completions	JSON、PNG
genai-bench	✅	❌	❌	❌	文本、图像、嵌入、重排序	合成数据、文件	并发	OpenAI 兼容、托管云服务	/chat/completions, /embeddings	控制台、XLSX、PNG
llm-perf	❌	❌	✅	❌	文本	合成数据	并发	OpenAI 兼容、托管云服务	/chat/completions	JSON
ollama-benchmark	✅	❌	❌	❌	文本	合成数据	同步	Ollama	/completions	控制台、JSON
vllm/benchmarks	✅	❌	❌	❌	文本	合成数据、特定数据集	同步、吞吐量、恒定、扫描	OpenAI 兼容、vLLM API	/completions, /chat-completions	控制台、PNG

最新功能

本节总结了用户可用的最新功能，并概述了当前的开发方向。这有助于读者了解平台的发展历程以及未来的预期。

近期新增功能

• 重构的新架构支持大规模高频率负载生成，并提供了更具扩展性的接口，以适应更多后端、数据管道、负载生成计划、基准测试约束及输出格式。
• 新增多模态基准测试支持，涵盖聊天补全、转录和翻译 API 中的图像、视频和音频工作负载。
• 扩展了指标收集范围，包括针对视觉、音频和文本输入的更丰富统计信息，例如图像尺寸、音频时长、视频帧数以及词级数据。

正在进行的开发

• 生成用于图像、音频和视频领域受控实验的多模态合成数据集。
• 扩展前缀选项，以测试系统提示和用户提示的变化。
• 实现多轮对话能力，用于对聊天代理和对话系统进行基准测试。
• 提供推测解码相关的特定视图和输出。

快速入门

快速入门将展示如何在几分钟内安装 GuideLLM、启动服务器并运行首次基准测试。

安装 GuideLLM

在安装之前，请确保满足以下先决条件：

• 操作系统：Linux 或 macOS
• Python：3.10 - 3.13

使用 pip 从 PyPI 安装最新版 GuideLLM：

pip install guidellm[recommended]

或者从源代码安装：

pip install git+https://github.com/vllm-project/guidellm.git

也可以直接运行来自 ghcr.io/vllm-project/guidellm 的最新容器：

podman run \
  --rm -it \
  -v "./results:/results:rw" \
  -e GUIDELLM_TARGET=http://localhost:8000 \
  -e GUIDELLM_PROFILE=sweep \
  -e GUIDELLM_MAX_SECONDS=30 \
  -e GUIDELLM_DATA="prompt_tokens=256,output_tokens=128" \
  ghcr.io/vllm-project/guidellm:latest

启动推理服务器

启动任意一个 OpenAI 兼容的端点。以 vLLM 为例：

vllm serve "neuralmagic/Meta-Llama-3.1-8B-Instruct-quantized.w4a16"

请确认服务器已在 http://localhost:8000 正常运行。

运行首次基准测试

运行一次扫描测试，以确定模型的最大性能和最高速率：

guidellm benchmark \
  --target "http://localhost:8000" \
  --profile sweep \
  --max-seconds 30 \
  --data "prompt_tokens=256,output_tokens=128"

运行过程中，您将看到进度更新和每次基准测试的摘要，如下所示：

检查输出结果

基准测试完成后，GuideLLM 会将所有结果保存到您指定的输出目录中（默认为当前目录）。控制台会打印汇总信息，并附带一组文件路径（.json、.csv、.html），其中包含了完整的运行结果。

下一节——“输出文件与报告”——将详细说明每个文件的内容以及如何利用它们进行分析、可视化或自动化操作。

输出文件与报告

运行快速入门基准测试后，GuideLLM 会将多个输出文件写入您指定的目录中。每个文件侧重于不同层次的分析，从屏幕上的快速摘要，到可用于仪表板和回归管道的完全结构化数据。

控制台输出

控制台提供了一个轻量级的摘要，包含本次运行中每个基准测试的高级统计信息。它非常适合用于快速检查，以确认服务器响应正确、负载扫描已完成，并且系统行为符合预期。此外，输出表格可以使用 | 作为分隔符复制并粘贴到电子表格软件中。各部分的格式大致如下所示：

benchmarks.json

此文件是整个基准测试会话的权威记录。它包含配置、元数据、每个基准测试的统计信息，以及带有单个请求计时的示例请求条目。您可以将其用于调试、深入分析，或使用 GenerativeBenchmarksReport 加载到 Python 中。

另外，您也可以通过使用 --outputs yaml 参数生成一个内容与 benchmarks.json 相同、但更易于人类阅读的 YAML 版本。

benchmarks.csv

此文件以紧凑的表格形式展示了每个基准测试的数据，字段包括最常用于报告的吞吐量、延迟百分位数、标记数量和速率信息。它可以在电子表格和 BI 工具中直接打开，非常适合用于跨次运行的比较。

benchmarks.html

HTML 报告提供了结果的可视化摘要，包括延迟分布图、吞吐量行为和生成模式等图表。它非常适合快速浏览，或与团队成员共享，而无需他们解析 JSON 文件。

常见用例与配置

GuideLLM 支持广泛的 LLM 基准测试工作流。以下示例展示了如何运行典型场景，并重点介绍了最重要的参数。如需完整的参数列表、详细信息和选项，请运行 guidellm benchmark run --help。

负载模式

模拟不同的应用需要不同的流量形状。此示例演示了基于速率的负载测试，采用每秒 10 个请求的恒定速率配置，持续 20 秒，使用包含 128 个提示标记和 256 个输出标记的合成数据。

guidellm benchmark \
  --target http://localhost:8000 \
  --profile constant \
  --rate 10 \
  --max-seconds 20 \
  --data "prompt_tokens=128,output_tokens=256"

关键参数：

• --profile：定义流量模式——可选值包括 synchronous（顺序请求）、concurrent（并行用户）、throughput（最大容量）、constant（固定请求/秒）、poisson（随机请求/秒）或 sweep（自动速率探索）。
• --rate：数值速率，其含义取决于所选的流量模式——对于 sweep 是基准测试的数量，对于 concurrent 是同时发起的请求数量，而对于 constant 或 poisson 则是每秒的请求数。
• --max-seconds：每个基准测试运行的最大持续时间（单位为秒）。您也可以使用 --max-requests 来按请求数限制运行。

数据集来源

GuideLLM 支持 HuggingFace 数据集、本地文件以及合成数据。此示例从 HuggingFace 加载 CNN DailyMail 数据集，并将文章列映射为提示，同时使用摘要标记数量列来确定输出长度。

guidellm benchmark run \
  --target http://localhost:8000 \
  --data "abisee/cnn_dailymail" \
  --data-args '{"name": "3.0.0"}' \
  --data-column-mapper '{"text_column":"article"}'

关键参数：

• --data：数据源规范——接受 HuggingFace 数据集 ID（需加前缀 hf:）、本地文件路径（.json、.csv、.jsonl、.txt），或合成数据配置（JSON 对象或 key=value 键值对，例如 prompt_tokens=256,output_tokens=128）。
• --data-args：加载数据集时使用的参数。有关有效选项，请参阅 datasets.load_dataset。
• --data-column-mapper：用于数据集创建的参数 JSON 对象——通常用于指定列映射，例如 text_column、output_tokens_count_column，或 HuggingFace 数据集的相关参数。
• --data-samples：从数据集中使用的样本数量——使用 -1（默认值）表示动态生成所有样本，或指定一个正整数以限制样本数量。
• --processor：用于生成合成数据的分词器或处理器名称——如果未提供且数据集需要，则会自动从模型中加载；接受 HuggingFace 模型 ID 或本地路径。

请求类型与 API 目标

您可以对聊天补全、文本补全或其他支持的请求类型进行基准测试。此示例配置基准测试以使用自定义数据集文件测试聊天补全 API，GuideLLM 会自动将请求格式化为匹配聊天补全的架构。

guidellm benchmark \
  --target http://localhost:8000 \
  --request-type chat_completions \
  --data path/to/data.json

关键参数：

• --request-type：指定 API 端点的格式——可选值包括 chat_completions（聊天 API 格式）、 completions（文本补全格式）、audio_transcription（音频转录）和 audio_translation（音频翻译）。

使用场景

内置场景将调度、数据集设置和请求格式化打包在一起，以标准化常见的测试模式。此示例使用预配置的聊天场景，其中包含了适用于聊天模型评估的适当默认值，任何额外的 CLI 参数都会覆盖场景的设置。

guidellm benchmark --scenario chat --target http://localhost:8000

关键参数：

• --scenario：内置场景名称或自定义场景配置文件的路径——内置选项包括针对常见用例预配置的测试模式；与此参数一起传递的 CLI 选项将覆盖场景的默认设置。

基准控制

预热、冷却和最大限制有助于确保测量的稳定性和可重复性。此示例运行一个并发基准测试，包含16个并行请求，使用10%的预热和冷却期以排除初始化和关闭的影响，同时限制测试在出现超过5次错误时停止。

guidellm benchmark \
  --target http://localhost:8000 \
  --profile concurrent \
  --rate 16 \
  --warmup 0.1 \
  --cooldown 0.1 \
  --max-errors 5 \
  --data "prompt_tokens=256,output_tokens=128" \
  --detect-saturation

关键参数：

• --warmup：预热设置——值介于0到1之间表示总请求数或总时间的百分比，值≥1则表示绝对的请求数或时间单位。
• --cooldown：冷却设置——格式与预热相同，用于将基准测试的最后一部分排除在分析之外，以避免关闭效应。
• --max-seconds：每个基准测试的最大持续时间（秒），超过该时间将自动终止。
• --max-requests：每个基准测试的最大请求数，超过该数量将自动终止。
• --max-errors：在基准测试完全停止之前允许出现的最大错误次数。
• --data：用于基准测试的数据——合成数据，输入256个标记，输出128个标记。
• --detect-saturation：启用过饱和检测功能，当模型发生过饱和时自动停止基准测试（有关更高级的控制，请参阅--over-saturation）。

开发与贡献

对扩展GuideLLM感兴趣的开发者可以使用该项目已建立的开发流程。本地设置、环境激活及测试说明均在DEVELOPING.md中列出。本指南解释了如何运行基准测试套件、验证更改，以及在开发过程中使用CLI或API的方法。贡献标准记录在CONTRIBUTING.md中，包括编码规范、提交结构和评审指南。这些标准有助于在平台演进过程中保持稳定性。CODE_OF_CONDUCT.md概述了在所有项目空间中进行尊重和建设性参与的期望。对于希望获取更深入参考资料的贡献者，文档涵盖了安装、后端、数据集、指标、输出类型和架构等内容。在添加新的后端、请求类型或数据集成时，查阅这些主题会很有帮助。发布说明和变更日志链接自GitHub Releases页面，为当前工作提供了历史背景。

文档

完整文档提供了本README中未涵盖的详细信息。其中包括安装步骤、后端配置、数据集处理、指标定义、输出格式、教程以及架构概览。这些参考资料有助于您更深入地探索该平台或将之集成到现有工作流中。

以下是一些值得关注的文档：

• 安装指南——本指南提供了安装GuideLLM的分步说明，包括先决条件和设置技巧。
• 后端指南——全面概述了支持的后端及其在GuideLLM中的设置方法。
• 数据/数据集指南——关于支持的数据集的信息，包括如何将其用于基准测试。
• 指标指南——对GuideLLM中使用的指标的详细解释，包括定义及如何解读。
• 输出指南——关于GuideLLM支持的不同输出格式及其使用方法的信息。
• 架构概览——详细介绍GuideLLM的设计、组件及其相互作用。

许可证

GuideLLM采用Apache许可证2.0版授权。

引用

如果您在研究或项目中发现GuideLLM有所帮助，请考虑引用它：

@misc{guidellm2024,
  title={GuideLLM：大型语言模型的可扩展推理与优化},
  author={Neural Magic, Inc.},
  year={2024},
  howpublished={\url{https://github.com/vllm-project/guidellm}},
}

GuideLLM 快速上手指南

GuideLLM 是一个面向生产环境的 LLM 推理基准测试与评估平台，专注于 SLO（服务等级目标）驱动的性能分析。它能模拟真实负载模式，生成详细的延迟分布（TTFT、ITL）和吞吐量报告，帮助团队优化模型部署。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS
• Python 版本：3.10 - 3.13
• 推理后端：需要运行一个 OpenAI 兼容的推理服务（例如 vLLM、TGI 等）。

安装步骤

您可以选择通过 PyPI 安装推荐版本，或直接从源码安装。

方式一：通过 PyPI 安装（推荐）

pip install guidellm[recommended]

提示：国内用户若下载缓慢，可添加清华或阿里镜像源： pip install guidellm[recommended] -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

pip install git+https://github.com/vllm-project/guidellm.git

方式三：使用容器运行

如果您偏好使用容器，可以直接运行最新的 Docker/Podman 镜像：

podman run \
  --rm -it \
  -v "./results:/results:rw" \
  -e GUIDELLM_TARGET=http://localhost:8000 \
  -e GUIDELLM_PROFILE=sweep \
  -e GUIDELLM_MAX_SECONDS=30 \
  -e GUIDELLM_DATA="prompt_tokens=256,output_tokens=128" \
  ghcr.io/vllm-project/guidellm:latest

基本使用

以下是启动服务并运行第一个基准测试的最小化流程。

1. 启动推理服务器

首先启动一个 OpenAI 兼容的推理服务。以下以 vLLM 为例：

vllm serve "neuralmagic/Meta-Llama-3.1-8B-Instruct-quantized.w4a16"

确保服务正常运行在 http://localhost:8000。

2. 运行基准测试

使用 guidellm benchmark 命令执行压力测试。以下示例将执行一次 Sweep（扫描） 模式的测试，自动探测模型的最大性能边界：

guidellm benchmark \
  --target "http://localhost:8000" \
  --profile sweep \
  --max-seconds 30 \
  --data "prompt_tokens=256,output_tokens=128"

参数说明：

• --target: 推理服务的地址。
• --profile sweep: 执行负载扫描，寻找最佳吞吐量和最大并发率。
• --max-seconds: 每个测试场景的最大持续时间。
• --data: 定义合成数据的输入/输出 Token 数量。

3. 查看结果

测试完成后，GuideLLM 会在当前目录生成以下文件：

• 控制台输出：实时显示进度和关键指标摘要。
• benchmarks.json：包含完整的配置、元数据和详细请求日志，适合程序化分析。
• benchmarks.csv：表格格式，包含吞吐量、延迟百分位数等核心指标，适合导入 Excel 分析。
• benchmarks.html：可视化报告，包含延迟分布图和吞吐量趋势图。