《互联网产品的 AI 架构·模型接入与能力边界》2.1 模型能力的五个维度

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

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

/** 档案校验只回答“这份档案能不能进入选型”，不评价模型本身好坏。 */
export interface ProfileIssue {
  field: string;
  code: "missing" | "range" | "duplicate" | "type";
  message: string;
}

export interface ProfileValidation {
  ok: boolean;
  issues: ProfileIssue[];
}

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

/**
 * 档案是选型的唯一事实来源，因此先校验再打分。
 * 一次返回全部问题，评审时能一次改完，而不是修一个报一个。
 */
export function validateProfile(profile: ModelProfile): ProfileValidation {
  const issues: ProfileIssue[] = [];
  const push = (field: string, code: ProfileIssue["code"], message: string): void => {
    issues.push({ field, code, message });
  };

  if (profile.id.trim() === "") {
    push("id", "missing", "模型 id 不能为空");
  }
  if (profile.provider.trim() === "") {
    push("provider", "missing", "provider 不能为空");
  }

  if (profile.capabilities.length === 0) {
    push("capabilities", "missing", "至少声明一个能力，否则档案无法被路由");
  }
  const seenCapabilities = new Set<string>();
  for (const capability of profile.capabilities) {
    if (capability.trim() === "") {
      push("capabilities", "missing", "能力标识不能为空");
    } else if (seenCapabilities.has(capability)) {
      push("capabilities", "duplicate", `能力重复：${capability}`);
    }
    seenCapabilities.add(capability);
  }

  if (!Number.isSafeInteger(profile.contextWindow) || profile.contextWindow <= 0) {
    push("contextWindow", "range", "上下文窗口必须是正整数");
  }
  if (!Number.isSafeInteger(profile.maxOutputTokens) || profile.maxOutputTokens <= 0) {
    push("maxOutputTokens", "range", "输出上限必须是正整数");
  } else if (profile.maxOutputTokens > profile.contextWindow) {
    push("maxOutputTokens", "range", "输出上限不能超过上下文窗口");
  }

  if (!Number.isSafeInteger(profile.inputMicrosPerMTok) || profile.inputMicrosPerMTok < 0) {
    push("inputMicrosPerMTok", "type", "输入价格必须是非负整数微元");
  }
  if (!Number.isSafeInteger(profile.outputMicrosPerMTok) || profile.outputMicrosPerMTok < 0) {
    push("outputMicrosPerMTok", "type", "输出价格必须是非负整数微元");
  }
  if (!Number.isFinite(profile.p95LatencyMs) || profile.p95LatencyMs <= 0) {
    push("p95LatencyMs", "range", "P95 延迟必须是正数");
  }

  if (profile.regions.length === 0) {
    push("regions", "missing", "至少声明一个可用区域");
  }
  const seenRegions = new Set<string>();
  for (const region of profile.regions) {
    if (region.trim() === "") {
      push("regions", "missing", "区域标识不能为空");
    } else if (seenRegions.has(region)) {
      push("regions", "duplicate", `区域重复：${region}`);
    }
    seenRegions.add(region);
  }

  if (!TIERS.includes(profile.qualityTier)) {
    push("qualityTier", "type", `未知质量档位：${String(profile.qualityTier)}`);
  }
  if (typeof profile.healthy !== "boolean") {
    push("healthy", "type", "healthy 必须是布尔值");
  }

  return { ok: issues.length === 0, issues };
}

/** 档案不合格时抛出统一的 invalid-request，避免坏数据流进评分。 */
export function assertValidProfile(profile: ModelProfile): void {
  const result = validateProfile(profile);
  if (!result.ok) {
    const fields = result.issues.map((issue) => issue.field).join(", ");
    throw new AiError("invalid-request", `invalid model profile ${profile.id}: ${fields}`);
  }
}

/**
 * 混合成本：按输入/输出占比折算成“每百万 token 的加权微元”。
 * 业务流量里输入通常远多于输出，默认 0.75/0.25 只是案例假设值，必须按真实请求重算。
 */
