reranker/rerank-cloud-perf-study/rerank_dashscope_perf_usage.md

下面是一份**简洁但完整的使用说明**，适合直接放在 README 或脚本注释里。
---
# rerank_dashscope_perf.py 使用说明
该脚本用于对 **DashScope `qwen3-rerank` 接口**进行并发性能测试，
测试接口：
```
POST https://dashscope.aliyuncs.com/compatible-api/v1/reranks
```
脚本支持：
* 并发压测
* 固定或动态生成 documents
* 自定义 doc 数量（例如 386）
* 输出详细 latency / RPS 统计
* 多并发梯度测试（如 1,5,10,20）
---
# 一、环境准备
### 1 安装依赖
脚本依赖 `httpx`：
```bash
pip install httpx
```
如果使用虚拟环境：
```bash
.venv/bin/pip install httpx
```
---
### 2 设置 DashScope API Key
```bash
export DASHSCOPE_API_KEY=你的key
```
也可以通过参数指定：
```bash
--api-key xxx
```
---
# 二、基本用法
最常见的压测方式：
```bash
python rerank_dashscope_perf.py \
  --duration 20 \
  --concurrency-list 1,5,10,20 \
  --timeout 90 \
  --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 \
  --rerank-top-n 386 \
  --output perf_result.json
```
含义：
| 参数                  | 说明            |
| ------------------- | ------------- |
| duration            | 每个并发测试持续时间（秒） |
| concurrency-list    | 并发列表          |
| timeout             | 单请求超时时间       |
| rerank-dynamic-docs | 启用动态 doc 生成   |
| rerank-doc-count    | 每个请求 doc 数量   |
| rerank-top-n        | 返回 top_n      |
| output              | 保存结果 JSON     |
---
# 三、测试模式
脚本有两种请求模式：
---
# 1 静态请求模式（默认）
如果**不使用 `--rerank-dynamic-docs`**，请求 payload 固定为：
```json
{
  "model": "qwen3-rerank",
  "documents": [
    "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
    "量子计算是计算科学的一个前沿领域",
    "预训练语言模型的发展给文本排序模型带来了新的进展"
  ],
  "query": "什么是文本排序模型",
  "top_n": 2
}
```
适合：
* 验证接口
* 小规模测试
---
# 2 动态 documents 模式（推荐）
启用参数：
```
--rerank-dynamic-docs
```
脚本会：
* 每个请求生成 **N 条 documents**
* 每条 doc 是 **随机词拼接句子**
* 每个请求 **内容不同**
示例 doc：
```
alce bafi kolo dede hobe anma cigi lofi asbe erko kaci molo fadi helo
mace biro aldi kolo gace hoin doka lale cebo fafa ineri kasi hobe lomo
gifi beme koha laci anfi celi dore ioce kobo hila mefi arce enbo hega
```
优点：
* 不依赖真实语料
* 更接近真实 token 分布
* 压测稳定
---
# 四、386 documents 压测示例
与你的测试方式一致：
```bash
python rerank_dashscope_perf.py \
  --duration 20 \
  --concurrency-list 1,5,10,20 \
  --timeout 90 \
  --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 \
  --rerank-top-n 386
```
每个请求：
```
query: wireless mouse
documents: 386条
每条doc长度: 15~40词
```
---
# 五、输出结果示例
终端输出：
```
[1/4] running rerank_dashscope @ concurrency=1 ...
=== Scenario: rerank_dashscope @ concurrency=1 ===
requests=84 success=84 fail=0 success_rate=100.0% rps=4.2
latency(ms): avg=230 p50=220 p90=260 p95=280 p99=310 max=340
status_codes: {200: 84}
```
字段说明：
| 指标              | 说明   |
| --------------- | ---- |
| requests        | 总请求数 |
| success         | 成功请求 |
| fail            | 失败请求 |
| success_rate    | 成功率  |
| rps             | 吞吐量  |
| p50/p90/p95/p99 | 延迟分位 |
| max             | 最大延迟 |
---
# 六、JSON 报告
如果指定：
```
--output perf_result.json
```
会生成报告：
```json
{
  "results": [
    {
      "concurrency": 1,
      "throughput_rps": 4.2,
      "latency_ms": {
        "avg": 230,
        "p95": 280
      }
    }
  ]
}
```
适合：
* 性能对比
* 画图
* 压测记录
---
# 七、常见参数
| 参数                          | 默认值       | 说明      |
| --------------------------- | --------- | ------- |
| --duration                  | 20        | 单并发测试时间 |
| --concurrency-list          | 1,5,10,20 | 并发梯度    |
| --timeout                   | 90        | 请求超时    |
| --rerank-doc-count          | 386       | doc数量   |
| --rerank-vocab-size         | 1000      | 词表大小    |
| --rerank-sentence-min-words | 15        | doc最小长度 |
| --rerank-sentence-max-words | 40        | doc最大长度 |
| --rerank-top-n              | 386       | 返回top_n |
---
# 八、推荐压测方式
推荐测试：
```
docs = 386
query = wireless mouse
concurrency = 1,5,10,20
duration = 20~60s
```
即可得到：
* latency 曲线
* RPS
* 并发极限