guidellm

GuideLLM 是一个面向真实世界 LLM 推理需求的 SLO 感知基准测试与评估平台，由 vLLM 项目维护（仓库地址：https://github.com/neuralmagic/guidellm）。它的目标是在接近生产环境的条件下，评估语言模型在不同工作负载和配置下的表现，帮助团队理解系统行为、资源需求与运行极限。

用途

GuideLLM 用于评估 LLM 部署在实际负载下的性能、效率与可靠性。它模拟与 OpenAI 兼容服务器和 vLLM 原生服务器的端到端交互，生成反映生产用量的工作负载模式，并产出详细报告，供工程与机器学习团队进行模型行为评估、部署调优和容量规划。

主要能力

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

使用方式

安装

前置条件：操作系统为 Linux 或 MacOS，Python 版本为 3.10 至 3.13。 可通过 pip 从 PyPI 安装最新版 GuideLLM，也可从源码安装，或运行来自 ghcr.io/vllm-project/guidellm 的最新容器镜像。已发布的镜像为多架构（linux/amd64 和 linux/arm64），适用于 Docker、Podman、Kubernetes 和 OpenShift；生产环境建议固定发布标签，不要使用 vX.Y.Z-amd64 / vX.Y.Z-arm64 这类架构特定标签作为镜像引用。

启动推理服务器

启动任意 OpenAI 兼容端点，例如 vLLM，并确认服务器运行在 http://localhost:8000。

运行首个基准测试

运行 sweep 以识别模型的最大性能和最大速率，过程中会显示进度更新和每个基准测试的摘要。

查看输出

基准测试完成后，GuideLLM 默认写入 benchmarks.json 和 benchmarks.csv，文件保存在由 GUIDELLM__DEFAULT_RESULTS_DIR 配置的目录中，未设置该变量时保存在当前目录，同时在控制台打印摘要和生成文件位置。使用 --output 可替换默认的 JSON 和 CSV 输出，并支持生成 HTML 等格式。

输出文件与报告

JSON 或 YAML 用于详细分析，CSV 用于电子表格对比，HTML 用于自包含的可视化报告，PLOT 用于静态性能图表。控制台提供每个基准测试的摘要，其表格可使用 | 作为分隔符复制到电子表格软件中。

常见用例与配置

• 流量模式：--profile kind=<type> 定义流量模式，可选 synchronous、concurrent、throughput、constant、poisson 或 sweep；constant/poisson 使用 rate 设置每秒请求数，concurrent 使用 streams，throughput 使用 max_concurrency。
• 约束：--constraint kind=max_duration,seconds=<seconds> 或 --constraint kind=max_requests,count=<count> 按时间或请求数限制每个策略；--constraint kind=max_errors,count=<count> 在错误总数超过阈值时停止；--constraint kind=over_saturation 启用过饱和检测。
• 数据集来源：支持 HuggingFace 数据集、本地文件和合成数据，如 synthetic_text、huggingface、json_file、csv_file、text_file、trace_synthetic 等，可重复指定多个来源；--data-column-mapper 用于字段映射；--data-loader type=pytorch,samples=1000 限制加载行数（-1 表示全部）；--tokenizer huggingface_auto "model=gpt2" 用于合成数据或本地 token 计数。
• 合成视觉数据：synthetic_image 和 synthetic_video 两种 --data 类型可与 synthetic_text 组合，用于基准测试视觉语言模型（VLM）服务配置。
• 请求类型与 API 目标：--backend 配置后端类型与连接设置，包括目标 OpenAI 兼容端点 URL 和 request_format（如 /v1/chat/completions、/v1/completions、/v1/embeddings、/v1/audio/transcriptions 等）。
• 场景：--config（别名 --scenario，-c）使用内置场景名称或自定义场景文件路径；CLI 选项会覆盖场景默认值。
• 基准控制：profile 配置支持 warmup 和 cooldown（百分比或绝对单位），用于排除初始化与关闭影响，保证测量的稳定性和可重复性。

适用场景

GuideLLM 适用于需要评估 LLM 在生产式环境下性能、效率与可靠性的团队，包括：对 OpenAI 兼容或 vLLM 原生服务进行基准测试；通过可复现的 sweep 确定安全运行区间；使用真实或合成数据（含多模态输入）进行受控实验；生成标准化报告用于仪表盘、分析和回归跟踪；以及为容量规划提供依据。

限制

资料中未提供具体性能数据、定价或商业收费信息。部分具体配置细节、参数完整列表可通过 guidellm run --help 以及官方文档查阅。开发与贡献相关工作流可参考 DEVELOPING.md、CONTRIBUTING.md 和 CODE_OF_CONDUCT.md，完整文档涵盖安装、后端配置、数据集处理、指标定义、输出格式、教程和架构概览。项目使用 Apache License 2.0 许可。