16 KiB
16 KiB
参数说明
执行 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自动调优功能使用详见[自动调优指南](./sla_auto_tune.md)。
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 模式说明
文本对话类
| 模式 | 说明 | 支持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使用示例 |
✓（必需） |
模型设置
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
--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 |
多轮对话压测使用详见[多轮对话压测指南](./multi_turn.md)。
其他参数
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
--db-commit-interval |
int |
在写入SQLite数据库前缓冲的行数 | 1000 |
--queue-size-multiplier |
int |
请求队列的最大大小 计算方式： parallel * multiplier |
5 |
--in-flight-task-multiplier |
int |
最大调度任务数 计算方式： parallel * multiplier |
2 |