企业官网建设流程全解析

Switchyard Token用量统计指南：prompt、completion、cached、reasoning四类指标详解

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard

Switchyard是一个让 LLM 应用跨模型、跨服务商路由流量的开源路由网关，在保持 OpenAI 与 Anthropic 原生 API 兼容的同时，把每次请求的Token 用量统计统一汇总。它把各家服务商五花八门的 usage 字段归一化为 prompt、completion、cached、reasoning 四类核心指标，并通过GET /v1/stats（JSON）和GET /metrics（Prometheus）两种端点实时输出，帮你快速算清每个模型的 token 账单与缓存命中率。

Token用量是怎么被记录的？

每一次被路由到后端的调用，Switchyard 都会在响应结束时做一件事：观测 usage，不动内容。

• 聚合（一次性）响应：直接从响应的 usage 字段记账；
• 流式响应：包装一层异步流，持续跟踪最后一条Usage事件，并在收到终止事件（如message_stop）后立即落账——即使客户端收到结束事件就断开连接，用量也不会丢。

这套观测逻辑在 crates/switchyard-server/src/usage_metrics.rs 中实现，配套的归一化Usage结构定义在 crates/protocol/src/llm.rs 里。

💡 细节：各提供商对缓存 token 的口径不一致（有的包含、有的不包含在 input_tokens 中），Switchyard 的协议层会先做归一化，保证统计口径统一。

四类核心指标一览：prompt、completion、cached、reasoning

其中prompt_tokens的计算逻辑可直接在 usage_metrics.rs 的token_usage函数中看到：它把非缓存输入、缓存读回、缓存创建三部分相加，避免“缓存 token 被漏计或重复计”。

📌 额外还有两个衍生字段：

• cache_creation_tokens：写入缓存的 token 数（缓存“建账”成本）；
• cacheable_prompt_tokens：理论可缓存的 prompt token 数，用于计算理论缓存命中率。

查看方式一：/v1/stats JSON 统计端点

向运行中的服务发起GET /v1/stats，即可拿到进程级的 JSON 快照，结构由 crates/switchyard-server/src/stats/accumulator.rs 定义：

• 顶层total_tokens：prompt、completion、cached、cache_creation、reasoning五项全局合计，外加total（= prompt + completion）；
• 每个模型一个条目：四类 token 累计值、avg_prompt_tokens/avg_completion_tokens（单次均值）、token_pct（token 占比），以及现成算好的cache_hit_rate（= cached ÷ prompt）与theoretical_cache_hit_rate；
• 分类器/judge 调用的用量单独放在classifier块中，与主路由流量分开核算。

需要清零重新统计时，POST /v1/stats/reset即可。

新手最常关心的两个问题：

1. 这个模型实际花了多少 token？→ 看total_tokens = prompt_tokens + completion_tokens；
2. 缓存省了多少钱？→cache_hit_rate越高，说明命中折扣价的缓存读回比例越大，reasoning 模型还需另看reasoning_tokens评估思考成本。

查看方式二：Prometheus 指标接入

如果已有监控栈，Switchyard 在GET /metrics暴露 Prometheus 文本格式，四个 token 计数器分别带model标签（即配置的端点 id，如openai/gpt-5.5）：

仓库已附带开箱即用的抓取配置与告警规则：

• 抓取配置：examples/prometheus/prometheus.yml
• 告警规则：examples/prometheus/switchyard.rules.yaml
• 完整指标字典：docs/internal/metrics_reference.md

把scrape_configs合并进现有 Prometheus 配置后，一条 PromQL 就能看清每个端点的流量与 token 占比：

sum by (model) (rate(switchyard_requests_total[5m])) / ignoring(model) group_left sum(rate(switchyard_requests_total[5m]))

小结

Switchyard 把“各提供商口径混乱”这件事封装在了协议层，你只需面向四类指标做成本核算与优化：关注prompt/completion算总量，用cached验证缓存省钱效果，用reasoning给思考型模型单独计费。

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard