《互联网产品的 AI 架构·推理性能与成本工程》5.3 缓存失效与一致性

// file: src/perf/cache-consistency.ts
// tier: L2
// verify: node --test test/perf/cache-consistency.test.ts

import { AiError } from "../core/errors.ts";
import type { CacheAccess } from "./cache-tiers.ts";
import { simulateLayer } from "./cache-tiers.ts";

export interface TenantAccess extends CacheAccess {
  tenantId: string;
}

export interface TenantCapacityReport {
  requests: number;
  sharedHits: number;
  partitionedHits: number;
  /** 分区后少掉的命中次数，正数表示容量碎片化的代价。 */
  lostHits: number;
}

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

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

/**
 * 同样总容量下，按租户均分与共享池的命中差异。
 * 键必须带租户前缀：共享池省内存，但绝不能省隔离。
 */
export function compareTenantCapacity(
  accesses: readonly TenantAccess[],
  sharedCapacity: number,
  perTenantCapacity: number,
): TenantCapacityReport {
  if (accesses.length === 0) fail("访问序列不能为空");
  requireInteger(sharedCapacity, "sharedCapacity", 0);
  requireInteger(perTenantCapacity, "perTenantCapacity", 0);

  const tenants = new Set<string>();
  const sharedTrace: CacheAccess[] = accesses.map((access) => {
    if (access.tenantId.trim() === "") fail("tenantId 不能为空");
    tenants.add(access.tenantId);
    return {
      key: `${access.tenantId}\u0000${access.key}`,
      cluster: access.cluster === undefined ? undefined : `${access.tenantId}\u0000${access.cluster}`,
    };
  });

  const sharedHits = simulateLayer(sharedTrace, sharedCapacity, "lru").hits;
  let partitionedHits = 0;
  for (const tenantId of tenants) {
    const own = accesses
      .filter((access) => access.tenantId === tenantId)
      .map((access) => ({ key: access.key, cluster: access.cluster }));
    partitionedHits += simulateLayer(own, perTenantCapacity, "lru").hits;
  }
  return {
    requests: accesses.length,
    sharedHits,
    partitionedHits,
    lostHits: sharedHits - partitionedHits,
  };
}

export interface InvalidationOption {
  strategy: "coarse" | "fine";
  entries: number;
  staleEntries: number;
  /** 一条本可命中的结果被误删后，重建它的成本。 */
  hitValueMicros: number;
  propagationMicrosPerEntry: number;
  /** 细粒度失效需要维护“事实到缓存键”的索引，每次写入都要付。 */
  indexMicrosPerWrite: number;
  writes: number;
}

export interface InvalidationCost {
  strategy: "coarse" | "fine";
  purgedEntries: number;
  wastedRebuilds: number;
  propagationMicros: number;
  indexMicros: number;
  wastedHitValueMicros: number;
  totalMicros: number;
}

function evaluateInvalidation(option: InvalidationOption): InvalidationCost {
  requireInteger(option.entries, "entries", 1);
  requireInteger(option.staleEntries, "staleEntries", 0);
  if (option.staleEntries > option.entries) fail("staleEntries 不能大于 entries");
  requireInteger(option.hitValueMicros, "hitValueMicros", 0);
  requireInteger(option.propagationMicrosPerEntry, "propagationMicrosPerEntry", 0);
  requireInteger(option.indexMicrosPerWrite, "indexMicrosPerWrite", 0);
  requireInteger(option.writes, "writes", 0);

  const purgedEntries = option.strategy === "coarse" ? option.entries : option.staleEntries;
  const wastedRebuilds = purgedEntries - option.staleEntries;
  const propagationMicros = purgedEntries * option.propagationMicrosPerEntry;
  const indexMicros = option.strategy === "fine" ? option.writes * option.indexMicrosPerWrite : 0;
  const wastedHitValueMicros = wastedRebuilds * option.hitValueMicros;
  return {
    strategy: option.strategy,
    purgedEntries,
    wastedRebuilds,
    propagationMicros,
    indexMicros,
    wastedHitValueMicros,
    totalMicros: propagationMicros + indexMicros + wastedHitValueMicros,
  };
}

/** 粗粒度失效便宜在索引，贵在误删；细粒度相反。比较的是总成本，不是删除条数。 */
export function compareInvalidation(
  coarse: InvalidationOption,
  fine: InvalidationOption,
): { coarse: InvalidationCost; fine: InvalidationCost; preferred: "coarse" | "fine"; savingMicros: number } {
  if (coarse.strategy !== "coarse" || fine.strategy !== "fine") {
    fail("compareInvalidation 需要一条 coarse 与一条 fine 方案");
  }
  const left = evaluateInvalidation(coarse);
  const right = evaluateInvalidation(fine);
  return {
    coarse: left,
    fine: right,
    preferred: left.totalMicros <= right.totalMicros ? "coarse" : "fine",
    savingMicros: Math.abs(left.totalMicros - right.totalMicros),
  };
}

export interface WilsonInterval {
  point: number;
  low: number;
  high: number;
}

