《互联网产品的 AI 架构·推理性能与成本工程》11.1 质量-成本-延迟的权衡面

A 支配 B  ⇔  qA ≥ qB  且  cA ≤ cB  且  lA ≤ lB
             且 (qA > qB 或 cA < cB 或 lA < lB)

marginal = (cost[i] - cost[prev]) / (quality[i] - quality[prev])

// file: src/perf/quality.ts
// tier: L1
// verify: node --test test/perf/quality.test.ts

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

export type SelectionObjective = "max-quality" | "min-cost" | "knee";

/** 一个候选点就是“某能力 + 某配置”在三条轴上的实测坐标。 */
export interface PerfCandidate {
  id: string;
  capability: string;
  quality: number;
  /** 每千次请求的整数微元成本。 */
  costMicrosPer1k: number;
  latencyP95Ms: number;
  /** 支撑该坐标的评测样本数；样本不足的坐标不能参与选点。 */
  sampleSize: number;
}

export interface CapabilityGuardrail {
  capability: string;
  minQuality: number;
  maxCostMicrosPer1k: number;
  maxLatencyP95Ms: number;
  minSampleSize: number;
}

export interface SelectionPolicy {
  objective: SelectionObjective;
  /** knee 模式：每提升 1 个质量点，最多愿意多付多少微元/千次。 */
  maxMarginalCostMicrosPerQualityPoint?: number;
}

export interface Rejection { id: string; reasons: string[] }

export interface FrontierPoint extends PerfCandidate {
  /** 相对上一个“质量新高”点的边际成本；不是新高时为 null。 */
  marginalCostMicrosPerQualityPoint: number | null;
  qualityLeader: boolean;
}

export interface FrontierSelection {
  chosen: string | null;
  feasible: string[];
  rejected: Rejection[];
  points: FrontierPoint[];
  rationale: string;
}

function fail(message: string): never {
  throw new AiError("invalid-request", `quality-frontier: ${message}`);
}

function validate(candidate: PerfCandidate): void {
  for (const field of ["id", "capability"] as const) {
    if (typeof candidate[field] !== "string" || candidate[field].trim() === "") fail(`${field} is required`);
  }
  if (!Number.isFinite(candidate.quality) || candidate.quality < 0 || candidate.quality > 1) {
    fail(`quality of "${candidate.id}" must be between 0 and 1`);
  }
  for (const field of ["costMicrosPer1k", "latencyP95Ms"] as const) {
    if (!Number.isInteger(candidate[field]) || candidate[field] < 0) fail(`${field} must be an integer >= 0`);
  }
  if (!Number.isInteger(candidate.sampleSize) || candidate.sampleSize < 1) {
    fail(`sampleSize of "${candidate.id}" must be an integer >= 1`);
  }
}

/** 三条轴都不差，且至少一条严格更好；只有被支配的点才可安全淘汰。 */
export function dominates(left: PerfCandidate, right: PerfCandidate): boolean {
  const noWorse =
    left.quality >= right.quality &&
    left.costMicrosPer1k <= right.costMicrosPer1k &&
    left.latencyP95Ms <= right.latencyP95Ms;
  const strict =
    left.quality > right.quality ||
    left.costMicrosPer1k < right.costMicrosPer1k ||
    left.latencyP95Ms < right.latencyP95Ms;
  return noWorse && strict;
}

function sameObjectives(left: PerfCandidate, right: PerfCandidate): boolean {
  return left.quality === right.quality &&
    left.costMicrosPer1k === right.costMicrosPer1k &&
    left.latencyP95Ms === right.latencyP95Ms;
}

/** Pareto 前沿只保留非支配点，并按成本升序排列。 */
export function paretoFrontier(candidates: readonly PerfCandidate[]): PerfCandidate[] {
  if (candidates.length === 0) fail("at least one candidate is required");
  const capability = candidates[0].capability;
  const seen = new Set<string>();
  for (const candidate of candidates) {
    validate(candidate);
    if (candidate.capability !== capability) fail(`mixed capabilities: ${capability} / ${candidate.capability}`);
    if (seen.has(candidate.id)) fail(`duplicate candidate "${candidate.id}"`);
    seen.add(candidate.id);
  }
  const nonDominated = candidates.filter(
    (candidate) => !candidates.some((other) => other.id !== candidate.id && dominates(other, candidate)),
  );
  const unique: PerfCandidate[] = [];
  for (const candidate of [...nonDominated].sort((left, right) => left.id.localeCompare(right.id))) {
    if (!unique.some((kept) => sameObjectives(kept, candidate))) unique.push(candidate);
  }
  return unique.sort((left, right) =>
    left.costMicrosPer1k - right.costMicrosPer1k ||
    left.latencyP95Ms - right.latencyP95Ms ||
    right.quality - left.quality ||
    left.id.localeCompare(right.id));
}

/**
 * 三维前沿投影到“成本-质量”平面后，只有不断刷新质量高点的点才构成质量阶梯。
 * 其余点用成本换延迟，不能用来计算“每提升一个质量点多少钱”。
 */
export function annotateFrontier(frontier: readonly PerfCandidate[]): FrontierPoint[] {
  const sorted = [...frontier].sort((left, right) =>
    left.costMicrosPer1k - right.costMicrosPer1k ||
    left.latencyP95Ms - right.latencyP95Ms ||
    right.quality - left.quality ||
    left.id.localeCompare(right.id));
  const points: FrontierPoint[] = [];
  let bestQuality = -1;
  let previous: PerfCandidate | null = null;
  for (const candidate of sorted) {
    const leader = candidate.quality > bestQuality;
    let marginal: number | null = null;
    if (leader) {
      if (previous !== null) {
        marginal = (candidate.costMicrosPer1k - previous.costMicrosPer1k) / (candidate.quality - previous.quality);
      }
      bestQuality = candidate.quality;
      previous = candidate;
    }
    points.push({ ...candidate, qualityLeader: leader, marginalCostMicrosPerQualityPoint: marginal });
  }
  return points;
}

