下面是一份简洁但完整的使用说明，适合直接放在 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：

pip install httpx

如果使用虚拟环境：

.venv/bin/pip install httpx

---

2 设置 DashScope API Key

export DASHSCOPE_API_KEY=你的key

也可以通过参数指定：

--api-key xxx

---

二、基本用法

最常见的压测方式：

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 固定为：

{
  "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 压测示例

与你的测试方式一致：

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

会生成报告：

{
  "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
• 并发极限