# 性能测试报告

## 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": {}
  }
}'
```

主要配置：
rerank_window=384

## 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`
- Search 多租户补测：`perf_reports/2026-03-12/search_tenant_matrix/`

## 12. Search 多租户补测（2026-03-12）

补测背景：
- 原报告中的 search 数据来自 `tenant_id=162`
- 该租户文档量偏小，无法覆盖不同数据规模下的性能趋势
- 本节补充 `backend_search` 在不同租户文档规模上的对比结果

租户与文档数（按需求方提供）：
- `tenant 0`: `10000`
- `tenant 1`: `500`
- `tenant 2`: `1000`
- `tenant 3`: `2000`
- `tenant 4`: `5000`

测试口径：
- 场景：`backend_search`（`POST /search/`）
- 并发：`1 / 5 / 10 / 20`
- 每档时长：`20s`
- 执行时间：`2026-03-12 10:15:01` 到 `2026-03-12 10:22:26`（CST）

执行命令（逐租户复现）：

```bash
cd /data/saas-search
mkdir -p perf_reports/2026-03-12/search_tenant_matrix
for t in 0 1 2 3 4; do
  .venv/bin/python scripts/perf_api_benchmark.py \
    --scenario backend_search \
    --concurrency-list 1,5,10,20 \
    --duration 20 \
    --tenant-id ${t} \
    --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/search_tenant_matrix/tenant_${t}.json
done
```

结果文件：
- `perf_reports/2026-03-12/search_tenant_matrix/tenant_0.json`
- `perf_reports/2026-03-12/search_tenant_matrix/tenant_1.json`
- `perf_reports/2026-03-12/search_tenant_matrix/tenant_2.json`
- `perf_reports/2026-03-12/search_tenant_matrix/tenant_3.json`
- `perf_reports/2026-03-12/search_tenant_matrix/tenant_4.json`

### 12.1 按租户汇总（overall）

| Tenant | 文档数 | 总请求 | 总成功率 | 汇总RPS | 加权平均延迟(ms) |
|---:|---:|---:|---:|---:|---:|
| 0 | 10000 | 195 | 87.18% | 2.00 | 4644.66 |
| 1 | 500 | 548 | 100.00% | 6.73 | 1346.28 |
| 2 | 1000 | 449 | 100.00% | 5.32 | 1731.96 |
| 3 | 2000 | 314 | 100.00% | 3.58 | 2605.60 |
| 4 | 5000 | 256 | 100.00% | 2.76 | 3491.67 |

### 12.2 按并发明细（backend_search）

| Tenant | 文档数 | 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| 0 | 10000 | 1 | 42 | 100.00% | 2.09 | 475.85 | 893.82 | 1034.47 |
| 0 | 10000 | 5 | 41 | 100.00% | 1.91 | 2558.69 | 4109.76 | 4532.22 |
| 0 | 10000 | 10 | 51 | 100.00% | 1.94 | 4816.46 | 5250.89 | 6729.64 |
| 0 | 10000 | 20 | 61 | 59.02% | 2.05 | 8773.39 | 10037.65 | 10156.94 |
| 1 | 500 | 1 | 120 | 100.00% | 5.99 | 166.04 | 312.03 | 1064.41 |
| 1 | 500 | 5 | 136 | 100.00% | 6.76 | 735.79 | 1291.69 | 1543.71 |
| 1 | 500 | 10 | 151 | 100.00% | 7.37 | 1349.03 | 2014.22 | 2020.32 |
| 1 | 500 | 20 | 141 | 100.00% | 6.77 | 2936.65 | 5295.54 | 5313.42 |
| 2 | 1000 | 1 | 110 | 100.00% | 5.47 | 182.13 | 353.14 | 465.31 |
| 2 | 1000 | 5 | 106 | 100.00% | 5.18 | 960.47 | 1333.72 | 2163.98 |
| 2 | 1000 | 10 | 112 | 100.00% | 5.26 | 1868.63 | 2352.51 | 2964.84 |
| 2 | 1000 | 20 | 121 | 100.00% | 5.38 | 3690.26 | 4101.46 | 4112.53 |
| 3 | 2000 | 1 | 68 | 100.00% | 3.39 | 294.03 | 650.96 | 1704.33 |
| 3 | 2000 | 5 | 85 | 100.00% | 3.99 | 1237.05 | 1663.36 | 2144.39 |
| 3 | 2000 | 10 | 80 | 100.00% | 3.56 | 2748.00 | 4102.92 | 4463.57 |
| 3 | 2000 | 20 | 81 | 100.00% | 3.41 | 5841.66 | 8352.47 | 8356.66 |
| 4 | 5000 | 1 | 60 | 100.00% | 2.92 | 341.68 | 650.83 | 838.99 |
| 4 | 5000 | 5 | 56 | 100.00% | 2.70 | 1813.34 | 2339.49 | 3073.57 |
| 4 | 5000 | 10 | 60 | 100.00% | 2.48 | 3900.04 | 5529.86 | 5533.53 |
| 4 | 5000 | 20 | 80 | 100.00% | 2.93 | 6722.73 | 7613.28 | 7620.42 |

异常说明：
- `tenant 0` 在并发 `20` 出现 `ReadTimeout`（25 次），该档成功率下降到 `59.02%`
- 其他租户在本轮口径下均为 `100%` 成功率