export function blendedCostMicrosPerMTok(profile: ModelProfile, inputShare = 0.75): number {
  if (!Number.isFinite(inputShare) || inputShare < 0 || inputShare > 1) {
    throw new AiError("invalid-request", "inputShare 必须在 0 到 1 之间");
  }
  const value =
    profile.inputMicrosPerMTok * inputShare +
    profile.outputMicrosPerMTok * (1 - inputShare);
  return Math.round(value);
}

/**
 * 质量档位到分数的映射是产品约定，不是客观测量。
 * 它只用于同一份预算表里的相对比较，不能拿去和外部榜单对齐。
 */
export const TIER_QUALITY_SCORE: Record<QualityTier, number> = {
  frontier: 1,
  standard: 0.7,
  economy: 0.4,
};

export type Dimension = "quality" | "latency" | "cost" | "context" | "controllability";

/** 打分预算来自产品约束，五个维度都用同一份预算归一化。 */
export interface DimensionBudget {
  maxBlendedMicrosPerMTok: number;
  maxP95LatencyMs: number;
  minContextWindow: number;
  inputShare?: number;
  /** 输出上限占上下文的比例上限，默认 0.25。 */
  maxOutputRatio?: number;
}

export interface DimensionScores {
  quality: number;
  latency: number;
  cost: number;
  context: number;
  controllability: number;
  /** 派生值，便于报告里直接展示成本，而不是只给一个分数。 */
  blendedMicrosPerMTok: number;
}

function clamp01(value: number): number {
  if (!Number.isFinite(value)) return 0;
  return Math.min(1, Math.max(0, value));
}

function assertBudget(budget: DimensionBudget): void {
  if (!Number.isFinite(budget.maxBlendedMicrosPerMTok) || budget.maxBlendedMicrosPerMTok <= 0) {
    throw new AiError("invalid-request", "maxBlendedMicrosPerMTok 必须是正数");
  }
  if (!Number.isFinite(budget.maxP95LatencyMs) || budget.maxP95LatencyMs <= 0) {
    throw new AiError("invalid-request", "maxP95LatencyMs 必须是正数");
  }
  if (!Number.isFinite(budget.minContextWindow) || budget.minContextWindow <= 0) {
    throw new AiError("invalid-request", "minContextWindow 必须是正数");
  }
  const ratio = budget.maxOutputRatio ?? 0.25;
  if (!Number.isFinite(ratio) || ratio <= 0 || ratio > 1) {
    throw new AiError("invalid-request", "maxOutputRatio 必须在 0 到 1 之间");
  }
}

/**
 * 五个维度统一折算到 0..1，越大越适合当前预算。
 * 延迟与成本在预算值处得 0.5 分，低于预算一半才拿满分，避免“刚好达标”被当成优秀。
 */
export function scoreProfile(profile: ModelProfile, budget: DimensionBudget): DimensionScores {
  assertBudget(budget);
  const blended = blendedCostMicrosPerMTok(profile, budget.inputShare ?? 0.75);
  const ratio = budget.maxOutputRatio ?? 0.25;

  const latency = clamp01(1 - profile.p95LatencyMs / budget.maxP95LatencyMs / 2);
  const cost = clamp01(1 - blended / budget.maxBlendedMicrosPerMTok / 2);
  const context = clamp01(profile.contextWindow / budget.minContextWindow / 2);

  let controllability = 0.4;
  if (profile.maxOutputTokens / profile.contextWindow <= ratio) {
    controllability += 0.2;
  }
  if (profile.regions.length >= 2) {
    controllability += 0.2;
  }
  if (profile.healthy) {
    controllability += 0.2;
  }

  return {
    quality: TIER_QUALITY_SCORE[profile.qualityTier],
    latency,
    cost,
    context,
    controllability: clamp01(controllability),
    blendedMicrosPerMTok: blended,
  };
}