# 大模型速度测试助手 (Ollama 版)

一个用于测试**本地 Ollama 大模型**响应速度的工具，提供 Web 界面，可测量
**TTFT（首 Token 延迟）、Prefill 时间、解码速度（tokens/s）、端到端延迟**等真实推理指标。

## 目录结构

```
llm_speed_test_app/
├── run.py                  # 启动入口
├── requirements.txt        # Python 依赖
├── backend/                # 后端（Python）
│   ├── config.py           # 配置（Ollama 地址、模型、端口）
│   ├── ollama_client.py    # Ollama API 客户端（流式调用 + 指标测量）
│   ├── engine.py           # 测试引擎（编排用例、统计、落盘）
│   ├── report.py           # HTML 报告生成
│   ├── server.py           # HTTP 服务器（API + 前端静态托管）
│   ├── stats.py            # 统计计算（均值/标准差/百分位）
│   └── test_cases/         # 7 个测试用例（真实调用 Ollama）
│       ├── base.py
│       ├── case_01_generation.py    纯文本生成基准
│       ├── case_02_simple_tool.py   简单工具调用延迟
│       ├── case_03_file_analysis.py 文件读取+分析
│       ├── case_04_parallel_tool.py 并行工具调用
│       ├── case_05_long_context.py   长上下文处理
│       ├── case_06_reasoning.py      复杂推理任务
│       └── case_07_multiturn.py      多轮对话累积
├── frontend/               # 前端（静态页面）
│   ├── index.html
│   ├── css/style.css
│   └── js/app.js
├── results/                # 测试结果 JSON（运行时自动创建）
└── report/                 # HTML 报告（运行时自动创建）
```

## 环境要求

- Python 3.8+
- [Ollama](https://ollama.com/) 已安装并启动
- 已拉取至少一个模型，例如：`ollama pull gemma2:2b`

## 快速开始

```bash
# 1. 启动 Ollama（如未启动）
ollama serve
# 或直接运行 ollama（Windows 桌面版一般自启）

# 2. 拉取模型（任选其一，或使用已拉取的模型）
ollama pull deepseek-r1:latest   # 约 5GB，轻量

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动应用
python run.py
```

然后浏览器打开 **http://localhost:8000**。

> 注意：如果前端下拉框显示"未找到已拉取的模型"，请确认 Ollama 服务已启动，
> 刷新页面即可重新加载模型列表。

## 使用说明

1. 选择测试用例（"推荐组合"勾选快速用例，耗时用例用于压力测试）
2. 选择模型（自动从本地 Ollama 拉取已安装模型）
3. 设置重复次数
4. 点击"开始测试"，观察实时进度
5. 测试完成后自动展示：推理核心指标、延迟对比图表、详细数据表
6. 可导出 CSV / JSON，或打开完整 HTML 报告

## 测试用例说明

| 用例 | 难度 | 说明 |
|---|---|---|
| 纯文本生成基准 | 简单 | 基础生成速度基准测试 |
| 简单工具调用延迟 | 简单 | 结构化工具输出的调用延迟 |
| 文件读取+分析 | 中等 | 文件读取与分析完整链路 |
| 并行工具调用 | 中等 | 串行 vs 并行请求的加速比 |
| 长上下文处理 | 耗时 | 500~4000 token 下 prefill 延迟变化 |
| 复杂推理任务 | 耗时 | 不同推理复杂度的延迟对比 |
| 多轮对话累积 | 耗时 | 上下文累积对延迟的影响 |

## 测量指标说明

| 指标 | 来源 |
|---|---|
| TTFT (首 Token 延迟) | 发起请求到首个生成 token 返回的时间 |
| Prefill Time | Ollama 返回的 `prompt_eval_duration`（prompt 预填充耗时） |
| Decode Speed | `eval_count / eval_duration`（生成速度 tokens/s） |
| E2E | 请求到完整回复的总耗时 |

## 配置（可选）

通过环境变量覆盖默认配置：

| 变量 | 默认值 | 说明 |
|---|---|---|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务地址 |
| `DEFAULT_MODEL` | `qwen3.6:35b-a3b` | 默认模型 |
| `SPEED_TEST_PORT` | `8000` | Web 服务端口 |

## API 一览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/models` | 本地已拉取的模型列表 |
| GET | `/api/cases` | 用例注册表 |
| POST | `/api/run` | 开始测试（后台线程执行），body: `{cases, repeats, model, skip_heavy}` |
| GET | `/api/status` | 当前运行进度 |
| POST | `/api/stop` | 停止当前测试 |
| GET | `/api/results/latest.json` | 最近一次测试结果 |
| GET | `/report.html` | 完整 HTML 报告 |