《互联网产品的 AI 架构·推理性能与成本工程》8.2 峰值、余量与弹性

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

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

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

function finite(value: number, field: string, min = 0): number {
  if (!Number.isFinite(value) || value < min) fail(`${field} must be a finite number >= ${min}`);
  return value;
}

function integer(value: number, field: string, min = 0): number {
  if (!Number.isInteger(value) || value < min) fail(`${field} must be an integer >= ${min}`);
  return value;
}

export interface LoadWindow {
  windowSeconds: number;
  requests: number;
}

export interface PeakOptions {
  /** 最近秩法的分位点，默认 0.95。 */
  percentile?: number;
  /** 在持续峰值之上再留的估算误差。 */
  marginRatio?: number;
}

export interface PeakEstimate {
  windows: number;
  observedPeakRps: number;
  sustainedPeakRps: number;
  plannedPeakRps: number;
  marginRatio: number;
}

/** 最近秩法取真实窗口，不用插值造出不存在的峰值。 */
function nearestRank(values: readonly number[], ratio: number): number {
  const sorted = [...values].sort((left, right) => left - right);
  const rank = Math.max(0, Math.min(sorted.length - 1, Math.ceil(ratio * sorted.length) - 1));
  return sorted[rank];
}

/** 观测峰值容易被单个尖峰带偏，持续峰值取窗口速率的 P95，再乘估算余量。 */
export function estimatePeakRate(windows: readonly LoadWindow[], options: PeakOptions = {}): PeakEstimate {
  if (windows.length === 0) fail("load windows must not be empty");
  const percentile = options.percentile ?? 0.95;
  const margin = options.marginRatio ?? 0.1;
  if (!(percentile > 0 && percentile <= 1)) fail("percentile must be in (0, 1]");
  if (margin < 0) fail("marginRatio must be >= 0");
  const rates = windows.map((window, index) => {
    if (!Number.isFinite(window.windowSeconds) || window.windowSeconds <= 0) {
      fail(`windows[${index}].windowSeconds must be > 0`);
    }
    finite(window.requests, `windows[${index}].requests`);
    return window.requests / window.windowSeconds;
  });
  const observed = Math.max(...rates);
  const sustained = nearestRank(rates, percentile);
  return {
    windows: windows.length,
    observedPeakRps: observed,
    sustainedPeakRps: sustained,
    plannedPeakRps: sustained * (1 + margin),
    marginRatio: margin,
  };
}

export interface CapacityInput {
  peakRps: number;
  headroomRatio: number;
  /** 单实例在目标利用率下的可持续 RPS，不是理论峰值。 */
  instanceRps: number;
  minInstances?: number;
}

export interface CapacityPlan {
  requiredRps: number;
  peakInstances: number;
  requiredInstances: number;
  spareInstances: number;
  spareRps: number;
  utilizationAtPeak: number;
  effectiveHeadroomRatio: number;
}

/** 实例是整数，余量最终体现为整实例的空闲容量。 */
export function planCapacity(input: CapacityInput): CapacityPlan {
  finite(input.peakRps, "peakRps");
  finite(input.headroomRatio, "headroomRatio");
  finite(input.instanceRps, "instanceRps");
  if (input.instanceRps <= 0) fail("instanceRps must be > 0");
  const minInstances = integer(input.minInstances ?? 0, "minInstances");
  const requiredRps = input.peakRps * (1 + input.headroomRatio);
  const peakInstances = Math.ceil(input.peakRps / input.instanceRps);
  const requiredInstances = Math.max(minInstances, Math.ceil(requiredRps / input.instanceRps));
  const capacityRps = requiredInstances * input.instanceRps;
  return {
    requiredRps,
    peakInstances,
    requiredInstances,
    spareInstances: requiredInstances - peakInstances,
    spareRps: capacityRps - input.peakRps,
    utilizationAtPeak: input.peakRps / capacityRps,
    effectiveHeadroomRatio: capacityRps / input.peakRps - 1,
  };
}

export interface ScaleUpInput {
  warmInstances: number;
  addInstances: number;
  instanceRps: number;
  coldStartMs: number;
  arrivalRps: number;
  backlogRequests?: number;
}

export interface ScaleUpResult {
  warmCapacityRps: number;
  totalCapacityRps: number;
  deficitRps: number;
  backlogAtReady: number;
  drainSeconds: number | null;
  drained: boolean;
}

function round3(value: number): number {
  return Math.round(value * 1000) / 1000;
}

/**
 * 冷启动期间新实例不贡献容量，超出的到达量全部变成积压。
 * 就绪后若总容量仍低于到达量，积压只会继续增长。
 */
export function simulateScaleUp(input: ScaleUpInput): ScaleUpResult {
  integer(input.warmInstances, "warmInstances");
  integer(input.addInstances, "addInstances");
  finite(input.instanceRps, "instanceRps");
  if (input.instanceRps <= 0) fail("instanceRps must be > 0");
  finite(input.coldStartMs, "coldStartMs");
  finite(input.arrivalRps, "arrivalRps");
  const initialBacklog = finite(input.backlogRequests ?? 0, "backlogRequests");
  const warmCapacityRps = input.warmInstances * input.instanceRps;
  const totalCapacityRps = (input.warmInstances + input.addInstances) * input.instanceRps;
  const deficitRps = Math.max(0, input.arrivalRps - warmCapacityRps);
  const backlogAtReady = initialBacklog + deficitRps * (input.coldStartMs / 1000);
  const surplusRps = totalCapacityRps - input.arrivalRps;
  if (backlogAtReady === 0) {
    return {
      warmCapacityRps, totalCapacityRps, deficitRps: round3(deficitRps),
      backlogAtReady: 0, drainSeconds: 0, drained: true,
    };
  }
  if (surplusRps <= 0) {
    return {
      warmCapacityRps, totalCapacityRps, deficitRps: round3(deficitRps),
      backlogAtReady: round3(backlogAtReady), drainSeconds: null, drained: false,
    };
  }
  return {
    warmCapacityRps, totalCapacityRps, deficitRps: round3(deficitRps),
    backlogAtReady: round3(backlogAtReady), drainSeconds: round3(backlogAtReady / surplusRps), drained: true,
  };
}

export interface HeadroomCostInput {
  spareInstances: number;
  instanceMicrosPerHour: number;
  hoursPerDay?: number;
}

/** 固定余量的代价：空闲实例按小时计费，换来确定性的峰值承载能力。 */
export function headroomCostMicros(input: HeadroomCostInput): number {
  finite(input.spareInstances, "spareInstances");
  integer(input.instanceMicrosPerHour, "instanceMicrosPerHour");
  const hours = input.hoursPerDay ?? 24;
  finite(hours, "hoursPerDay");
  return Math.round(input.spareInstances * input.instanceMicrosPerHour * hours);
}

node examples/perf/peak-plan.ts

observed_peak_rps=12.667
sustained_peak_rps=11.667
planned_peak_rps=13.417
required_rps=17.442
instances=6/7
utilization_at_peak=76.67%
spare_rps=4.083
cold_deficit_rps=5
cold_backlog=450
drain_seconds=180
idle_cost_micros_per_day=2880000