1. 为什么小白程序员需要一套统一的指标采集方案
刚接触大模型应用开发时，最容易踩的坑不是模型选错，而是指标口径混乱。同一个“延迟”，有人测的是首字时间，有人测的是完整响应时间；同一个“成本”，有人只算输出 Token，有人把系统提示词和检索文档全算进去。结果就是团队里三个人报出三套数据，谁也说服不了谁。
我试过在一个客服机器人项目里同时接三家模型供应商，光是切换 Key 和 Base URL 就写了好几套配置，测出来的 TTFT 数据因为网络路径不同根本没法横向对比。后来把调用通道统一到一个入口，所有指标才真正具备可比性。这也是这篇要解决的核心问题：用一套统一的 Key 和 API 通道，把 30 个核心指标的采集脚本跑通，让数据能放在同一张表里对照。
这篇文章面向的是刚入门大模型、但已经能写 Python 脚本的程序员。你不需要懂推理引擎底层，只要能发 HTTP 请求、会看 JSON 返回，就能跟着把指标采集框架搭起来。全文会围绕延迟、吞吐、Token 成本、准确率这几类指标展开，每一类都给出可复制的配置和验证动作。
先说清楚这 30 个指标的分层逻辑，不然后面采集会没有章法。它们大致分五层：模型质量层（解决率、幻觉率、空答率、意图识别准确率、RAG 召回率、事实一致性）、用户体验层（首轮满意度、转人工率、任务完成率、CSAT、代码采纳率、多轮完成率）、系统效率层（Token 成本、TTFT、端到端延迟、QPS、Token 使用效率、可用性）、业务价值层（功能采纳率、单位解决成本、工单偏转率、效率提升、LTV/CAC、模型 ROI）、数据闭环层（反馈回流率、Badcase 归因、评测集覆盖率、模型漂移率、置信度校准、数据闭环周期）。
小白最容易犯的错，是一上来就想把 30 个全测一遍。实际上系统效率层的 6 个指标最适合作为起点，因为它们全部可以通过 API 调用直接量化，不依赖人工标注，跑一遍脚本就能出数。质量层和体验层的指标需要标注数据或用户行为埋点，适合在效率层跑通之后再逐步接入。
这里有个关键认知：指标不是越多越好，而是口径要统一、可复现。你今天用 A 通道测出 TTFT 是 800ms，明天换 B 通道测出 1200ms，如果不控制变量，这个数据毫无意义。所以下一步先把调用通道固定下来。
2. TaoToken 统一 Key 与 API 通道的前置准备
要让 30 个指标可比，第一步是让所有请求走同一条路。TaoToken 在这里扮演的角色是统一入口：你用一个 Key、一个 Base URL，就能调用多家模型，切换模型只需要改一个 model 字段，网络路径和鉴权方式保持一致，指标才有横向对比的基础。
先明确几个地址，后面配置会反复用到：
- 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
- API 根地址：https://taotoken.net/api
- 模型对话页：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite
- Coding Plan 页：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite
- 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite
拿到 Key 的流程不复杂：进控制台，在 API Keys 页面创建一个新 Key，复制出来存到环境变量里。不要硬编码在脚本里，后面采集脚本会跑很多次，Key 泄露风险很高。
这里要强调一个容易被忽略的点：TaoToken 的 API 是OpenAI 兼容格式，也就是说你原来用 openai 这个 Python 库写的代码，只需要改base_url和api_key两个参数就能跑。这对指标采集特别友好，因为大部分现成的评测脚本都是按 OpenAI 格式写的，迁移成本几乎为零。
环境变量这样设置，Linux/macOS 用 export，Windows 用 set：
# Linux / macOS export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api" # Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的Key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"装依赖只需要两个库，一个是 openai 官方 SDK，一个是用来做统计的 pandas：
pip install openai pandas验证 Key 是否可用，先跑一个最小请求，别急着上采集脚本：
import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "只回复两个字：收到"}], ) print(resp.choices[0].message.content) print("usage:", resp.usage)如果这一步返回“收到”，说明通道打通了。如果报 401，先检查 Key 有没有复制完整、有没有多余空格；如果报连接错误，检查 base_url 是不是写成了带/v1的旧格式——TaoToken 的根地址就是https://taotoken.net/api，SDK 会自动拼接路径。
这里有个前置认知要建立：统一通道的价值不只是省事，而是让变量可控。当你测 TTFT 时，网络路径、鉴权耗时、请求排队策略都是固定的，唯一变化的是 model 字段。这样测出来的差异，才能归因到模型本身，而不是通道差异。
3. 可复制的指标采集配置与脚本骨架
这一节是全文的核心，给出可以直接复制运行的配置和脚本。先建一个项目目录，结构如下：
ai-metrics/ ├── config.json ├── collector.py └── results/config.json里放采集参数，把模型列表、测试轮次、超时时间都抽出来，方便改：
{ "base_url": "https://taotoken.net/api", "models": ["gpt-4o-mini", "gpt-4o", "claude-3-5-sonnet"], "rounds": 5, "timeout": 60, "prompts": { "short": "用一句话解释什么是向量数据库。", "long": "请分五点详细说明 RAG 系统的完整链路，每点不少于 50 字。", "code": "写一个 Python 函数，输入列表返回去重后的结果，要求保留原顺序。" } }注意base_url这里写的是https://taotoken.net/api，和上一节环境变量保持一致。models列表里放你要对比的模型，TaoToken 支持多家模型，切换只改这个数组。
接下来是采集脚本collector.py，核心是流式请求 + 时间戳打点，这样才能同时拿到 TTFT 和端到端延迟：
import os import json import time import statistics from openai import OpenAI with open("config.json", "r", encoding="utf-8") as f: cfg = json.load(f) client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=cfg["base_url"], timeout=cfg["timeout"], ) def measure_once(model: str, prompt: str) -> dict: start = time.perf_counter() first_token_ts = None chunks = [] usage = None stream = client.chat.completions.create( model=model, messages=[{"role": "user", "content": prompt}], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: if first_token_ts is None: first_token_ts = time.perf_counter() chunks.append(chunk.choices[0].delta.content) if chunk.usage: usage = chunk.usage end = time.perf_counter() text = "".join(chunks) return { "model": model, "ttft_ms": round((first_token_ts - start) * 1000, 2) if first_token_ts else None, "e2e_ms": round((end - start) * 1000, 2), "prompt_tokens": usage.prompt_tokens if usage else None, "completion_tokens": usage.completion_tokens if usage else None, "total_tokens": usage.total_tokens if usage else None, "output_chars": len(text), } def run_all() -> list: rows = [] for model in cfg["models"]: for pname, prompt in cfg["prompts"].items(): for i in range(cfg["rounds"]): try: row = measure_once(model, prompt) row["prompt_type"] = pname row["round"] = i + 1 rows.append(row) print(f"[OK] {model} / {pname} / round {i+1} " f"ttft={row['ttft_ms']}ms e2e={row['e2e_ms']}ms") except Exception as e: print(f"[FAIL] {model} / {pname} / round {i+1}: {e}") return rows if __name__ == "__main__": os.makedirs("results", exist_ok=True) data = run_all() with open("results/raw.json", "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) print(f"共采集 {len(data)} 条记录，已写入 results/raw.json")这段脚本有几个设计点值得说明。第一，用time.perf_counter()而不是time.time()，前者精度更高，适合测毫秒级延迟。第二，stream_options={"include_usage": True}是关键，流式模式下默认不返回 usage，加上这个参数才能在最后一个 chunk 拿到 Token 统计。第三，每个模型每个 prompt 跑 5 轮，是为了后面算 P95，单次数据没有统计意义。
跑起来之后，你会得到一份raw.json，里面每条记录都包含模型、prompt 类型、TTFT、端到端延迟、Token 消耗。这就是后面所有指标计算的原始数据。
这里要提醒一个坑：不同模型的 Token 计费口径不一样。有的模型把系统提示词算进输入，有的不算；有的模型输出 Token 和输入 Token 价格差 3 到 4 倍。所以采集时一定要把 prompt_tokens 和 completion_tokens 分开记录，不能只记 total。
4. 验证请求与结果对照表
采集完原始数据，下一步是把它聚合成可读的对照表。这一步用 pandas 做，几行代码就能出结果：
import json import pandas as pd with open("results/raw.json", "r", encoding="utf-8") as f: data = json.load(f) df = pd.DataFrame(data) def p95(s): return s.quantile(0.95) summary = df.groupby(["model", "prompt_type"]).agg( ttft_p50=("ttft_ms", "median"), ttft_p95=("ttft_ms", p95), e2e_p50=("e2e_ms", "median"), e2e_p95=("e2e_ms", p95), avg_prompt_tokens=("prompt_tokens", "mean"), avg_completion_tokens=("completion_tokens", "mean"), avg_total_tokens=("total_tokens", "mean"), ).round(2).reset_index() summary.to_csv("results/summary.csv", index=False, encoding="utf-8-sig") print(summary.to_string(index=False))跑完之后你会得到类似这样的对照表（数值是示例，实际以你的采集结果为准）：
| model | prompt_type | ttft_p50 | ttft_p95 | e2e_p50 | e2e_p95 | avg_total_tokens |
|---|---|---|---|---|---|---|
| gpt-4o-mini | short | 420 | 680 | 1100 | 1600 | 85 |
| gpt-4o-mini | long | 450 | 720 | 4200 | 5800 | 620 |
| gpt-4o | short | 610 | 950 | 1500 | 2100 | 90 |
| gpt-4o | long | 640 | 1020 | 5600 | 7400 | 650 |
| claude-3-5-sonnet | short | 580 | 880 | 1400 | 1900 | 88 |
| claude-3-5-sonnet | long | 600 | 960 | 5100 | 6900 | 640 |
这张表能直接回答几个关键问题。第一，TTFT 和端到端延迟是两回事：short prompt 下 TTFT 都在 400 到 600ms，但 long prompt 的端到端延迟能到 5 秒以上，说明生成长度对总耗时影响巨大。第二，P95 比 P50 更值得看：如果只看中位数，你会觉得延迟很健康，但 P95 往往高出 50% 以上，这才是用户真实感受到的“偶尔卡顿”。
有了这张表，Token 成本就能直接算。假设某模型输入 1 元/百万 Token、输出 3 元/百万 Token，单次调用成本 = prompt_tokens × 输入单价 + completion_tokens × 输出单价。把单价填进脚本，就能在表里加一列cost_per_call。
再进一步，可以算Token 使用效率：有效输出 Token 除以总消耗 Token。如果一次调用 prompt_tokens 是 3000、completion_tokens 是 200，那效率只有 6% 左右，说明大量 Token 花在了上下文填充上。这个指标能直接指导你优化系统提示词和检索文档长度。
验证动作做到这里，你已经有了延迟、吞吐、成本三类指标的实测数据。接下来把质量类指标接进来：准备一组带标准答案的测试题，用同样的通道跑一遍，人工或脚本比对输出，算出准确率、幻觉率、空答率。因为通道统一，质量数据和效率数据可以按 model 字段直接 join，形成完整的模型画像。
5. 本篇常见错误排查
采集过程中最容易撞上的几类报错，这里逐个拆解。
401 Unauthorized。最常见的原因是 Key 没读到。先确认环境变量有没有生效：在 Python 里打印os.environ.get("TAOTOKEN_API_KEY")，如果是 None，说明 export 没在当前终端生效，或者你换了终端窗口。另一个原因是 Key 前后带了空格或换行，复制的时候容易带上。还有一种情况是 Key 被禁用或额度耗尽，去控制台的 API Keys 页面确认状态。
local proxy failed / connection error。这类报错通常是 base_url 写错了。TaoToken 的根地址是https://taotoken.net/api，不要手动加/v1，SDK 会自己拼。如果你从别处复制了带/v1的配置，改成不带即可。另外检查一下本机有没有设置全局代理环境变量（HTTP_PROXY / HTTPS_PROXY），如果有，请求可能会被错误路由，临时 unset 掉再试。
reading choices 报错 / KeyError: 'choices'。这个错误一般出现在流式解析时。有些返回的 chunk 里choices是空数组（比如最后一个只带 usage 的 chunk），直接取chunk.choices[0]就会越界。正确写法是先判断if chunk.choices and chunk.choices[0].delta.content，脚本里已经这么处理了。如果你自己改代码，记得保留这个判断。
OAuth / 鉴权相关报错。如果你用的是某些 CLI 工具（比如 Claude Code 类工具），它们可能走的是 OAuth 流程而不是 API Key。这种情况下要确认工具支持自定义 Base URL 和 Key。以 Claude Code 为例，需要配置三件套：Base URL 填https://taotoken.net/api，Key 填你的 TaoToken Key，Model ID 填你要用的模型名。三个缺一不可，只填 Key 不填 Base URL 会走默认端点，导致鉴权失败。
usage 为 None。流式模式下如果不加stream_options={"include_usage": True}，最后一个 chunk 不会带 usage，导致 Token 统计全是 None。加上这个参数即可。注意有些模型可能不支持这个参数，如果报错就去掉，改用非流式请求单独测 Token。
TTFT 数据异常大。如果某几次 TTFT 突然到几秒，先看是不是首次请求（冷启动），再跑几轮取中位数就能过滤掉。如果持续偏大，检查本机网络，或者换个时间段再测。指标采集最忌讳拿单次异常值下结论。
模型名报错 model not found。TaoToken 支持的模型名以控制台或模型对话页展示的为准，不要凭记忆写。去模型对话页确认准确的 model ID，复制到 config.json 里。
排查的核心思路是分层定位：先确认 Key 和 Base URL 对不对（401 和连接错误），再确认请求参数对不对（choices 和 usage），最后确认模型名对不对（model not found）。大部分问题都出在前两层。
6. 把指标采集接入日常开发流程
跑通一次采集不难，难的是让它持续产生价值。这里给几个落地建议。
第一，把采集脚本挂到 CI 里。每次模型配置变更或提示词调整，自动跑一轮采集，对比上一版数据。如果 TTFT P95 上涨超过 20%，或者 Token 成本上涨超过 15%，就阻断合并。这样能防止“悄悄变慢变贵”。
第二，建立基线表。第一次采集的结果存为 baseline，之后每次采集都和 baseline 对比。模型漂移率这个指标就是这么算出来的：同一套测试题，隔一个月再跑，看准确率和延迟的变化幅度。
第三，质量指标要配标注流程。效率指标可以全自动，但幻觉率、事实一致性这些必须有人工标注。建议先攒 100 到 200 条测试样本，覆盖高频场景，每次发版跑一遍。样本不用多，但要稳定，这样才能看出趋势。
第四，成本要按业务口径算，不是按 API 口径算。API 账单只是分子的一部分，还要把向量库检索费、知识库维护人力、标注成本摊进去，才是真实的单位解决成本。这个数字才能和人工客服成本对比，判断 AI 方案是否真的划算。
如果你打算长期做模型评测和 Agent 开发，可以了解一下 Coding Plan，它更适合高频调用场景。日常验证模型效果，直接用模型对话页手动试几个 prompt 就够了。接入文档里有完整的参数说明和示例代码，遇到不确定的字段先去那里查。
最后留一个实操建议：先跑通 6 个效率指标，再逐步加质量指标。不要一上来就追求 30 个全覆盖，那样很容易因为标注数据不足而卡住。效率指标当天就能出数，有了正反馈，再往质量层推进会顺很多。指标的价值不在于数量，而在于你能不能持续采集、持续对比、持续改进。
