From e269f8f99d153ef8ea067047f2a624a326e90c8a Mon Sep 17 00:00:00 2001 From: orangels Date: Wed, 6 May 2026 23:32:06 +0800 Subject: [PATCH] docs: add end-to-end testing guide for RPM and benchmarks --- docs/testing-guide.md | 208 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 docs/testing-guide.md diff --git a/docs/testing-guide.md b/docs/testing-guide.md new file mode 100644 index 0000000..6c23afa --- /dev/null +++ b/docs/testing-guide.md @@ -0,0 +1,208 @@ +# 端到端测试指南 + +## 前置条件 + +```bash +# 设置环境变量 +export ANTHROPIC_RELAY_TOKEN="your-token-here" +export OPENAI_RELAY_TOKEN="your-token-here" + +# 构建 +cargo build --release +``` + +确认 `config.yaml` 中 provider 配置正确(base_url、protocol、default_model)。 + +--- + +## 阶段 1:RPM 限流测试(Anthropic 协议) + +目标:验证中转站实际 RPM 限制,推断限流器类型。 + +### 1.1 连通性验证 + +```bash +cargo run -- check --provider anthropic --prompt "Reply with pong." + +# 流式模式(应输出 first_token_ms) +cargo run -- check --provider anthropic --stream --prompt "Reply with pong." +``` + +验证要点: +- 非流式:返回文本 + elapsed_ms +- 流式:额外输出 first_token_ms,且 first_token_ms < elapsed_ms + +### 1.2 Sustained 模式 — 持续发送 + +以目标 RPM 匀速发送,观察成功率。 + +```bash +# 基线:100 RPM,预期全部成功 +cargo run -- rpm --provider anthropic --mode sustained --rpm 100 --duration 60s --prompt "Hi" + +# 目标:200 RPM,观察是否有 429 +cargo run -- rpm --provider anthropic --mode sustained --rpm 200 --duration 60s --prompt "Hi" + +# 超限:250 RPM,预期出现限流 +cargo run -- rpm --provider anthropic --mode sustained --rpm 250 --duration 30s --prompt "Hi" +``` + +### 1.3 Burst 模式 — 瞬时并发 + +一次性发出所有请求,测试瞬时容量。 + +```bash +# 测试 burst 容量 +cargo run -- rpm --provider anthropic --mode burst --burst 50 --prompt "Hi" +cargo run -- rpm --provider anthropic --mode burst --burst 100 --prompt "Hi" +cargo run -- rpm --provider anthropic --mode burst --burst 200 --prompt "Hi" +``` + +### 1.4 Token Bucket 模式 — 令牌桶 + +先 burst 耗尽桶容量,再观察补充速率。 + +```bash +cargo run -- rpm --provider anthropic --mode token-bucket --rpm 200 --burst 50 --prompt "Hi" +``` + +关注:burst 阶段成功数 ≈ burst 值,refill 阶段恢复速率 ≈ rpm/60 req/s。 + +### 1.5 Sliding Window 模式 — 滑动窗口 + +测试请求在滑动时间窗口内的恢复行为。 + +```bash +cargo run -- rpm --provider anthropic --mode sliding-window --burst 200 --prompt "Hi" +cargo run -- rpm --provider anthropic --mode sliding-window --burst 200 --probe-seconds 120 --prompt "Hi" +``` + +关注:60s 后成功率是否明显回升(滑动窗口特征)。 + +### 1.6 Window Boundary 模式 — 固定窗口边界 + +在分钟边界前后发送请求,测试窗口重置行为。 + +```bash +cargo run -- rpm --provider anthropic --mode window-boundary --burst 100 --prompt "Hi" +``` + +关注:边界后成功率是否突然恢复(固定窗口特征)。 + +### 1.7 Diagnose 模式 — 综合诊断 + +组合多种探针,自动推断限流器类型。 + +```bash +cargo run -- rpm --provider anthropic --mode diagnose --rpm 200 --burst 50 --prompt "Hi" +``` + +输出中 `likely_limiter` 字段为推断结果: +- `TokenBucket` — 令牌桶(refill 探针稳定恢复) +- `FixedWindow` — 固定窗口(边界后突然恢复) +- `SlidingWindow` — 滑动窗口(60s 后逐步恢复) +- `Unknown` — 信号不足,无法判断 + +### 1.8 关注指标 + +| 指标 | 含义 | +|------|------| +| success / failure | 成功/失败请求数 | +| 429 错误计数 | 被限流的请求数 | +| latency_ms p50/p95/p99 | 请求总延迟百分位 | +| ttft_ms p50/p95/p99 | 首 token 延迟百分位(仅流式) | +| likely_limiter | 推断的限流器类型(仅 diagnose) | + +### 1.9 建议测试策略 + +1. 先用低 RPM(100)确认全部成功,建立基线 +2. 逐步提高 RPM(150 → 200 → 250),找到限流阈值 +3. 用 diagnose 模式推断限流器类型 +4. 根据推断结果,用对应的专项模式深入验证 + +--- + +## 阶段 2:数据集精度验证 + +目标:验证各模型在标准数据集上的准确率。 + +### 2.1 拉取数据集 + +```bash +cargo run -- dataset fetch +``` + +数据存储在 `data/benchmarks/` 目录。 + +### 2.2 AIME 2026(数学竞赛题) + +```bash +# 快速验证(10 题) +cargo run -- bench aime2026 --provider anthropic --limit 10 + +# 完整测试 +cargo run -- bench aime2026 --provider anthropic + +# 指定更强模型 +cargo run -- bench aime2026 --provider anthropic --model anthropic/claude-sonnet-4-20250514 +``` + +### 2.3 GPQA Diamond(研究生级别多选题) + +```bash +# 快速验证(10 题) +cargo run -- bench gpqa-diamond --provider anthropic --limit 10 + +# 完整测试 +cargo run -- bench gpqa-diamond --provider anthropic + +# 指定模型 +cargo run -- bench gpqa-diamond --provider anthropic --model anthropic/claude-sonnet-4-20250514 +``` + +### 2.4 精度参考基线 + +| 数据集 | claude-haiku-4.5 | claude-sonnet-4 | gpt-4o-mini | +|--------|-----------------|-----------------|-------------| +| AIME 2026 | ~15-25% | ~40-60% | ~20-30% | +| GPQA Diamond | ~30-40% | ~50-65% | ~35-45% | + +注:实际精度受 prompt 模板、temperature 等因素影响,以上为近似参考值。 + +### 2.5 报告输出 + +报告自动写入 `reports/` 目录,JSON 格式,包含: +- 总体准确率(accuracy) +- 每道题的对错明细(wrong_cases) +- 延迟百分位(latency_ms、ttft_ms) +- 错误统计(errors) + +--- + +## 流式模式补充说明 + +所有命令均支持 `--stream` 参数: + +```bash +# RPM 测试 + 流式 +cargo run -- rpm --provider anthropic --mode sustained --rpm 200 --duration 60s --stream --prompt "Hi" + +# Benchmark + 流式 +cargo run -- bench aime2026 --provider anthropic --stream +``` + +流式模式下报告额外包含 TTFT(Time To First Token)百分位数据。 + +如果 provider config 中已设置 `stream: true`,则默认使用流式,无需额外传参。CLI `--stream` 参数优先级高于 config。 + +--- + +## 故障排查 + +| 现象 | 可能原因 | +|------|----------| +| 连接超时 | base_url 不可达,检查网络/DNS | +| 401 Unauthorized | api_token 环境变量未设置或已过期 | +| 全部 429 | RPM 设置过高,降低后重试 | +| accuracy 为 0 | 模型输出格式不匹配 judge 规则,检查 wrong_cases | +| ttft_ms 全部 None | 未启用流式模式 |