《互联网产品的 AI 架构·模型接入与能力边界》10.2 降级策略：小模型、规则、模板、排队

摘要：我的订单什么时候到？订单什么时候到？什么时候到？

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

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

/** 降级链上允许出现的五种角色，顺序由编排者显式声明。 */
export type StrategyKind = "primary" | "small-model" | "rules" | "template" | "queue";

export interface StrategyStep {
  id: string;
  kind: StrategyKind;
  /** 越小越先执行；质量与成本的取舍是产品决策，不用公式代替。 */
  priority: number;
  /** 案例估计值，用于进入链之前的预算过滤。 */
  estimatedMs: number;
  estimatedMicros: number;
  /** 0..1 的案例估计值，不是离线评测分数。 */
  quality: number;
  /** 是否依赖模型提供方；降级风暴时这类步骤先被摘掉。 */
  requiresProvider: boolean;
}

export interface DegradeBudget {
  remainingMs: number;
  remainingMicros: number;
  /** 低于该质量的结果不返回给用户。 */
  minQuality: number;
}

export interface StormState {
  recentFailures: number;
  /** 连续失败达到该值进入风暴模式；0 表示关闭保护。 */
  threshold: number;
}

export type ChainMode = "normal" | "storm";

export interface ChainDecision {
  mode: ChainMode;
  chosen: StrategyStep[];
  skipped: { id: string; reason: string }[];
}

export interface StepOutput {
  text: string;
  costMicros: number;
  elapsedMs: number;
  quality: number;
}

export type StepHandler = (step: StrategyStep) => Promise<StepOutput> | StepOutput;

export interface ChainRun {
  text: string;
  usedStepId: string;
  kind: StrategyKind;
  degraded: boolean;
  quality: number;
  spentMicros: number;
  spentMs: number;
  failures: { id: string; reason: string }[];
}

function validateStep(step: StrategyStep): void {
  if (step.id.trim() === "") {
    throw new AiError("invalid-request", "降级步骤必须有 id");
  }
  if (step.quality < 0 || step.quality > 1) {
    throw new AiError("invalid-request", `${step.id}: quality 必须在 0..1 之间`);
  }
  if (step.estimatedMs < 0 || step.estimatedMicros < 0) {
    throw new AiError("invalid-request", `${step.id}: 预算估计不能为负`);
  }
}

/** 成功或失败都要更新风暴计数，失败清零意味着模型已经恢复。 */
export function recordOutcome(state: StormState, ok: boolean): StormState {
  return { ...state, recentFailures: ok ? 0 : state.recentFailures + 1 };
}

/**
 * 选出本次可用的步骤序列。
 * 顺序来自 priority；过滤来自预算、质量下限与提供方健康度；
 * 风暴模式下额外摘掉依赖提供方的步骤，避免所有请求同时涌向备用模型。
 */
export function selectChain(
  steps: StrategyStep[],
  budget: DegradeBudget,
  storm: StormState = { recentFailures: 0, threshold: 0 },
): ChainDecision {
  const seen = new Set<string>();
  for (const step of steps) {
    validateStep(step);
    if (seen.has(step.id)) {
      throw new AiError("invalid-request", `${step.id}: 降级步骤重复`);
    }
    seen.add(step.id);
  }
  if (budget.minQuality < 0 || budget.minQuality > 1) {
    throw new AiError("invalid-request", "minQuality 必须在 0..1 之间");
  }

  const mode: ChainMode =
    storm.threshold > 0 && storm.recentFailures >= storm.threshold ? "storm" : "normal";
  const skipped: { id: string; reason: string }[] = [];
  const chosen: StrategyStep[] = [];
  const ordered = [...steps].sort((a, b) => a.priority - b.priority || a.id.localeCompare(b.id));

  for (const step of ordered) {
    if (mode === "storm" && step.requiresProvider) {
      skipped.push({ id: step.id, reason: "storm" });
      continue;
    }
    if (step.estimatedMs > budget.remainingMs) {
      skipped.push({ id: step.id, reason: "deadline" });
      continue;
    }
    if (step.estimatedMicros > budget.remainingMicros) {
      skipped.push({ id: step.id, reason: "cost" });
      continue;
    }
    if (step.quality < budget.minQuality) {
      skipped.push({ id: step.id, reason: "quality" });
      continue;
    }
    chosen.push(step);
  }

  return { mode, chosen, skipped };
}

/**
 * 按顺序执行降级链。估算只用于入场过滤，实际消耗以返回值为准并继续扣减，
 * 这样后面步骤看到的是真实剩余预算，而不是乐观估计。
 */
export async function runChain(
  chain: StrategyStep[],
  handlers: Partial<Record<StrategyKind, StepHandler>>,
  budget: DegradeBudget,
): Promise<ChainRun> {
  let remainingMs = budget.remainingMs;
  let remainingMicros = budget.remainingMicros;
  let spentMs = 0;
  let spentMicros = 0;
  const failures: { id: string; reason: string }[] = [];

  for (const step of chain) {
    const handler = handlers[step.kind];
    if (!handler) {
      failures.push({ id: step.id, reason: "no-handler" });
      continue;
    }
    if (step.estimatedMs > remainingMs) {
      failures.push({ id: step.id, reason: "deadline" });
      continue;
    }
    if (step.estimatedMicros > remainingMicros) {
      failures.push({ id: step.id, reason: "cost" });
      continue;
    }
    try {
      const output = await handler(step);
      spentMs += output.elapsedMs;
      spentMicros += output.costMicros;
      remainingMs -= output.elapsedMs;
      remainingMicros -= output.costMicros;
      if (output.quality < budget.minQuality) {
        failures.push({ id: step.id, reason: "quality" });
        continue;
      }
      return {
        text: output.text,
        usedStepId: step.id,
        kind: step.kind,
        degraded: step.kind !== "primary",
        quality: output.quality,
        spentMicros,
        spentMs,
        failures,
      };
    } catch (error) {
      failures.push({
        id: step.id,
        reason: error instanceof Error ? error.message : String(error),
      });
    }
  }

  throw new AiError("unavailable", "降级链已耗尽", {
    usage: { inputTokens: 0, outputTokens: 0, costMicros: spentMicros },
  });
}

node --test test/degrade/chain.test.ts

✔ 按 priority 排序，不看输入顺序 (0.979666ms)
✔ 预算不足时跳过昂贵步骤，而不是让整条链失败 (0.11625ms)
✔ 质量下限会拦住模板兜底 (0.091375ms)
✔ 风暴模式摘掉依赖提供方的步骤 (0.104167ms)
✔ 成功一次即退出风暴模式，失败继续累加 (0.082916ms)
✔ 重复步骤与非法质量在选链前被拒绝 (0.292167ms)
✔ 执行链按顺序失败转移，并记录真实消耗 (0.203375ms)
✔ 实际质量低于下限时继续尝试下一步 (0.096625ms)
✔ 整条链耗尽时抛出 unavailable 并带上已花成本 (0.178792ms)
ℹ tests 9
ℹ pass 9
ℹ fail 0