原文内容

AI 辅助构建校园大模型 API 压测与观测脚本

面向 USTC Token Plan / 词元计划成长营的实践案例。
关键词：OpenAI-compatible API、模型发现、JSONL 日志、429 限流、可观测性、样例报告。

这个案例解决什么问题

事情是这样的。

我一开始想解决的，不是「怎么调用一次大模型 API」。

这个问题其实很快就能解决。配置 base_url、API Key、模型名，然后发一个请求，能返回就说明链路通了。

但真实使用里更麻烦的问题在后面。

同一个 Key 到底能访问哪些模型？

请求稍微多一点，会不会 429？

长输出任务会不会超时？

平台统计页面短时间没变化时，任务到底是卡住了，还是请求还没完成？

如果只看终端输出，过几天还能不能复盘当时到底发生了什么？

我觉得这些问题，才是真正影响后续开发体验的东西。

所以我在 AI 辅助下做了一个小型的校园大模型 API 压测与观测脚本。它的目标不是把资源跑满，也不是制造用量，而是做容量观察、稳定性验证、接口可用性评估和可观测性建设。

说得更直白一点，就是把「感觉这个接口稳不稳」变成「我能用日志和指标说清楚它在什么参数下表现怎么样」。

我的设计思路

1. 先发现模型，再发请求

脚本启动后先调用 /v1/models，读取当前 Key 实际可访问的模型列表。

这个动作很小，但很关键。

因为文档里的模型名、别人分享的模型名、自己印象里的模型名，和当前账号实际能调用的模型，不一定完全一致。先发现模型，再进入测试，可以少掉很多无效排查。

如果自动发现失败，脚本不会假装一切正常，而是应该明确记录 model_discovery_failed，让后续排查知道问题发生在模型发现阶段。

2. 分阶段试跑，不一步到位

我把一次观测拆成三个阶段。

我自己更喜欢这种慢一点的方式。

先证明脚本和配置没有问题，再逐步暴露系统边界。这样一旦出问题，比较容易判断它是配置错误、限流、超时，还是脚本本身的 bug。

3. 把 429 当成边界信号

以前我看到 429，第一反应就是，坏了，失败了。

后来做这个脚本时我发现，429 其实很有价值。

它告诉你，当前这组参数已经碰到了请求速率边界。

这时候最重要的不是立刻重跑，而是记录上下文：

• 当时的模型是什么；
• 并发是多少；
• QPS 是多少；
• 重试了几次；
• 退避时间是多少；
• 是所有模型都 429，还是只有某个模型明显触发。

这些信息记录下来，下一轮就可以有依据地降低 QPS、减少并发、增加退避时间，或者把长任务和短任务拆开配置。

4. 用 JSONL 留下可复盘证据

脚本会把每个请求写成一行 JSONL。

成功也记，失败也记。

单行只保留工程指标，不把请求正文和模型完整输出混进运行日志。

示例：

{"ts":"2026-05-XXT10:00:01+08:00","run_id":"demo_run_001","stage":"smoke","model":"model-a","request_id":"req_0001","status":"ok","http_status":200,"latency_ms":1842,"prompt_tokens":128,"completion_tokens":220,"total_tokens":348,"retry_count":0}
{"ts":"2026-05-XXT10:03:12+08:00","run_id":"demo_run_001","stage":"medium","model":"model-a","request_id":"req_0017","status":"rate_limited","http_status":429,"latency_ms":318,"prompt_tokens":0,"completion_tokens":0,"total_tokens":0,"error_type":"rate_limit","retry_count":1}
{"ts":"2026-05-XXT10:08:41+08:00","run_id":"demo_run_001","stage":"long_task","model":"model-c","request_id":"req_0042","status":"timeout","http_status":null,"latency_ms":180000,"prompt_tokens":0,"completion_tokens":0,"total_tokens":0,"error_type":"timeout","retry_count":2}

这种格式的好处是，后面无论用脚本统计，还是让 AI 帮忙整理报告，都比较方便。

AI 在这个过程中帮了我什么

AI 在这里不是替我决定压测目标。

它更像一个工程副驾驶。

我把一个很模糊的想法丢给它，说我想知道校园大模型 API 到底稳不稳。它帮我把这个问题拆成几个模块：

• 模型发现；
• 请求调度；
• 错误处理；
• JSONL 日志；
• 指标汇总；
• 报告生成；
• 公开分享前的字段整理。

然后它继续帮我补脚手架。

比如提醒我不要把 API Key 写进配置文件，而是从环境变量读取。

比如每个请求不要只打印到终端，而是写入结构化日志。

比如报告里不要只写平均延迟，最好看 p50、p95、p99。

再比如看到 429、timeout 这类错误时，不要只写「失败」，而是把错误类型和参数一起记录下来。

这些建议单独看都不复杂。

但组合起来以后，这个事情就从一次随手测试，变成了一个可以复盘的小工具。

目录内容

这个案例里，我放了几个可以直接参考的示例文件。

api-pressure-observability/
├── README.md
├── examples/
│   ├── config.example.json
│   └── pressure-run.sample.jsonl
├── reports/
│   └── sample-report.md
└── scripts/
    └── pressure_mvp.example.py

如何运行一个小规模试跑

先设置 API Key 环境变量。

PowerShell 示例：

$env:CAMPUS_LLM_API_KEY = "你的 API Key"

然后运行一个非常小的 smoke 测试：

python .\scripts\pressure_mvp.example.py `
  --base-url "https://example-campus-api.edu.cn/v1" `
  --api-key-env CAMPUS_LLM_API_KEY `
  --models auto `
  --stage smoke `
  --requests 4 `
  --max-tokens 512 `
  --output .\runs\pressure-run.local.jsonl

这里的 base-url 是占位示例。真实使用时，请换成你有权限访问的 OpenAI-compatible API 地址。

我建议第一次只跑很小的请求数，确认下面几件事：

• /v1/models 能正常返回；
• 聊天补全接口能返回；
• JSONL 文件能持续写入；
• usage 字段能正常记录；
• 日志里只保留运行指标，不混入请求正文和模型完整输出。

确认这些都没问题以后，再逐步增加请求数、输出长度或观测阶段。

一份样例报告长什么样

我在 reports/sample-report.md 里放了一份样例报告。

它不是为了展示真实数据，而是展示报告口径。

我比较建议报告至少包含这些部分：

• 一句话结论；
• 测试范围；
• 核心指标；
• 异常分析；
• 下一轮建议。

尤其是结论要克制。

不要写「接口已经完全稳定，可以放心大规模使用」。

更合理的写法是：

在本轮小规模试跑中，模型发现和聊天补全接口可用。中等验证阶段出现过 429，说明当前参数已经碰到请求速率边界。下一轮建议降低 QPS 或增加退避时间，再继续观察。

这个表述没那么炸裂，但更诚实。

我从这个案例里学到的几件事

1. API 可用性不是一次请求能证明的

一次请求成功，只说明链路通了。

多请求、长输出、限流、重试、超时，这些才是更接近真实使用的场景。

2. 结构化日志比终端输出可靠

终端输出适合当场看。

JSONL 适合事后复盘。

这两个东西最好都要有。

3. 429 不只是失败

429 是边界信号。

它提醒我们当前请求策略需要调整，而不是提醒我们硬顶。

4. 公开分享前先整理字段

成长营投稿是分享经验，不是暴露现场。

运行日志里真正有价值的是状态码、延迟、token usage、错误类型和重试次数。公开示例只保留这些字段，方便别人复现方法，而不是复现我的现场环境。

5. AI 最适合补齐工程细节

AI 不应该替人决定测试目标。

但它很适合帮你拆模块、补脚手架、设计日志字段、整理报告、检查边界。

这件事听起来不酷，但很有用。