参数说明

执行 evalscope perf --help 可获取全部参数说明。

基本设置

参数	类型	说明	默认值
--model	str	测试模型名称，或模型路径	-
--url	str	API地址，支持/chat/completions、/completions和/responses端点	-
--name	str	wandb/swanlab数据库结果名称和结果数据库名称	{model_name}_{current_time}
--api	str	服务API类型 • openai: OpenAI兼容Chat Completions API（需提供--url） • openai_responses: OpenAI官方Responses API • openai_embedding: OpenAI兼容Embedding API • openai_rerank: OpenAI/Cohere兼容Rerank API • local: 启动本地transformers推理 • local_vllm: 启动本地vLLM推理服务 • 自定义：参考自定义API指南	-
--port	int	本地推理服务端口 仅对local和local_vllm有效	8877
--attn-implementation	str	Attention实现方式 仅在api=local时有效	None （可选：flash_attention_2、eager、sdpa）
--api-key	str	API密钥	None
--debug	bool	是否输出调试信息	False

网络配置

参数	类型	说明	默认值
--total-timeout	int	每个请求的总超时时间（秒）	21600（6小时）
--connect-timeout	int	网络连接超时（秒）	None
--read-timeout	int	网络读取超时（秒）	None
--headers	str	额外的HTTP头 格式：key1=value1 key2=value2 将用于每个查询	-
--no-test-connection	bool	不发送连接测试，直接开始压测	False

请求控制

参数	类型	说明	默认值
--parallel	list[int]	并发请求的数量 可传入多个值，空格分隔	1
--number	list[int]	发出的请求总数量 可传入多个值（需与parallel一一对应）	1000
--rate	float	请求调度速率（请求/秒） • -1: 不做速率节流；在默认 closed-loop 模式下，请求会尽快调度，但实际同时在飞的 HTTP 请求数仍受 --parallel 限制，并不会一次性全部发送到服务端 • > 0: 请求按泊松到达模型调度，间隔服从均值为 1/rate 的指数分布，即平均每秒调度 rate 个请求	-1
--log-every-n-query	int	每N个查询记录日志	100
--stream	bool	是否使用SSE流输出 需要启用以测量TTFT（Time to First Token）指标	True
--sleep-interval	int	每次性能测试之间的休眠时间（秒） 避免过载服务器	5
--open-loop	bool	启用开放环路（open-loop）模式： 请求按 --rate 指定的速率发出，无论服务端是否已处理完之前的请求。 • --rate 变为扫描变量（支持多值） • --number 须与 --rate 等长，表示每轮发出的请求总数 • --parallel 在此模式下被忽略（内部设为 -1 / INF） 详见使用示例	False
--warmup-num	float	预热请求数量或比例： • 0：禁用预热（默认） • >= 1：绝对数量，如 --warmup-num 10 表示预热 10 个请求 • 0 < value < 1：比例模式，如 --warmup-num 0.1 表示预热数量为 --number 的 10% 预热请求使用与正式压测相同的并发/速率发送，但不计入性能指标 适用于消除冷启动影响（如 KV-cache 填充、JIT 编译等） 详见使用示例	0
--duration	float	单次压测的墙钟时间预算（秒） 软退出语义：到点后不再启动新请求，但已经在飞行中的请求会跑完才退出 多轮模式下的"已在飞"指的是已经 claim 的 trace 跑完所有剩余 turn（trace-level soft exit，与上游 trie 一致） 与 --number 同时设置时取先达到的那个为停止条件	None

小技巧

Closed-loop 模式（默认） 与 Open-loop 模式（--open-loop）的参数行为对比：

	Closed-loop（默认）	Open-loop（--open-loop）
--rate	控制请求调度速率（-1 表示无 pacing，但仍受 --parallel 并发上限约束；R 为泊松到达均值）	控制请求发出速率；必须 > 0；支持多值（如 5 10 20），每个值对应一轮独立压测
--number	每轮总请求数，与 --parallel 等长	每轮总请求数，须与 --rate 等长
--parallel	同时在飞行中的最大请求数；每个 worker 收到响应后才发下一条（背压保护）	被忽略，并发上限为无穷大（INF）；请求按调度立即发出，不等待响应
适用场景	测量服务在受控并发下的延迟与吞吐	模拟真实流量（请求到达与服务时间无关）；扫描多速率点的吞吐-延迟曲线

SLA设置

