# 性能测试报告

## 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
```

### 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）

测试方法：
- `query` 固定为 `wireless mouse`
- 每次请求 `docs=386`
- 从 `1000` 个候选单词中随机采样，先随机句长 `15-40`，再生成每条 doc 句子
- 并发 `1/5/10/20`，每档 `20s`
- 结果文件：`perf_reports/2026-03-12/rerank_realistic/rerank_386docs.json`

复现命令：

```bash
.venv/bin/python scripts/perf_api_benchmark.py \
  --scenario rerank \
  --duration 20 \
  --concurrency-list 1,5,10,20 \
  --timeout 60 \
  --rerank-dynamic-docs \
  --rerank-doc-count 386 \
  --rerank-vocab-size 1000 \
  --rerank-sentence-min-words 15 \
  --rerank-sentence-max-words 40 \
  --rerank-query "wireless mouse" \
  --rerank-seed 20260312 \
  --reranker-base http://127.0.0.1:6007 \
  --output perf_reports/2026-03-12/rerank_realistic/rerank_386docs.json
```

| 并发 | 请求数 | 成功率 | 吞吐(RPS) | Avg(ms) | P95(ms) | Max(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 14 | 100.0% | 0.67 | 1498.64 | 1799.25 | 2160.96 |
| 5 | 15 | 100.0% | 0.62 | 8011.99 | 9725.61 | 9726.02 |
| 10 | 20 | 100.0% | 0.61 | 16217.12 | 18043.05 | 18050.04 |
| 20 | 20 | 100.0% | 0.60 | 33252.35 | 33456.74 | 33480.14 |

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

### 8.1 关键观察

- `backend_search`：吞吐约 `8 rps` 平台化，延迟随并发上升明显，属于重链路（检索+向量+重排）特征。
- `backend_suggest`：吞吐高且稳定（约 `200+ rps`），对并发更友好。
- `embed_text`：随并发提升吞吐持续增长，延迟平滑上升，扩展性较好。
- `rerank`：在 `docs=386` 的真实口径下，吞吐约 `0.6 rps`，延迟随并发显著抬升（并发20下 P95 约 `33.5s`），是当前最重瓶颈。

### 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/`
- Reranker 386 docs 口径补测：`perf_reports/2026-03-12/rerank_realistic/rerank_386docs.json`

## 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%` 成功率

## 13. Rerank 后端对比（qwen3_vllm vs DashScope 云服务）

目标：
- 使用同一套构造数据，对比两个 rerank 微服务在电商搜索重排场景下的速度差异
- 为后端选型提供直接依据

测试口径（两端一致）：
- query：固定 `wireless mouse`
- docs：每次请求固定 `386` 条
- 构造方式：从 `1000` 词池随机采样；每条 doc 句长随机 `15-40`
- `top_n`：`30`（模拟 `page+size`）
- 并发：`1 / 5 / 10 / 20`
- 每档时长：`20s`
- 每个后端跑 `2` 轮，以下表格为两轮均值

执行文件：
- vLLM：`perf_reports/2026-03-12/rerank_backend_compare/vllm_round1_topn30.json`
- vLLM：`perf_reports/2026-03-12/rerank_backend_compare/vllm_round2b_topn30.json`
- Cloud：`perf_reports/2026-03-12/rerank_backend_compare/cloud_round1_topn30.json`
- Cloud：`perf_reports/2026-03-12/rerank_backend_compare/cloud_round2_topn30.json`

### 13.1 两轮均值对比

| 并发 | vLLM RPS | Cloud RPS | vLLM P95(ms) | Cloud P95(ms) | vLLM Avg(ms) | Cloud Avg(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 0.625 | 0.220 | 1937.68 | 6371.03 | 1602.37 | 4752.53 |
| 5 | 0.585 | 1.040 | 9421.37 | 7372.85 | 8480.29 | 4543.84 |
| 10 | 0.595 | 1.820 | 18040.65 | 7637.43 | 16767.64 | 4820.35 |
| 20 | 0.590 | 3.530 | 33766.06 | 8445.39 | 33563.23 | 4890.59 |

### 13.2 结论

- 单并发（`c=1`）下，`qwen3_vllm` 更快（更低延迟、略高吞吐）。
- 从 `c=5` 开始，DashScope 云后端明显更快：
  - `c=5`：Cloud 吞吐约为 vLLM 的 `1.78x`
  - `c=10`：Cloud 吞吐约为 vLLM 的 `3.06x`
  - `c=20`：Cloud 吞吐约为 vLLM 的 `5.98x`
- 在“电商搜索在线重排（有并发）”场景下，当前实现建议优先选云后端。

说明：
- 本轮对比基于当前实现：`dashscope_rerank` 支持 `top_n`（本次取 `30`），`qwen3_vllm` 当前仍按全量 docs 评分。
- 若后续为本地模型实现 `top_n` 局部重排能力，需要重新对比后再最终定版。

## 14. Rerank 后端对比（top_n=386 重测）

目标：
- 在“返回条数不裁剪（`top_n=386`）”口径下，对比 `qwen3_vllm` 与 DashScope 云后端
- 补充 `Avg(ms)` 与整体平均耗时，便于容量规划

测试口径（两端一致）：
- query：固定 `wireless mouse`
- docs：每次请求固定 `386` 条
- 构造方式：从 `1000` 词池随机采样；每条 doc 句长随机 `15-40`
- `top_n`：`386`
- 并发：`1 / 5 / 10 / 20`
- 每档时长：`20s`

执行文件（有效）：
- vLLM：`perf_reports/2026-03-12/rerank_backend_compare/vllm_topn386_round1_valid.json`
- Cloud：`perf_reports/2026-03-12/rerank_backend_compare/cloud_topn386_round1_valid_fixedkey.json`

说明：
- `cloud_topn386_round1_valid.json` 为无效结果（上游 `401 invalid_api_key` 导致服务端返回 `500`），已在修正 key 后重跑得到 `cloud_topn386_round1_valid_fixedkey.json`。

### 14.1 分并发结果（含平均耗时）

| 并发 | vLLM RPS | Cloud RPS | vLLM Avg(ms) | Cloud Avg(ms) | vLLM P95(ms) | Cloud P95(ms) |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 0.61 | 0.15 | 1625.86 | 6749.21 | 2104.40 | 7800.55 |
| 5 | 0.61 | 0.60 | 8109.97 | 6343.14 | 9571.81 | 11059.64 |
| 10 | 0.65 | 1.60 | 15378.46 | 5418.25 | 15624.69 | 9865.85 |
| 20 | 0.66 | 2.48 | 30185.74 | 6090.37 | 30421.31 | 10685.54 |

### 14.2 整体平均耗时（加权）

| 后端 | 汇总RPS | 加权平均耗时(ms) | 成功率 |
|---|---:|---:|---:|
| vLLM | 0.64 | 15501.03 | 100.0% |
| Cloud | 1.30 | 5932.08 | 100.0% |

### 14.3 结论

- 单并发（`c=1`）下，`vLLM` 延迟优势明显。
- 在并发 `10/20` 下，Cloud 吞吐显著高于 `vLLM`，且平均耗时/尾延迟更低。
- 电商在线重排（存在并发）场景，当前更适合优先 Cloud；离线或低并发场景可保留 `vLLM`。