digit-cracker/BENCHMARK_GUIDE.md

# 并发性能测试使用指南

## 📋 概述

本项目提供了完整的并发性能测试工具，用于评估 YOLO 数字识别系统在多用户同时访问场景下的性能表现。

## 🎯 测试工具

### 1. `benchmark_concurrent.py` - 核心测试脚本

模拟 n 个用户并发执行数字识别任务。

**主要功能：**
- ✅ 支持自定义并发用户数和每用户图片数
- ✅ 循环使用 valid 文件夹中的图片
- ✅ 统计详细的性能指标（QPS、响应时间、成功率等）
- ✅ 生成文本和 JSON 格式的报告
- ✅ 支持不同的模型和配置参数

**基本用法：**

```bash
# 模拟10个用户，每个用户识别20张图片
python scripts/benchmark_concurrent.py --users 10 --images-per-user 20

# 使用详细输出模式
python scripts/benchmark_concurrent.py --users 5 --images-per-user 10 --verbose

# 调整置信度阈值
python scripts/benchmark_concurrent.py --users 10 --images-per-user 20 --conf 0.15

# 指定输出文件
python scripts/benchmark_concurrent.py --users 20 --output results/my_test.txt
```

**完整参数：**

```bash
--users N               # 并发用户数量（默认: 10）
--images-per-user N     # 每个用户识别的图片数量（默认: 20）
--model PATH           # 模型路径（默认: 最佳模型）
--source DIR           # 图片源文件夹（默认: valid）
--conf FLOAT           # 置信度阈值（默认: 0.2）
--imgsz INT            # 输入图片大小（默认: 320）
--output FILE          # 输出报告路径（默认: results/benchmark_report.txt）
--verbose              # 显示详细日志
```

### 2. `run_benchmark_quick.sh` - 快速测试套件

运行一组预定义的快速测试（1, 3, 5, 8 个并发用户），适合快速验证。

**使用方法：**

```bash
./scripts/run_benchmark_quick.sh
```

**测试配置：**
- 并发级别：1, 3, 5, 8 用户
- 每用户图片数：10 张
- 总共测试：10 + 30 + 50 + 80 = 170 张图片

**输出：**
- 各并发级别的详细报告
- 性能对比摘要表格
- 保存位置：`results/benchmark_quick/`

### 3. `run_benchmark_suite.sh` - 完整测试套件

运行更全面的测试（1, 3, 5, 10, 15, 20 个并发用户）。

**使用方法：**

```bash
./scripts/run_benchmark_suite.sh
```

**测试配置：**
- 并发级别：1, 3, 5, 10, 15, 20 用户
- 每用户图片数：20 张
- 总共测试：20 + 60 + 100 + 200 + 300 + 400 = 1080 张图片

**输出：**
- 各并发级别的详细报告
- 性能对比摘要表格
- 保存位置：`results/benchmark_suite/`

## 📊 性能指标说明

### 报告包含的指标

**总体性能：**
- **总执行时间**：所有并发用户完成的总时间
- **总识别图片数**：所有用户处理的图片总数
- **成功率**：成功识别的图片比例
- **吞吐量 (QPS)**：每秒处理的图片数量

**响应时间统计：**
- **平均响应时间**：单张图片的平均识别时间
- **最小/最大响应时间**：响应时间的范围
- **P50/P90/P95/P99**：百分位数，表示大部分请求的响应时间

**各用户性能：**
- 每个用户的图片数、成功数、总耗时、平均耗时

## 📈 测试结果示例

### 快速测试结果（实际测试数据）

```
并发用户 | 总图片  | 总耗时(s) | QPS    | 平均响应(s)
---------|---------|-----------|--------|------------
1        | 10      | 0.17      | 60.30  | 0.014
3        | 30      | 0.36      | 84.35  | 0.027
5        | 50      | 0.58      | 86.05  | 0.042
8        | 80      | 1.10      | 72.65  | 0.081
```

### 标准测试结果（10用户×20图）

```
总体性能:
  - 总执行时间: 2.85 秒
  - 总识别图片数: 200
  - 成功: 200 (100.0%)
  - 吞吐量 (QPS): 70.28 图片/秒

响应时间统计:
  - 平均响应时间: 0.123 秒
  - P50 响应时间: 0.109 秒
  - P90 响应时间: 0.167 秒
  - P99 响应时间: 0.342 秒
```

## 💡 使用建议

### 场景选择

