企业官网建设流程全解析

Local Studio 是一款用于自托管 LLM 推理的控制面板，统一管理 vLLM、SGLang、llama.cpp、exllamav3 等后端。它的Usage 用量分析页面是理解"本机推理成本"的核心入口：自动统计每个请求消耗的 Token、缓存命中率、首 Token 延迟（TTFT）和解码速度，并用一年期的 Token 热力图把用量趋势变成一眼可读的图案。

为什么本地推理也需要一张"用量账单"

自建推理栈不像云端 API 每月推一张账单，但成本真实存在：

• 显存时间：一张高端显卡跑满 24 小时的功耗与机会成本，比想象中贵；
• GPU 利用率：哪些模型占走了大部分 Token，哪些几乎没人用；
• 缓存效果：前缀缓存命中率越高，重复读取长上下文的开销越低。

Usage 页面正是为回答这些问题设计的：它统计"通过控制器代理的每一笔推理"，而不是让你翻日志。

打开 Usage 页面：一屏看懂用量总览

在左侧导航栏选择Usage（路由/usage，见 left-sidebar-nav.tsx），页面顶部是一组常驻指标：

页面右上角有刷新按钮，前端逻辑见 usage-page.tsx 与 use-usage.ts。数据来自控制器/usage接口，接口内部带有 15 秒缓存以避免频繁聚合（见 usage-routes.ts）。

Token 热力图：一年用量一眼看清

"Past year" 区域是一个 GitHub 贡献图风格的每日 Token 热力图：

• 横向 53 周、纵向 7 天，每天一个方格，色深代表当日 Token 量；
• 颜色分 5 档，按历史数据的 25%/50%/75% 分位数动态划分——你的重度日才会显示最深色，而不是被绝对值压扁；
• 鼠标悬停任意一天，立即显示"日期 · Token 数 · 请求数"；
• 时间轴按 UTC 日期计算。

实现见 token-activity-heatmap.tsx，其中 L43-L49 定义了分位数阈值逻辑。

怎么用：深色格子就是你的算力消耗峰值。连续深色通常意味着某个自动化任务在跑批量推理——回去查一下是不是该调小上下文或提高缓存复用。

Models 标签页：Token 成本与推理速度明细

这是成本管控的核心页。顶部三张卡片回答"钱花在哪"：

1. Token mix：输入 Token 与输出 Token 的比例。输入占比高的工作负载，缓存命中就是直接省钱；
2. Cache hit rate：提示词 Token 中由前缀缓存命中的比例，以及被复用的 Token 量。≥50% 会标绿，代表 prefill 阶段大量复用；
3. Decode：按输出 Token 加权的解码速度（tok/s）——这是聊天时"体感"生成速度。

下方表格按模型列出：请求数、Token 总量（含输入/输出拆分）、每请求平均 Token、Prefill tok/s（读上下文速度）、Decode tok/s（出字速度）、TTFT（首 Token 延迟）、Latency（P50 中位数）、成功率。点击任意一行会打开详情抽屉，展示该模型逐日的 Token 趋势（见 usage-models-tab.tsx 与 usage-model-drawer.tsx）。

选型建议：Decode 高但 TTFT 也高的模型，适合"短问长答"场景；反过来适合低延迟问答。TTFT 异常飙升往往是上下文过长或缓存失效的信号。

Activity 标签页：高峰时段与周环比趋势

Activity 页把流量按时间切开，顶部六张卡片覆盖：

• Last hour / Last 24 hours：最近 1 小时、24 小时的请求与 Token 量；
• 24h change：与上一个 24 小时的环比百分比；
• Tokens this week / Week over week：本周 Token 量及周环比——用量突然翻倍时最先在这里露馅；
• Active days：保留窗口内有 Token 记录的天数。

中段是一张"Hour of day" 柱状图（按 UTC 小时聚合的历史全量请求分布），页内注释说得直白：机器真正被叫起来工作的时段一目了然，曲线平坦的部分就是安排基准测试或重启服务的窗口（见 usage-activity-tab.tsx）。

底部是按月份分组的每日明细表（日期、请求、Token、输入/输出拆分、平均延迟、成功率），并在末尾附"Busiest days"——这台机器历史负载天花板，供你评估硬件是否还有余量。

Controller 与 Errors 标签页：异常与失败排查

前面两个标签页关注"模型"，这两个关注"模型前面的进程"：

• Controller 标签页：控制器本身服务的每一条路由的请求量、失败数、平均/最长耗时、成功率，以及按 2xx/3xx/4xx/5xx 分档的状态码分布；若启用了代理工作台，还会统计Agent 工具调用的次数与成功率——某个函数成功率低，意味着对话中会出现"悄悄卡住"的回合（见 usage-controller-tab.tsx）；
• Errors 标签页：把失败请求与失败的工调用按时间倒序列出，消息列最宽、时间用"4 分钟前"这类相对表述——判断"是不是我刚才那次操作导致"正需要这种视角（见 usage-errors-tab.tsx）。

成功率只告诉你"出事了"，Errors 页才告诉你"出了什么事"。

数据从哪来：代理层自动记账

Usage 页面无需任何手动配置，因为记账发生在OpenAI 兼容代理层：每个聊天请求（流式与非流式）结束时的usage字段被解析，连同 TTFT、总耗时、状态码一起写入本地 SQLite 的inference_requests表。

• 记账逻辑：inference-accounting.ts（流式入口在 recordStreamingInferenceUsage）；
• 存储与聚合：inference-request-store.ts 定义了表结构——prompt/completion/reasoning Token、缓存读写 Token 分列存储，这正是 Models 页"Cache hit rate"卡片的来源；
• 每日明细保留 366 天（见 usage 聚合查询），这就是热力图"Past year"的范围。

前端展示的字段契约集中在 usage-schema.ts 与 usage.ts，想扩展自定义指标时可从这里入手。

5 个用 Usage 页面管控推理成本的技巧

1. 每周看一次周环比：Activity 页的 Week over week 卡片是"用量异常"最快的预警器；
2. 盯缓存命中率：Prefill 密集型负载（长系统提示、多轮对话）命中率高才算健康，低于 50% 时检查请求是否共享前缀；
3. 用热力图找异常日：突然的深色格对应批量任务或失控循环，点进 Models 页确认是哪个模型；
4. 在平坦时段做维护：Hour of day 柱状图的低谷安排模型切换与基准测试，避免打断真实流量；
5. 成功率掉档先查 Errors：Controller 页看到 5xx 上升后，直接去 Errors 页按时间线定位是哪条路由、什么报错。

小结

Local Studio 的 Usage 页面把自托管推理中最不直观的三件事——Token 花在哪、什么时候花、为什么失败——变成了热力图、表格和错误时间线。对新手来说，先看总览和热力图建立体感，再深入 Models 页对比各模型的 TTFT、解码速度与缓存命中，就能用数据回答"这台机器到底值不值"。