Uni LLM Bench：自托管LLM API基准测试平台实战指南

1. 为什么要自己做一套 LLM API 基准测试平台先说个真实场景。我们团队做多租户平台上游接了好几家大模型 API有官方的也有走聚合网关的。上个月某个渠道换了底层模型线上监控没做细等业务方反馈回答变慢了、还老报错的时候我们才去手动 curl 了几个接口对比延迟。结果呢高峰期测出来的数据和凌晨测的完全是两回事根本没有可比性。那一刻我就确定了不能再用手动点两下 Postman、看个返回时间这种土办法来评估 LLM API 了得有一套自己能随时跑、数据能留存、报告能横向对比的基准测试平台。这就是我做 Uni LLM Bench 的起点。它的定位很明确一个自托管的、轻量化的、专门针对 LLM API 做基准测试的工具。所谓自托管就是整个服务跑在你自己控制的服务器上不依赖任何第三方 SaaS测试数据和 API 密钥都留在内网所谓轻量化就是不要一上来就上 Kubernetes、上消息队列、上监控全家桶一台普通机器甚至开发机就能跑起来。它解决的问题也很具体当你需要在大模型 API 之间做选型、需要验证渠道稳定性、需要在新模型上线前做容量评估时给你一套可复现、可量化、可长期跟踪的测试方案。这套东西适合谁用我觉得有三类人。第一类是正在做模型选型的后端开发手上握着 DeepSeek、智谱、通义、以及各种 OpenAI 兼容接口的 key想知道同样一个任务谁快谁稳谁便宜第二类是 LLM 应用平台的运维或 SRE需要定期巡检线上 API 的健康状态第三类是在研发内部评估私有化部署模型的同学自托管正好能把测试请求限制在内网不会把内部数据送到外部服务。接下来的篇幅我会从设计思路、核心指标、代码实现到部署实操完整拆一遍也会顺手把我在开发过程中踩过的坑都讲清楚。2. 整体设计思路与方案选型2.1 自托管到底省了什么很多团队评估 API 性能时用的还是在线压测网站或者直接用 API 厂商自己的控制台看延迟。这两种方式我都不太推荐作为基准数据来源原因有三个。第一在线压测工具的节点在公网测出来的延迟包含了公网传输和跨运营商绕路跟你的业务服务器实际访问 API 的路径完全不是一回事数据失真第二测试请求会经过第三方平台转发请求内容如果含有业务数据等于多了一次数据暴露面第三厂商控制台给的指标往往做了平滑和聚合粒度不够细你也拿不到底层日志。自托管直接把这三个问题都绕过去了。部署在你自己的服务器上走的就是你业务的真实网络路径测出来的数据对你有真实参考意义请求直接发给 API 网关不经过任何中间人原始数据、日志、统计口径全在自己手里想怎么算就怎么算。所以我从一开始就确定这个平台必须以自托管为第一原则不做任何公网中转。2.2 轻量化把够用做成设计标准说实话市面上不是没有开源的 API 压测平台但大多重量级。有的基于 Kubernetes 部署有的要依赖 Redis、ClickHouse 存时序数据有的还带一套完整的前端工作台。功能确实全但对于我就是想快速对比几个模型的延迟和成功率这个需求来说运维成本直接劝退。Uni LLM Bench 走了另一条路单体 Python 服务 轻量前端 SQLite 存储所有组件用 Docker Compose 编排整个部署下来不超过 15 分钟。我把它的轻拆成三个层面部署环境轻不要求 GPU不要求大内存512MB 内存的机器就能跑控制面和执行器依赖轻核心就 FastAPI、aiohttp、SQLite 三个主力组件没有外部消息队列使用轻所有测试场景用一份 YAML 配置描述改配置比改代码快得多。有人会问SQLite 够用吗并发写入会不会锁这里我说下实际的量级估算。一次基准测试任务假设并发 32、总请求数 500 条数据落库也就几千行。SQLite 在这种写入量下完全没压力而且单文件备份非常方便。只有当你把测试规模拉到每天几万条以上、还要跑复杂的统计查询时才值得考虑换 PostgreSQL但那是另一个故事了不在轻量化这个范畴里讨论。2.3 技术选型为什么是 FastAPI 加 aiohttp技术栈的选择逻辑也很直接。控制面我选 FastAPI理由很朴素自带 OpenAPI 文档联调方便异步支持好写个 Web 界面后端和 REST API 都很快。执行器部分我选 aiohttp 而不是 requests因为基准测试的核心动作就是高并发发 HTTP 请求requests 是同步库要用线程池模拟并发线程一多不仅内存开销大上下文切换还影响测试数据本身的真实性。aiohttp 是纯异步的配合 asyncio.Semaphore 可以精确控制并发数在单进程内就能撑起几百上千的并发连接而且底层的连接复用机制对压测场景非常友好。还有一个小细节aiohttp 支持自定义 trace_config可以在请求生命周期的每个阶段插入钩子函数比如连接建立完成、请求头发送完毕、响应头到达、响应完全读尽这些时间点都能拿到回调。TTFT首 Token 时间、连接耗时、下载耗时就靠这些钩子精确测量而不是简单地用总耗时减去请求构造时间这种粗糙办法。这个能力对做 LLM 基准测试来说几乎是量身定做的requests 没有对应的等价机制。3. 核心指标与测试维度拆解3.1 延迟类指标延迟到底该看哪几个数做 LLM API 基准测试最容易犯的错误就是只盯着端到端延迟。端到端延迟当然重要但它是个综合结果没法告诉你瓶颈在哪。我的做法是把延迟拆成多个阶段来分别统计每个阶段对应不同的用户体验问题。第一个是 TTFT也就是从发送请求到收到第一个 token 的时间。这个指标最直接影响用户感知TTFT 超过 3 秒用户就会觉得卡住了。对流式接口来说TTFT 就是首包字节到达时间对非流式接口我把它定义为响应头抵达的时间。第二个是 Token 间延迟也就是两个 token 之间的间隔时间。这个指标反映模型吐字是否均匀如果出现某个 token 间隔突然飙到几秒说明模型推理或网络传输出现了抖动。第三个是端到端总时延即最后一个 token 到达的时间这是用户看到完整回答所需的时间。单次测试的数据没有任何统计意义一次网络抖动就能让延迟翻倍。所以 Uni LLM Bench 里我对每个测试场景都会跑多轮然后输出百分位数P50 表示典型水平P90 表示大多数情况下的上限P95 和 P99 则专门用来暴露尾部延迟。拿 P99 来说如果一个 API 的 P99 延迟是 P50 的 5 倍以上那它在高并发下一定有稳定性问题即使平均值看起来不错也不能选它做生产渠道。3.2 吞吐与稳定性指标别只看延迟还得看容量延迟是单次请求的体验吞吐是系统在单位时间内能处理的请求量两者要放在一起看才有意义。基准测试里我主要统计三个吞吐指标TPS每秒事务数单位时间内成功完成的请求数量反映 API 网关或模型的并发处理能力Token 吞吐tok/s整轮测试中每秒产生并传输的 token 总数这个指标直接影响用户体感也直接关联计费成本并发连接数单纯看 TPS 不看并发数会误导人所以我会记录测试时的并发配置并做阶梯加压观察 TPS 是否随并发线性增长、在哪一点开始回落。稳定性指标主要看成功率。这里有个细节要提醒一下HTTP 状态码 200 不代表请求真的成功了。很多 LLM 网关在业务层报错时也会返回 200比如内容安全拦截返回 400 但包裹在 200 响应体里、JSON 解析失败、模型返回了空 choices 数组等。所以不能只按 HTTP 状态码判断成败得加上一层业务校验校验响应体里 choices 字段是否存在且非空。这个我在实现里单独写了一组校验规则后面会细讲。3.3 测试场景与参数固定策略做基准测试必须保证对照组只改变一个变量参数不固定的话数据就废了。最典型的就是 temperature。它控制输出的随机性同样的问题temperature 设为 0.7 和 0.0延迟和 token 数都可能天差地别。这里有个原理层面的背景可以补充一下temperature 本质上是调整模型输出概率分布的熵温度越高低概率 token 被采样的机会越大模型在不同分支间犹豫的时间可能变长输出长度也可能变化温度越低输出越趋近于贪心解码长度相对稳定。所以测试前我会把生产配置里最常用的一组采样参数锁死写入 YAML 配置确保每次测试的随机性可控。另外我做了四类测试场景单轮问答适合快速对比不同模型的延迟水平Prompt 使用固定模板多轮对话模拟真实业务带上上下文历史测试长上下文下的性能衰减流式输出验证 SSEServer-Sent Events场景下的 TTFT 和 Token 间延迟混合负载同时混入不同复杂度的 Prompt模拟真实生产流量用于容量评估。4. 关键模块实现与代码解读4.1 配置驱动的测试定义整个平台的使用入口是 YAML 配置文件我不太想让用户每次跑测试都要写 Python 代码。配置主要分成几个块API 连接信息、模型参数、测试场景、并发策略和统计导出设置。一个典型的配置长这样provider: name: deepseek_test base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY # 统一的采样参数由这里的 generation 模板控制 generation: temperature: 0 max_tokens: 512 concurrency: start: 1 peak: 32 step: 4 ramp_interval_sec: 10 scenarios: - name: single_turn_short type: chat stream: false rounds: 50 prompt: 请用一句话解释什么是数据库索引。 - name: multi_turn_with_history type: chat stream: true rounds: 30 conversation_history: 5有一点特别重要api_key 不要直接写在 YAML 文件里而是用环境变量名替代读取时再从环境变量注入。这样配置文件可以进 Git 仓库做版本管理密钥只存在部署环境里哪怕配置文件泄露也不会直接暴露凭据。4.2 并发控制与请求调度并发控制的实现核心是 asyncio.Semaphore我封装了一个简单的压测执行器。它的工作流程是先按配置里的并发档位逐渐加压每个档位运行若干轮收集该并发水平下的指标再进入下一个档位。这样能画出一条并发-延迟-吞吐的曲线比一把梭直接打满并发更有价值。压测时还有个防护机制全局限流器。它限制了每秒最多发起的请求数防止测试本身对被测 API 造成攻击式流量也防止触发对方防火墙的误判。限流值我一般默认设置为并发数的 2 倍因为单次流式请求可能持续几十秒总量不一定大但瞬间握手请求可能很多。这里有个很容易踩的坑连接池大小。aiohttp 默认的 TCPConnector 连接数限制是 100如果你说并发 200实际上到 100 就被卡住了后面请求排队测试数据全部失真。所以初始化连接池时必须显式设置 limit 参数而且要大于最大并发数。我自己线上配置的并发上限是 64连接池限制给到 128留一倍余量。4.3 数据采集与统计口径数据采集是整个平台最核心的环节口径不对后面全是白算。我用 aiohttp 的 trace_config 挂载了四个钩子连接建立、请求发送、响应头到达、响应完成。在每个钩子里记录时间戳最后汇总成下面的时间线DNS 解析耗时如果 API 域名需要解析连接建立耗时request 序列化与发送耗时服务端处理耗时从请求发完到收到第一个字节流式读取总耗时。拿 TTFT 来说我定的口径是从开始发起请求到第一个响应字节从 socket 读到的时间差这个可以直观反映用户等待首个 token 的体验。统计时还要处理异常样本。比如某次请求因为网络闪断直接抛了 ConnectionResetError这个样本的端到端耗时是无效的不能算进延迟百分位只能算进成功率分母。所以我的做法是为每个样本标记 is_success 和 error_type 两个字段统计延迟时先按错误类型过滤统计成功率时再把它们纳进去。这样每个指标的口径都是清晰的。4.4 结果导出与可复现性测试结果我会同时落两份一份进 SQLite 便于查询历史记录和趋势分析另一份导出为 JSON/CSV方便拉到数据分析工具里做更精细的可视化。每轮测试我都生成一个 run_id 作为唯一标识由时间戳加随机后缀组成同一份配置跑的测试可以通过 run_id 关联方便做 A/B 对比。为了让结果可复现配置里还会自动记录环境信息Python 版本、平台版本、执行机所在网络出口 IP、被测 API 的 base_url、模型名、采样参数。这些元数据在评估一个历史测试是否还有效时非常有用比如你发现某天的 P95 变差了一看元数据才发现那天被测模型供应商刚好把流量切到了另一线路。没有这些信息很难回溯归因。5. 部署与实操流程5.1 五分钟内从零跑起来部署我提供了两种方式。最推荐的是 Docker Compose整个编排只有一个服务镜像已经推到公共仓库拉下来直接跑。git clone https://github.com/yourname/uni-llm-bench.git cd uni-llm-bench # 参考 .env.example 创建 .env填入需要测试的 API Key cp .env.example .env docker compose up -d起来之后控制台监听在 8080 端口访问http://your-server:8080就能看到简洁的任务创建页面。我没有做登录注册因为定位是内网工具安全靠部署环境本身的网络策略保证如果你要暴露到公网建议在前面挂一层企业网关做鉴权这个后面我会专门提。不习惯 Docker 的话也可以直接用 Python 跑。要求是 Python 3.10装依赖后执行uvicorn app.main:app --host 0.0.0.0 --port 8080就启动了。依赖只有一行pip install -r requirements.txt没有系统级依赖虚拟环境里装很干净。5.2 用 DeepSeek 和 OpenAI 兼容接口做一次实测我拿 DeepSeek 的接口做一次完整演示。DeepSeek 的 API 兼容 OpenAI 格式base_url 指向https://api.deepseek.com/v1鉴权方式也是 Bearer Token。有一点容易踩坑模型名必须精确匹配DeepSeek 有deepseek-chat和deepseek-reasoner等型号不同时段的可用型号可能有调整如果你填了不存在的模型名接口会直接返回 400 错误提示 The supported api model names are xxx而且有些网关返回的提示里列出的模型列表可能跟你预期的不一致。我的建议是先在命令行用一分钟确认型号可用再写进配置curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: ping}], max_tokens: 5 }拿到 200 响应后再把模型名写进 Uni LLM Bench 的配置里。然后跑一个快速测试python -m uni_llm_bench run --config examples/deepseek_small.yaml --report json执行完毕后终端会打印摘要同时生成完整报告。我实测过一个小规模场景并发 8、30 轮、单轮短问答耗时大约 2 分钟结果里 TTFT P50 在某时段是 0.8 秒P95 到了 2.3 秒这说明高峰期尾部延迟偏高如果是线上用户交互场景建议开启流式输出对体验改善非常明显。5.3 报告解读数字背后的含义拿到报告后重点别只看平均值先看三列成功率、P95 延迟、Token 吞吐。成功率低于 99% 的渠道如果没有明确成本优势直接淘汰P95 延迟能反映高峰期是否满足体验承诺比如你给前端的 SLO 是 P95 小于 2 秒那测试里的 P95 必须低于 1.5 秒才留有余量Token 吞吐决定了同样的预算下能服务多少用户吞吐越低单个请求消耗的时间越长资源成本越高。还有个小技巧跑基准测试不要只在白天跑建议在凌晨和白天各跑一轮。很多 API 服务商的负载有明显的时间特征晚上的 P95 可能只有白天的三分之一。对选型来说白天高峰期数据更值得参考因为是用户真实体验的时段。6. 常见问题排查与避坑指南6.1 鉴权与配额类错误的快速识别我在开发和使用过程中把 LLM API 调用中最常遇到的错误整理成了一张排查表很多问题单看状态码就能定位。错误现象常见原因排查方向400 模型名不支持填入了不存在的模型名比如把deepseek-chat写成deepseek-v4用命令行直接调一次接口确认可用模型列表400 内容风险拦截Prompt 命中了服务商的内容安全策略检查提示词文本中是否有敏感内容换一个中性 Prompt401/403 鉴权失败API Key 错误、过期、或没有对应模型权限检查环境变量是否注入回服务商控制台验证 Key 状态429 配额耗尽触发了每分钟或每 5 小时的调用量上限查看返回头里的限制字段等待冷却或申请更高配额连接超时/连接拒绝网络不通、代理配置影响、防火墙拦截用curl -v先探测连通性这里提一个很容易混淆的场景429 里常见的一类提示是“You have exceeded the 5-hour usage quota”这是按自然时间窗口计算的配额不是每分钟限流等窗口过了再测就行。还有一种隐蔽的 429服务商返回的响应体里带重试时间但状态码是 200我在业务校验层专门处理了这种伪装成功的响应如果你自己写脚本也要注意这一点。6.2 容器环境与网络相关的诡异问题自托管平台跑在 Docker 里自带一套隔离环境但也带来了一些特有的问题。很多人第一次启动报错是Failed to connect to the Docker daemon at npipe:////./pipe/docker_engine这通常出现在 Windows 平台上 Docker Desktop 没启动或者当前用户没有权限访问 Docker 引擎。解决方案很直接启动 Docker Desktop或者把用户加入 docker 组Linux 下执行sudo usermod -aG docker $USER然后重新登录。另一个容易被忽略的是容器 DNS 问题。Uni LLM Bench 的 Docker 容器如果无法解析 API 的域名所有请求都会报域名解析失败但你在宿主机上 curl 却是好的。排查时用docker exec container cat /etc/resolv.conf查看容器内的 DNS 配置如果指向了内网 DNS 而内网 DNS 无法解析公网域名就需要在 compose 文件里给容器指定公共 DNS比如dns: [223.5.5.5, 8.8.8.8]。这类问题不遇到一次真的很难想到。6.3 密钥安全管理自托管不是免死金牌自托管平台把密钥掌握在自己手里确实比把密钥贴在第三方测试网站上安全得多但不代表可以随意处理。我在平台里内置了几个强制约束API Key 一律通过环境变量注入不出现在任何配置文件和数据库明文记录中数据库存储时对密钥默认脱敏落库的是sk-***abc这种形式测试报告导出时也会自动过滤授权头信息。这里还要多说一句市面上有些免费测试 API的网站会诱导用户填入真实的 API Key这类 Key 很容易被收集之后用于盗刷。如果是团队内部多人协作测试我建议用一个专门的测试账号分配独立的 Key别用生产环境的最高权限 Key。这样即使 Key 意外泄露影响面也可控。6.4 结果可信度的最后一道防线最后分享一个我调试了很久的经验基准测试本身不能成为被测系统的瓶颈。如果你用一台很弱的机器跑高并发测试操作系统网络栈或 CPU 会先成为瓶颈测出来的数据反映的是你的测试机器而不是 API 服务。我的经验是执行机的 CPU 使用率在测试期间不要超过 50%如果超过了就要降低并发档位或换更强的机器。一个简单的验证方法是跑两轮同样的测试第二轮如果延迟数据明显劣化先检查一下是不是执行机资源被占满了。另外测试频率不要太密。LLM API 普遍有缓存层同一个 Prompt 在短时间内重复请求命中的可能是网关缓存而非模型真实推理导致延迟数据偏低。为了减少缓存影响我在 Prompt 模板里增加了一个可选参数可以把时间戳或随机串拼进用户消息里让缓存失效迫使请求打到真实的模型推理链路。这个开关默认关闭但做严肃对比测试时我建议打开。我在实际使用中发现把一个 LLM API 基准测试平台从能跑通做到结果可信中间隔着大量细节。TTFT 的测量时机、错误请求是否纳入统计、采样参数有没有锁死、执行机资源会不会成为瓶颈……这些点任何一个没处理好出来的报告都只是自我安慰。Uni LLM Bench 目前已经在我们团队稳定跑了两个月每周自动跑一轮巡检成功帮我挡掉过一次上游渠道深夜故障——要不是看到 P99 延迟突然从 3 秒飙升到 15 秒我们可能要到第二天业务反馈才知道出了问题。后续我打算再给它加上告警通知比如 P95 连续两轮超过阈值就推送到飞书群再配合历史报告的回归对比让这套平台从主动跑测试变成被动发现问题价值会更大一些。