# evalscope_perf_benchmark

**Repository Path**: ddgit123/evalscope_perf_benchmark

## Basic Information

- **Project Name**: evalscope_perf_benchmark
- **Description**: # evalscope_perf_benchmark

基于 evalscope 框架的大模型性能压测工具

## 功能特性

- 🚀 高性能并发测试
- 🔌 插件化架构
- 📊 详细性能指标
- 🔧 易于扩展和定制
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大模型性能压测工具 README

## 项目简介

这是一个基于 `evalscope`框架开发的**自定义大模型性能压测工具**，旨在为用户提供灵活、高效的大语言模型（LLM）性能测试和基准评估能力。通过该工具，用户可以对各类大语言模型进行多维度、多场景的性能压测，获取详尽的性能指标与分析结果，辅助模型优化与选型决策。

---

## 🌟 功能特性

-  **✅ 多模型支持**：适配各种大语言模型 API 接口，支持灵活接入不同模型服务。
-  **✅ 并发测试**：支持多线程并发请求，模拟高并发、真实用户场景。
-  **✅ 流式响应**：完整支持流式输出模型的性能测试，评估流式场景下的响应效率。
-  **✅ 自定义数据集**：支持从文件加载测试数据集，便于针对不同场景定制测试内容。
-  **✅ 详细统计**：提供全面的性能指标和统计分析，包括吞吐量、延迟、成功率等关键数据。
-  **✅ 插件化架构**：采用模块化设计，易于扩展新的模型接口和数据集格式，满足定制化需求。
-  **✅ 时长与请求数双控制**：支持固定请求数与压测时长两种模式，适应不同测试目标。
-  **✅ 可视化支持**：集成 [SwanLab](https://swanlab.cn/)可视化工具，实时监控与展示压测结果。

---

## 📁 项目结构

```
.
├── run_benchmark.py              # 主运行文件（含三种使用版本：并发压测、时长压测、综合配置）
├── custom_api.py                 # 自定义 API 插件示例（模拟LLM API）
├── custom_dataset.py             # 自定义数据集插件示例（模拟数据集）
├── extended_arguments.py         # 扩展的压测参数类，支持时长控制与可视化配置
├── extended_benchmark.py         # 扩展的压测逻辑，支持时长控制
├── extended_main.py              # 扩展的主运行逻辑，整合时长控制与可视化
├── dataset/
│   └── querys.txt                # 默认测试数据集（每行一个查询问题）
├── visualization_manager.py      # 可视化管理模块（SwanLab集成）
├── benchmark_config.ini          # 压测配置文件（第三版使用，可选）
├── README.md                     # 本说明文档
└── requirements.txt              # 依赖库列表（见文档10）
```

> **注意**：`custom_api.py`和 `custom_dataset.py`为示例插件，用户可根据实际需求编写自定义插件，详见【自定义扩展】部分。

---

## 🚀 快速开始

### 1. 环境准备

#### 安装 Python 依赖

确保已安装 Python 3.7 及以上版本，然后安装项目所需的依赖库：

```
pip install -r requirements.txt
```

> **依赖库列表见requirements.txt，主要包括** **`evalscope`** **,**  **`swanlab`** **,**  **`aiohttp`** **,**  **`sqlite3`** **等。**

#### 准备测试数据

在 `dataset/`目录下准备测试问题文件，例如 `querys.txt`，**每行一个查询问题**，例如：

```
请介绍一下人工智能的发展历史
如何学习机器学习？
解释一下深度学习的基本原理
国家电网的经营范围包括哪些？
列举国家电网的三大核心业务板块。
```

> **默认数据集文件为** **`dataset/querys.txt`** **，用户可自行修改数据集路径与内容。**

---

## 配置说明


## 配置文件说明（benchmark_config.ini）

### [model] - 模型配置部分
配置模型相关参数

| 参数名 | 示例值 | 说明                            |
|--------|--------|-------------------------------|
| name | 通义千问2.5-72B | 模型名称标识                        |
| url | http://127.0.0.1:18063/lmp-cloud-ias-server/api/llm/chat/completions/V2 | 模型API接口地址                     |
| api | mock_llm | API插件类型：mock_llm（自定义的模拟LLM接口） |

### [dataset] - 数据集配置部分
配置测试数据集相关参数

| 参数名 | 示例值 | 说明                              |
|--------|--------|---------------------------------|
| type | mock_dataset | 数据集插件类型：mock_dataset（自定义的模拟数据集） |
| path | dataset/querys.txt | 测试数据集文件路径，每行一个查询问题              |

### [inference] - 推理参数配置部分
配置模型推理相关参数

| 参数名 | 示例值 | 说明 |
|--------|--------|------|
| max_tokens | 512 | 可以生成的最大token数量 |
| temperature | 0.7 | 生成多样性控制参数（0-2之间，值越大随机性越强） |
| stream | yes | 是否使用流式输出：yes/no |

### [auth] - 认证信息配置部分
配置API认证信息

| 参数名 | 示例值 | 说明 |
|--------|--------|------|
| key | 4f2d383beb34439694efa18adf908b9d | API认证密钥（Authorization） |

### [benchmark] - 压测参数配置部分
配置性能压测相关参数

| 参数名 | 示例值 | 说明 |
|--------|--------|------|
| parallel | 5 | 并发线程数，模拟同时在线用户数 |
| mode | 1 | 压测模式：1=时长控制，2=固定请求数 |
| duration | 10 | 压测时长（当mode=1时生效） |
| duration_unit | 1 | 时间单位：1=秒，2=分钟 |
| number | 5 | 请求数量（当mode=2时生效） |
| use_visualization | yes | 是否启用可视化：yes/no |
| swanlab_project | llm-benchmark | SwanLab可视化项目名称 |
| swanlab_experiment_name | my-experiment | SwanLab实验名称 |
| swanlab_description | LLM性能压测实验 | 实验描述信息 |

## 使用说明

### 1. 基本使用
修改配置后直接运行 `run_benchmark.py` 即可开始压测。

### 2. 压测模式说明

#### 模式1：时长控制
- **适用场景**：按指定时间持续压测，适合稳定性测试
- **配置要点**：设置 `mode=1`，并配置 `duration` 和 `duration_unit`

#### 模式2：固定请求数
- **适用场景**：发送指定数量的请求后停止，适合性能基准测试
- **配置要点**：设置 `mode=2`，并配置 `number`

### 3. 数据集文件格式
- 文件编码：UTF-8
- 格式要求：每行一个查询问题
- 示例：

#### 🛠️ 版本三：支持配置文件、选择压测时长、可视化（推荐，综合版）

- **适用场景**：希望通过配置文件管理压测参数，支持灵活选择压测模式（时长/请求数）、集成可视化工具（如SwanLab）进行实时监控与结果展示。
- **配置方式**：

  - 工具会自动在项目根目录创建默认配置文件 `benchmark_config.ini`，用户也可手动修改该文件。
  - 运行时会通过交互式命令行引导用户选择配置，或直接使用配置文件中的默认值。
  - 支持启用或禁用SwanLab可视化，配置项目与实验信息。
- **运行方式**：执行 `python run_benchmark.py`。


---

## 📈 输出结果

工具运行后会输出详细的性能指标，包括但不限于：

- **总请求数** 和 **成功率**
- **平均响应时间** 与 **各百分位延迟**
- **Tokens 消耗统计**（Prompt + Completion）
- **吞吐量**（requests/second, tokens/second）
- **错误分析与诊断信息**

具体指标说明详见项目文档中的【指标说明】部分，包括：

- **Time taken for tests**：测试总时长
- **Request throughput (req/s)** ：请求吞吐量
- **Output token throughput (tok/s)** ：输出吞吐量
- **Average latency**：平均延迟
- **Average time to first token (TTFT)** ：首token时间
- **Average inter-token latency (ITL)** ：输出token间时延
- **Percentage Metrics**：如 P50, P90, P99 延迟等

---

## 🔧 自定义扩展

### 1. 添加新的模型接口

1. **创建新的 API 插件文件**（如 `my_llm_api.py`）：

```
from evalscope.perf.plugin.api.default_api import DefaultApiPlugin
from evalscope.perf.plugin.registry import register_api

@register_api("my_llm")
class MyLLMApiPlugin(DefaultApiPlugin):
    def build_request(self, messages, param=None):
        # 自定义请求构建逻辑
        pass
    
    def parse_responses(self, responses, request=None, **kwargs):
        # 自定义响应解析逻辑
        pass
```

1. **在** **`run_benchmark.py`****中导入并配置使用新插件**：

```
import my_llm_api

args = Arguments(
    api="my_llm",
    # ... 其他配置
)
```

### 2. 添加新的数据集格式

1. **创建新的数据集插件文件**（如 `my_dataset.py`）：

```
from evalscope.perf.plugin.datasets.base import DatasetPluginBase
from evalscope.perf.plugin.registry import register_dataset

@register_dataset("my_dataset")
class MyDatasetPlugin(DatasetPluginBase):
    def build_messages(self) -> Iterator[List[Dict]]:
        # 自定义数据加载与消息构建逻辑
        pass
```

1. **在配置中使用新数据集**：

```
args = Arguments(
    dataset="my_dataset",
    dataset_path="path/to/your/dataset",
)
```

---

## 🛡️ 注意事项

1. **API 密钥安全**：建议通过环境变量或配置文件安全地管理密钥。
2. **服务稳定性**：确保测试的目标模型服务稳定可用，避免因服务中断影响压测结果。
3. **资源限制**：根据模型服务商的速率限制与自身硬件资源，合理设置并发参数，避免过载。
4. **测试数据**：使用具有代表性的测试问题，以获得准确、可对比的压测结果。
5. **调试模式**：如遇问题，可开启调试模式（`debug=True`），查看详细日志输出，便于排查问题。

---

## 🧪 故障排除

如在使用过程中遇到问题，可参考以下步骤进行排查：

1. **开启调试模式**：在参数中设置 `debug=True`，查看详细日志。
2. **检查网络连接**：确保能够访问模型服务的 API 端点，网络稳定。
3. **验证认证信息**：确认 API 密钥、请求头等认证信息正确无误。
4. **查看日志输出**：通过控制台或日志文件，获取详细的错误信息与堆栈跟踪。

---

## 📚 指标说明

### 基础指标

| 指标                | 英文名称                          | 解释                                            | 公式                                       |
| --------------------- | ----------------------------------- | ------------------------------------------------- | -------------------------------------------- |
| 测试总时长          | Time taken for tests              | 整个测试过程从开始到结束所花费的总时间          | 最后一个请求结束时间 - 第一个请求开始时间  |
| 并发数              | Number of concurrency             | 同时发送请求的客户端数量                        | 预设值                                     |
| 总请求数            | Total requests                    | 在整个测试过程中发送的所有请求的数量            | 成功请求数 + 失败请求数                    |
| 成功请求数          | Succeed requests                  | 成功完成并返回预期结果的请求数量                | 直接统计                                   |
| 失败请求数          | Failed requests                   | 由于各种原因未能成功完成的请求数量              | 直接统计                                   |
| 输出吞吐量          | Output token throughput(tok/s)    | 每秒钟处理的平均标记（token）数                 | 总输出token数 / 测试总时长                 |
| 总吞吐量            | Total token throughput(tok/s)     | 每秒钟处理的平均标记（token）数                 | 总输入token数 + 总输出token数 / 测试总时长 |
| 请求吞吐量          | Request throughput(req/s)         | 每秒钟成功处理的平均请求数                      | 成功请求数 / 测试总时长                    |
| 总延迟时间          | Total latency                     | 所有成功请求的延迟时间总和                      | 所有成功请求的延迟时间之和                 |
| 平均延迟            | Average latency                   | 从发送请求到接收完整响应的平均时间              | 总延迟时间 / 成功请求数                    |
| 平均首token时间     | Average time to first token       | 从发送请求到接收到第一个响应标记的平均时间      | 总首chunk延迟 / 成功请求数                 |
| 平均每输出token时间 | Average time per output token     | 生成每个输出标记所需的平均时间（不包含首token） | 总每输出token时间 / 成功请求数             |
| 平均输出token间时延 | Average inter-token latency       | 生成每个输出token之间的平均间隔时间             | 总输出token间时延 / 成功请求数             |
| 平均输入token数     | Average input tokens per request  | 每个请求的平均输入标记数                        | 总输入token数 / 成功请求数                 |
| 平均输出token数     | Average output tokens per request | 每个请求的平均输出标记数                        | 总输出token数 / 成功请求数                 |

### 百分位指标 (Percentile)

| 指标              | 英文名称                     | 解释                                                                         |
| ------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| 首次生成token时间 | TTFT (Time to First Token)   | 从发送请求到生成第一个token的时间（以秒为单位），评估首包延时                |
| 输出token间时延   | ITL (Inter-token Latency)    | 生成每个输出token间隔时间（以秒为单位），评估输出是否平稳                    |
| 每token延迟       | TPOT (Time per Output Token) | 生成每个输出token所需的时间（不包含首token，以秒为单位），评估解码速度       |
| 端到端延迟时间    | Latency                      | 从发送请求到接收完整响应的时间（以秒为单位）：TTFT + TPOT \*Output tokens |
| 输入token数       | Input tokens                 | 请求中输入的token数量                                                        |
| 输出token数       | Output tokens                | 响应中生成的token数量                                                        |
| 输出吞吐量        | Output Throughput(tok/s)     | 每秒输出的token数量：输出tokens / 端到端延时                                 |
| 总吞吐量          | Total throughput(tok/s)      | 每秒处理的token数量：(输入tokens + 输出tokens) / 端到端延时                  |

---

---

## 📜 许可证

本项目基于 `evalscope`框架开发，遵循相应的开源协议。具体许可证信息请参考 `evalscope`项目的相关说明。

---



**祝您使用愉快，测试顺利！**