《互联网产品的 AI 架构·推理性能与成本工程》5.1 结果缓存的经济性判据

净收益 = H × (Cg − Ch) − N × Cl − E × Cs − 失效次数 × Ci − H × p × Ce

命中率* = (Cl + (E × Cs + 失效次数 × Ci) / N) / (Cg − Ch − p × Ce)

条目边际收益 = 期望复用次数 × (Cg − Ch) − 条目存储成本

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

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

/** 一个能力在统计窗口内的缓存收支，金额一律是整数微元。 */
export interface CapabilityCacheEcon {
  capability: string;
  requests: number;
  hits: number;
  /** 一次未命中原本要花的生成成本。 */
  generationMicros: number;
  /** 一次命中从缓存取回并传输的成本。 */
  hitServeMicros: number;
  /** 每次请求都要付的查找成本，命中与未命中都算。 */
  lookupMicros: number;
  /** 窗口内保留的条目数。 */
  entries: number;
  /** 每个条目在窗口内的存储摊销。 */
  storageMicrosPerEntry: number;
  invalidationEvents: number;
  invalidationMicrosPerEvent: number;
  /** 语义命中里被判定为错误的比例。 */
  falseHitRate: number;
  /** 一次误命中的返工、投诉与补偿成本。 */
  falseHitCostMicros: number;
}

export interface CacheCostBreakdown {
  lookupMicros: number;
  storageMicros: number;
  invalidationMicros: number;
  totalMicros: number;
}

export interface CapabilityCacheReport {
  capability: string;
  requests: number;
  hits: number;
  hitRate: number;
  grossBenefitMicros: number;
  overhead: CacheCostBreakdown;
  falseHitCostMicros: number;
  netBenefitMicros: number;
  netPerRequestMicros: number;
  /** 每请求固定开销除以“每次命中净省”，低于它缓存必亏。 */
  breakEvenHitRate: number;
  /** 净收益占毛收益的比例，用来区分“赚一点”和“值得做”。 */
  marginRatio: number;
  verdict: "profitable" | "marginal" | "loses";
}

export interface CacheEconomicsReport {
  requests: number;
  hits: number;
  hitRate: number;
  grossBenefitMicros: number;
  overhead: CacheCostBreakdown;
  falseHitCostMicros: number;
  netBenefitMicros: number;
  netPerRequestMicros: number;
  noCacheMicros: number;
  withCacheMicros: number;
  costReduction: number;
  byCapability: CapabilityCacheReport[];
  losingCapabilities: string[];
}

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

function requireInteger(value: number, field: string, min: number): number {
  if (!Number.isInteger(value) || value < min) fail(`${field} 必须是 >= ${min} 的整数`);
  return value;
}

function requireRatio(value: number, field: string): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
    fail(`${field} 必须落在 [0, 1]`);
  }
  return value;
}

function validate(item: CapabilityCacheEcon): void {
  if (item.capability.trim() === "") fail("capability 不能为空");
  requireInteger(item.requests, "requests", 1);
  requireInteger(item.hits, "hits", 0);
  if (item.hits > item.requests) fail(`${item.capability}: hits 不能大于 requests`);
  requireInteger(item.generationMicros, "generationMicros", 0);
  requireInteger(item.hitServeMicros, "hitServeMicros", 0);
  requireInteger(item.lookupMicros, "lookupMicros", 0);
  requireInteger(item.entries, "entries", 0);
  requireInteger(item.storageMicrosPerEntry, "storageMicrosPerEntry", 0);
  requireInteger(item.invalidationEvents, "invalidationEvents", 0);
  requireInteger(item.invalidationMicrosPerEvent, "invalidationMicrosPerEvent", 0);
  requireRatio(item.falseHitRate, "falseHitRate");
  requireInteger(item.falseHitCostMicros, "falseHitCostMicros", 0);
}

/**
 * 盈亏平衡命中率 = 每请求固定开销 / 每次命中的净节省。
 * 分母里扣掉命中服务成本与期望误命中成本，所以“命中率高”本身不构成理由。
 */
export function breakEvenHitRate(item: CapabilityCacheEcon): number {
  validate(item);
  const fixedPerRequest =
    item.lookupMicros +
    (item.entries * item.storageMicrosPerEntry + item.invalidationEvents * item.invalidationMicrosPerEvent) /
      item.requests;
  const savingPerHit =
    item.generationMicros - item.hitServeMicros - item.falseHitRate * item.falseHitCostMicros;
  if (savingPerHit <= 0) return Number.POSITIVE_INFINITY;
  return fixedPerRequest / savingPerHit;
}

