update at 2025-10-30 16:31:47

2025-10-30 16:31:47 +08:00
parent b431199a00
commit eba2f07990
5 changed files with 985 additions and 1 deletions
--- a/BENCHMARK_GUIDE.md
+++ b/BENCHMARK_GUIDE.md
@@ -0,0 +1,325 @@
+# 并发性能测试使用指南
+
+## 📋 概述
+
+本项目提供了完整的并发性能测试工具，用于评估 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