跳到主要内容

Perf（流式性能）

Perf 插件用于为流式 chat 请求记录请求级性能指标，并把结果写入请求日志的 ext_fields.perf。

当前它主要回答的是：

  • 首个有效输出什么时候出现（TTFT）
  • 成功 upstream attempt 的生成阶段持续了多久
  • 如果上游 usage 可识别，输出了多少 token，以及对应的 tops

启用方式​

Perf 插件不需要额外配置。

当前实现下：

  • 没有独立的静态配置项
  • 没有独立的 route 级 plugin_config
  • 也没有单独的 management API 配置入口

它会默认参与 chat forward 链路，但只有满足条件时才会真正写出 ext_fields.perf。

生效范围​

Perf 当前只挂在 OnForwardChat hook 上，因此只对 chat 主链路生效。

具体来说，只有同时满足以下条件时，才可能产出 ext_fields.perf：

  1. 当前请求属于 chat 流程
  2. 请求是流式请求（stream=true）
  3. 响应过程中出现了首个“有效输出”事件

当前支持的流式 chat 协议包括：

  • /v1/chat/completions
  • /v1/responses
  • /v1/messages

如果是以下情况，Perf 不会产生日志：

  • 非流式 chat 请求
  • 没有进入 chat forward 链路的请求
  • 整个响应过程中没有观察到有效输出事件

执行位置​

在当前插件顺序中，Perf 位于：

  • 之后：guard

这意味着 Perf 记录的是当前 chat 主链路里实际写给客户端的流式输出时序，而不是某个更早阶段的理论时间点。

请求日志​

ext_fields.perf 使用以下 proto：

Perf 只写请求日志扩展字段：

{
  "perf": {
    "ttft_ms": 142,
    "generation_ms": 918,
    "output_tokens": 231,
    "tops": 251.63
  }
}

最常见字段语义是：

  • ttft_ms
    • 从请求计时起点到首个非空输出型 IR delta 的时间
    • 口径不是“首字节”，而是“首个有效输出事件”
  • generation_ms
    • 对应成功 upstream attempt 从首个有效输出到该 attempt 结束的耗时
  • output_tokens
    • 上游 usage 归一化后的输出 token 数
  • tops
    • output_tokens / generation_ms * 1000

字段缺失规则​

Perf 不是每次都写完整四个字段。

一条都不写​

以下情况直接不写 ext_fields.perf：

  • 非流式请求
  • 没有观测到首个有效输出事件

只写部分字段​

如果已经观测到首个有效输出，通常至少会写：

  • ttft_ms
  • generation_ms（前提是成功 attempt 的结束时间可得）

但下面两个字段是可选的：

  • output_tokens
  • tops

它们只有在上游响应 usage 可以明确判断“输出 token 已知”时才会写出。
如果上游没有提供可识别 usage，Perf 仍可能写出 ttft_ms / generation_ms，但不会写 output_tokens / tops。

当前实现细节​

Perf 识别“首个有效输出”的依据不是固定只看文本，还包括其他输出型 delta。当前实现会把这些情况视为有效输出：

  • 文本输出
  • tool arguments chunk
  • reasoning text
  • refusal text
  • tool output chunk

对 Claude Messages 这类协议，如果 content_block_start 里已经携带了初始输出内容，Perf 也会把它视为首个有效输出。