# lq_token_test 使用文档 `lq_token_test` 是一个 Rust 命令行工具,用来测试大模型中转站的协议兼容性、RPM 限流表现、并发表现,以及基于官方数据集的简单准确率表现。 当前支持: - OpenAI-compatible 协议 - Anthropic-compatible 协议 - YAML 配置文件 - AIME 2026 数据集 - GPQA-Diamond 数据集 - benchmark 准确率统计 - RPM 限流模式测试 - JSON 报告输出 ## 1. 构建和基础检查 ```bash cargo fmt --check cargo test cargo clippy --all-targets -- -D warnings cargo run -- --help ``` 编译 release 版本: ```bash cargo build --release ``` release 二进制在: ```text target/release/lq_token_test ``` ## 2. 配置文件 复制示例配置: ```bash cp config.example.yaml config.yaml ``` 示例: ```yaml default_provider: openai providers: openai: protocol: openai base_url: "https://relay.example.com/v1" api_token: "${OPENAI_RELAY_TOKEN}" default_model: "gpt-4o-mini" anthropic: protocol: anthropic base_url: "https://relay.example.com" api_token: "${ANTHROPIC_RELAY_TOKEN}" default_model: "claude-3-5-sonnet-latest" benchmarks: data_dir: "data/benchmarks" aime2026: source: "huggingface:MathArena/aime_2026" split: "train" gpqa_diamond: source: "huggingface:Idavidrein/gpqa" split: "gpqa_diamond" ``` 设置 token: ```bash export OPENAI_RELAY_TOKEN="..." export ANTHROPIC_RELAY_TOKEN="..." ``` 注意:工具只会解析当前使用的 provider token。比如只运行 `--provider anthropic` 时,不需要设置 `OPENAI_RELAY_TOKEN`。 ## 3. 协议连通性测试 OpenAI-compatible: ```bash cargo run -- check \ --config config.yaml \ --provider openai \ --model gpt-4o-mini \ --prompt "Reply with the word ready." ``` Anthropic-compatible: ```bash cargo run -- check \ --config config.yaml \ --provider anthropic \ --model claude-3-5-sonnet-latest \ --prompt "Reply with the word ready." ``` 如果不传 `--model`,会使用配置里的 `default_model`。 ## 4. 下载数据集 AIME 2026: ```bash cargo run -- dataset fetch aime2026 ``` 下载后会生成: ```text data/benchmarks/aime2026/aime2026.jsonl data/benchmarks/aime2026/metadata.yaml ``` GPQA-Diamond: ```bash cargo run -- dataset fetch gpqa-diamond ``` 如果 Hugging Face 要求认证,先设置: ```bash export HF_TOKEN="..." ``` 数据集目录 `data/benchmarks/` 不会提交到 git。 ## 5. 数据集 benchmark AIME 2026 小样本: ```bash cargo run -- bench aime2026 \ --config config.yaml \ --provider anthropic \ --limit 3 \ --concurrency 1 ``` AIME 2026 完整测试: ```bash cargo run -- bench aime2026 \ --config config.yaml \ --provider anthropic \ --concurrency 4 ``` GPQA-Diamond 小样本: ```bash cargo run -- bench gpqa-diamond \ --config config.yaml \ --provider anthropic \ --limit 5 \ --concurrency 1 ``` GPQA-Diamond 完整测试: ```bash cargo run -- bench gpqa-diamond \ --config config.yaml \ --provider anthropic \ --concurrency 4 ``` benchmark 会输出: - accuracy - success / failed - latency p50 / p95 / p99 - errors - wrong cases - report 路径 ## 6. RPM 测试模式 当前支持 6 种 RPM 模式: ```text sustained burst token-bucket sliding-window window-boundary diagnose ``` ### 6.1 sustained:稳定 RPM 压测 适合测试服务是否能长期稳定承受目标 RPM。 ```bash cargo run -- rpm \ --config config.yaml \ --mode sustained \ --provider anthropic \ --rpm 120 \ --duration 60s \ --prompt "hello" ``` 逻辑: ```text 每 60 / rpm 秒启动一个请求 请求可以重叠 持续 duration ``` ### 6.2 burst:瞬时突发测试 适合测试瞬时并发、突发容量、初始桶容量。 ```bash cargo run -- rpm \ --config config.yaml \ --mode burst \ --provider anthropic \ --burst 120 \ --prompt "hello" ``` 逻辑: ```text t=0 同时发送 burst 个请求 ``` ### 6.3 token-bucket:令牌桶测试 适合测试桶容量和 token refill 速率。 ```bash cargo run -- rpm \ --config config.yaml \ --mode token-bucket \ --provider anthropic \ --rpm 120 \ --burst 120 \ --probe-seconds 30 \ --prompt "hello" ``` 逻辑: ```text 先 burst 打空桶 再按 rpm 推导的 refill 速率发送探针请求 ``` 例如: ```text rpm = 120 refill rate = 2 req/s ``` ### 6.4 sliding-window:滑动窗口测试 适合测试滚动 60 秒窗口的恢复行为。 ```bash cargo run -- rpm \ --config config.yaml \ --mode sliding-window \ --provider anthropic \ --rpm 120 \ --burst 120 \ --probe-seconds 90 \ --prompt "hello" ``` 逻辑: ```text t=0 burst 之后每秒发送探针 观察是否接近 60 秒后恢复 ``` ### 6.5 window-boundary:固定窗口边界测试 适合测试 fixed window 是否在自然分钟边界重置额度。 ```bash cargo run -- rpm \ --config config.yaml \ --mode window-boundary \ --provider anthropic \ --rpm 120 \ --burst 120 \ --window-offset-ms 500 \ --prompt "hello" ``` 逻辑: ```text 在分钟边界前发送一批请求 在分钟边界后发送一批请求 观察边界后是否明显恢复 ``` ### 6.6 diagnose:未知模式诊断 如果不知道后端是什么限流模式,可以用 diagnose。 ```bash cargo run -- rpm \ --config config.yaml \ --mode diagnose \ --provider anthropic \ --rpm 120 \ --burst 120 \ --probe-seconds 90 \ --prompt "hello" ``` 报告中会给出 best-effort 推断: ```text token_bucket fixed_window sliding_window unknown ``` 注意:真实大模型服务通常同时包含 RPM、TPM、并发数、队列长度、账号级限流、模型级限流、区域级限流等多种机制。诊断结果是强信号,不是绝对证明。 ## 7. 报告文件 benchmark 和 rpm 都会生成 JSON 报告: ```text reports/*.json ``` 查看最新报告: ```bash ls -lt reports | head ``` 格式化查看: ```bash jq . reports/<报告文件>.json ``` benchmark report 包含: - benchmark - provider - model - dataset - run 参数 - accuracy - success / failed - latency p50 / p95 / p99 - errors - wrong_cases RPM report 包含: - mode - provider - model - target_rpm - actual_rpm - request counts - latency p50 / p95 / p99 - errors - mode_detail - diagnose inference RPM report 不会保存原始 prompt,也不会保存 token。 ## 8. 推荐测试顺序 第一次测试建议: ```text 1. check 单次请求 2. sustained 低 RPM 3. burst 小突发 4. 数据集 limit 小样本 5. 提高 concurrency 6. token-bucket / sliding-window / window-boundary 7. diagnose 8. 完整 benchmark ``` 示例: ```bash cargo run -- check --provider anthropic --prompt "hello" cargo run -- rpm --mode sustained --provider anthropic --rpm 10 --duration 30s --prompt "hello" cargo run -- rpm --mode burst --provider anthropic --burst 10 --prompt "hello" cargo run -- bench aime2026 --provider anthropic --limit 3 --concurrency 1 ``` ## 9. 和官方结果对比 使用 benchmark 结果对比官方宣传分数时,需要尽量对齐: - 数据集来源 - 数据集版本 - prompt 模板 - temperature - max_tokens - 样本数量 - 判分逻辑 - 是否允许工具调用 - 是否多次采样 当前工具的结果更适合作为: ```text 中转站 relay benchmark signal ``` 不要把单次结果直接当作官方 benchmark 的严格复现。