《互联网产品的 AI 架构·平台化与治理》6.1 线上质量信号与抽检

netPerThousand = (点赞×1 + 采纳×2 - 转人工×2 - 重复提问×2 - 投诉×4) / 请求数 × 1000

n0 = z² × p × (1 - p) / e²

n = n0 / (1 + (n0 - 1) / N)

// file: src/gov/quality-ops.ts
// tier: L2
// verify: node --test test/gov/quality-ops.test.ts

/** 线上质量信号分五类：两类正信号、三类负信号，权重只用于排序与预警。 */
export type QualitySignalKind = "like" | "adopt" | "handoff" | "repeat-question" | "complaint";

export interface QualitySignalDefinition {
  kind: QualitySignalKind;
  direction: "positive" | "negative";
  weight: number;
  note: string;
}

export const QUALITY_SIGNALS: readonly QualitySignalDefinition[] = [
  { kind: "like", direction: "positive", weight: 1, note: "主动点赞；成本最低、噪声最大" },
  { kind: "adopt", direction: "positive", weight: 2, note: "复制、引用或发送；比点赞更接近真实采纳" },
  { kind: "handoff", direction: "negative", weight: 2, note: "转人工；说明模型没有闭环" },
  { kind: "repeat-question", direction: "negative", weight: 2, note: "同一会话重复提问；说明意图未命中" },
  { kind: "complaint", direction: "negative", weight: 4, note: "显式投诉；最贵也最可信的负信号" },
];

export interface SignalSnapshot {
  capability: string;
  tenant: string;
  requests: number;
  counts: Readonly<Record<QualitySignalKind, number>>;
}

export interface SignalSummary {
  capability: string;
  tenant: string;
  requests: number;
  positiveWeighted: number;
  negativeWeighted: number;
  netPerThousand: number;
}

/** 信号必须先除以请求数；绝对值不能跨能力、跨租户比较。 */
export function summarizeSignals(snapshot: SignalSnapshot): SignalSummary {
  if (!Number.isInteger(snapshot.requests) || snapshot.requests <= 0) {
    throw new Error("quality-ops: requests must be a positive integer");
  }
  let positive = 0;
  let negative = 0;
  for (const definition of QUALITY_SIGNALS) {
    const count = snapshot.counts[definition.kind] ?? 0;
    if (!Number.isInteger(count) || count < 0) {
      throw new Error(`quality-ops: invalid count for ${definition.kind}`);
    }
    if (definition.direction === "positive") positive += count * definition.weight;
    else negative += count * definition.weight;
  }
  return {
    capability: snapshot.capability,
    tenant: snapshot.tenant,
    requests: snapshot.requests,
    positiveWeighted: positive,
    negativeWeighted: negative,
    netPerThousand: round4(((positive - negative) / snapshot.requests) * 1000),
  };
}

export type ConfidenceLevel = 0.9 | 0.95 | 0.99;
const Z_SCORE: Readonly<Record<ConfidenceLevel, number>> = { 0.9: 1.6449, 0.95: 1.96, 0.99: 2.5758 };

export interface SampleSizeInput {
  /** 当期可抽检的总体量，必须为正整数。 */
  population: number;
  /** 预期合格率，取 0 与 1 之间；保守取 0.5 可得到最大样本量。 */
  expectedRate: number;
  /** 允许的绝对误差，例如 0.02 表示 ±2 个百分点。 */
  margin: number;
  confidence: ConfidenceLevel;
}

export interface SampleSizePlan {
  z: number;
  /** 无限总体公式得到的样本量。 */
  uncorrected: number;
  /** 有限总体校正后的样本量，未取整。 */
  corrected: number;
  /** 实际抽检量，向上取整且不超过总体。 */
  sample: number;
  /** 校正系数；等于 1 表示总体足够大、不需要校正。 */
  finitePopulationCorrection: number;
}

/** 比例抽检的样本量：先算无限总体，再做有限总体校正。 */
export function planSampleSize(input: SampleSizeInput): SampleSizePlan {
  const { population, expectedRate, margin, confidence } = input;
  if (!Number.isInteger(population) || population <= 0) {
    throw new Error("quality-ops: population must be a positive integer");
  }
  if (!(expectedRate > 0 && expectedRate < 1)) {
    throw new Error("quality-ops: expectedRate must be between 0 and 1");
  }
  if (!(margin > 0 && margin < 1)) {
    throw new Error("quality-ops: margin must be between 0 and 1");
  }
  const z = Z_SCORE[confidence];
  if (z === undefined) throw new Error(`quality-ops: unsupported confidence ${confidence}`);
  const uncorrected = (z * z * expectedRate * (1 - expectedRate)) / (margin * margin);
  const corrected = uncorrected / (1 + (uncorrected - 1) / population);
  return {
    z,
    uncorrected: round4(uncorrected),
    corrected: round4(corrected),
    sample: Math.min(population, Math.ceil(corrected)),
    finitePopulationCorrection: round4(corrected / uncorrected),
  };
}