参数	类型	说明	默认值
--sla-auto-tune	bool	是否启用SLA自动调优模式	False
--sla-variable	str	自动调优的变量 可选：parallel（并发数）、rate（请求速率）	parallel
--sla-params	str	SLA约束条件 JSON字符串 支持指标：avg_latency, p99_latency, avg_ttft, p99_ttft, avg_tpot, p99_tpot, rps, tps 支持操作符：<=, <, min (延时类); >=, >, max (吞吐类) 示例：'[{"p99_latency": "<=2"}]'	None
--sla-upper-bound	int	被调优变量的搜索上界	65536
--sla-lower-bound	int	被调优变量的搜索下界	1
--sla-fixed-parallel	int	在 --sla-variable=rate 时使用的固定并发数；未设置时默认回退到 --sla-upper-bound 以兼容旧行为	None
--sla-num-runs	int	每个并发级别的运行次数（取平均值）	3
--sla-number-multiplier	float	每次测试时请求总数相对于被调优变量（并发数或速率）的倍数，即 number = round(variable × N)；未设置时默认为 2	None

参见

SLA自动调优功能使用详见自动调优指南。

Prompt设置

参数	类型	说明	默认值
--max-prompt-length	int	最大输入prompt长度 超过该值时将丢弃prompt	131072
--min-prompt-length	int	最小输入prompt长度 小于该值时将丢弃prompt	0
--prefix-length	int	prompt的前缀长度 仅对random数据集有效	0
--prompt	str	指定请求prompt 字符串或本地文件（通过@/path/to/file指定） 优先级高于dataset 示例：@./prompt.txt	-
--query-template	str	指定查询模板 JSON字符串或本地文件（通过@/path/to/file指定） 示例：@./query_template.json	-
--apply-chat-template	bool	是否应用聊天模板	None（根据URL后缀自动判断）
--image-width	int	随机VL数据集图像宽度	224
--image-height	int	随机VL数据集图像高度	224
--image-format	str	随机VL数据集图像格式	RGB
--image-num	int	随机VL数据集图像数量	1
--image-patch-size	int	图像的patch大小 仅用于本地图像token计算	28

数据集配置

参数	类型	说明	默认值
--dataset	str	数据集模式，详见下表	-
--dataset-path	str	数据集文件或目录路径 指向文件时直接读取；指向目录时在目录内查找对应数据文件（适用于离线环境使用已下载的数据集缓存）	-
--data-source	str	数据集加载源，可选值：modelscope、huggingface、local 未指定时默认使用 modelscope；当 --dataset-path 为本地目录时自动视为 local	modelscope
--dataset-args	str	数据集专属参数（JSON 字符串），按 --dataset 所选数据集的 schema 校验（传入未知键会直接报错）。承载真实文本数据集的定长输入参数 target_input_len / input_len_mode，并取代已废弃的 --multi-turn-args。详见下方「dataset-args：数据集专属参数」小节	-

dataset 模式说明

文本对话类

模式	说明	支持dataset-path
openqa	从ModelScope自动下载OpenQA prompt长度较短（一般<100 token） 指定dataset_path时使用jsonl文件的question字段	✓
longalpaca	从ModelScope自动下载LongAlpaca-12k prompt长度较长（一般>6000 token） 指定dataset_path时使用jsonl文件的instruction字段	✓
line_by_line	逐行将txt文件的每一行作为一个prompt 必需提供dataset_path	✓（必需）
random	根据prefix-length、max-prompt-length和min-prompt-length随机生成prompt 必需指定tokenizer-path 使用示例	✗
custom	自定义数据集解析器 参考自定义数据集指南	✓

多模态类

模式	说明	支持dataset-path
flickr8k	从ModelScope自动下载Flick8k 构建图文输入，数据集较大，适合评测多模态模型 支持--dataset-path指向本地数据集目录（离线环境）	✓（目录）
kontext_bench	从ModelScope自动下载Kontext-Bench 构建图文输入，约1000条数据，适合快速评测多模态模型 支持--dataset-path指向本地数据集目录（离线环境）	✓（目录）
random_vl	随机生成图像和文本输入 在random基础上增加图像相关参数 使用示例	✗

Embedding 类

