《互联网产品的 AI 架构·推理性能与成本工程》1.1 首字、单 token 与整体延迟

TTFT = 排队（queue） + 冷启动（cold start） + 预填充（prefill）

E2E 预算 ≥ TTFT 预算 + TPOT 预算 × (最大输出 token 数 - 1)

// file: src/perf/metrics.ts
// tier: L1
// verify: node --test test/perf/metrics.test.ts

import { AiError } from "../core/errors.ts";
import { percentile } from "../observe/baseline.ts";

/**
 * 一次流式请求的时间线。所有时刻来自同一个单调时钟。
 * 拆成四个时刻，才能把「用户等首字」拆成排队、冷启动与预填充。
 */
export interface StreamTimeline {
  requestId: string;
  /** 网关接单时刻，用户感知的延迟从这里起算。 */
  enqueuedAtMs: number;
  /** 调度器把请求分配给 worker 的时刻。 */
  admittedAtMs: number;
  /** 模型可以开始预填充的时刻；冷启动会把它整体推迟。 */
  readyAtMs: number;
  /** 每个输出 token 的到达时刻，必须包含首 token 且严格递增。 */
  tokenAtMs: readonly number[];
}

export interface FirstTokenSplit {
  queueMs: number;
  coldStartMs: number;
  prefillMs: number;
  /** 用户视角的 TTFT：排队 + 冷启动 + 预填充。 */
  ttftMs: number;
}

export interface LatencyBreakdown {
  requestId: string;
  tokens: number;
  firstToken: FirstTokenSplit;
  /** 相邻 token 的间隔，长度等于 tokens - 1。 */
  itlMs: readonly number[];
  /** 解码阶段平均每个 token 的耗时。 */
  tpotMs: number;
  decodeMs: number;
  e2eMs: number;
}

function fail(message: string): never {
  throw new AiError("invalid-request", `metrics: ${message}`);
}

function assertTimestamp(value: number, label: string): void {
  if (!Number.isFinite(value) || value < 0) fail(`${label} 必须是非负有限数`);
}

/**
 * 把一条时间线拆成可解释的分段。
 * 约束不只是“字段非负”，还包括时刻单调与 token 严格递增：
 * 一条自相矛盾的时间线算出来的 P95 没有意义。
 */
export function decomposeTimeline(timeline: StreamTimeline): LatencyBreakdown {
  assertTimestamp(timeline.enqueuedAtMs, "enqueuedAtMs");
  assertTimestamp(timeline.admittedAtMs, "admittedAtMs");
  assertTimestamp(timeline.readyAtMs, "readyAtMs");
  for (const [index, at] of timeline.tokenAtMs.entries()) {
    assertTimestamp(at, `tokenAtMs[${index}]`);
  }
  if (timeline.tokenAtMs.length === 0) {
    fail(`${timeline.requestId}: 至少需要一个输出 token`);
  }
  if (timeline.enqueuedAtMs > timeline.admittedAtMs) {
    fail(`${timeline.requestId}: admittedAtMs 早于 enqueuedAtMs`);
  }
  if (timeline.admittedAtMs > timeline.readyAtMs) {
    fail(`${timeline.requestId}: readyAtMs 早于 admittedAtMs`);
  }
  const firstAt = timeline.tokenAtMs[0];
  const lastAt = timeline.tokenAtMs[timeline.tokenAtMs.length - 1];
  if (timeline.readyAtMs > firstAt) {
    fail(`${timeline.requestId}: 首 token 早于模型就绪`);
  }
  for (let index = 1; index < timeline.tokenAtMs.length; index += 1) {
    if (timeline.tokenAtMs[index] <= timeline.tokenAtMs[index - 1]) {
      fail(`${timeline.requestId}: token 时刻必须严格递增`);
    }
  }

  const queueMs = timeline.admittedAtMs - timeline.enqueuedAtMs;
  const coldStartMs = timeline.readyAtMs - timeline.admittedAtMs;
  const prefillMs = firstAt - timeline.readyAtMs;
  const ttftMs = firstAt - timeline.enqueuedAtMs;
  const decodeMs = lastAt - firstAt;
  const tokens = timeline.tokenAtMs.length;
  const itlMs = timeline.tokenAtMs.slice(1).map((at, index) => at - timeline.tokenAtMs[index]);
  // TPOT 不含首 token：它衡量的是首字之后每个 token 的平均间隔。
  const tpotMs = tokens === 1 ? 0 : decodeMs / (tokens - 1);

  return {
    requestId: timeline.requestId,
    tokens,
    firstToken: { queueMs, coldStartMs, prefillMs, ttftMs },
    itlMs,
    tpotMs,
    decodeMs,
    e2eMs: lastAt - timeline.enqueuedAtMs,
  };
}