export interface WilsonInterval {
  point: number;
  low: number;
  high: number;
  confidence: ConfidenceLevel;
}
/** Wilson 区间：小样本与接近 0/1 的比例比正态近似更稳。 */
export function wilsonInterval(
  passed: number,
  total: number,
  confidence: ConfidenceLevel = 0.95,
): WilsonInterval {
  if (!Number.isInteger(passed) || !Number.isInteger(total) || total <= 0 || passed < 0 || passed > total) {
    throw new Error("quality-ops: passed/total must satisfy 0 <= passed <= total");
  }
  const z = Z_SCORE[confidence];
  if (z === undefined) throw new Error(`quality-ops: unsupported confidence ${confidence}`);
  const point = passed / total;
  const denominator = 1 + (z * z) / total;
  const center = (point + (z * z) / (2 * total)) / denominator;
  const half = (z * Math.sqrt((point * (1 - point)) / total + (z * z) / (4 * total * total))) / denominator;
  return {
    point: round6(point),
    low: round6(Math.max(0, center - half)),
    high: round6(Math.min(1, center + half)),
    confidence,
  };
}

export interface SampleStratum {
  capability: string;
  tenant: string;
  population: number;
}

export interface StratumAllocation extends SampleStratum {
  sample: number;
}

export interface AllocationOptions {
  /** 每个分层至少抽多少；用于保证长尾租户不至于完全缺席。 */
  minimumPerStratum?: number;
}

/** 按 population 比例分配，最小配额优先，余数用最大余数法，合计精确等于样本量。 */
export function allocateSample(
  strata: readonly SampleStratum[],
  sampleSize: number,
  options: AllocationOptions = {},
): StratumAllocation[] {
  if (strata.length === 0) throw new Error("quality-ops: strata must not be empty");
  if (!Number.isInteger(sampleSize) || sampleSize <= 0) {
    throw new Error("quality-ops: sampleSize must be a positive integer");
  }
  const minimum = options.minimumPerStratum ?? 1;
  if (!Number.isInteger(minimum) || minimum < 0) {
    throw new Error("quality-ops: minimumPerStratum must be a non-negative integer");
  }
  for (const stratum of strata) {
    if (!Number.isInteger(stratum.population) || stratum.population <= 0) {
      throw new Error(`quality-ops: invalid population for ${stratum.capability}/${stratum.tenant}`);
    }
  }
  const totalPopulation = strata.reduce((sum, stratum) => sum + stratum.population, 0);
  const target = Math.min(sampleSize, totalPopulation);
  if (target < strata.length * minimum) {
    throw new Error("quality-ops: sampleSize is smaller than the minimum allocation");
  }
  const base = strata.map((stratum) => Math.min(minimum, stratum.population));
  const remaining = target - base.reduce((sum, value) => sum + value, 0);
  const remainingPopulation = strata.reduce((sum, stratum, index) => sum + (stratum.population - base[index]), 0);
  const quotas = strata.map((stratum, index) =>
    remainingPopulation === 0 ? 0 : (remaining * (stratum.population - base[index])) / remainingPopulation,
  );
  const extra = quotas.map((quota) => Math.floor(quota));
  let assigned = extra.reduce((sum, value) => sum + value, 0);
  const order = quotas
    .map((quota, index) => ({ index, fraction: quota - Math.floor(quota) }))
    .sort((left, right) => right.fraction - left.fraction || left.index - right.index);
  let cursor = 0;
  let guard = 0;
  while (assigned < remaining && guard < remaining * order.length + order.length) {
    const { index } = order[cursor % order.length];
    if (base[index] + extra[index] < strata[index].population) {
      extra[index] += 1;
      assigned += 1;
    }
    cursor += 1;
    guard += 1;
  }
  return strata.map((stratum, index) => ({
    capability: stratum.capability,
    tenant: stratum.tenant,
    population: stratum.population,
    sample: base[index] + extra[index],
  }));
}

function round4(value: number): number {
  return Math.round(value * 1e4) / 1e4;
}

function round6(value: number): number {
  return Math.round(value * 1e6) / 1e6;
}