《互联网产品的 AI 架构·推理性能与成本工程》12.2 降级链的成本约束

requestCost = Σ (stepRuns × stepCost) + failedAttemptCost

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

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

export type DegradeKind = "primary" | "small-model" | "rules" | "template" | "queue";

/** 降级链上的一步：成本、时间、质量与重试次数都必须显式声明。 */
export interface CostedStep {
  id: string; kind: DegradeKind;
  /** 越小越先执行；顺序是产品决策，不由成本公式自动排序。 */
  priority: number;
  /** 入场成本估计，整数微元；实际成本以处理器返回为准。 */
  estimatedMicros: number; estimatedMs: number;
  /** 0..1 的质量估计，不是离线评测分数。 */
  quality: number; requiresProvider: boolean;
  /** 同一请求最多执行几次，默认 1；重试必须显式写出来。 */
  maxRuns?: number;
}

export interface DegradeCostPolicy {
  budgetMicros: number; deadlineMs: number; qualityFloor: number;
  /** 单请求总尝试次数上限，包含首次与重试。 */
  maxAttempts: number;
  /** 后一步成本不得超过前一步的该倍数；1 表示只能持平或更便宜。 */
  maxCostInflation: number;
  /** 每花 1 微元至少要换回的质量；0 表示关闭该判据。 */
  minQualityPerMicro: number;
}

export const DEFAULT_DEGRADE_COST: DegradeCostPolicy = {
  budgetMicros: 1_000, deadlineMs: 3_000, qualityFloor: 0.6,
  maxAttempts: 3, maxCostInflation: 1, minQualityPerMicro: 0,
};

export type PlanRejectReason =
  | "duplicate" | "quality-floor" | "budget" | "deadline" | "cost-inversion" | "efficiency";
export interface PlanRejection { id: string; reason: PlanRejectReason; detail: string; }
export interface CostedPlan {
  steps: CostedStep[]; rejected: PlanRejection[];
  estimatedMicros: number;
  /** 按 maxRuns 与 maxAttempts 推演的最坏成本，不超过预算。 */
  worstCaseMicros: number;
}

