Metadata-Version: 2.4
Name: benchscope
Version: 1.0.0
Summary: vLLM / SGLang 推理服务性能测试 Web 工具 (benchscope)
Author-email: benchscope <benchscope@example.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/benchscope/benchscope
Project-URL: Documentation, https://github.com/benchscope/benchscope#readme
Project-URL: Source, https://github.com/benchscope/benchscope
Keywords: vllm,sglang,benchmark,llm,performance-test,inference,openai-api,web-ui,benchscope
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Benchmark
Classifier: Framework :: FastAPI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: requests>=2.31
Requires-Dist: openpyxl>=3.1
Requires-Dist: pydantic>=2
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: modelscope
Requires-Dist: modelscope>=1.15; extra == "modelscope"
Dynamic: license-file

# benchscope

vLLM / SGLang 推理服务性能测试 Web 工具（类似 tensorboard-dashboard 的单进程 pip 工具）。

连接 vLLM / SGLang（或任意 OpenAI 兼容）推理服务的 API 即可进行性能压测，
实时展示并发数-吞吐/时延曲线、日志管理与 xlsx 汇总分析。

## 功能特性（V1）

- **双框架**：vLLM（`vllm bench serve`）与 SGLang（`sglang.bench_serving`），
  bench 工具在 benchscope 所在机器以子进程运行，**推理服务端无需安装任何插件**，只需提供 OpenAI 兼容 API。
- **数据集**：
  - `random`：可多选输入/输出长度组合（默认 3K/1K、1K/1K、256/256，可自定义）；
  - `sharegpt`：自动从 modelscope 下载
    [gliang1001/ShareGPT_V3_unfiltered_cleaned_split](https://www.modelscope.cn/datasets/gliang1001/ShareGPT_V3_unfiltered_cleaned_split)
    （JSON 数组自动流式转换为 jsonl 缓存）；
  - `自定义数据集`：支持网页上传 jsonl 或填写服务器本地路径，功能与 sharegpt 一致。
- **测试配置**：并发数列表可编辑（默认 1,4,8,16,32,40,64,128），
  `--max-concurrency` 与 `--num-prompts` 保持一致，请求速率可选 `inf`（不限速）；
  GPU 型号/数量自动检测（nvidia-smi）并可手动编辑；TPOT 阈值设置与最佳并发高亮；
  框架常用参数表单 + 自由参数编辑器。
- **实时结果**：每个并发结果实时入表（表头中英双语），
  六条曲线（Output 吞吐 / Total 吞吐 / TTFT mean / TPOT mean / TTFT P99 / TPOT P99），横轴并发数。
- **日志**：每次测试一个 `月日-时分秒` 目录，含原始 bench 日志、mean 汇总 CSV、P99 汇总 CSV、
  `benchmark-*.xlsx`（均值 / P99 双 sheet，列：GPU、模型、精度、推理框架、输入长度、输出长度、
  并发数、output、peakoutput、total、ttft、itl、tpot、单用户=1000/tpot），支持预览与下载。
- **分析**：均值 / P99 两大分析块，output/peakoutput/total/ttft/itl/tpot 六曲线；
  指定 TPOT 阈值后自动标记最接近（低于）阈值的记录为最佳并发。
- **状态监控**：顶部导航实时显示 网站服务 / 推理服务 就绪或离线，推理服务断开自动变更状态。

## 安装与启动

```bash
# 后端依赖
pip install -e .

# 前端（可选，若 webui/ 已有构建产物可跳过）
cd web && npm install && npm run build && cd ..

# 启动（默认 http://0.0.0.0:8080，自动打开浏览器）
benchscope
# 或指定端口 / 不自动开浏览器
benchscope --port 8080 --no-browser
```

开发模式：

```bash
# 终端 1：后端
python -m benchscope.cli --port 8080 --no-browser
# 终端 2：前端热更新（代理到 8080）
cd web && npm run dev    # http://127.0.0.1:5173
```

## 服务设置

打开页面右上角「服务设置」：

- Base URL：推理服务 OpenAI 兼容地址（默认 `http://192.168.1.67:8000`），
  Endpoint、API Key、额外请求头；
- GPU 自动检测（nvidia-smi）或手动填写；
- 日志目录 `logs_dir` 与数据集缓存目录 `datasets_dir`（默认 `./logs`、`./datasets`）；
- TPOT 阈值默认值、请求速率默认值；
- bench 执行命令模板：`vllm bench serve` / `python -m sglang.bench_serving`。

## 使用流程

1. 打开页面，确认顶部「推理服务：就绪」；
2. 进入 vLLM 或 SGLang 测试页，选择模型（来自 `/v1/models`）、数据集、并发数等；
3. 点击「命令预览」确认将要执行的 bench 命令，点击「开始测试」；
4. 实时结果面板逐条刷新，曲线实时更新；日志分析面板可查看原始日志、汇总与 xlsx；
5. 测试完成后自动生成 `logs/<月日-时分秒>/benchmark-*.xlsx`（均值 + P99 双 sheet）。

## 目录结构

```
benchscope/
├── benchscope/
│   ├── cli.py                # benchscope 命令入口
│   ├── config.py             # 配置持久化 (~/.benchscope/config.json)
│   ├── constants.py          # 默认值（并发列表、长度组合等）
│   ├── datasets.py           # sharegpt 下载/转换、自定义数据集
│   ├── gpu.py                # GPU 自动检测
│   ├── parser.py             # bench 输出解析（mean + P99）
│   ├── summary.py            # CSV 与 xlsx 汇总生成
│   ├── benches/              # vllm/sglang 命令构建与执行
│   └── server/               # FastAPI + WebSocket + 测试编排
├── web/                      # Vue3 + Ant Design Vue 前端源码
├── asserts/                  # 参考脚本与样例日志（test-non.py 等）
└── tests/mock_openai_server.py  # 本地联调用模拟 OpenAI 服务
```

## 开发调试

- 无 vllm/sglang 环境联调：设置环境变量 `BENCHSCOPE_FAKE_BENCH=1` 后启动，bench 将以仿真数据执行；
- 本地模拟推理服务：`python tests/mock_openai_server.py`（端口 8001），
  在服务设置中把 Base URL 指向 `http://127.0.0.1:8001`。

## 规划

V1 纯文本性能测试（本版本）→ V2 多模态模型测试 → V3 全模态 → V4 世界模型；
V5 常见数据集精度测试 → V6 modelscope 官方模型对比分析。
