1. 为什么 AI API 响应耗时统计总是不准很多人在 Python 里统计 AI API 响应耗时第一反应是time.time()前后一减打印一个数字就完事。我早期也这么干直到线上批量任务从 3 分钟涨到 12 分钟日志里却全是「耗时 2.1 秒」这种看起来正常的数字才发现问题单次请求的耗时被平均掉了真正拖慢整体的是少数几个长尾请求以及本地并发排队。AI API 的响应耗时和普通 HTTP 接口不一样。普通接口的耗时基本等于网络往返加服务端处理而 AI API 的耗时可以拆成好几段本地 DNS 解析与 TCP/TLS 连接、请求体发送、上游排队、模型预填充Prefill、逐 token 生成、响应体接收。你如果只测一个总时间根本分不清是网络慢、排队久还是模型生成慢。举个实际场景你写了个脚本用 AI API 批量给 500 条商品评论做情感分类。跑起来发现总耗时 8 分钟平均每条 0.96 秒。你觉得还行但老板说「能不能压到 3 分钟」。这时候你去看日志只有总耗时没有分段数据你只能猜是不是模型选大了是不是提示词太长了是不是并发开太高了猜来猜去改了半天可能只优化了 10%。正确的做法是先测量再定位最后优化。测量要精确到阶段定位要能区分 TTFT首字延迟和总生成时间优化要基于数据而不是感觉。这篇文章就围绕 Python 统计 AI API 响应耗时这条线给出可复制的计时装饰器、分阶段埋点、日志配置并演示把 endpoint 切到 TaoToken 后怎么对比响应数据验证瓶颈定位流程。适合谁看正在用 Python 调 AI API 做自动化脚本、后端服务、批量任务的开发者遇到过「接口偶尔变慢但不知道原因」的人想建立一套可持续的性能监控习惯的人。你不需要很深的性能工程背景会写 Python 函数、会用 requests 或 openai SDK 就能跟上。核心检索词先明确Python 统计 AI API 响应耗时本质是「分阶段计时 结构化日志 对比验证」。下面从环境准备开始一步步落地。2. TaoToken 前置准备与 Python 环境配置要把耗时统计跑通你得先有一个稳定的 AI API 入口。我这里用 TaoToken 作为演示 endpoint原因是它兼容 OpenAI SDK 的调用方式改base_url就能接上方便你做「同一段计时代码换 endpoint 对比数据」的实验。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先说 Python 环境。建议 Python 3.9 以上装两个包就够pip install openai httpxopenai是官方 SDKhttpx用来做更细粒度的连接层观测后面分阶段埋点会用到。如果你用的是 requests也可以但 httpx 对超时和连接复用的控制更清晰。接下来拿 Key。进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成一个 Key复制保存。注意 Key 只显示一次丢了就重新生成。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 后先写一个最小可运行脚本确认能调通import time from openai import OpenAI client OpenAI( api_key你的 TaoToken Key, base_urlhttps://taotoken.net/api/v1, ) start time.perf_counter() resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 用一句话解释什么是首字延迟}], ) elapsed time.perf_counter() - start print(f总耗时: {elapsed:.3f}s) print(resp.choices[0].message.content)这里有几个点要注意。base_url要带/v1因为 OpenAI SDK 会在后面拼/chat/completions。模型 ID 要写你账号里可用的比如gpt-4o-mini、claude-3-5-sonnet这类具体以模型列表为准模型对话页在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你要长期跑编码类 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。跑通之后你会看到一个总耗时数字。但这个数字还不够我们要把它拆开。在拆之前先确认你的网络环境是正常的不要在有本地代理干扰的情况下测否则连接耗时会被放大数据不可信。另外第一次调用会包含 TLS 握手建议先 warmup 一次再开始正式计时避免把冷启动算进去。环境配置清单项目值说明Python3.9低于 3.9 部分类型注解会报错openai SDK最新版pip install -U openaihttpx最新版用于连接层观测base_urlhttps://taotoken.net/api/v1注意带 /v1api_key控制台生成只显示一次模型 ID以模型列表为准不要硬编码不存在的模型配置完成后进入下一步写计时装饰器和分阶段埋点。3. 可复制的计时装饰器与分阶段埋点配置这一节是核心。我们要做三件事一个通用的计时装饰器、一套分阶段埋点、一份结构化日志配置。全部可复制。先看计时装饰器。它的作用是自动记录函数调用的总耗时、成功/失败状态并输出结构化日志。不要用time.time()用time.perf_counter()它单调递增不受系统时间调整影响。import time import logging import functools logger logging.getLogger(ai_api_timer) def timed(nameNone): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): label name or func.__name__ start time.perf_counter() try: result func(*args, **kwargs) cost time.perf_counter() - start logger.info( api_call_ok, extra{label: label, cost_s: round(cost, 3), status: ok}, ) return result except Exception as exc: cost time.perf_counter() - start logger.error( api_call_fail, extra{label: label, cost_s: round(cost, 3), status: fail, error: str(exc)}, ) raise return wrapper return decorator这个装饰器只给了总耗时。要分阶段得在调用内部埋点。AI API 的分阶段可以这样切import time from openai import OpenAI client OpenAI(api_key你的 Key, base_urlhttps://taotoken.net/api/v1) def call_with_stages(prompt, modelgpt-4o-mini): stages {} t0 time.perf_counter() # 阶段1构造请求本地序列化 messages [{role: user, content: prompt}] t1 time.perf_counter() stages[build_request] t1 - t0 # 阶段2发起请求到收到响应对象含连接、排队、生成 resp client.chat.completions.create(modelmodel, messagesmessages) t2 time.perf_counter() stages[request_total] t2 - t1 # 阶段3解析响应 content resp.choices[0].message.content t3 time.perf_counter() stages[parse_response] t3 - t2 stages[total] t3 - t0 return content, stages但这样还是分不清「连接」和「生成」。要拆得更细用流式模式测 TTFTdef call_stream_with_ttft(prompt, modelgpt-4o-mini): t0 time.perf_counter() first_token_time None chunks [] stream client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], streamTrue, ) for chunk in stream: if first_token_time is None: first_token_time time.perf_counter() delta chunk.choices[0].delta.content if delta: chunks.append(delta) t_end time.perf_counter() ttft (first_token_time - t0) if first_token_time else None total t_end - t0 return .join(chunks), {ttft_s: round(ttft, 3) if ttft else None, total_s: round(total, 3)}TTFT 大说明排队或预填充慢TTFT 小但 total 大说明生成速度慢或输出太长。这两个指标一分开瓶颈方向就清楚了。日志配置用 JSON 格式方便后续用脚本聚合import logging import json class JsonFormatter(logging.Formatter): def format(self, record): payload { ts: self.formatTime(record), level: record.levelname, msg: record.getMessage(), } for key in (label, cost_s, status, error, ttft_s, total_s): if hasattr(record, key): payload[key] getattr(record, key) return json.dumps(payload, ensure_asciiFalse) handler logging.StreamHandler() handler.setFormatter(JsonFormatter()) logger logging.getLogger(ai_api_timer) logger.addHandler(handler) logger.setLevel(logging.INFO)如果你用 Cline MCP 或 Claude Code 这类工具做开发配置里通常要写全三件套Base URL、Key、Model ID。以 settings 片段为例{ aiProvider: { baseUrl: https://taotoken.net/api/v1, apiKey: 你的 TaoToken Key, modelId: gpt-4o-mini } }Codex 的 auth.json 类似{ base_url: https://taotoken.net/api/v1, api_key: 你的 TaoToken Key, model: gpt-4o-mini }这三件套缺一不可少一个就会报 401 或 model not found。配置好之后跑一次带埋点的调用你会得到类似这样的输出{ts: 2025-01-01 10:00:00, level: INFO, msg: api_call_ok, label: call_stream_with_ttft, ttft_s: 0.42, total_s: 2.87, status: ok}有了这些数据下一步就是验证请求是否成功以及怎么对比不同 endpoint 的响应。4. 验证请求与对比 TaoToken 响应数据埋点写完要验证两件事请求确实成功了以及数据确实能反映差异。先写一个验证脚本跑 10 次统计 TTFT 和 total 的分布import statistics def benchmark(prompt, modelgpt-4o-mini, rounds10): ttfts, totals [], [] for i in range(rounds): content, stats call_stream_with_ttft(prompt, model) if stats[ttft_s]: ttfts.append(stats[ttft_s]) totals.append(stats[total_s]) return { ttft_avg: round(statistics.mean(ttfts), 3) if ttfts else None, ttft_p95: round(sorted(ttfts)[int(len(ttfts) * 0.95) - 1], 3) if ttfts else None, total_avg: round(statistics.mean(totals), 3), total_p95: round(sorted(totals)[int(len(totals) * 0.95) - 1], 3), } result benchmark(用三句话说明什么是 API 响应耗时, rounds10) print(result)跑出来大概是这样的结构{ttft_avg: 0.45, ttft_p95: 0.78, total_avg: 2.91, total_p95: 4.12}注意看 p95。平均值会骗人p95 才能暴露长尾。如果 ttft_avg 是 0.45 但 ttft_p95 是 0.78说明大部分请求排队正常少数请求排队偏久。如果 total_p95 远大于 total_avg说明生成阶段有波动。接下来做对比实验同一段代码把 base_url 从原来的 endpoint 换成 TaoToken 的 https://taotoken.net/api/v1 跑同样的 10 次记录两组数据。对比维度指标原 endpointTaoToken差异ttft_avg0.620.45-27%ttft_p951.100.78-29%total_avg3.402.91-14%total_p955.204.12-21%以上数字是演示结构实际以你测到的为准。重点不是数字本身而是流程你先有分阶段数据再换 endpoint 对比就能判断延迟主要来自哪一段。如果换 endpoint 后 TTFT 明显下降说明原来那段的排队或连接有问题如果 TTFT 没变但 total 变了说明生成速度有差异。验证请求成功与否除了看返回内容还要看异常分支。故意传一个错误的 Key你会看到 401{level: ERROR, msg: api_call_fail, status: fail, error: Error code: 401 - {error: {message: Invalid API key}}}故意传一个不存在的模型会看到 model not found。这些错误也要被计时装饰器捕获否则你的耗时统计会漏掉失败请求导致平均值偏低误判性能。还有一个常见现象reading choices报错。这通常是因为响应结构和你解析的字段不匹配比如流式和非流式混用。流式返回的 chunk 里choices[0].delta.content可能是 None你要判空。非流式才是choices[0].message.content。这个坑我在批量脚本里踩过日志里一堆reading choices排查半天才发现是 stream 参数写错了。验证通过后进入排障环节。5. 本篇常见错误排查这一节列真实会遇到的报错以及怎么用耗时数据定位。401 Invalid API key。原因通常是 Key 写错、Key 过期、或者 base_url 和 Key 不匹配。排查顺序先确认 Key 是从控制台复制的完整字符串没有多余空格再确认 base_url 是 https://taotoken.net/api/v1 带 /v1最后确认这个 Key 有对应模型的权限。耗时日志里如果 401 的 cost_s 很小比如 0.05s说明请求根本没到模型是鉴权阶段就被拒了。local proxy failed / connection error。这类报错说明本地网络层有问题可能是代理配置干扰、DNS 解析失败、或者连接超时。注意不要用任何非正规的网络工具保持本地网络环境干净。排查方法先用curl -v https://taotoken.net/api/v1/models看能不能通再跑 Python 脚本。如果 curl 通而 Python 不通检查 Python 的 httpx 是否走了系统代理。耗时日志里这类错误的 cost_s 往往等于你设置的 timeout 值比如 30s说明是超时而非快速失败。reading choices 报错。前面提过流式和非流式字段不同。流式用chunk.choices[0].delta.content非流式用resp.choices[0].message.content。如果你在流式循环里访问message就会报 AttributeError 或 KeyError。修复方式统一封装一个extract_content(chunk, streamTrue)函数内部判空。OAuth / auth.json 配置错误。如果你用 Codex 或类似工具auth.json 里三件套写错会报 OAuth 相关错误。检查 base_url、api_key、model 三个字段是否齐全JSON 格式是否合法不要有多余逗号。这类错误在耗时日志里表现为请求还没发出就失败cost_s 接近 0。TTFT 正常但 total 异常大。这不是报错但是性能问题。原因通常是 max_tokens 设太大或者提示词要求输出很长。排查打印resp.usage.completion_tokens看实际生成了多少 token。如果 completion_tokens 远超预期说明输出没被限制住。优化方式在请求里加max_tokens并在提示词里明确「用一句话回答」。并发过高导致排队。如果你用 asyncio 或线程池同时发 50 个请求TTFT 会集体变大。排查把并发降到 5再测一次 TTFT。如果明显下降说明是本地或服务端排队。优化方式用 Semaphore 控制并发数或者分批发送。排障的核心思路先看 cost_s 的量级快速失败0.1s多半是配置或鉴权问题慢失败接近 timeout多半是网络或排队问题成功但慢TTFT 大或 total 大多半是模型或提示词问题。有了分阶段数据你不用猜。6. 把耗时监控变成日常习惯最后说落地。一次性测完就丢意义不大。真正有用的是把耗时指标持续记录下来按天、按模型、按任务类型聚合。你可以把 JSON 日志写到文件然后用一个简单脚本做聚合import json from collections import defaultdict def aggregate(log_path): stats defaultdict(list) with open(log_path) as f: for line in f: try: rec json.loads(line) except json.JSONDecodeError: continue if rec.get(msg) api_call_ok and total_s in rec: stats[rec.get(label, unknown)].append(rec[total_s]) for label, costs in stats.items(): costs.sort() print(f{label}: n{len(costs)} avg{sum(costs)/len(costs):.3f}s p95{costs[int(len(costs)*0.95)-1]:.3f}s) aggregate(ai_api_timer.log)这样你每天跑一次就能看到趋势。如果某天 p95 突然翻倍你就知道要查了。查的时候先看是 TTFT 涨了还是 total 涨了再对应到具体原因。几个实用技巧。第一warmup 很重要第一次调用包含 TLS 握手不要算进统计。第二测 TTFT 一定要用流式非流式拿不到首字时间。第三p95 比平均值更能反映用户体验重点关注 p95。第四换 endpoint 对比时保持模型、提示词、并发数完全一致否则数据不可比。第五把耗时日志和业务日志分开避免混在一起难聚合。如果你要长期跑编码类或 Agent 类任务建议用 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 配合上面的耗时监控能持续观察任务执行效率。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题可以先查文档。模型对话页在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 可以用来快速验证某个模型是否可用。回到最开始的问题Python 统计 AI API 响应耗时不是打印一个数字就完事。你要分阶段、分指标、持续记录、对比验证。计时装饰器负责兜底分阶段埋点负责定位JSON 日志负责聚合endpoint 对比负责验证。这套流程跑顺了下次再遇到「接口变慢」你打开日志就能说出瓶颈在哪而不是靠猜。