《互联网产品的 AI 架构·推理性能与成本工程》4.1 输出上限与停止条件

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

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

/** 结构化输出只需要知道“最深要闭合几层”，不需要完整 Schema。 */
export interface StructuredShape {
  maxDepth: number;
  openStringLikely?: boolean;
}

export interface OutputBudgetInput {
  capability: string;
  targetTokens: number;
  hardCapTokens: number;
  structured?: StructuredShape;
  marginRatio?: number;
}

export interface OutputBudgetPlan {
  capability: string;
  targetTokens: number;
  marginTokens: number;
  closureTokens: number;
  maxTokens: number;
  cappedByModel: boolean;
  closureGuaranteed: boolean;
  shortfallTokens: number;
}

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

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

/** 每个未闭合容器一个闭符号，字符串再预留一个闭引号；按保守口径算 token。 */
export function closureReserveTokens(shape: StructuredShape): number {
  requireInteger(shape.maxDepth, "structured.maxDepth", 1);
  return shape.maxDepth + (shape.openStringLikely === false ? 0 : 1);
}

/** 把产品目标、抖动余量与闭包空间合成 maxTokens；闭包装不下就拒绝计划。 */
export function planOutputBudget(input: OutputBudgetInput): OutputBudgetPlan {
  const target = requireInteger(input.targetTokens, "targetTokens", 1);
  const hardCap = requireInteger(input.hardCapTokens, "hardCapTokens", 1);
  const ratio = input.marginRatio ?? 0.1;
  if (!(ratio >= 0 && ratio < 1)) fail("marginRatio must be in [0, 1)");

  const margin = Math.ceil(target * ratio);
  const closure = input.structured ? closureReserveTokens(input.structured) : 0;
  const wanted = target + margin + closure;
  const maxTokens = Math.min(wanted, hardCap);
  const closureGuaranteed = maxTokens >= closure + 1;
  if (input.structured && !closureGuaranteed) {
    fail(`hardCapTokens ${hardCap} cannot fit closure ${closure} plus content`);
  }

  return {
    capability: input.capability,
    targetTokens: target,
    marginTokens: margin,
    closureTokens: closure,
    maxTokens,
    cappedByModel: wanted > hardCap,
    closureGuaranteed,
    shortfallTokens: Math.max(0, wanted - maxTokens),
  };
}

export interface StopHit {
  /** 停止序列第一个字符在输出中的码点下标。 */
  index: number;
  sequence: string;
  /** 停止序列之前的文本，序列本身不进入结果。 */
  keptText: string;
}

function indexOfSequence(haystack: readonly string[], needle: readonly string[]): number {
  if (needle.length === 0 || needle.length > haystack.length) return -1;
  outer: for (let start = 0; start <= haystack.length - needle.length; start += 1) {
    for (let offset = 0; offset < needle.length; offset += 1) {
      if (haystack[start + offset] !== needle[offset]) continue outer;
    }
    return start;
  }
  return -1;
}

/** 同一位置命中多个序列时选最长的一个，让“更具体”的停止词优先。 */
export function findStopSequence(text: string, sequences: readonly string[]): StopHit | null {
  const chars = Array.from(text);
  let best: StopHit | null = null;
  for (const sequence of sequences) {
    if (sequence === "") continue;
    const needle = Array.from(sequence);
    const index = indexOfSequence(chars, needle);
    if (index < 0) continue;
    const better = best === null || index < best.index
      || (index === best.index && needle.length > Array.from(best.sequence).length);
    if (better) best = { index, sequence, keptText: chars.slice(0, index).join("") };
  }
  return best;
}

export interface ScanResult {
  text: string;
  hit: StopHit | null;
}

/** 跨增量块扫描停止序列；末尾可能是序列前缀的部分必须压住，等下一块再判断。 */
export class StopSequenceScanner {
  readonly #sequences: string[][];
  #buffer: string[] = [];
  #emitted: string[] = [];
  #stopped = false;

  constructor(sequences: readonly string[]) {
    this.#sequences = sequences.filter((item) => item !== "").map((item) => Array.from(item));
  }

