《互联网产品的 AI 架构·推理性能与成本工程》8.3 配额与预算的容量映射

peakRps     = dailyTokens × peakHourShare / 3600 / avgTokensPerRequest
concurrency = peakRps × latencyMs / 1000

blendedPrice = inputShare × inputPrice + outputShare × outputPrice
maxTokens    = floor(monthlyBudget / blendedPrice × 1,000,000)

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

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

function fail(message: string): never {
  throw new AiError("invalid-request", `capacity-quota: ${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;
}

export interface TokenPrice {
  inputMicrosPerMTok: number;
  outputMicrosPerMTok: number;
}

export interface TokenMix {
  inputShare: number;
  outputShare: number;
}

export function blendedMicrosPerMTok(price: TokenPrice, mix: TokenMix): number {
  finite(price.inputMicrosPerMTok, "price.inputMicrosPerMTok");
  finite(price.outputMicrosPerMTok, "price.outputMicrosPerMTok");
  finite(mix.inputShare, "mix.inputShare");
  finite(mix.outputShare, "mix.outputShare");
  if (Math.abs(mix.inputShare + mix.outputShare - 1) > 1e-9) fail("token mix shares must sum to 1");
  return mix.inputShare * price.inputMicrosPerMTok + mix.outputShare * price.outputMicrosPerMTok;
}

/** 预算是硬约束：先按输入输出混合价算每百万 token 的微元，再向下取整。 */
export function budgetToTokens(budgetMicros: number, price: TokenPrice, mix: TokenMix): number {
  integer(budgetMicros, "budgetMicros");
  const blended = blendedMicrosPerMTok(price, mix);
  if (blended <= 0) fail("blended price must be > 0");
  return Math.floor((budgetMicros / blended) * 1_000_000);
}

export interface TenantQuota {
  tenantId: string;
  /** 每日 token 配额，按 attempts 计，不扣缓存命中。 */
  dailyTokens: number;
  monthlyBudgetMicros: number;
  /** 保底额度：共享池再紧张也要保留的日 token 数。 */
  floorTokens: number;
  /** 共享池剩余额度的分配权重。 */
  weight: number;
}

export interface QuotaProfile {
  avgTokensPerRequest: number;
  /** 峰值小时承载的请求占全天的比例，例如 0.12。 */
  peakHourShare: number;
  latencyMs: number;
  price: TokenPrice;
  mix: TokenMix;
}

export interface QuotaCapacity {
  tenantId: string;
  avgRps: number;
  peakRps: number;
  peakConcurrency: number;
  dailyCostMicros: number;
  budgetDays: number | null;
  budgetSufficient: boolean;
  maxRequestsFromBudget: number;
}

/** token 配额先换算成峰值 RPS，再用 Little 定律换算成并发。 */
export function peakConcurrencyForTokens(tokensPerDay: number, profile: QuotaProfile): number {
  finite(tokensPerDay, "tokensPerDay");
  finite(profile.avgTokensPerRequest, "avgTokensPerRequest");
  if (profile.avgTokensPerRequest <= 0) fail("avgTokensPerRequest must be > 0");
  if (!(profile.peakHourShare > 0 && profile.peakHourShare <= 1)) fail("peakHourShare must be in (0, 1]");
  finite(profile.latencyMs, "latencyMs");
  const peakRps = (tokensPerDay * profile.peakHourShare) / 3600 / profile.avgTokensPerRequest;
  return (peakRps * profile.latencyMs) / 1000;
}

export function mapQuotaToCapacity(quota: TenantQuota, profile: QuotaProfile): QuotaCapacity {
  if (quota.tenantId.trim() === "") fail("tenantId must not be empty");
  integer(quota.dailyTokens, "dailyTokens");
  integer(quota.monthlyBudgetMicros, "monthlyBudgetMicros");
  integer(quota.floorTokens, "floorTokens");
  if (quota.floorTokens > quota.dailyTokens) fail(`${quota.tenantId}: floorTokens exceeds dailyTokens`);
  finite(quota.weight, "weight");
  if (quota.weight <= 0) fail("weight must be > 0");

  const blended = blendedMicrosPerMTok(profile.price, profile.mix);
  const peakRps = (quota.dailyTokens * profile.peakHourShare) / 3600 / profile.avgTokensPerRequest;
  const dailyCostMicros = Math.round((quota.dailyTokens * blended) / 1_000_000);
  const costPerRequest = (profile.avgTokensPerRequest * blended) / 1_000_000;
  return {
    tenantId: quota.tenantId,
    avgRps: quota.dailyTokens / 86_400 / profile.avgTokensPerRequest,
    peakRps,
    peakConcurrency: peakConcurrencyForTokens(quota.dailyTokens, profile),
    dailyCostMicros,
    budgetDays: dailyCostMicros === 0 ? null : quota.monthlyBudgetMicros / dailyCostMicros,
    budgetSufficient: dailyCostMicros * 30 <= quota.monthlyBudgetMicros,
    maxRequestsFromBudget: costPerRequest === 0 ? 0 : Math.floor(quota.monthlyBudgetMicros / costPerRequest),
  };
}

export interface PoolInput {
  poolConcurrency: number;
  poolDailyTokens: number;
  tenants: readonly TenantQuota[];
  profile: QuotaProfile;
}

export interface TenantAllocation {
  tenantId: string;
  floorTokens: number;
  sharedTokens: number;
  totalTokens: number;
  guaranteedConcurrency: number;
  allocatedConcurrency: number;
}

export interface PoolPlan {
  tenantCount: number;
  floorTokens: number;
  sharedTokens: number;
  floorShortfallTokens: number;
  guaranteedConcurrency: number;
  allocatedConcurrency: number;
  overcommitRatio: number;
  feasible: boolean;
  allocations: TenantAllocation[];
}

function splitByWeight(pool: number, tenants: readonly TenantQuota[]): number[] {
  const weightSum = tenants.reduce((sum, tenant) => sum + tenant.weight, 0);
  const exact = tenants.map((tenant) => (pool * tenant.weight) / weightSum);
  const shares = exact.map((value) => Math.floor(value));
  let remainder = pool - shares.reduce((sum, value) => sum + value, 0);
  const order = exact
    .map((value, index) => ({ index, fraction: value - Math.floor(value) }))
    .sort((left, right) => right.fraction - left.fraction || left.index - right.index);
  for (const item of order) {
    if (remainder <= 0) break;
    shares[item.index] += 1;
    remainder -= 1;
  }
  return shares;
}

/** 保底额度先扣，剩余共享额度按权重分配；映射到并发后必须装进池子。 */
export function planSharedPool(input: PoolInput): PoolPlan {
  integer(input.poolConcurrency, "poolConcurrency");
  integer(input.poolDailyTokens, "poolDailyTokens");
  if (input.tenants.length === 0) fail("tenants must not be empty");
  const floorTokens = input.tenants.reduce((sum, tenant) => sum + tenant.floorTokens, 0);
  const floorShortfallTokens = Math.max(0, floorTokens - input.poolDailyTokens);
  const sharedTokens = Math.max(0, input.poolDailyTokens - floorTokens);
  const shares = floorShortfallTokens > 0 ? input.tenants.map(() => 0) : splitByWeight(sharedTokens, input.tenants);
  const allocations = input.tenants.map((tenant, index) => {
    const totalTokens = tenant.floorTokens + shares[index];
    return {
      tenantId: tenant.tenantId,
      floorTokens: tenant.floorTokens,
      sharedTokens: shares[index],
      totalTokens,
      guaranteedConcurrency: peakConcurrencyForTokens(tenant.floorTokens, input.profile),
      allocatedConcurrency: peakConcurrencyForTokens(totalTokens, input.profile),
    };
  });
  const guaranteedConcurrency = allocations.reduce((sum, item) => sum + item.guaranteedConcurrency, 0);
  const allocatedConcurrency = allocations.reduce((sum, item) => sum + item.allocatedConcurrency, 0);
  return {
    tenantCount: input.tenants.length,
    floorTokens,
    sharedTokens,
    floorShortfallTokens,
    guaranteedConcurrency,
    allocatedConcurrency,
    overcommitRatio: input.poolConcurrency === 0 ? 0 : allocatedConcurrency / input.poolConcurrency,
    feasible: floorShortfallTokens === 0 && allocatedConcurrency <= input.poolConcurrency,
    allocations,
  };
}

node examples/perf/quota-map.ts

tenant-a peak_rps=28.986 concurrency=52.174 daily_cost=695652 budget_days=35.94 budget_ok=true
tenant-b peak_rps=7.246 concurrency=13.043 daily_cost=173913 budget_days=23.00 budget_ok=false
floors=1500000000 shared=1300000000
allocated_concurrency=73.043 overcommit=0.913 feasible=true
tenant-a floor=1200000000 shared=975000000 total=2175000000
tenant-b floor=300000000 shared=325000000 total=625000000