《互联网产品的 AI 架构·推理性能与成本工程》6.1 量化的精度与延迟权衡

// file: src/perf/compress.ts
// tier: L2
// verify: node --test test/perf/compress.test.ts

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

/** 档位只描述位宽与相对开销，不绑定任何厂商的量化格式。 */
export const QUANT_LEVELS = ["none", "w8", "w4"] as const;
export type QuantLevel = (typeof QUANT_LEVELS)[number];

export interface QuantProfile {
  level: QuantLevel; bits: number; latencyFactor: number; memoryFactor: number;
  /** 质量惩罚倍率：0 表示不量化。 */
  penaltyScale: number;
}

export const QUANT_PROFILES: Record<QuantLevel, QuantProfile> = {
  none: { level: "none", bits: 16, latencyFactor: 1, memoryFactor: 1, penaltyScale: 0 },
  w8: { level: "w8", bits: 8, latencyFactor: 0.82, memoryFactor: 0.55, penaltyScale: 1 },
  w4: { level: "w4", bits: 4, latencyFactor: 0.68, memoryFactor: 0.35, penaltyScale: 2.2 },
};

export type Sensitivity = "low" | "medium" | "high";

export interface CapabilityQuantRule {
  capability: string;
  sensitivity: Sensitivity;
  /** 允许的最激进档位；none 表示该能力禁止量化。 */
  maxLevel: QuantLevel;
  reason: string;
}

export const DEFAULT_QUANT_RULES: Record<string, CapabilityQuantRule> = {
  "search.rerank": { capability: "search.rerank", sensitivity: "low", maxLevel: "w4", reason: "排序偏好可容忍小幅扰动" },
  "chat.reply": { capability: "chat.reply", sensitivity: "medium", maxLevel: "w4", reason: "自然语言回答允许措辞差异" },
  "doc.summarize": { capability: "doc.summarize", sensitivity: "medium", maxLevel: "w4", reason: "摘要允许改述，事实必须存活" },
  "code.review": { capability: "code.review", sensitivity: "high", maxLevel: "w8", reason: "缺陷定位依赖稳定推理" },
  "finance.extract": { capability: "finance.extract", sensitivity: "high", maxLevel: "none", reason: "金额、单号必须逐字符一致" },
  "safety.classify": { capability: "safety.classify", sensitivity: "high", maxLevel: "none", reason: "安全误判不可逆" },
};

const PENALTY: Record<Sensitivity, number> = { low: 0.012, medium: 0.026, high: 0.055 };
const RANK: Record<QuantLevel, number> = { none: 0, w8: 1, w4: 2 };

export interface QuantQualitySample {
  id: string;
  capability: string;
  /** 未量化时的质量分，0 到 1，来自同一套离线评测。 */
  baselineScore: number;
  baselineLatencyMs: number;
  baselineCostMicros: number;
  critical?: boolean;
}

export interface QuantSampleResult {
  id: string; capability: string; critical: boolean;
  baselineScore: number; quantizedScore: number; drop: number;
  baselineLatencyMs: number; quantizedLatencyMs: number;
  baselineCostMicros: number; quantizedCostMicros: number; catastrophic: boolean;
}

export interface CapabilityQuantSummary {
  capability: string; samples: number; baselineMean: number;
  quantizedMean: number; meanDrop: number; catastrophic: number;
}

export interface BlockedCapability { capability: string; maxLevel: QuantLevel; reason: string }

export interface QuantAcceptancePolicy {
  minSamples: number; minSamplesPerCapability: number; maxMeanDrop: number;
  maxP05Drop: number; maxCatastrophicRate: number; maxLatencyP95Ratio: number; maxCostRatio: number;
}

export const DEFAULT_ACCEPTANCE: QuantAcceptancePolicy = {
  minSamples: 20,
  minSamplesPerCapability: 4,
  maxMeanDrop: 0.04,
  maxP05Drop: 0.08,
  maxCatastrophicRate: 0.01,
  maxLatencyP95Ratio: 0.9,
  maxCostRatio: 0.8,
};