export interface LatencyBudget {
  /** 首字预算：从接单到第一个 token。 */
  ttftMs: number;
  /** 单 token 预算：首字之后每个 token 的平均间隔。 */
  tpotMs: number;
  /** 端到端预算：从接单到最后一个 token。 */
  e2eMs: number;
}

/**
 * 预算之间必须自洽：端到端预算至少要覆盖首字预算与剩余 token 的解码预算。
 * 否则一份“三项都达标”的预算在最大输出时必然违约。
 */
export function assertBudgetCoversTokens(budget: LatencyBudget, maxOutputTokens: number): void {
  for (const [label, value] of Object.entries(budget)) assertTimestamp(value, label);
  if (maxOutputTokens < 1 || !Number.isInteger(maxOutputTokens)) {
    fail("maxOutputTokens 必须是正整数");
  }
  const minimum = budget.ttftMs + budget.tpotMs * (maxOutputTokens - 1);
  if (budget.e2eMs < minimum) {
    fail(`e2eMs=${budget.e2eMs} 覆盖不了 ttftMs + tpotMs×(tokens-1)=${minimum}`);
  }
}

export interface BudgetViolation {
  metric: "ttft" | "tpot" | "e2e";
  actualMs: number;
  budgetMs: number;
}

/** 三项分开判定，避免一个超标的平均值把首字违约掩盖掉。 */
export function checkLatencyBudget(
  breakdown: LatencyBreakdown,
  budget: LatencyBudget,
): { ok: boolean; violations: BudgetViolation[] } {
  const violations: BudgetViolation[] = [];
  if (breakdown.firstToken.ttftMs > budget.ttftMs) {
    violations.push({ metric: "ttft", actualMs: breakdown.firstToken.ttftMs, budgetMs: budget.ttftMs });
  }
  if (breakdown.tpotMs > budget.tpotMs) {
    violations.push({ metric: "tpot", actualMs: breakdown.tpotMs, budgetMs: budget.tpotMs });
  }
  if (breakdown.e2eMs > budget.e2eMs) {
    violations.push({ metric: "e2e", actualMs: breakdown.e2eMs, budgetMs: budget.e2eMs });
  }
  return { ok: violations.length === 0, violations };
}

export interface LatencySummary {
  samples: number;
  ttftP50Ms: number;
  ttftP95Ms: number;
  itlP95Ms: number;
  tpotP50Ms: number;
  tpotP95Ms: number;
  e2eP50Ms: number;
  e2eP95Ms: number;
}

function pick(values: readonly number[], ratio: number): number {
  return percentile(values, ratio);
}

/**
 * 汇总只报分位数，不报平均值。
 * 流式体验由首字和长尾决定，平均值会把一次 3 秒的冷启动抹成“还不错”。
 */
export function summarizeLatency(breakdowns: readonly LatencyBreakdown[]): LatencySummary {
  const ttft = breakdowns.map((item) => item.firstToken.ttftMs);
  const tpot = breakdowns.map((item) => item.tpotMs);
  const e2e = breakdowns.map((item) => item.e2eMs);
  const itl = breakdowns.flatMap((item) => item.itlMs);
  return {
    samples: breakdowns.length,
    ttftP50Ms: pick(ttft, 0.5),
    ttftP95Ms: pick(ttft, 0.95),
    itlP95Ms: pick(itl, 0.95),
    tpotP50Ms: pick(tpot, 0.5),
    tpotP95Ms: pick(tpot, 0.95),
    e2eP50Ms: pick(e2e, 0.5),
    e2eP95Ms: pick(e2e, 0.95),
  };
}

node --test test/perf/metrics.test.ts

ℹ tests 6
ℹ pass 6
ℹ fail 0
ℹ duration_ms 177.025208