《互联网产品的 AI 架构·模型接入与能力边界》4.3 路由的可解释性与灰度

// file: src/routing/explain.ts
// tier: L1
// verify: node --test test/routing/explain.test.ts

import { stableBucket } from "./router.ts";
import type { RouteDecision, RouteRejectReason } from "./router.ts";
import type { QualityTier, TenantId } from "../core/types.ts";

export interface ExplanationLine {
  /** 稳定代码，便于日志聚合与前端按需展示。 */
  code: string;
  text: string;
}

export interface RankedCandidate {
  modelId: string;
  tier: QualityTier;
  rank: number;
  /** 保留三位小数，避免解释文本随浮点尾数抖动。 */
  score: number;
  probe: boolean;
  selected: boolean;
}

export interface RouteExplanation {
  requestId: string;
  selected: string | null;
  summary: string;
  /** 为什么选它。 */
  chosen: ExplanationLine[];
  /** 为什么没选它：既包括被过滤的，也包括可服务但排序靠后的。 */
  rejected: ExplanationLine[];
  ranking: RankedCandidate[];
}

const REJECT_TEXT: Record<RouteRejectReason, string> = {
  "capability-mismatch": "没有声明请求所需能力",
  "region-mismatch": "不支持请求所在区域",
  unhealthy: "注册表标记为不健康",
  "circuit-open": "熔断冷却中，暂不参与路由",
  "zero-weight": "策略权重为 0，已被停用",
  "context-too-small": "上下文窗口装不下估算输入与输出",
  "output-limit-too-small": "模型输出上限低于请求",
  "deadline-too-tight": "P95 延迟超过端到端截止预算",
};

/** 把一次路由决策翻译成人能读、机器也能聚合的解释。 */
export function explainDecision(decision: RouteDecision): RouteExplanation {
  const chosen: ExplanationLine[] = [];
  const rejected: ExplanationLine[] = [];
  const primary = decision.primary;

  if (primary) {
    chosen.push({
      code: "selected.tier",
      text: `选中 ${primary.model.id}：档位 ${primary.tier}，在候选排序中位列第一`,
    });
    chosen.push({
      code: "selected.score",
      text: `加权分数 ${primary.score.toFixed(3)}（权重 ${primary.weight}），同档位按分数从高到低排序`,
    });
    if (primary.probe) {
      chosen.push({
        code: "selected.probe",
        text: "该模型处于熔断冷却后的半开探针，成功一次即可恢复",
      });
    }
    if (decision.degraded) {
      chosen.push({
        code: "selected.degraded",
        text: "主选档位低于请求的质量下限，这是一次显式降级",
      });
    }
  }

  for (const rejection of decision.rejected) {
    rejected.push({
      code: `rejected.${rejection.reason}`,
      text: `${rejection.modelId}：${REJECT_TEXT[rejection.reason]}；${rejection.detail}`,
    });
  }

  const ranking: RankedCandidate[] = decision.candidates.map((candidate, index) => ({
    modelId: candidate.model.id,
    tier: candidate.tier,
    rank: index + 1,
    score: Number(candidate.score.toFixed(3)),
    probe: candidate.probe,
    selected: index === 0,
  }));

  for (const candidate of ranking.slice(1)) {
    rejected.push({
      code: "rejected.ranked-lower",
      text: `${candidate.modelId}：可服务但排序第 ${candidate.rank}，低于主选`,
    });
  }

  const healthRejected = decision.rejected.filter(
    (item) => item.reason === "unhealthy" || item.reason === "circuit-open",
  ).length;
  const summary = primary
    ? `选中 ${primary.model.id}；候选 ${decision.candidates.length} 个，淘汰 ${decision.rejected.length} 个，其中健康或熔断原因 ${healthRejected} 个。`
    : `没有可用候选：${decision.rejected.length} 个模型全部被排除。`;

  return {
    requestId: decision.requestId,
    selected: primary?.model.id ?? null,
    summary,
    chosen,
    rejected,
    ranking,
  };
}

export type CanaryKey = "tenant" | "request";

export interface CanaryRule {
  id: string;
  /** 灰度命中的目标模型；必须已经出现在候选里才会生效。 */
  targetModelId: string;
  /** 基点：10000 表示 100%，避免浮点比例。 */
  percentageBps: number;
  /** 按租户稳定命中，还是按请求稳定命中。 */
  key: CanaryKey;
  /** 命中后是否把目标模型提升到第一位。 */
  promote: boolean;
}

export interface CanaryContext {
  tenantId: TenantId;
  requestId: string;
}

export interface CanaryResult {
  decision: RouteDecision;
  applied: string[];
  skipped: string[];
}

/** 稳定判断一次请求是否落入灰度；同一 key 的结果不会随进程重启改变。 */
export function canaryHit(rule: CanaryRule, context: CanaryContext): boolean {
  if (rule.percentageBps <= 0) {
    return false;
  }
  if (rule.percentageBps >= 10_000) {
    return true;
  }
  const key =
    rule.key === "tenant" ? `tenant:${context.tenantId}` : `request:${context.requestId}`;
  return stableBucket(`${rule.id}:${key}`, 10_000) < rule.percentageBps;
}

/**
 * 应用灰度规则。目标模型不在候选中时记入 skipped，而不是临时创造候选。
 * promote 会改变候选顺序与 primary；degraded 仍表示相对质量下限的原始判断，
 * 因此灰度目标应优先选择同档位模型。
 */
export function applyCanary(
  decision: RouteDecision,
  rules: readonly CanaryRule[],
  context: CanaryContext,
): CanaryResult {
  let candidates = [...decision.candidates];
  const applied: string[] = [];
  const skipped: string[] = [];

  for (const rule of rules) {
    if (!canaryHit(rule, context)) {
      continue;
    }
    const index = candidates.findIndex(
      (candidate) => candidate.model.id === rule.targetModelId,
    );
    if (index === -1) {
      skipped.push(`${rule.id}:target-not-candidate`);
      continue;
    }
    if (rule.promote && index > 0) {
      const [target] = candidates.splice(index, 1);
      candidates = [target, ...candidates];
    }
    applied.push(rule.id);
  }

  return {
    decision: {
      ...decision,
      candidates,
      primary: candidates[0] ?? null,
    },
    applied,
    skipped,
  };
}

node --test test/routing/explain.test.ts

✔ 解释给出选中理由、排序与被淘汰原因 (1.277584ms)
✔ 没有候选时解释明确指出全部被排除 (0.107333ms)
✔ 显式降级会写进选中理由 (0.09375ms)
✔ 租户灰度命中稳定，0 与 10000 基点边界明确 (0.411959ms)
✔ 按请求灰度会让同一租户的不同请求落到不同侧 (0.198959ms)
✔ 灰度命中后提升目标模型，目标不在候选中则跳过 (0.167583ms)
ℹ tests 6
ℹ suites 0
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 148.340833