《互联网产品的 AI 架构·模型接入与能力边界》2.2 选型矩阵：离线评测与在线 A/B

// file: src/core/selection-matrix.ts
// tier: L1
// verify: node --test test/core/selection-matrix.test.ts

import { AiError } from "./errors.ts";
import { blendedCostMicrosPerMTok, scoreProfile } from "./model-profile.ts";
import type { DimensionScores } from "./model-profile.ts";
import type { CapabilityId, ModelProfile } from "./types.ts";

/** 选型需求来自能力契约，不允许在评分函数里偷偷放宽。 */
export interface SelectionRequirement {
  capability: CapabilityId;
  region?: string;
  minContextWindow: number;
  maxP95LatencyMs: number;
  maxBlendedMicrosPerMTok: number;
  /** 输入 token 占比，默认 0.75（案例假设值）。 */
  inputShare?: number;
  /** 默认 true：不健康的模型不进入候选。 */
  requireHealthy?: boolean;
}

export interface CriterionWeights {
  quality: number;
  latency: number;
  cost: number;
  context: number;
  controllability: number;
}

export type RejectionCode =
  | "capability"
  | "region"
  | "healthy"
  | "context"
  | "latency"
  | "cost";

export interface Rejection {
  modelId: string;
  code: RejectionCode;
  detail: string;
}

export interface RankedCandidate {
  modelId: string;
  provider: string;
  /** 0..1 的加权分，只在本轮候选之间可比。 */
  score: number;
  breakdown: DimensionScores;
  /** 原始延迟，用于权重为 0 时的稳定并列处理。 */
  p95LatencyMs: number;
  rank: number;
}

/** 并列组必须显式记录，否则不同 sort 实现会给出不同名次。 */
export interface TieGroup {
  modelIds: string[];
  resolvedBy: "cost" | "latency" | "id";
  /** 组内第一名在结果中的名次，从 1 开始。 */
  rankStart: number;
}

export interface RankingResult {
  ranked: RankedCandidate[];
  rejected: Rejection[];
  weights: CriterionWeights;
  ties: TieGroup[];
}

const WEIGHT_KEYS: readonly (keyof CriterionWeights)[] = [
  "quality",
  "latency",
  "cost",
  "context",
  "controllability",
];

function assertRequirement(requirement: SelectionRequirement): void {
  if (requirement.capability.trim() === "") {
    throw new AiError("invalid-request", "capability 不能为空");
  }
  if (!Number.isFinite(requirement.minContextWindow) || requirement.minContextWindow <= 0) {
    throw new AiError("invalid-request", "minContextWindow 必须是正数");
  }
  if (!Number.isFinite(requirement.maxP95LatencyMs) || requirement.maxP95LatencyMs <= 0) {
    throw new AiError("invalid-request", "maxP95LatencyMs 必须是正数");
  }
  if (
    !Number.isFinite(requirement.maxBlendedMicrosPerMTok) ||
    requirement.maxBlendedMicrosPerMTok <= 0
  ) {
    throw new AiError("invalid-request", "maxBlendedMicrosPerMTok 必须是正数");
  }
}

/** 权重先校验再归一化：负权重与全零权重都会让排序失去意义。 */
export function normalizeWeights(weights: CriterionWeights): CriterionWeights {
  let sum = 0;
  for (const key of WEIGHT_KEYS) {
    const value = weights[key];
    if (!Number.isFinite(value) || value < 0) {
      throw new AiError("invalid-request", `权重 ${key} 必须是非负有限数`);
    }
    sum += value;
  }
  if (sum === 0) {
    throw new AiError("invalid-request", "权重之和不能为 0");
  }
  const normalized: CriterionWeights = {
    quality: 0,
    latency: 0,
    cost: 0,
    context: 0,
    controllability: 0,
  };
  for (const key of WEIGHT_KEYS) {
    normalized[key] = weights[key] / sum;
  }
  return normalized;
}

