《互联网产品的 AI 架构·推理性能与成本工程》13.2 优化方案与 ADR

月节省 = 平均成本 × 月请求量 × 降本比例
回本期 = 实施成本 ÷ (月节省 ÷ 30)

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

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

export type RiskLevel = "low" | "medium" | "high";

/** ADR 的输入必须是 13.1 报告里的同一组数字，不能用另一套口径。 */
export interface AdrBaseline {
  avgCostMicros: number;
  e2eP95Ms: number;
  qualityMean: number;
  monthlyRequests: number;
}

export interface AdrCandidate {
  id: string;
  title: string;
  levers: string[];
  /** 负数表示降本；正数表示会涨价。 */
  costDeltaPct: number;
  p95DeltaPct: number;
  /** 质量分变化，单位是百分点；-1.5 表示从 0.882 降到 0.867。 */
  qualityDeltaPts: number;
  implementationCostMicros: number;
  evidenceSamples: number;
  risk: RiskLevel;
  reversible: boolean;
  rollback: string[];
  exit: string[];
}

export interface AdrPolicy {
  maxQualityDropPts: number;
  maxP95IncreasePct: number;
  minEvidenceSamples: number;
  allowHighRisk: boolean;
}

export const DEFAULT_ADR_POLICY: AdrPolicy = {
  maxQualityDropPts: 1.5,
  maxP95IncreasePct: 10,
  minEvidenceSamples: 200,
  allowHighRisk: false,
};

export interface CandidateAssessment {
  id: string;
  title: string;
  eligible: boolean;
  reasons: string[];
  savingsMicrosPerMonth: number;
  qualityAfter: number;
  p95AfterMs: number;
  paybackDays: number;
  reversibility: "reversible" | "one-way";
  risk: RiskLevel;
}

export interface AdrAlternative {
  id: string;
  verdict: "accepted" | "rejected";
  reason: string;
}

export interface AdrRecord {
  id: string;
  title: string;
  status: "accepted" | "rejected";
  context: string;
  decision: string;
  consequences: string[];
  alternatives: AdrAlternative[];
}

export interface AdrDecision {
  status: "accepted" | "rejected";
  chosen: string | null;
  assessments: CandidateAssessment[];
  adr: AdrRecord;
}

const RISK_ORDER: Record<RiskLevel, number> = { low: 0, medium: 1, high: 2 };

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

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

function validateCandidate(candidate: AdrCandidate): void {
  for (const field of ["id", "title"] as const) {
    if (candidate[field].trim() === "") fail(`${field} is required`);
  }
  if (candidate.levers.length === 0) fail(`${candidate.id}: levers must not be empty`);
  integer(candidate.evidenceSamples, `${candidate.id}.evidenceSamples`, 1);
  integer(candidate.implementationCostMicros, `${candidate.id}.implementationCostMicros`);
  if (!Number.isFinite(candidate.costDeltaPct)) fail(`${candidate.id}: costDeltaPct must be finite`);
  if (candidate.rollback.length === 0) fail(`${candidate.id}: rollback conditions are required`);
  if (candidate.exit.length === 0) fail(`${candidate.id}: exit conditions are required`);
}

function assess(
  baseline: AdrBaseline,
  candidate: AdrCandidate,
  policy: AdrPolicy,
): CandidateAssessment {
  validateCandidate(candidate);
  const savingsMicrosPerMonth = Math.round(
    baseline.avgCostMicros * baseline.monthlyRequests * (-candidate.costDeltaPct / 100),
  );
  const qualityAfter = Number((baseline.qualityMean + candidate.qualityDeltaPts / 100).toFixed(3));
  const p95AfterMs = Math.round(baseline.e2eP95Ms * (1 + candidate.p95DeltaPct / 100));
  const dailySavings = savingsMicrosPerMonth / 30;
  const paybackDays = savingsMicrosPerMonth <= 0
    ? Number.POSITIVE_INFINITY
    : Math.ceil(candidate.implementationCostMicros / dailySavings);

  const reasons: string[] = [];
  if (candidate.evidenceSamples < policy.minEvidenceSamples) {
    reasons.push(`evidence ${candidate.evidenceSamples} < ${policy.minEvidenceSamples}`);
  }
  if (-candidate.qualityDeltaPts > policy.maxQualityDropPts) {
    reasons.push(`quality drop ${(-candidate.qualityDeltaPts).toFixed(2)} > ${policy.maxQualityDropPts}`);
  }
  if (candidate.p95DeltaPct > policy.maxP95IncreasePct) {
    reasons.push(`p95 increase ${candidate.p95DeltaPct}% > ${policy.maxP95IncreasePct}%`);
  }
  if (candidate.risk === "high" && !policy.allowHighRisk) {
    reasons.push("high risk is not allowed by policy");
  }
  if (!candidate.reversible) reasons.push("candidate is one-way; no rollback path");
  if (savingsMicrosPerMonth <= 0) reasons.push("no positive monthly saving");

  return {
    id: candidate.id,
    title: candidate.title,
    eligible: reasons.length === 0,
    reasons,
    savingsMicrosPerMonth,
    qualityAfter,
    p95AfterMs,
    paybackDays,
    reversibility: candidate.reversible ? "reversible" : "one-way",
    risk: candidate.risk,
  };
}