/** 单个能力的缓存账：毛收益减查找、存储、失效与误命中，剩下的才是净收益。 */
export function evaluateCapabilityCache(item: CapabilityCacheEcon): CapabilityCacheReport {
  validate(item);
  const grossBenefitMicros = item.hits * (item.generationMicros - item.hitServeMicros);
  const overhead: CacheCostBreakdown = {
    lookupMicros: item.requests * item.lookupMicros,
    storageMicros: item.entries * item.storageMicrosPerEntry,
    invalidationMicros: item.invalidationEvents * item.invalidationMicrosPerEvent,
    totalMicros: 0,
  };
  overhead.totalMicros =
    overhead.lookupMicros + overhead.storageMicros + overhead.invalidationMicros;
  const falseHitCostMicros = Math.round(item.hits * item.falseHitRate * item.falseHitCostMicros);
  const netBenefitMicros = grossBenefitMicros - overhead.totalMicros - falseHitCostMicros;
  const marginRatio = grossBenefitMicros === 0 ? 0 : netBenefitMicros / grossBenefitMicros;
  return {
    capability: item.capability,
    requests: item.requests,
    hits: item.hits,
    hitRate: item.hits / item.requests,
    grossBenefitMicros,
    overhead,
    falseHitCostMicros,
    netBenefitMicros,
    netPerRequestMicros: netBenefitMicros / item.requests,
    breakEvenHitRate: breakEvenHitRate(item),
    marginRatio,
    verdict: netBenefitMicros < 0 ? "loses" : marginRatio < 0.2 ? "marginal" : "profitable",
  };
}

function sumOverhead(reports: readonly CapabilityCacheReport[]): CacheCostBreakdown {
  const total = reports.reduce(
    (acc, report) => ({
      lookupMicros: acc.lookupMicros + report.overhead.lookupMicros,
      storageMicros: acc.storageMicros + report.overhead.storageMicros,
      invalidationMicros: acc.invalidationMicros + report.overhead.invalidationMicros,
      totalMicros: acc.totalMicros + report.overhead.totalMicros,
    }),
    { lookupMicros: 0, storageMicros: 0, invalidationMicros: 0, totalMicros: 0 },
  );
  return total;
}

/** 汇总时先算每个能力的净收益再相加，避免用整体命中率掩盖某个亏损能力。 */
export function evaluateCacheEconomics(
  items: readonly CapabilityCacheEcon[],
): CacheEconomicsReport {
  if (items.length === 0) fail("没有能力样本，无法评估缓存经济性");
  const byCapability = items.map(evaluateCapabilityCache);
  const requests = byCapability.reduce((sum, report) => sum + report.requests, 0);
  const hits = byCapability.reduce((sum, report) => sum + report.hits, 0);
  const grossBenefitMicros = byCapability.reduce((sum, report) => sum + report.grossBenefitMicros, 0);
  const falseHitCostMicros = byCapability.reduce((sum, report) => sum + report.falseHitCostMicros, 0);
  const netBenefitMicros = byCapability.reduce((sum, report) => sum + report.netBenefitMicros, 0);
  const noCacheMicros = items.reduce(
    (sum, item) => sum + item.requests * item.generationMicros,
    0,
  );
  return {
    requests,
    hits,
    hitRate: hits / requests,
    grossBenefitMicros,
    overhead: sumOverhead(byCapability),
    falseHitCostMicros,
    netBenefitMicros,
    netPerRequestMicros: netBenefitMicros / requests,
    noCacheMicros,
    withCacheMicros: noCacheMicros - netBenefitMicros,
    costReduction: noCacheMicros === 0 ? 0 : netBenefitMicros / noCacheMicros,
    byCapability,
    losingCapabilities: byCapability
      .filter((report) => report.verdict === "loses")
      .map((report) => report.capability),
  };
}

/**
 * 命中的复用窗口必须先覆盖“写入 + 失效传播 + 下一次读到”的时间。
 * 返回窗口内可被复用的次数；小于 1 表示条目活不到下一次命中。
 */
export function reuseWindowHits(reuseIntervalMs: number, entryLifetimeMs: number): number {
  if (!Number.isFinite(reuseIntervalMs) || reuseIntervalMs <= 0) {
    fail("reuseIntervalMs 必须是正有限数");
  }
  if (!Number.isFinite(entryLifetimeMs) || entryLifetimeMs < 0) {
    fail("entryLifetimeMs 必须是非负有限数");
  }
  return Math.floor(entryLifetimeMs / reuseIntervalMs);
}

/**
 * 单个条目的边际收益：被再读一次省下的生成成本，减去它占用的存储。
 * 用来判断“这条结果值不值得留”，而不是只看整体命中率。
 */
export function entryMarginalMicros(
  generationMicros: number,
  hitServeMicros: number,
  storageMicrosPerEntry: number,
  expectedReuses: number,
): number {
  requireInteger(generationMicros, "generationMicros", 0);
  requireInteger(hitServeMicros, "hitServeMicros", 0);
  requireInteger(storageMicrosPerEntry, "storageMicrosPerEntry", 0);
  if (!Number.isFinite(expectedReuses) || expectedReuses < 0) {
    fail("expectedReuses 必须是非负有限数");
  }
  return (
    expectedReuses * (generationMicros - hitServeMicros) - storageMicrosPerEntry
  );
}

node --test test/perf/cache-econ.test.ts

ℹ tests 7
ℹ pass 7
ℹ fail 0
ℹ duration_ms 184.97075