# 性能测试报告

## 1. 文档目标

本报告用于沉淀 `search / suggest / embedding / reranker` 四类接口的并发性能基线，并提供可复现的完整执行流程。  
新同事可直接按本文命令重跑全流程，得到同结构结果文件并横向对比。

## 2. 本次测试范围与方法

测试范围：
- `backend_search` -> `POST /search/`
- `backend_suggest` -> `GET /search/suggestions`
- `embed_text` -> `POST /embed/text`
- `rerank` -> `POST /rerank`

并发矩阵：
- `1 / 5 / 10 / 20`

执行方式：
- 每组压测持续 `20s`
- 使用统一脚本 `scripts/perf_api_benchmark.py`
- 通过 `--scenario` 多值 + `--concurrency-list` 一次性跑完 `场景 x 并发`

## 3. 压测工具优化说明（复用现有脚本）

为了解决原脚本“一次只能跑一个场景+一个并发”的可用性问题，本次直接扩展现有脚本：
- `scripts/perf_api_benchmark.py`

能力：
- 一条命令执行 `场景列表 x 并发列表` 全矩阵
- 输出单份 JSON 报告（含每组结果与 overall 汇总）

示例：

```bash
.venv/bin/python scripts/perf_api_benchmark.py \
  --scenario backend_search,backend_suggest,embed_text,rerank \
  --concurrency-list 1,5,10,20 \
  --duration 20 \
  --tenant-id 162 \
  --output perf_reports/$(date +%F)/perf_matrix_report.json
```

## 4. 测试环境快照（本次）

时间：
- `2026-03-12 08:11:34 CST`

代码版本：
- Git commit: `28e57bb`
- Python: `3.12.3`

机器信息：
- OS: `Linux ai-db 6.8.0-71-generic`
- CPU: `Intel(R) Xeon(R) Platinum 8255C CPU @ 2.50GHz`
- vCPU: `8`
- 内存: `30Gi`（可用约 `15Gi`）

服务健康：
- `GET http://127.0.0.1:6002/health` -> healthy
- `GET http://127.0.0.1:6005/health` -> embedding loaded (`tei`)
- `GET http://127.0.0.1:6006/health` -> translation healthy
- `GET http://127.0.0.1:6007/health` -> reranker loaded (`Qwen/Qwen3-Reranker-0.6B`)

索引doc数/租户基本信息：
tenant_id = 162 ：注意当前该租户总 doc 数只有53，reranker、suggest、search的性能指标跟租户的doc数高度相关。以后要补充一个
```
curl -u 'saas:4hOaLaf41y2VuI8y' -X GET 'http://localhost:9200/search_products_tenant_162/_count?pretty' -H 'Content-Type: application/json' -d '{
  "query": {
    "match_all": {}
  }
}'
```

## 5. 执行前准备（可复现步骤）

### 5.1 环境与依赖

```bash
cd /data/saas-search
source activate.sh
.venv/bin/python --version
```

### 5.2 启动服务

推荐：

```bash
./scripts/service_ctl.sh start embedding translator reranker backend
```

如果 `backend` 未成功常驻，可临时手动启动：

```bash
.venv/bin/python main.py serve --host 0.0.0.0 --port 6002 --es-host http://localhost:9200
```

### 5.3 健康检查

```bash
curl -sS http://127.0.0.1:6002/health
curl -sS http://127.0.0.1:6005/health
curl -sS http://127.0.0.1:6006/health
curl -sS http://127.0.0.1:6007/health
```

## 6. 压测执行命令（本次实际）

```bash
cd /data/saas-search
.venv/bin/python scripts/perf_api_benchmark.py \
  --scenario backend_search,backend_suggest,embed_text,rerank \
  --concurrency-list 1,5,10,20 \
  --duration 20 \
  --tenant-id 162 \
  --backend-base http://127.0.0.1:6002 \
  --embedding-base http://127.0.0.1:6005 \
  --translator-base http://127.0.0.1:6006 \
  --reranker-base http://127.0.0.1:6007 \
  --output perf_reports/2026-03-12/perf_matrix_report.json
```

