《互联网产品的 AI 架构·模型接入与能力边界》2.3 多模型并存的现实

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

import { AiError } from "./errors.ts";
import type { CapabilityId, ModelProfile, QualityTier } from "./types.ts";

/**
 * 组合策略描述“产品要求”，不是“现有模型碰巧能做什么”。
 * 缺少的能力必须显式出现在缺口里，而不是被静默忽略。
 */
export interface PortfolioPolicy {
  requiredCapabilities?: CapabilityId[];
  region?: string;
  /** 每个能力至少要覆盖的质量档位，用来防止只剩便宜模型。 */
  requiredTiers?: Record<CapabilityId, QualityTier[]>;
  /** 同一能力至少需要的健康模型数，默认 2。 */
  minRedundancy?: number;
}

export type GapKind =
  | "missing"
  | "all-unhealthy"
  | "insufficient-redundancy"
  | "missing-tier"
  | "single-provider";

export interface CoverageGap {
  capability: CapabilityId;
  kind: GapKind;
  detail: string;
}

export interface CapabilityCoverage {
  capability: CapabilityId;
  /** 目标区域内声明了该能力的模型，包含不健康模型。 */
  models: string[];
  healthyModels: string[];
  /** 健康模型背后的提供方，用于判断是否被单一供应商锁死。 */
  providers: string[];
  /** 健康模型实际提供的质量档位。 */
  tiers: QualityTier[];
}

export interface CoverageCell {
  modelId: string;
  provider: string;
  covered: boolean;
  healthy: boolean;
  inRegion: boolean;
}

export interface CoverageMatrixRow {
  capability: CapabilityId;
  cells: CoverageCell[];
}

export interface PortfolioReport {
  capabilities: CapabilityCoverage[];
  gaps: CoverageGap[];
  /** 目标区域内健康模型涉及的提供方数量。 */
  providerCount: number;
  /** 目标区域内健康模型占全部模型的比例，0..1。 */
  healthyShare: number;
  matrix: CoverageMatrixRow[];
}

const TIER_ORDER: readonly QualityTier[] = ["frontier", "standard", "economy"];

function assertPolicy(policy: PortfolioPolicy): number {
  const minRedundancy = policy.minRedundancy ?? 2;
  if (!Number.isSafeInteger(minRedundancy) || minRedundancy < 1) {
    throw new AiError("invalid-request", "minRedundancy 必须是 >= 1 的整数");
  }
  for (const [capability, tiers] of Object.entries(policy.requiredTiers ?? {})) {
    for (const tier of tiers) {
      if (!TIER_ORDER.includes(tier)) {
        throw new AiError("invalid-request", `能力 ${capability} 声明了未知档位 ${String(tier)}`);
      }
    }
  }
  return minRedundancy;
}

/**
 * 组合分析只回答三个问题：每个能力有谁覆盖、哪里有缺口、是否被单一提供方锁死。
 * 它不做路由决策，路由仍然由网关按请求预算实时选择。
 */
export function analyzePortfolio(
  profiles: readonly ModelProfile[],
  policy: PortfolioPolicy = {},
): PortfolioReport {
  const minRedundancy = assertPolicy(policy);
  const region = policy.region;

  const inRegion = (profile: ModelProfile): boolean =>
    region === undefined || profile.regions.includes(region);

  const capabilities = new Set<CapabilityId>(policy.requiredCapabilities ?? []);
  for (const profile of profiles) {
    for (const capability of profile.capabilities) {
      capabilities.add(capability);
    }
  }
  for (const capability of Object.keys(policy.requiredTiers ?? {})) {
    capabilities.add(capability);
  }
  const orderedCapabilities = [...capabilities].sort();

  const gaps: CoverageGap[] = [];
  const coverage: CapabilityCoverage[] = [];
  const matrix: CoverageMatrixRow[] = [];

  for (const capability of orderedCapabilities) {
    const covering = profiles.filter((profile) => profile.capabilities.includes(capability));
    const scoped = covering.filter(inRegion);
    const healthy = scoped.filter((profile) => profile.healthy);
    const providers = [...new Set(healthy.map((profile) => profile.provider))].sort();
    const tiers = TIER_ORDER.filter((tier) => healthy.some((profile) => profile.qualityTier === tier));

    coverage.push({
      capability,
      models: scoped.map((profile) => profile.id).sort(),
      healthyModels: healthy.map((profile) => profile.id).sort(),
      providers,
      tiers,
    });

    matrix.push({
      capability,
      cells: profiles.map((profile) => ({
        modelId: profile.id,
        provider: profile.provider,
        covered: profile.capabilities.includes(capability),
        healthy: profile.healthy,
        inRegion: inRegion(profile),
      })),
    });

    if (scoped.length === 0) {
      gaps.push({
        capability,
        kind: "missing",
        detail: region ? `区域 ${region} 没有任何模型声明该能力` : "没有任何模型声明该能力",
      });
      continue;
    }
    if (healthy.length === 0) {
      gaps.push({
        capability,
        kind: "all-unhealthy",
        detail: `${scoped.length} 个模型覆盖该能力，但全部不健康`,
      });
      continue;
    }
    if (healthy.length < minRedundancy) {
      gaps.push({
        capability,
        kind: "insufficient-redundancy",
        detail: `健康模型 ${healthy.length} 个，低于要求的 ${minRedundancy} 个`,
      });
    }
    if (providers.length === 1) {
      gaps.push({
        capability,
        kind: "single-provider",
        detail: `仅由 ${providers[0]} 提供，故障或涨价时没有替代`,
      });
    }
    const required = policy.requiredTiers?.[capability] ?? [];
    for (const tier of TIER_ORDER) {
      if (required.includes(tier) && !tiers.includes(tier)) {
        gaps.push({
          capability,
          kind: "missing-tier",
          detail: `缺少健康可用的 ${tier} 档模型`,
        });
      }
    }
  }

  const scopedProfiles = profiles.filter(inRegion);
  const healthyProfiles = scopedProfiles.filter((profile) => profile.healthy);

  return {
    capabilities: coverage,
    gaps,
    providerCount: new Set(healthyProfiles.map((profile) => profile.provider)).size,
    healthyShare:
      scopedProfiles.length === 0 ? 0 : healthyProfiles.length / scopedProfiles.length,
    matrix,
  };
}

/** 只取缺口类型，便于在发布门禁里做集合比较。 */
export function gapKinds(report: PortfolioReport): GapKind[] {
  return [...new Set(report.gaps.map((gap) => gap.kind))].sort();
}