《互联网产品的 AI 架构·推理性能与成本工程》9.2 多维归因方法

volume = (Q1 - Q0) × C0 / Q0
mix    = Q1 × Σ (s1 - s0) × r0
rate   = (C1 - C0) - volume - mix

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

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

/** 模型解释“钱花在谁身上”，提示版本与路由解释“能不能改”。 */
export type DimensionName = "tenant" | "capability" | "promptVersion" | "model" | "route";

export const DIMENSIONS: readonly DimensionName[] = ["tenant", "capability", "promptVersion", "model", "route"];

export interface CostCell {
  tenant: string;
  capability: string;
  promptVersion: string;
  model: string;
  route: string;
  calls: number;
  costMicros: number;
}

export interface CostPeriod {
  label: string;
  cells: readonly CostCell[];
}

export interface CellDelta {
  tenant: string;
  capability: string;
  promptVersion: string;
  model: string;
  route: string;
  baselineCalls: number;
  currentCalls: number;
  baselineMicros: number;
  currentMicros: number;
  deltaMicros: number;
  deltaCalls: number;
  status: "matched" | "new" | "retired";
}

export interface DimensionView {
  value: string;
  baselineCalls: number;
  currentCalls: number;
  baselineMicros: number;
  currentMicros: number;
  deltaMicros: number;
  /** 该取值对总差异的贡献比例；总差异为 0 时记为 0。 */
  shareOfDelta: number;
}

export interface Decomposition {
  grain: readonly DimensionName[];
  baselineCalls: number;
  currentCalls: number;
  baselineMicros: number;
  currentMicros: number;
  deltaMicros: number;
  volumeMicros: number;
  mixMicros: number;
  /** 同一格内单次成本变化；最后一项吸收取整。 */
  rateMicros: number;
  roundingAdjustmentMicros: number;
}

/** 可行动维度：每个取值都要能落到一个团队和一根杠杆上。 */
export const DIMENSION_ACTION: Record<DimensionName, { owner: string; lever: string }> = {
  tenant: { owner: "商务与配额", lever: "定价、套餐、配额与结算规则" },
  capability: { owner: "产品", lever: "能力合并、降级或下线" },
  promptVersion: { owner: "提示工程", lever: "压缩上下文、修改提示与输出约束" },
  model: { owner: "模型平台", lever: "选型与路由目标模型" },
  route: { owner: "网关", lever: "升级阈值、路由策略与降级顺序" },
};

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

function text(value: string, field: string): string {
  if (typeof value !== "string" || value.trim() === "") fail(`${field} is required`);
  return value;
}

function count(value: number, field: string): number {
  if (!Number.isInteger(value) || value < 0) fail(`${field} must be a non-negative integer`);
  return value;
}

function keyOf(cell: Pick<CostCell, DimensionName>): string {
  return DIMENSIONS.map((dimension) => cell[dimension]).join("\u0000");
}

function validateCell(cell: CostCell): void {
  for (const dimension of DIMENSIONS) text(cell[dimension], dimension);
  count(cell.calls, "calls");
  count(cell.costMicros, "costMicros");
  if (cell.calls === 0 && cell.costMicros !== 0) fail("a cell with zero calls must have zero cost");
}

/** 同一账期内同一个维度组合只能出现一次，重复意味着上游已经聚合错了。 */
export function indexCells(period: CostPeriod): Map<string, CostCell> {
  text(period.label, "period.label");
  const cells = new Map<string, CostCell>();
  for (const cell of period.cells) {
    validateCell(cell);
    const key = keyOf(cell);
    if (cells.has(key)) fail(`${period.label}: duplicate cell ${key.replaceAll("\u0000", "/")}`);
    cells.set(key, { ...cell });
  }
  return cells;
}

/** 全外连接求差：新增格与下线格都保留，差异才能与总账对上。 */
export function deltaRows(baseline: CostPeriod, current: CostPeriod): CellDelta[] {
  const before = indexCells(baseline);
  const after = indexCells(current);
  const keys = [...new Set([...before.keys(), ...after.keys()])].sort();
  const rows = keys.map((key): CellDelta => {
    const left = before.get(key);
    const right = after.get(key);
    const source = right ?? left;
    if (source === undefined) fail(`missing cell ${key}`);
    const baselineCalls = left?.calls ?? 0;
    const currentCalls = right?.calls ?? 0;
    const baselineMicros = left?.costMicros ?? 0;
    const currentMicros = right?.costMicros ?? 0;
    return {
      tenant: source.tenant,
      capability: source.capability,
      promptVersion: source.promptVersion,
      model: source.model,
      route: source.route,
      baselineCalls,
      currentCalls,
      baselineMicros,
      currentMicros,
      deltaMicros: currentMicros - baselineMicros,
      deltaCalls: currentCalls - baselineCalls,
      status: left === undefined ? "new" : right === undefined ? "retired" : "matched",
    };
  });
  return rows.sort((left, right) => {
    const byDelta = Math.abs(right.deltaMicros) - Math.abs(left.deltaMicros);
    return byDelta !== 0 ? byDelta : keyOf(left).localeCompare(keyOf(right));
  });
}