/** 硬约束按固定顺序检查，返回第一条不满足的原因，避免一次请求刷出多条噪声。 */
export function rejectionFor(
  profile: ModelProfile,
  requirement: SelectionRequirement,
): Rejection | null {
  if (!profile.capabilities.includes(requirement.capability)) {
    return { modelId: profile.id, code: "capability", detail: `未声明能力 ${requirement.capability}` };
  }
  if ((requirement.requireHealthy ?? true) && !profile.healthy) {
    return { modelId: profile.id, code: "healthy", detail: "模型当前不健康" };
  }
  if (requirement.region && !profile.regions.includes(requirement.region)) {
    return { modelId: profile.id, code: "region", detail: `不支持区域 ${requirement.region}` };
  }
  if (profile.contextWindow < requirement.minContextWindow) {
    return {
      modelId: profile.id,
      code: "context",
      detail: `上下文 ${profile.contextWindow} < ${requirement.minContextWindow}`,
    };
  }
  if (profile.p95LatencyMs > requirement.maxP95LatencyMs) {
    return {
      modelId: profile.id,
      code: "latency",
      detail: `P95 ${profile.p95LatencyMs}ms > ${requirement.maxP95LatencyMs}ms`,
    };
  }
  const blended = blendedCostMicrosPerMTok(profile, requirement.inputShare ?? 0.75);
  if (blended > requirement.maxBlendedMicrosPerMTok) {
    return {
      modelId: profile.id,
      code: "cost",
      detail: `混合成本 ${blended} > ${requirement.maxBlendedMicrosPerMTok}`,
    };
  }
  return null;
}

function weightedScore(scores: DimensionScores, weights: CriterionWeights): number {
  return (
    scores.quality * weights.quality +
    scores.latency * weights.latency +
    scores.cost * weights.cost +
    scores.context * weights.context +
    scores.controllability * weights.controllability
  );
}

/**
 * 排序规则固定为：分数降序 -> 混合成本升序 -> P95 升序 -> id 字典序。
 * 最后两项只在某个维度被权重排除（权重为 0）时才可能生效，用于让结果可复现。
 */
function compareCandidates(a: RankedCandidate, b: RankedCandidate): number {
  if (a.score !== b.score) return b.score - a.score;
  if (a.breakdown.blendedMicrosPerMTok !== b.breakdown.blendedMicrosPerMTok) {
    return a.breakdown.blendedMicrosPerMTok - b.breakdown.blendedMicrosPerMTok;
  }
  if (a.p95LatencyMs !== b.p95LatencyMs) {
    return a.p95LatencyMs - b.p95LatencyMs;
  }
  return a.modelId < b.modelId ? -1 : a.modelId > b.modelId ? 1 : 0;
}

function tieResolvedBy(
  group: RankedCandidate[],
  profilesById: Map<string, ModelProfile>,
): TieGroup["resolvedBy"] {
  const cost = group[0].breakdown.blendedMicrosPerMTok;
  if (group.some((item) => item.breakdown.blendedMicrosPerMTok !== cost)) return "cost";
  const latency = profilesById.get(group[0].modelId)?.p95LatencyMs;
  if (group.some((item) => profilesById.get(item.modelId)?.p95LatencyMs !== latency)) {
    return "latency";
  }
  return "id";
}

/**
 * 一次完整的离线选型：硬约束过滤，加权评分，显式并列处理。
 * 同一输入必须得到逐字节相同的结果，便于把评测报告当作回归基线。
 */
export function rankCandidates(
  profiles: readonly ModelProfile[],
  requirement: SelectionRequirement,
  weights: CriterionWeights,
): RankingResult {
  assertRequirement(requirement);
  const normalized = normalizeWeights(weights);
  const inputShare = requirement.inputShare ?? 0.75;

  const rejected: Rejection[] = [];
  const scored: RankedCandidate[] = [];

  for (const profile of profiles) {
    const rejection = rejectionFor(profile, requirement);
    if (rejection) {
      rejected.push(rejection);
      continue;
    }
    const breakdown = scoreProfile(profile, {
      maxBlendedMicrosPerMTok: requirement.maxBlendedMicrosPerMTok,
      maxP95LatencyMs: requirement.maxP95LatencyMs,
      minContextWindow: requirement.minContextWindow,
      inputShare,
    });
    scored.push({
      modelId: profile.id,
      provider: profile.provider,
      score: weightedScore(breakdown, normalized),
      breakdown,
      p95LatencyMs: profile.p95LatencyMs,
      rank: 0,
    });
  }

  scored.sort(compareCandidates);
  scored.forEach((candidate, index) => {
    candidate.rank = index + 1;
  });

  const profilesById = new Map(profiles.map((profile) => [profile.id, profile]));
  const ties: TieGroup[] = [];
  let start = 0;
  while (start < scored.length) {
    let end = start + 1;
    while (end < scored.length && scored[end].score === scored[start].score) {
      end += 1;
    }
    if (end - start > 1) {
      const group = scored.slice(start, end);
      ties.push({
        modelIds: group.map((item) => item.modelId),
        resolvedBy: tieResolvedBy(group, profilesById),
        rankStart: start + 1,
      });
    }
    start = end;
  }

  return { ranked: scored, rejected, weights: normalized, ties };
}