| 测试场景 | 推荐工具 | 适用情况 |
|---------|---------|---------|
| 快速验证 | `run_benchmark_quick.sh` | 代码修改后快速验证性能 |
| 完整评估 | `run_benchmark_suite.sh` | 系统上线前全面测试 |
| 自定义测试 | `benchmark_concurrent.py` | 特定并发场景测试 |
| 压力测试 | `benchmark_concurrent.py` | 使用更高的并发数（如50+） |

### 测试流程建议

**1. 开发阶段**

```bash
# 快速测试，验证功能正常
python scripts/benchmark_concurrent.py --users 3 --images-per-user 5 --verbose
```

**2. 性能优化**

```bash
# 运行快速套件，对比优化前后
./scripts/run_benchmark_quick.sh
```

**3. 上线前验证**

```bash
# 运行完整套件，全面评估
./scripts/run_benchmark_suite.sh
```

**4. 压力测试**

```bash
# 高并发测试
python scripts/benchmark_concurrent.py --users 50 --images-per-user 10
```

### 性能调优建议

如果性能不理想，可以尝试：

1. **调整模型参数**
   ```bash
   # 降低置信度阈值
   --conf 0.15
   
   # 减小输入图片尺寸
   --imgsz 256
   ```

2. **优化并发配置**
   - 根据 CPU 核心数调整并发用户数
   - 监控系统资源使用情况

3. **使用更快的模型**
   ```bash
   # 使用更小的模型（如果准确率满足要求）
   --model yolov8n.pt
   ```

## 📁 输出文件说明

### 文本报告 (`.txt`)

详细的性能测试报告，包含：
- 测试配置信息
- 总体性能统计
- 响应时间分析
- 各用户执行情况
- 失败任务详情（如有）

### JSON 数据 (`.json`)

结构化的测试数据，包含：
```json
{
  "config": {...},           // 测试配置
  "summary": {               // 总体统计
    "total_time": 2.85,
    "total_images": 200,
    "qps": 70.28
  },
  "users": [                 // 每个用户的详细结果
    {
      "user_id": 0,
      "results": [...],      // 每张图片的识别结果
      "total_time": 2.50,
      "success_count": 20,
      "avg_time": 0.125
    }
  ]
}
```

JSON 文件可用于：
- 后续数据分析
- 生成自定义报告
- 性能趋势对比

## 🔍 故障排查

### 问题：测试时间过长

**原因：** 并发数或图片数设置过高

**解决：**
```bash
# 减少并发数或图片数
python scripts/benchmark_concurrent.py --users 5 --images-per-user 10
```

### 问题：部分识别失败

**原因：** 图片质量差或置信度阈值过高

**解决：**
```bash
# 降低置信度阈值
python scripts/benchmark_concurrent.py --conf 0.1

# 或先对图片进行预处理
python scripts/preprocess_images.py --input valid --output valid-processed --method clahe
python scripts/benchmark_concurrent.py --source valid-processed
```

### 问题：QPS 过低

**可能原因：**
- 模型加载开销（每个线程独立加载）
- 图片尺寸过大
- 系统资源不足

**优化建议：**
- 减小 `--imgsz` 参数
- 关闭其他占用资源的程序
- 监控 CPU 使用率

## 📝 自定义测试

### 创建自定义测试脚本

```bash
#!/bin/bash
# 自定义测试场景

# 场景1：低并发长时间测试
python scripts/benchmark_concurrent.py \
    --users 2 \
    --images-per-user 100 \
    --output results/scenario1.txt

# 场景2：高并发短时间测试
python scripts/benchmark_concurrent.py \
    --users 50 \
    --images-per-user 5 \
    --output results/scenario2.txt

# 场景3：不同配置对比
for conf in 0.1 0.15 0.2 0.25; do
    python scripts/benchmark_concurrent.py \
        --users 10 \
        --images-per-user 10 \
        --conf $conf \
        --output results/benchmark_conf_${conf}.txt
done
```

## 🎓 最佳实践

1. **基线测试**：先建立性能基线（单用户测试）
2. **逐步加压**：从低并发逐步提高到高并发
3. **多次测试**：每个场景测试3-5次，取平均值
4. **记录环境**：记录测试时的系统环境和资源使用情况
5. **对比分析**：保存历史测试数据，进行趋势分析

## 📞 相关文档

- [README.md](../README.md) - 项目完整文档
- [QUICKSTART.md](../QUICKSTART.md) - 快速开始指南
- [FINAL_REPORT.md](../FINAL_REPORT.md) - 项目性能报告

---

**作者**: Gavin Chan  
**创建日期**: 2025-01-30  
**最后更新**: 2025-01-30