/**
 * 按单个维度汇总。每个视角都能把总差异解释 100%，
 * 但不同视角之间不能相加，否则同一笔钱会被重复计算。
 */
export function viewBy(rows: readonly CellDelta[], dimension: DimensionName): DimensionView[] {
  if (!DIMENSIONS.includes(dimension)) fail(`unknown dimension ${dimension}`);
  const buckets = new Map<string, DimensionView>();
  for (const row of rows) {
    const value = row[dimension];
    const bucket = buckets.get(value);
    if (bucket === undefined) {
      buckets.set(value, {
        value,
        baselineCalls: row.baselineCalls,
        currentCalls: row.currentCalls,
        baselineMicros: row.baselineMicros,
        currentMicros: row.currentMicros,
        deltaMicros: row.deltaMicros,
        shareOfDelta: 0,
      });
    } else {
      bucket.baselineCalls += row.baselineCalls;
      bucket.currentCalls += row.currentCalls;
      bucket.baselineMicros += row.baselineMicros;
      bucket.currentMicros += row.currentMicros;
      bucket.deltaMicros += row.deltaMicros;
    }
  }
  const totalDelta = rows.reduce((sum, row) => sum + row.deltaMicros, 0);
  const views = [...buckets.values()];
  for (const view of views) view.shareOfDelta = totalDelta === 0 ? 0 : view.deltaMicros / totalDelta;
  return views.sort((left, right) => {
    const byDelta = Math.abs(right.deltaMicros) - Math.abs(left.deltaMicros);
    return byDelta !== 0 ? byDelta : left.value.localeCompare(right.value);
  });
}

function grainIndex(period: CostPeriod, grain: readonly DimensionName[]): Map<string, { calls: number; costMicros: number }> {
  const buckets = new Map<string, { calls: number; costMicros: number }>();
  for (const cell of period.cells) {
    validateCell(cell);
    const key = grain.map((dimension) => cell[dimension]).join("\u0000");
    const bucket = buckets.get(key);
    if (bucket === undefined) buckets.set(key, { calls: cell.calls, costMicros: cell.costMicros });
    else {
      bucket.calls += cell.calls;
      bucket.costMicros += cell.costMicros;
    }
  }
  return buckets;
}

/**
 * 量、结构、单价三因子分解。grain 必须稳定：
 * 把 promptVersion 放进去，提示改版会被误判成“新格”，全部差异落到单价项。
 */
export function decompose(
  baseline: CostPeriod,
  current: CostPeriod,
  grain: readonly DimensionName[],
): Decomposition {
  if (grain.length === 0) fail("grain must not be empty");
  if (new Set(grain).size !== grain.length) fail("grain must not contain duplicates");
  for (const dimension of grain) if (!DIMENSIONS.includes(dimension)) fail(`unknown dimension ${dimension}`);

  const before = grainIndex(baseline, grain);
  const after = grainIndex(current, grain);
  const keys = [...new Set([...before.keys(), ...after.keys()])].sort();
  let baselineCalls = 0;
  let currentCalls = 0;
  let baselineMicros = 0;
  let currentMicros = 0;
  for (const key of keys) {
    baselineCalls += before.get(key)?.calls ?? 0;
    currentCalls += after.get(key)?.calls ?? 0;
    baselineMicros += before.get(key)?.costMicros ?? 0;
    currentMicros += after.get(key)?.costMicros ?? 0;
  }
  if (baselineCalls === 0 || currentCalls === 0) fail("both periods must contain at least one call");

  const deltaMicros = currentMicros - baselineMicros;
  const rawVolume = (currentCalls - baselineCalls) * (baselineMicros / baselineCalls);
  let rawMix = 0;
  for (const key of keys) {
    const left = before.get(key);
    const right = after.get(key);
    if (left === undefined || right === undefined) continue;
    const shareBefore = left.calls / baselineCalls;
    const shareAfter = right.calls / currentCalls;
    rawMix += (shareAfter - shareBefore) * (left.costMicros / left.calls);
  }
  rawMix *= currentCalls;

  const volumeMicros = Math.round(rawVolume);
  const mixMicros = Math.round(rawMix);
  const rateMicros = deltaMicros - volumeMicros - mixMicros;
  return {
    grain: [...grain],
    baselineCalls,
    currentCalls,
    baselineMicros,
    currentMicros,
    deltaMicros,
    volumeMicros,
    mixMicros,
    rateMicros,
    roundingAdjustmentMicros: rateMicros - Math.round(deltaMicros - rawVolume - rawMix),
  };
}

node --test test/perf/attribution.test.ts

ℹ tests 9
ℹ pass 9
ℹ fail 0
ℹ duration_ms 146.558333