产物文件：
- `perf_reports/2026-03-12/perf_matrix_report.json`
- `results[]` 中每条包含 `scenario + concurrency` 的单组结果
- `overall` 为本次执行总体汇总

## 7. 结果总览（本次实测）

### 7.1 Search（backend_search）

| 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 160 | 100.0% | 7.98 | 124.89 | 228.06 | 345.49 |
| 5 | 161 | 100.0% | 7.89 | 628.91 | 1271.49 | 1441.02 |
| 10 | 181 | 100.0% | 8.78 | 1129.23 | 1295.88 | 1330.96 |
| 20 | 161 | 100.0% | 7.63 | 2594.00 | 4706.44 | 4783.05 |

### 7.2 Suggest（backend_suggest）

| 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 3502 | 100.0% | 175.09 | 5.68 | 8.70 | 15.98 |
| 5 | 4168 | 100.0% | 208.10 | 23.93 | 36.93 | 59.53 |
| 10 | 4152 | 100.0% | 207.25 | 48.05 | 59.45 | 127.20 |
| 20 | 4190 | 100.0% | 208.99 | 95.20 | 110.74 | 181.37 |

### 7.3 Embedding（embed_text）

| 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 966 | 100.0% | 48.27 | 20.63 | 23.41 | 49.80 |
| 5 | 1796 | 100.0% | 89.57 | 55.55 | 69.62 | 109.84 |
| 10 | 2095 | 100.0% | 104.42 | 95.22 | 117.66 | 152.48 |
| 20 | 2393 | 100.0% | 118.70 | 167.37 | 212.21 | 318.70 |

### 7.4 Reranker（rerank）

| 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 802 | 100.0% | 40.06 | 24.87 | 37.45 | 49.63 |
| 5 | 796 | 100.0% | 39.53 | 125.70 | 190.02 | 218.60 |
| 10 | 853 | 100.0% | 41.89 | 235.87 | 315.37 | 402.27 |
| 20 | 836 | 100.0% | 40.92 | 481.98 | 723.56 | 781.81 |

## 8. 指标解读与并发建议

### 8.1 关键观察

- `backend_search`：吞吐约 `8 rps` 平台化，延迟随并发上升明显，属于重链路（检索+向量+重排）特征。
- `backend_suggest`：吞吐高且稳定（约 `200+ rps`），对并发更友好。
- `embed_text`：随并发提升吞吐持续增长，延迟平滑上升，扩展性较好。
- `rerank`：吞吐在 `~40 rps` 附近平台化，延迟随并发线性抬升，符合模型推理瓶颈特征。

### 8.2 并发压测建议

- 冒烟并发：`1/5`
- 常规回归：`1/5/10/20`
- 稳态评估：建议把 `duration` 提升到 `60~300s`
- 峰值评估：在确认 timeout 与 max_errors 策略后，追加 `30/50` 并发

## 9. 如何复现“完整全过程”

1. 准备环境（第 5 节）
2. 启动服务并通过健康检查
3. 执行矩阵命令（第 6 节）
4. 查看结果：
   - 原始明细：`perf_reports/<date>/perf_matrix_report.json` 的 `results[]`
   - 汇总结果：同文件中的 `overall`
5. 若需导出到周报或 PR，直接拷贝本报告第 7 节四张表

## 10. 常见问题与排障

### 10.1 backend 端口起来又掉

现象：
- `service_ctl status backend` 显示 `running=no`

处理：
- 先看 `logs/backend.log`
- 用手动命令前台启动，确认根因：

```bash
.venv/bin/python main.py serve --host 0.0.0.0 --port 6002 --es-host http://localhost:9200
```

### 10.2 压测脚本依赖缺失

现象：
- 报 `ModuleNotFoundError: httpx`

处理：
- 使用项目虚拟环境执行：

```bash
.venv/bin/python scripts/perf_api_benchmark.py -h
```

### 10.3 某场景成功率下降

排查顺序：
1. 看 `errors` 字段（HTTP码、timeout、payload校验失败）
2. 检查对应服务健康与日志
3. 缩小并发重跑单场景定位阈值

## 11. 关联文件

- 压测脚本：`scripts/perf_api_benchmark.py`
- 本次结果：`perf_reports/2026-03-12/perf_matrix_report.json`