模式	说明	支持dataset-path
embedding	从文件加载文本数据评测Embedding模型 支持Line-by-line(TXT)或JSONL格式（含text字段）	✓ (必需)
random_embedding	根据max-prompt-length和min-prompt-length随机生成query评测Embedding模型 必需指定tokenizer-path	✗
embedding_batch	批量发送文本数据评测Embedding模型 从文件加载数据 支持--extra-args '{"batch_size": 8}'设置批次大小	✓ (必需)
random_embedding_batch	批量发送根据max-prompt-length和min-prompt-length随机生成query数据评测Embedding模型 必需指定tokenizer-path 支持--extra-args '{"batch_size": 8}'设置批次大小	✗

Rerank 类

模式	说明	支持dataset-path
rerank	从文件加载Query-Document对评测Rerank模型 支持JSONL格式 (含query和documents字段)	✓ (必需)
random_rerank	根据max-prompt-length和min-prompt-length随机生成query数据评测Rerank模型 必需指定tokenizer-path 支持--extra-args '{"num_documents": 10, "document_length_ratio": 5}'设置文档数量和相对query的长度倍数	✗

多轮对话类

需配合 --multi-turn 使用，详见多轮对话压测指南。

模式	说明	支持dataset-path
random_multi_turn	合成多轮对话，每轮随机生成 token 序列 必需 --tokenizer-path、--max-turns 使用示例	✗
share_gpt_zh_multi_turn	从 ModelScope 自动下载中文 ShareGPT 数据集（约 70k 条），保留完整多轮对话 使用示例	✓
share_gpt_en_multi_turn	从 ModelScope 自动下载英文 ShareGPT 数据集（约 70k 条），保留完整多轮对话	✓
custom_multi_turn	使用本地 JSONL 文件作为自定义多轮对话数据集 每行为 OpenAI messages 格式的 JSON 数组，适合已有对话数据直接压测 必需提供dataset_path 使用示例	✓（必需）

生产流量回放类

需配合 --open-loop 使用，按录制的原始到达节奏逐字回放真实请求。详见使用示例。

模式	说明	支持dataset-path
workload_trace	回放录制的生产流量 JSONL：按原始时间戳、请求体、headers 逐字重放，贴近真实负载（突发流量、异构请求、多模型路由） 每条请求自带 model，保留多模型混合路由 必需 --open-loop 和 --dataset-path；--model/--number 可选（trace 自带模型与条数）	✓（必需）

dataset-args：数据集专属参数

--dataset-args 用一个 JSON 字符串为不同数据集传入专属参数（键名写错会直接报错，便于排查）。常见两个场景：

场景一：把真实数据的输入截断到固定长度

想用真实数据（而非 random）压测某个固定输入长度时用它。支持 openqa、longalpaca、line_by_line、单轮 ShareGPT（share_gpt_zh / share_gpt_en），需配合 --tokenizer-path。

# 把每条输入截断到 2048 token
evalscope perf \
  --model qwen2.5 --url http://127.0.0.1:8000/v1/completions \
  --dataset share_gpt_zh --tokenizer-path /path/to/tokenizer \
  --dataset-args '{"target_input_len": 2048}'

键	说明	默认值
target_input_len	目标输入 token 数。设置后每条 prompt 都会被截断到该长度	不启用
input_len_mode	对短于目标的 prompt 怎么处理：cap（原样保留，该条长度可能小于目标）；drop（丢弃，保证产出的每条都恰好等于目标）	cap

它和 --max/min-prompt-length 的区别：

• --max/min-prompt-length 只筛选、不改内容——长度不在区间内的样本被丢弃，你得到的是长短不一的真实样本；

• target_input_len 会改写内容——把每条 prompt 截到指定长度，适合“固定输入长度”的对照压测。

想让“每条恰好 N token”，只能用 target_input_len；把 --min-prompt-length 和 --max-prompt-length 设成相等是做不到的（真实数据几乎没有恰好等于 N 的，会被筛空）。random 数据集除外——它是现场生成的，min=max 即可定长，无需本参数。

场景二：多轮对话数据集的长度参数

swe_smith 等多轮数据集的 token 长度参数也通过 --dataset-args 传入，详见多轮对话压测指南。

场景三：回放真实生产流量

用 workload_trace 把录制的生产流量按原始到达节奏逐字回放，贴近真实负载。必需 --open-loop，无需 --rate（到达时刻由 trace 时间戳决定）。完整示例见生产流量回放（workload_trace）。

trace 文件为 JSONL，每行一条请求记录：

{"body": {"model": "qwen-plus", "messages": [{"role": "user", "content": "hi"}]}, "timestamp": 1700000000.0}
{"body": {"model": "qwen-max", "messages": [...]}, "timestamp": 1700000001.5, "headers": {"X-Tag": "exp"}, "request_id": "req-42", "completion_tokens": 256}