function guardrailReasons(candidate: PerfCandidate, guardrail: CapabilityGuardrail): string[] {
  const reasons: string[] = [];
  if (candidate.capability !== guardrail.capability) reasons.push(`capability ${candidate.capability} != ${guardrail.capability}`);
  if (candidate.quality < guardrail.minQuality) reasons.push(`quality ${candidate.quality.toFixed(3)} < ${guardrail.minQuality.toFixed(3)}`);
  if (candidate.costMicrosPer1k > guardrail.maxCostMicrosPer1k) reasons.push(`cost ${candidate.costMicrosPer1k} > ${guardrail.maxCostMicrosPer1k}`);
  if (candidate.latencyP95Ms > guardrail.maxLatencyP95Ms) reasons.push(`latency ${candidate.latencyP95Ms} > ${guardrail.maxLatencyP95Ms}`);
  if (candidate.sampleSize < guardrail.minSampleSize) reasons.push(`sample ${candidate.sampleSize} < ${guardrail.minSampleSize}`);
  return reasons;
}

function pick(feasible: readonly FrontierPoint[], policy: SelectionPolicy): FrontierPoint | null {
  if (feasible.length === 0) return null;
  if (policy.objective === "max-quality") {
    return [...feasible].sort((left, right) =>
      right.quality - left.quality ||
      left.costMicrosPer1k - right.costMicrosPer1k ||
      left.latencyP95Ms - right.latencyP95Ms ||
      left.id.localeCompare(right.id))[0];
  }
  if (policy.objective === "min-cost") {
    return [...feasible].sort((left, right) =>
      left.costMicrosPer1k - right.costMicrosPer1k ||
      left.latencyP95Ms - right.latencyP95Ms ||
      right.quality - left.quality ||
      left.id.localeCompare(right.id))[0];
  }
  const threshold = policy.maxMarginalCostMicrosPerQualityPoint;
  if (threshold === undefined || !Number.isFinite(threshold) || threshold <= 0) {
    fail("knee objective requires a positive maxMarginalCostMicrosPerQualityPoint");
  }
  const leaders = feasible.filter((point) => point.qualityLeader);
  const affordable = leaders.filter((point) =>
    point.marginalCostMicrosPerQualityPoint !== null &&
    point.marginalCostMicrosPerQualityPoint <= threshold);
  return affordable.length > 0 ? affordable[affordable.length - 1] : leaders[0] ?? null;
}

/**
 * 先按能力护栏过滤，再在前沿上按显式目标选点。
 * 被支配且可行与被护栏拒绝的原因分开记录，避免把“更差”说成“不可行”。
 */
export function selectOnFrontier(
  candidates: readonly PerfCandidate[],
  guardrail: CapabilityGuardrail,
  policy: SelectionPolicy,
): FrontierSelection {
  const frontier = paretoFrontier(candidates);
  const points = annotateFrontier(frontier);
  const feasible = points.filter((point) => guardrailReasons(point, guardrail).length === 0);
  // 边际成本必须在“过滤后的可行集”上重算：被护栏淘汰的中间点不该抬高阶梯价格。
  const ladder = annotateFrontier(feasible);

  const feasibleIds = new Set(feasible.map((point) => point.id));
  const frontierIds = new Set(frontier.map((point) => point.id));
  const rejected: Rejection[] = [];
  for (const candidate of candidates) {
    if (feasibleIds.has(candidate.id)) continue;
    const reasons = guardrailReasons(candidate, guardrail);
    if (reasons.length > 0) {
      rejected.push({ id: candidate.id, reasons });
      continue;
    }
    if (!frontierIds.has(candidate.id)) {
      const dominator = candidates.find((other) => other.id !== candidate.id && dominates(other, candidate));
      rejected.push({
        id: candidate.id,
        reasons: [dominator ? `dominated by "${dominator.id}"` : "equivalent to another frontier point"],
      });
    }
  }

  const chosen = pick(ladder, policy);
  const rationale = chosen
    ? `objective=${policy.objective}; chosen "${chosen.id}" (quality ${chosen.quality.toFixed(3)}, cost ${chosen.costMicrosPer1k}, latency ${chosen.latencyP95Ms}); feasible=${feasible.length}, rejected=${rejected.length}`
    : `objective=${policy.objective}; no feasible candidate; rejected=${rejected.length}`;
  return { chosen: chosen?.id ?? null, feasible: feasible.map((point) => point.id), rejected, points, rationale };
}

node examples/perf/quality-frontier.ts

frontier=a,b,e,c,d
a quality=0.72 cost=180 latency=420 marginal=null
b quality=0.80 cost=260 latency=460 marginal=1000.00
e quality=0.83 cost=300 latency=700 marginal=1333.33
c quality=0.84 cost=420 latency=520 marginal=12000.00
d quality=0.86 cost=700 latency=610 marginal=14000.00
objective=max-quality chosen=c feasible=b,c rejected=6
objective=min-cost chosen=b feasible=b,c rejected=6
objective=knee chosen=c feasible=b,c rejected=6
feasible-ladder b marginal=null
feasible-ladder c marginal=4000.00