# 性能测试报告
  
  ## 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`。