字段	必需	说明
body	✓	完整请求体（dict 或 JSON 字符串），原样发送
timestamp	✓	到达时刻（数字或 ISO-8601 字符串），仅相对间隔有意义，须单调不减
headers		该请求专属 HTTP 头（与 CLI headers 合并，CLI 优先；hop-by-hop 头会被剔除）
request_id		透传到结果，用于与原始请求关联
completion_tokens		配合 match_output_length 使用

键	类型	说明	默认值
speed	float	回放倍速（2.0 = 2× 快，0.5 = 2× 慢）	1.0
model_override	str	把所有请求的 model 全量替换为该值	不启用
model_mapping	dict	按名映射 model（命中优先；未命中保留原值）	不启用
match_output_length	bool	用记录的 completion_tokens 设 max_tokens 并启用 ignore_eos（需 vLLM 等支持；对约束解码请求自动跳过 ignore_eos）	false

备注

--model 对 workload_trace 不会改写 trace body——每条请求保留自己的 model，从而保留多模型混合路由。需要改模型请用 model_override / model_mapping。

备注

--multi-turn-args 已废弃，请改用 --dataset-args（键名不变）。旧参数仍可用，会自动并入 --dataset-args（同名键以 --dataset-args 为准）。

模型设置

参数	类型	说明	默认值
--tokenizer-path	str	分词器权重路径 用于计算输入和输出的token数量 通常与模型权重在同一目录	None
--frequency-penalty	float	frequency_penalty值	-
--logprobs	bool	是否返回对数概率	-
--max-tokens	int 或 int int	可以生成的最大token数量 • 单个整数：固定值，如 --max-tokens 2048 • 两个整数：最小值 最大值，每次请求从该范围均匀随机采样，如 --max-tokens 512 2048	2048
--min-tokens	int	生成的最少token数量 注意：并非所有模型服务都支持 对于vLLM>=0.8.1，需额外设置 --extra-args '{"ignore_eos": true}'	-
--n-choices	int	生成的补全选择数量	-
--seed	int	随机种子	None
--stop	str	停止生成的tokens	-
--stop-token-ids	list[int]	停止生成的token ID列表	-
--temperature	float	采样温度	0
--top-p	float	top_p采样	-
--top-k	int	top_k采样	-
--extra-args	str	额外传入请求体的参数 JSON字符串格式 示例：'{"ignore_eos": true}'	-
--tokenize-prompt	bool	在客户端将prompt tokenize为token ID列表，绕过服务端重新tokenize，通过/v1/completions直接发送	False

数据存储

参数	类型	说明	默认值
--visualizer	str	可视化工具 可选：wandb、swanlab、clearml 设置后指标将保存到指定工具	None
--enable-progress-tracker	bool	是否开启进度追踪，将层级压测进度实时写入progress.json，可通过服务接口查询	False
--wandb-api-key	str	wandb API密钥 已废弃，请使用--visualizer wandb	-
--swanlab-api-key	str	swanlab API密钥 已废弃，请使用--visualizer swanlab	-
--outputs-dir	str	输出文件路径	./outputs
--no-timestamp	bool	输出目录不包含时间戳	False

多轮对话设置

参数	类型	说明	默认值
--multi-turn	bool	启用多轮对话压测模式；--number 表示总发送 turn 数，--parallel 表示并发 turn 数	False
--min-turns	int	每个对话最少用户轮数；random_multi_turn 与 swe_smith 使用	1
--max-turns	int	每个对话最多用户轮数；random_multi_turn 必需；ShareGPT/custom_multi_turn 可选（截断过长对话）；swe_smith 用作每个对话轮数采样上界，未设置时回退到 --min-turns	None
--num-workers	int	CPU 密集型数据集/请求生成的 worker 进程数。 0 = 根据 CPU 亲和性自动检测；1 = 串行（无多进程）；>1 = 显式指定 worker 数。 用于 random（长 prompt 并行生成）和 swe_smith（live 构建）。取代已废弃的 multi_turn_args.num_workers。	0

参见

多轮对话压测使用详见多轮对话压测指南。

其他参数

参数	类型	说明	默认值
--db-commit-interval	int	在写入SQLite数据库前缓冲的行数	1000
--queue-size-multiplier	int	请求队列的最大大小 计算方式：parallel * multiplier	5
--in-flight-task-multiplier	int	最大调度任务数 计算方式：parallel * multiplier	2