function pick(assessments: readonly CandidateAssessment[]): CandidateAssessment | null {
  const eligible = assessments.filter((item) => item.eligible);
  if (eligible.length === 0) return null;
  return [...eligible].sort((left, right) =>
    right.savingsMicrosPerMonth - left.savingsMicrosPerMonth ||
    RISK_ORDER[left.risk] - RISK_ORDER[right.risk] ||
    left.p95AfterMs - right.p95AfterMs ||
    left.id.localeCompare(right.id))[0];
}

/**
 * 决策函数只做三件事：按护栏淘汰、按收益排序、把结果写成 ADR。
 * 回退条件与退出条件必须分开：前者是失败时怎么撤，后者是什么时候停止投入。
 */
export function decideAdr(
  baseline: AdrBaseline,
  candidates: readonly AdrCandidate[],
  policy: AdrPolicy = DEFAULT_ADR_POLICY,
): AdrDecision {
  if (candidates.length === 0) fail("至少需要一个候选方案");
  integer(baseline.monthlyRequests, "baseline.monthlyRequests", 1);
  if (!Number.isFinite(baseline.avgCostMicros) || baseline.avgCostMicros < 0) fail("baseline.avgCostMicros 非法");
  if (!Number.isFinite(baseline.e2eP95Ms) || baseline.e2eP95Ms < 0) fail("baseline.e2eP95Ms 非法");
  if (!Number.isFinite(baseline.qualityMean) || baseline.qualityMean < 0 || baseline.qualityMean > 1) {
    fail("baseline.qualityMean 必须落在 [0, 1]");
  }

  const assessments = candidates.map((candidate) => assess(baseline, candidate, policy));
  const chosen = pick(assessments);
  const byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
  const alternatives: AdrAlternative[] = assessments.map((item) => ({
    id: item.id,
    verdict: item.id === chosen?.id ? "accepted" : "rejected",
    reason: item.id === chosen?.id
      ? `savings ${item.savingsMicrosPerMonth} micros/month, payback ${item.paybackDays} days`
      : item.reasons.length > 0 ? item.reasons.join("; ") : "lower saving than the accepted option",
  }));

  const context =
    `baseline: ${baseline.avgCostMicros} micros/request, p95 ${baseline.e2eP95Ms}ms, ` +
    `quality ${baseline.qualityMean.toFixed(3)}, ${baseline.monthlyRequests} requests/month; ` +
    `policy: quality drop <= ${policy.maxQualityDropPts}pts, p95 increase <= ${policy.maxP95IncreasePct}%, ` +
    `evidence >= ${policy.minEvidenceSamples}.`;
  const consequences = chosen === null
    ? ["没有候选方案同时满足收益与护栏；保持基线，补充证据后再决策"]
    : [
      ...byId.get(chosen.id)!.exit.map((condition) => `退出条件：${condition}`),
      ...byId.get(chosen.id)!.rollback.map((condition) => `回退条件：${condition}`),
      `预期质量 ${chosen.qualityAfter.toFixed(3)}，P95 ${chosen.p95AfterMs}ms，回本期 ${chosen.paybackDays} 天`,
    ];

  return {
    status: chosen === null ? "rejected" : "accepted",
    chosen: chosen?.id ?? null,
    assessments,
    adr: {
      id: "ADR-013",
      title: chosen === null ? "本轮不采纳成本优化方案" : `采纳「${chosen.title}」`,
      status: chosen === null ? "rejected" : "accepted",
      context,
      decision: chosen === null
        ? "所有候选方案至少违反一项护栏，暂不改变基线。"
        : `采纳「${chosen.title}」，预计每月节省 ${chosen.savingsMicrosPerMonth} 微元，` +
          `回本期 ${chosen.paybackDays} 天。`,
      consequences,
      alternatives,
    },
  };
}