支出上限与成本护栏

概述

支出上限用于限制线上 AI 流量的估算 USD 支出。控制台中对应两处配置：Spending limit（项目级）和 Cost guardrail（工作流模型级）。

可以只设其一，也可以同时设置：

• 项目支出上限 — 整个项目的计价支出总和
• 工作流支出上限 — 某个 Primary、Backup 1 或 Backup 2 模型的支出

每个上限都绑定 UTC 周期（hourly、daily、weekly、monthly）。支出达到上限后，新的供应商调用会被拦截，API 返回预算类错误。

与输入护栏不同：输入护栏 拦截不安全内容；支出上限在达到预算阈值时拦截请求。

检查顺序

普通线上请求按以下顺序评估：

1. Test mode — 工作流处于 test mode 时，跳过所有支出上限
2. Cache hit — price = 0 的缓存响应跳过所有上限
3. 项目上限 — 若已配置且支出已达上限，立即拦截（不故障转移）
4. 工作流槽位上限 — 若该槽位超预算，跳过该模型并尝试下一个备份

项目上限已触发时，不会尝试备份，即使 Overview 上某个工作流槽位仍显示有剩余预算。

同步、异步、流式、Playground（生产工作流）和 OpenAI 兼容路由均适用。

什么计入支出

项目总额

项目支出汇总满足以下条件的成功请求日志：

• status 为 success
• price 大于 0
• primary_req_id 为空（仅顶层请求，子级故障转移记录不计入）

工作流槽位总额

工作流上限按「工作流 + 供应商 + 模型」统计。ModelRiver 汇总该槽位所有 price 非空的成功日志，包括同一模型上已计价的故障转移尝试。

缓存命中（price = 0）不计入任一总额，也不会触发预算检查。

预算周期

所有周期按 UTC 边界重置：

Overview 和预算错误响应在需要时会包含 period_start 和 reset_at。

设置项目支出上限

1. 打开项目，在侧边栏进入 Settings
2. 在 Spending limit 中填写 Maximum spend (USD)（支持三位小数，如 $0.009）
3. 选择 Reset every（hourly、daily、weekly 或 monthly）
4. 保存

清空金额并保存即可移除上限。金额须大于零；设置金额时必须选择周期。

设置工作流支出上限

1. 打开 Workflows，编辑生产工作流
2. 在 Primary、Backup 1 或 Backup 2 步骤中找到 Cost guardrail
3. 设置 Budget (USD) 和 Reset
4. 保存工作流

仅已选择供应商和模型的槽位可以设上限。

槽位超预算时该模型会被跳过。若有备份，ModelRiver 会尝试下一个。若所有尝试的模型都因预算被跳过，请求失败并返回 workflow_budget_exceeded。

Overview 页面

Spending limits 区块显示：

• 项目卡片 — 支出 vs 上限、剩余预算、重置时间；若任何生产工作流模型缺少 USD 目录定价，会显示配置警告
• 各工作流行 — 每个已设上限槽位的支出与上限，支持快速编辑
• 汇总标签 — 受保护工作流数、接近上限模型数（80%+）、已达上限模型数

进度条在约 80% 时变琥珀色，达到上限时变红。即使支出仍低，只要可路由模型缺少定价，项目也可能显示配置警告。

软执行

支出总额会缓存约 10 秒以保持检查速度。高并发下，阻断前可能多通过少量请求 — Overview 或错误响应中的支出可能略高于上限（例如 $0.011797 对比 $0.011 上限）。

上限值始终来自已保存的配置。拦截条件是缓存支出已 >= cap，而非对当前请求的预测成本。

定价必须已知

仅当 ModelRiver 对路由模型有 USD 定价时，上限才会生效。

当任何活跃生产工作流模型缺少定价时，Overview 会显示配置警告。请补全目录定价，或在上限可安全执行前移除上限。

上限拦截请求时

工作流上限 — workflow_budget_exceeded（402）

故障转移链中所有尝试的模型均因预算被跳过。响应包含 attempts 数组，原因如 daily budget ($0.009) reached。

Request Logs 中通常可见：

• 一条或多条 Skipped 记录（response_source: budget_guardrail）
• 一条父级 Error 记录，携带终端 API 错误内容

项目上限 — project_budget_exceeded（402）

路由前项目支出已达上限，不尝试备份。响应包含 cap_usd、spent_usd、period、reset_at。

Request Logs 为单条 Error 记录，response_source: budget_guardrail，token 为 0，未调用供应商。

响应示例与旧版错误别名（budget_exceeded、budget_config_error）见 错误处理。

Test mode 与 Playground

不想消耗预算时，请使用 test mode。

实用建议

• 若需按功能/模型控制支出，先为单个模型设上限，再用项目上限作兜底
• 调参阶段用 hourly 或 daily，上线后可改为 weekly 或 monthly
• 保存上限后跑几次线上请求，确认 Overview 数字符合预期
• 结合 成本分析，根据日志中的实际价格设定合理上限

后续步骤

• 成本分析 — 从 Request Logs 查看支出
• 错误处理 — 预算错误类型与 HTTP 状态码
• 创建工作流 — 模型、备份与可选上限
• 控制台 — 设置与 Overview
• 回到可观测性