export interface QuantEvaluation {
  level: QuantLevel; profile: QuantProfile; samples: QuantSampleResult[];
  baselineMean: number; quantizedMean: number; meanDrop: number;
  baselineP05: number; quantizedP05: number; p05Drop: number; worstDrop: number;
  catastrophicRate: number; baselineP95LatencyMs: number; p95LatencyMs: number; latencyP95Ratio: number;
  baselineCostMicros: number; quantizedCostMicros: number; costRatio: number;
  byCapability: Record<string, CapabilityQuantSummary>;
  blockedCapabilities: BlockedCapability[];
  decision: { accepted: boolean; reasons: string[] };
}

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

function fnv1a(text: string): number {
  let hash = 0x811c9dc5;
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash;
}

function mean(values: readonly number[]): number {
  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
}

/** 未登记的能力默认禁止量化：新能力必须显式给规则，而不是继承宽松默认值。 */
export function ruleFor(capability: string): CapabilityQuantRule {
  return DEFAULT_QUANT_RULES[capability] ?? {
    capability, sensitivity: "high", maxLevel: "none", reason: "未登记的能力默认禁止量化",
  };
}

export function checkQuantizable(capability: string, level: QuantLevel): { allowed: boolean; reason: string } {
  const rule = ruleFor(capability);
  const allowed = RANK[level] <= RANK[rule.maxLevel];
  return {
    allowed,
    reason: allowed
      ? `${capability} 允许 ${level}：${rule.reason}`
      : `${capability} 最高只允许 ${rule.maxLevel}，目标 ${level} 被拒绝：${rule.reason}`,
  };
}

function validate(sample: QuantQualitySample): void {
  if (sample.id.trim() === "" || sample.capability.trim() === "") fail("样本 id 与 capability 不能为空");
  if (!(sample.baselineScore >= 0 && sample.baselineScore <= 1)) fail(`样本 ${sample.id} 的 baselineScore 必须落在 [0, 1]`);
  if (!Number.isFinite(sample.baselineLatencyMs) || sample.baselineLatencyMs <= 0) fail(`样本 ${sample.id} 的延迟必须是正数`);
  if (!Number.isInteger(sample.baselineCostMicros) || sample.baselineCostMicros < 0) fail(`样本 ${sample.id} 的成本必须是非负整数`);
}

/** 质量损失用确定性模型模拟：能力敏感度 × 档位倍率 × 样本噪声。 */
function simulate(sample: QuantQualitySample, profile: QuantProfile): QuantSampleResult {
  const rule = ruleFor(sample.capability);
  const noise = 0.8 + (fnv1a(`${sample.id}:quality`) % 401) / 1000;
  const penalty = PENALTY[rule.sensitivity] * profile.penaltyScale * noise;
  const quantizedScore = Math.min(1, Math.max(0, sample.baselineScore - penalty));
  const quantizedLatencyMs =
    Math.round(sample.baselineLatencyMs * profile.latencyFactor) + (fnv1a(`${sample.id}:latency`) % 5);
  const costFactor = profile.level === "w4" ? 0.45 : profile.level === "w8" ? 0.7 : 1;
  const drop = sample.baselineScore - quantizedScore;
  return {
    id: sample.id,
    capability: sample.capability,
    critical: sample.critical === true,
    baselineScore: sample.baselineScore,
    quantizedScore,
    drop,
    baselineLatencyMs: sample.baselineLatencyMs,
    quantizedLatencyMs,
    baselineCostMicros: sample.baselineCostMicros,
    quantizedCostMicros: Math.round(sample.baselineCostMicros * costFactor),
    catastrophic: drop >= 0.12,
  };
}

function decide(
  data: Omit<QuantEvaluation, "decision" | "blockedCapabilities">,
  policy: QuantAcceptancePolicy,
  blocked: readonly BlockedCapability[],
): QuantEvaluation["decision"] {
  const reasons: string[] = [];
  if (blocked.length > 0) reasons.push(`能力不允许该档位：${blocked.map((item) => item.capability).join(",")}`);
  if (data.samples.length < policy.minSamples) reasons.push(`样本不足：${data.samples.length}/${policy.minSamples}`);
  for (const summary of Object.values(data.byCapability)) {
    if (summary.samples < policy.minSamplesPerCapability) {
      reasons.push(`能力 ${summary.capability} 样本不足：${summary.samples}/${policy.minSamplesPerCapability}`);
    }
  }
  if (data.meanDrop > policy.maxMeanDrop) reasons.push(`平均质量下降 ${data.meanDrop.toFixed(4)} > ${policy.maxMeanDrop}`);
  if (data.p05Drop > policy.maxP05Drop) reasons.push(`P05 质量下降 ${data.p05Drop.toFixed(4)} > ${policy.maxP05Drop}`);
  if (data.catastrophicRate > policy.maxCatastrophicRate) {
    reasons.push(`灾难性样本比例 ${data.catastrophicRate.toFixed(4)} > ${policy.maxCatastrophicRate}`);
  }
  if (data.latencyP95Ratio > policy.maxLatencyP95Ratio) {
    reasons.push(`P95 延迟比例 ${data.latencyP95Ratio.toFixed(3)} > ${policy.maxLatencyP95Ratio}`);
  }
  if (data.costRatio > policy.maxCostRatio) reasons.push(`成本比例 ${data.costRatio.toFixed(3)} > ${policy.maxCostRatio}`);
  if (data.samples.some((sample) => sample.critical && sample.catastrophic)) {
    reasons.push("关键样本出现灾难性质量下降");
  }
  return { accepted: reasons.length === 0, reasons };
}