function fail(message: string): never {
  throw new AiError("invalid-request", `degrade-cost: ${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;
}

function validateStep(step: CostedStep): void {
  if (step.id.trim() === "") fail("step id must not be empty");
  finite(step.priority, `${step.id}.priority`);
  integer(step.estimatedMicros, `${step.id}.estimatedMicros`);
  integer(step.estimatedMs, `${step.id}.estimatedMs`);
  finite(step.quality, `${step.id}.quality`);
  if (step.quality > 1) fail(`${step.id}.quality must be in [0, 1]`);
  if (step.maxRuns !== undefined) integer(step.maxRuns, `${step.id}.maxRuns`, 1);
}

/**
 * 降级链的两条硬约束：质量不能低于承诺，成本不能越降越贵。
 * 估算只用于入场过滤；真正花出去的钱由执行阶段按实际返回值记账。
 */
export function planCostedChain(
  steps: readonly CostedStep[],
  policy: DegradeCostPolicy = DEFAULT_DEGRADE_COST,
): CostedPlan {
  finite(policy.budgetMicros, "budgetMicros");
  finite(policy.deadlineMs, "deadlineMs");
  finite(policy.qualityFloor, "qualityFloor");
  if (policy.qualityFloor > 1) fail("qualityFloor must be in [0, 1]");
  integer(policy.maxAttempts, "maxAttempts", 1);
  finite(policy.maxCostInflation, "maxCostInflation");
  finite(policy.minQualityPerMicro, "minQualityPerMicro");

  const rejected: PlanRejection[] = [];
  const accepted: CostedStep[] = [];
  const seen = new Set<string>();
  const ordered = [...steps].sort(
    (left, right) => left.priority - right.priority || left.id.localeCompare(right.id),
  );

  for (const step of ordered) {
    if (seen.has(step.id)) {
      rejected.push({ id: step.id, reason: "duplicate", detail: "duplicate step id" });
      continue;
    }
    seen.add(step.id);
    validateStep(step);
    if (step.quality < policy.qualityFloor) {
      rejected.push({ id: step.id, reason: "quality-floor", detail: `${step.quality} < ${policy.qualityFloor}` });
      continue;
    }
    if (step.estimatedMicros > policy.budgetMicros) {
      rejected.push({ id: step.id, reason: "budget", detail: `${step.estimatedMicros} > ${policy.budgetMicros}` });
      continue;
    }
    if (step.estimatedMs > policy.deadlineMs) {
      rejected.push({ id: step.id, reason: "deadline", detail: `${step.estimatedMs}ms > ${policy.deadlineMs}ms` });
      continue;
    }
    const previous = accepted[accepted.length - 1];
    if (previous && step.estimatedMicros > previous.estimatedMicros * policy.maxCostInflation) {
      rejected.push({
        id: step.id, reason: "cost-inversion",
        detail: `${step.estimatedMicros} > ${previous.id} ${previous.estimatedMicros} × ${policy.maxCostInflation}`,
      });
      continue;
    }
    if (
      policy.minQualityPerMicro > 0 && step.estimatedMicros > 0 &&
      step.quality / step.estimatedMicros < policy.minQualityPerMicro
    ) {
      rejected.push({ id: step.id, reason: "efficiency", detail: "quality per micros is too low" });
      continue;
    }
    accepted.push(step);
  }

  let worstCaseMicros = 0;
  let runs = 0;
  for (const step of accepted) {
    for (let run = 0; run < (step.maxRuns ?? 1) && runs < policy.maxAttempts; run += 1) {
      worstCaseMicros += step.estimatedMicros;
      runs += 1;
    }
  }
  return {
    steps: accepted, rejected,
    estimatedMicros: accepted.reduce((sum, step) => sum + step.estimatedMicros, 0),
    worstCaseMicros: Math.min(worstCaseMicros, policy.budgetMicros),
  };
}

export type StepResult =
  | { ok: true; quality: number; costMicros: number; elapsedMs: number; text: string }
  | { ok: false; costMicros: number; elapsedMs: number; error: string };
export type CostedHandler = (step: CostedStep) => StepResult;
export type HandlerMap = Record<string, CostedHandler>;
export type StopReason = "served" | "budget" | "deadline" | "attempts" | "exhausted";
export interface CostedRecord {
  stepId: string; run: number; ok: boolean; costMicros: number; elapsedMs: number; quality: number;
}
export interface CostedRun {
  outcome: "served" | "shed"; usedStepId: string | null; quality: number;
  costMicros: number; elapsedMs: number; attempts: number;
  stopReason: StopReason; records: CostedRecord[];
}

function shed(
  stopReason: StopReason, spent: number, elapsed: number, attempts: number, records: CostedRecord[],
): CostedRun {
  return {
    outcome: "shed", usedStepId: null, quality: 0,
    costMicros: spent, elapsedMs: elapsed, attempts, stopReason, records,
  };
}

/**
 * 执行降级链。四个退出条件必须同时存在：拿到合格结果、钱花完、时间到、次数用尽。
 * 少了任何一个，降级就会变成“无限重试”或“越降越贵”。
 */
export function runCostedChain(
  plan: CostedPlan, handlers: HandlerMap, policy: DegradeCostPolicy = DEFAULT_DEGRADE_COST,
): CostedRun {
  let spent = 0; let elapsed = 0; let attempts = 0;
  const records: CostedRecord[] = [];

  for (const step of plan.steps) {
    for (let run = 1; run <= (step.maxRuns ?? 1); run += 1) {
      if (attempts >= policy.maxAttempts) return shed("attempts", spent, elapsed, attempts, records);
      if (spent + step.estimatedMicros > policy.budgetMicros) {
        return shed("budget", spent, elapsed, attempts, records);
      }
      if (elapsed + step.estimatedMs > policy.deadlineMs) {
        return shed("deadline", spent, elapsed, attempts, records);
      }
      const handler = handlers[step.id];
      if (!handler) {
        records.push({ stepId: step.id, run, ok: false, costMicros: 0, elapsedMs: 0, quality: 0 });
        break;
      }
      const result = handler(step);
      attempts += 1;
      spent += result.costMicros;
      elapsed += result.elapsedMs;
      records.push({
        stepId: step.id, run, ok: result.ok, costMicros: result.costMicros,
        elapsedMs: result.elapsedMs, quality: result.ok ? result.quality : 0,
      });
      if (result.ok && result.quality >= policy.qualityFloor) {
        return {
          outcome: "served", usedStepId: step.id, quality: result.quality,
          costMicros: spent, elapsedMs: elapsed, attempts, stopReason: "served", records,
        };
      }
      if (spent >= policy.budgetMicros) return shed("budget", spent, elapsed, attempts, records);
      if (elapsed >= policy.deadlineMs) return shed("deadline", spent, elapsed, attempts, records);
    }
  }
  return shed("exhausted", spent, elapsed, attempts, records);
}