《互联网产品的 AI 架构·推理性能与成本工程》13.3 进入卷三

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

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

export interface OrchestrationStep {
  id: string;
  inputTokens: number;
  outputTokens: number;
  latencyMs: number;
  /** 单次尝试的失败率；重试会把有效失败率降到它的幂。 */
  failureRate: number;
}

/**
 * 多能力编排的最小成本模型：共享上下文在首跳全价，后续按前缀复用计价；
 * 每次交接额外传递上一跳结果与增量上下文。
 */
export interface OrchestrationScenario {
  steps: readonly OrchestrationStep[];
  sharedContextTokens: number;
  handoffContextTokens: number;
  resultTokensPerHop: number;
  prefixReuseRatio: number;
  cachedInputPriceRatio: number;
  retriesPerStep: number;
  handoffLatencyMs: number;
  inputMicrosPerKTok: number;
  outputMicrosPerKTok: number;
}

export interface HandoffAnalysis {
  steps: number;
  standaloneCostMicros: number;
  orchestratedCostMicros: number;
  handoffTokensPerHop: number;
  /** 相对“每个能力各自携带完整上下文”的成本变化；负数代表更省。 */
  costDeltaPct: number;
  retryCostMicros: number;
  successProbability: number;
  costPerSuccessMicros: number;
  standaloneCostPerSuccessMicros: number;
  /** 编排后成功路径的累计延迟，包含每次交接开销。 */
  latencyMs: number;
  latencyTaxPct: number;
  /** 复用率低于此值时，共享上下文不如直接复制。 */
  breakEvenReuseRatio: number | null;
  /** 要让整体成功率达到目标，单步失败率的上限。 */
  maxStepFailureForTarget: number;
  expectedWastedCostMicros: number;
}

export const HANDOFF_QUESTIONS = [
  "跨能力调用：哪些上下文必须随调用传递，哪些可以只传引用、摘要或游标？",
  "上下文复用：共享前缀的复用率低于多少时，传递成本会超过复制成本？",
  "失败传播：上游失败后，下游应该跳过、重试，还是用部分结果继续？",
] as const;

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

function finite(value: number, field: string, min = 0): number {
  if (!Number.isFinite(value) || value < min) fail(`${field} must be a finite number >= ${min}`);
  return value;
}

function integer(value: number, field: string, min = 0): number {
  if (!Number.isInteger(value) || value < min) fail(`${field} must be an integer >= ${min}`);
  return value;
}

function ratio(value: number, field: string): number {
  if (!Number.isFinite(value) || value < 0 || value > 1) fail(`${field} must be in [0, 1]`);
  return value;
}

function inputCost(tokens: number, pricePerKTok: number, factor = 1): number {
  return Math.ceil((tokens * pricePerKTok * factor) / 1_000);
}

function outputCost(tokens: number, pricePerKTok: number): number {
  return Math.ceil((tokens * pricePerKTok) / 1_000);
}

function validate(scenario: OrchestrationScenario): void {
  if (scenario.steps.length === 0) fail("至少需要一个能力步骤");
  const seen = new Set<string>();
  for (const step of scenario.steps) {
    if (step.id.trim() === "") fail("step.id 不能为空");
    if (seen.has(step.id)) fail(`重复的 step.id ${step.id}`);
    seen.add(step.id);
    integer(step.inputTokens, `${step.id}.inputTokens`);
    integer(step.outputTokens, `${step.id}.outputTokens`);
    finite(step.latencyMs, `${step.id}.latencyMs`);
    ratio(step.failureRate, `${step.id}.failureRate`);
  }
  integer(scenario.sharedContextTokens, "sharedContextTokens");
  integer(scenario.handoffContextTokens, "handoffContextTokens");
  integer(scenario.resultTokensPerHop, "resultTokensPerHop");
  ratio(scenario.prefixReuseRatio, "prefixReuseRatio");
  ratio(scenario.cachedInputPriceRatio, "cachedInputPriceRatio");
  integer(scenario.retriesPerStep, "retriesPerStep");
  finite(scenario.handoffLatencyMs, "handoffLatencyMs");
  integer(scenario.inputMicrosPerKTok, "inputMicrosPerKTok", 1);
  integer(scenario.outputMicrosPerKTok, "outputMicrosPerKTok", 1);
}