/** 同一批样本配对评估：每条样本同时有未量化分与量化分，差值可逐条复算。 */
export function evaluateQuantization(
  samples: readonly QuantQualitySample[],
  level: QuantLevel,
  policy: QuantAcceptancePolicy = DEFAULT_ACCEPTANCE,
): QuantEvaluation {
  if (samples.length === 0) fail("至少需要一条评测样本");
  const profile = QUANT_PROFILES[level];
  if (profile === undefined) fail(`未知量化档位：${String(level)}`);
  for (const sample of samples) validate(sample);

  const blockedMap = new Map<string, BlockedCapability>();
  for (const sample of samples) {
    const rule = ruleFor(sample.capability);
    if (RANK[level] > RANK[rule.maxLevel]) {
      blockedMap.set(sample.capability, { capability: sample.capability, maxLevel: rule.maxLevel, reason: rule.reason });
    }
  }
  const results = samples.map((sample) => simulate(sample, profile));

  const groups = new Map<string, QuantSampleResult[]>();
  for (const result of results) {
    const bucket = groups.get(result.capability) ?? [];
    bucket.push(result);
    groups.set(result.capability, bucket);
  }
  const byCapability: Record<string, CapabilityQuantSummary> = {};
  for (const [capability, bucket] of groups) {
    const baselineMean = mean(bucket.map((item) => item.baselineScore));
    const quantizedMean = mean(bucket.map((item) => item.quantizedScore));
    byCapability[capability] = {
      capability, samples: bucket.length, baselineMean, quantizedMean,
      meanDrop: baselineMean - quantizedMean,
      catastrophic: bucket.filter((item) => item.catastrophic).length,
    };
  }

  const baselineScores = results.map((item) => item.baselineScore);
  const quantizedScores = results.map((item) => item.quantizedScore);
  const baselineP05 = percentile(baselineScores, 0.05);
  const quantizedP05 = percentile(quantizedScores, 0.05);
  const baselineP95LatencyMs = percentile(results.map((item) => item.baselineLatencyMs), 0.95);
  const p95LatencyMs = percentile(results.map((item) => item.quantizedLatencyMs), 0.95);
  const baselineCostMicros = results.reduce((sum, item) => sum + item.baselineCostMicros, 0);
  const quantizedCostMicros = results.reduce((sum, item) => sum + item.quantizedCostMicros, 0);
  const baselineMean = mean(baselineScores);
  const quantizedMean = mean(quantizedScores);
  const catastrophic = results.filter((item) => item.catastrophic).length;

  const data = {
    level, profile, samples: results, baselineMean, quantizedMean,
    meanDrop: baselineMean - quantizedMean,
    baselineP05, quantizedP05, p05Drop: baselineP05 - quantizedP05,
    worstDrop: Math.max(...results.map((item) => item.drop)),
    catastrophicRate: catastrophic / results.length,
    baselineP95LatencyMs, p95LatencyMs,
    latencyP95Ratio: p95LatencyMs / baselineP95LatencyMs,
    baselineCostMicros, quantizedCostMicros,
    costRatio: quantizedCostMicros / baselineCostMicros,
    byCapability,
  };
  return { ...data, blockedCapabilities: [...blockedMap.values()], decision: decide(data, policy, [...blockedMap.values()]) };
}

node --test test/perf/compress.test.ts

ℹ tests 8
ℹ pass 8
ℹ fail 0