/** 误命中率是小比例事件，用 Wilson 区间比正态近似更稳，样本少时不会给出负下界。 */
export function wilsonInterval(successes: number, total: number, z = 1.96): WilsonInterval {
  requireInteger(successes, "successes", 0);
  requireInteger(total, "total", 1);
  if (successes > total) fail("successes 不能大于 total");
  if (!(z > 0) || !Number.isFinite(z)) fail("z 必须是正有限数");
  const point = successes / total;
  const denominator = 1 + (z * z) / total;
  const centre = point + (z * z) / (2 * total);
  const spread = z * Math.sqrt((point * (1 - point)) / total + (z * z) / (4 * total * total));
  return {
    point,
    low: Math.max(0, (centre - spread) / denominator),
    high: Math.min(1, (centre + spread) / denominator),
  };
}

export interface FalseHitAuditInput {
  hits: number;
  falseHits: number;
  savedMicrosPerHit: number;
  falseHitCostMicros: number;
  z?: number;
}

export interface FalseHitAuditReport extends WilsonInterval {
  /** 预算 = 单次命中净省 / 单次误命中代价。 */
  budget: number;
  verdict: "within-budget" | "over-budget" | "inconclusive";
}

/** 审计结论看区间上界，不看点估计：样本少时“看起来达标”可能只是没抽到。 */
export function auditFalseHits(input: FalseHitAuditInput): FalseHitAuditReport {
  requireInteger(input.hits, "hits", 1);
  requireInteger(input.falseHits, "falseHits", 0);
  if (input.falseHits > input.hits) fail("falseHits 不能大于 hits");
  requireInteger(input.savedMicrosPerHit, "savedMicrosPerHit", 0);
  requireInteger(input.falseHitCostMicros, "falseHitCostMicros", 0);
  const interval = wilsonInterval(input.falseHits, input.hits, input.z ?? 1.96);
  const budget =
    input.falseHitCostMicros === 0
      ? 1
      : Math.min(1, input.savedMicrosPerHit / input.falseHitCostMicros);
  const verdict =
    interval.high <= budget ? "within-budget" : interval.low > budget ? "over-budget" : "inconclusive";
  return { ...interval, budget, verdict };
}

export interface VersionRetentionReport {
  retain: boolean;
  expectedSavingMicros: number;
  storageCostMicros: number;
  netMicros: number;
}

/**
 * 回滚时保留上一版本的缓存，等价于买一份保险：
 * 期望省下的冷启动重建成本，要大于多占一份内存的存储成本。
 */
export function evaluateVersionRetention(
  entries: number,
  rebuildCostMicros: number,
  storageMicrosPerEntry: number,
  rollbackProbability: number,
): VersionRetentionReport {
  requireInteger(entries, "entries", 0);
  requireInteger(rebuildCostMicros, "rebuildCostMicros", 0);
  requireInteger(storageMicrosPerEntry, "storageMicrosPerEntry", 0);
  if (!(rollbackProbability >= 0 && rollbackProbability <= 1)) {
    fail("rollbackProbability 必须落在 [0, 1]");
  }
  const expectedSavingMicros = Math.round(rollbackProbability * entries * rebuildCostMicros);
  const storageCostMicros = entries * storageMicrosPerEntry;
  const netMicros = expectedSavingMicros - storageCostMicros;
  return { retain: netMicros > 0, expectedSavingMicros, storageCostMicros, netMicros };
}

export interface StaleDecisionInput {
  ageMs: number;
  ttlMs: number;
  maxStaleMs: number;
  staleServeCostMicros: number;
  degradeCostMicros: number;
  failCostMicros: number;
  degradedAvailable: boolean;
}

export interface StaleDecision {
  decision: "fresh" | "serve-stale" | "degrade" | "fail";
  expectedCostMicros: number;
  reason: string;
}

/**
 * 缓存与降级的交互：过期不等于必须回源。
 * 只有在 stale 窗口内、且“送旧结果”的代价不高于降级或失败时，才允许送旧。
 */
export function decideStale(input: StaleDecisionInput): StaleDecision {
  if (!Number.isFinite(input.ageMs) || input.ageMs < 0) fail("ageMs 必须是非负有限数");
  if (!Number.isFinite(input.ttlMs) || input.ttlMs < 0) fail("ttlMs 必须是非负有限数");
  if (!Number.isFinite(input.maxStaleMs) || input.maxStaleMs < 0) fail("maxStaleMs 必须是非负有限数");
  requireInteger(input.staleServeCostMicros, "staleServeCostMicros", 0);
  requireInteger(input.degradeCostMicros, "degradeCostMicros", 0);
  requireInteger(input.failCostMicros, "failCostMicros", 0);

  if (input.ageMs <= input.ttlMs) {
    return { decision: "fresh", expectedCostMicros: 0, reason: "within-ttl" };
  }
  const staleMs = input.ageMs - input.ttlMs;
  const alternatives: Array<{ decision: StaleDecision["decision"]; cost: number; reason: string }> = [];
  if (staleMs <= input.maxStaleMs) {
    alternatives.push({ decision: "serve-stale", cost: input.staleServeCostMicros, reason: "stale-within-window" });
  }
  if (input.degradedAvailable) {
    alternatives.push({ decision: "degrade", cost: input.degradeCostMicros, reason: "degraded-available" });
  }
  alternatives.push({ decision: "fail", cost: input.failCostMicros, reason: "no-alternative" });
  alternatives.sort((left, right) => left.cost - right.cost);
  return {
    decision: alternatives[0].decision,
    expectedCostMicros: alternatives[0].cost,
    reason: alternatives[0].reason,
  };
}

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

ℹ tests 8
ℹ pass 8
ℹ fail 0
ℹ duration_ms 149.624417