/**
 * 把“独立调用”与“顺序编排”放在同一套 token 单价下比较。
 * 编排省下的是重复上下文，付出的是交接 token、交接延迟与失败传播。
 */
export function analyzeHandoff(
  scenario: OrchestrationScenario,
  successTarget = 0.95,
): HandoffAnalysis {
  validate(scenario);
  if (!(successTarget > 0 && successTarget < 1)) fail("successTarget 必须落在 (0, 1)");
  const reuseFactor = 1 - scenario.prefixReuseRatio * (1 - scenario.cachedInputPriceRatio);
  const handoffTokensPerHop = scenario.handoffContextTokens + scenario.resultTokensPerHop;

  let standaloneCost = 0;
  let standaloneFullCost = 0;
  let orchestratedCost = 0;
  let fullCost = 0;
  let expectedCost = 0;
  let expectedWithoutRetry = 0;
  let reach = 1;
  let success = 1;
  let latency = 0;
  let standaloneLatency = 0;

  scenario.steps.forEach((step, index) => {
    const standaloneStep =
      inputCost(scenario.sharedContextTokens + step.inputTokens, scenario.inputMicrosPerKTok) +
      outputCost(step.outputTokens, scenario.outputMicrosPerKTok);
    standaloneCost += standaloneStep;
    standaloneLatency += step.latencyMs;

    const sharedCost = index === 0
      ? inputCost(scenario.sharedContextTokens, scenario.inputMicrosPerKTok)
      : inputCost(scenario.sharedContextTokens, scenario.inputMicrosPerKTok, reuseFactor);
    const handoffCost = index === 0
      ? 0
      : inputCost(handoffTokensPerHop, scenario.inputMicrosPerKTok);
    const stepCost = sharedCost + handoffCost +
      inputCost(step.inputTokens, scenario.inputMicrosPerKTok) +
      outputCost(step.outputTokens, scenario.outputMicrosPerKTok);
    orchestratedCost += stepCost;

    const attemptFactor = 1 + scenario.retriesPerStep * step.failureRate;
    const effectiveFailure = Math.pow(step.failureRate, 1 + scenario.retriesPerStep);
    standaloneFullCost += standaloneStep * attemptFactor;
    fullCost += stepCost * attemptFactor;
    expectedCost += reach * stepCost * attemptFactor;
    expectedWithoutRetry += reach * stepCost;
    latency += reach * (step.latencyMs + (index === 0 ? 0 : scenario.handoffLatencyMs));
    reach *= 1 - effectiveFailure;
    success *= 1 - effectiveFailure;
  });

  const costPerSuccess = success === 0 ? Number.POSITIVE_INFINITY : expectedCost / success;
  const standaloneCostPerSuccess = success === 0 ? Number.POSITIVE_INFINITY : standaloneFullCost / success;
  const breakEven = handoffTokensPerHop === 0
    ? 0
    : scenario.sharedContextTokens === 0 || scenario.cachedInputPriceRatio === 1
      ? null
      : handoffTokensPerHop / (scenario.sharedContextTokens * (1 - scenario.cachedInputPriceRatio));
  const maxStepFailure = Math.pow(
    1 - Math.pow(successTarget, 1 / scenario.steps.length),
    1 / (1 + scenario.retriesPerStep),
  );

  return {
    steps: scenario.steps.length,
    standaloneCostMicros: standaloneCost,
    orchestratedCostMicros: orchestratedCost,
    handoffTokensPerHop,
    costDeltaPct: standaloneCost === 0 ? 0 : ((orchestratedCost - standaloneCost) / standaloneCost) * 100,
    retryCostMicros: Math.round(expectedCost - expectedWithoutRetry),
    successProbability: success,
    costPerSuccessMicros: Math.round(costPerSuccess),
    standaloneCostPerSuccessMicros: Math.round(standaloneCostPerSuccess),
    latencyMs: Math.round(latency),
    latencyTaxPct: standaloneLatency === 0 ? 0 : ((latency - standaloneLatency) / standaloneLatency) * 100,
    breakEvenReuseRatio: breakEven !== null && breakEven <= 1 ? Number(breakEven.toFixed(4)) : null,
    maxStepFailureForTarget: Number(maxStepFailure.toFixed(4)),
    expectedWastedCostMicros: Math.round(expectedCost - success * fullCost),
  };
}