  get stopped(): boolean {
    return this.#stopped;
  }

  feed(chunk: string): ScanResult {
    if (this.#stopped) return { text: "", hit: null };
    this.#buffer.push(...Array.from(chunk));
    const hit = findStopSequence(
      this.#buffer.join(""),
      this.#sequences.map((sequence) => sequence.join("")),
    );
    if (hit !== null) {
      this.#stopped = true;
      const keptText = this.#emitted.join("") + hit.keptText;
      this.#buffer = [];
      return { text: hit.keptText, hit: { ...hit, keptText } };
    }

    const holdback = this.#holdback();
    const emitCount = Math.max(0, this.#buffer.length - holdback);
    const text = this.#buffer.slice(0, emitCount).join("");
    this.#emitted.push(...this.#buffer.slice(0, emitCount));
    this.#buffer = this.#buffer.slice(emitCount);
    return { text, hit: null };
  }

  #holdback(): number {
    const longest = Math.max(0, ...this.#sequences.map((sequence) => sequence.length - 1));
    const limit = Math.min(this.#buffer.length, longest);
    for (let length = limit; length > 0; length -= 1) {
      const suffix = this.#buffer.slice(this.#buffer.length - length);
      for (const sequence of this.#sequences) {
        if (length >= sequence.length) continue;
        if (sequence.slice(0, length).every((char, index) => char === suffix[index])) {
          return length;
        }
      }
    }
    return 0;
  }
}

export type OutputStopKind =
  | "complete" | "stop-sequence" | "max-tokens" | "max-tokens-valid"
  | "truncated-structure" | "content-filter" | "tool-call" | "empty";

export interface OutputClassificationInput {
  finishReason: "stop" | "length" | "tool_call" | "content_filter" | null;
  text: string;
  /** 结构化输出传解析结果；普通文本保持 undefined。 */
  structuredValid?: boolean;
  stopHit?: StopHit | null;
}

export interface OutputClassification {
  kind: OutputStopKind;
  usable: boolean;
  retryable: boolean;
  keptText: string;
  detail: string;
}

/** 截断不是布尔值：同时看结束原因、结构是否闭合、是否命中停止词。 */
export function classifyOutput(input: OutputClassificationInput): OutputClassification {
  const text = input.text;
  if (input.stopHit) {
    const kept = input.stopHit.keptText;
    return {
      kind: "stop-sequence", usable: kept.trim() !== "", retryable: false, keptText: kept,
      detail: `hit stop sequence ${JSON.stringify(input.stopHit.sequence)} at char ${input.stopHit.index}`,
    };
  }
  if (input.finishReason === "content_filter") {
    return { kind: "content-filter", usable: false, retryable: false, keptText: "", detail: "blocked by provider content filter" };
  }
  if (input.finishReason === "tool_call") {
    return { kind: "tool-call", usable: text !== "", retryable: false, keptText: text, detail: "tool call payload" };
  }
  if (text === "") {
    return { kind: "empty", usable: false, retryable: true, keptText: "", detail: "provider returned no content" };
  }
  if (input.finishReason === "length") {
    if (input.structuredValid === true) {
      return { kind: "max-tokens-valid", usable: true, retryable: false, keptText: text, detail: "hit token cap but structure is still valid" };
    }
    if (input.structuredValid === false) {
      return { kind: "max-tokens", usable: false, retryable: true, keptText: text, detail: "hit token cap before structure closed" };
    }
    return { kind: "max-tokens", usable: true, retryable: false, keptText: text, detail: "plain text is partial but readable" };
  }
  if (input.structuredValid === false) {
    return { kind: "truncated-structure", usable: false, retryable: true, keptText: text, detail: "model stopped before structure closed" };
  }
  return { kind: "complete", usable: true, retryable: false, keptText: text, detail: "completed with a valid ending" };
}

node --test test/perf/output.test.ts

ℹ tests 13
ℹ pass 13
ℹ fail 0
ℹ duration_ms 133.424375