管理多租户网关中的 Anthropic API 版本和 Beta 标头

Anthropic 兼容的 API 网关不应将 anthropic-version 和 anthropic-beta 视为普通的直通标头。他们选择可以更改验证规则、响应块、流式传输事件、可用性、定价和缓存记帐的协议行为和实验功能。

实际问题是保留本机 Claude 行为，但不允许一个租户的请求标头绕过平台政策。解决方案是使协议准入成为一流的网关决策：对调用方进行身份验证、解析其版本策略、验证请求的 Beta 功能、选择兼容的路由并准确记录上游发送的内容。

定义政策边界

事实： 直接 Claude API 请求需要 anthropic-version 标头，尽管官方 SDK 通常会提供该标头。 Anthropic 测试版功能通过 anthropic-beta 或 SDK 特定测试版参数请求。

建议：将这两个值都解释为请求的功能，而不是受信任的路由指令。客户端可能会要求提供版本或测试版，但网关会决定租户、API 密钥、模型、区域和上游凭据是否支持该组合。

不要默默地删除未经批准的测试版。这可以将显式请求转变为具有不同语义的成功调用。在调度前拒绝它，并显示稳定的网关错误，该错误可识别不受支持的功能，而不会暴露上游凭据或内部路由详细信息。

{
  "type": "gateway_policy_error",
  "code": "beta_not_allowed",
  "message": "The requested Anthropic beta is not enabled for this API key.",
  "details": {
    "beta": "example-beta-2026-01-01",
    "policy_id": "claude-production"
  }
}

针对准入失败返回 4xx 响应，并针对网关或上游故障保留 5xx 响应。即使 Anthropic 更改其自己的错误格式，也保持错误架构稳定。

构建版本和功能注册表

日期形状的版本字符串很容易在语法上进行验证，但无法仅通过语法进行控制。网关需要一个包含其实际测试过的版本和 Beta 功能的注册表。

版本记录

每个版本记录应包括：

• 规范版本标识符和生命周期状态：测试、可用、默认、已弃用或已阻止。
• 支持的请求字段、内容块、停止原因、使用字段和已知流式传输事件。
• 兼容模型、上游平台、区域和凭据池。
• 合同夹具结果和最近一次成功测试的日期。
• 定价目录兼容性和任何已知的缓存核算影响。
• 采用限制、弃用日期和更换指南。

测试版记录

测试版功能需要单独记录，因为它们的可用性和操作风险可能与基础 API 版本不同。记录规范测试版名称、兼容版本和型号、允许的区域、必需的请求字段、可能的响应块、流式传输事件、定价处理、速率限制类别和推出状态。

将其建模为数据而不是应用条件。然后，策略评估者可以回答一个具体问题：“密钥 K 可以在路由 R 上使用带有 beta 集 B 的版本 V 吗？”同一目录可以支持团队的多模型API网关，而无需强制每个适配器实施自己的租户规则。

为每个租户提供明确的版本政策

支持三种策略模式：

1. 固定：租户或密钥必须使用一个确切的版本。拒绝缺失或不同的值。
2. 当前网关： 缺少的标头将解析为网关的测试默认值。显式客户端值仍处于验证状态。
3. 批准的范围：客户端可以从有限的测试版本许可列表中进行选择。

避免将“范围”解释为两个端点之间的每个日期。 Anthropic 版本是标识符，而不是连续的语义版本序列。存储一组明确的允许值。

在选择上游路由之前解析有效版本：

requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)

将请求值和有效值分开。当政策提供默认值时，它们可能会有所不同，但审核记录必须使该替换可见。

从结构上解析 Beta 标头

请勿授权具有子字符串匹配或原始字符串相等性的测试版功能。根据上游接受的语法解析标头API，适当拒绝格式错误或重复的条目，并比较规范的特征标识符。

规范排序对于政策缓存键和遥测维度非常有用：

requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a  // serialized in accepted upstream syntax

保留足够的请求元数据以供调试，但当规范化标识符足够时，不要无限期地保留原始标头。标头日志可能包含不必要的客户端元数据，存储它们可以扩大保留和访问控制的范围。

测试版授权应在租户范围内，最好是在密钥范围内。开发密钥可以接收实验功能，而无需自动将其授予生产工作负载。对许可名单的更改应会产生包含参与者、原因、先前状态、新状态和有效时间的控制平面审核事件。

将入场与路由分开

请求不能仅仅因为其模型名称存在而被路由。路由资格是协议和基础设施功能的交集：

eligible(route) =
  route.platform supports effective_version
  AND route.model supports every admitted_beta
  AND route.region permits every admitted_beta
  AND route.credentials are entitled to those capabilities
  AND route.pricing_catalog can account for the result

如果没有路由满足完整集合，则在发送请求之前失败。不要为了使某条路线符合条件而放弃测试版功能。不要自动替换另一个版本，除非租户政策明确定义了该行为。

这种分离对于池凭据、支持客户提供的密钥或跨区域操作的网关很重要。通往同一模型的两条路线可以具有不同的功能访问权限、驻留限制或速率限制。

保留本机响应语义

事实： Anthropic 消息响应可能会因工具使用、令牌限制、上下文窗口限制、暂停轮流和拒绝等原因而结束。流式传输响应使用命名的服务器发送的事件，并且Anthropic的兼容性指南要求客户端容忍新的事件类型。

建议： 不要将所有成功的最终状态折叠为“已完成”。在本机响应和网关遥测中保留上游停止原因。应用程序可能需要执行工具、继续暂停的转弯、减少上下文或提出拒绝。

流代理应识别记帐和生命周期管理所需的事件，同时保持前向兼容：

• 当租户的政策允许本机传递时转发未知事件类型。
• 在有限的诊断元数据中保留原始事件名称和序列位置。
• 不要使用在不熟悉的附加事件上关闭流的详尽枚举。
• 区分上游错误事件与传输断开连接和客户端取消。
• 仅从权威领域最终确定使用；当最终使用不可用时，将不完整的流标记为临时流。

如果网关还公开 OpenAI 形状的端点，请将该适配器与本机消息路径分开。 Anthropic 的 OpenAI 兼容性层已记录字段和功能限制。通用内部信封可以帮助进行路由，但不得丢弃内容块顺序、缓存控制、思维签名、工具状态或特定于提供商的停止原因。

使会计版本感知

事实： 提示缓存使用将普通输入令牌、缓存创建输入令牌和缓存读取输入令牌分开。总投入消耗必须考虑所有适用的类别。

版本或测试版更改可能会改变缓存资格、内容表示或返回的使用字段。因此，每个使用事件都应包括：

• 已请求且有效的API版本。
• 请求并接受测试集。
• 租户、API密钥、策略、路由、模型、区域和上游请求 ID。
• 状态、停止原因、流完成状态和错误归因。
• 输入、输出、缓存创建和缓存读取令牌类别。
• 定价目录版本和临时或最终费用状态。

这些维度让统一人工智能API计费解释了为什么相似的请求会产生不同的成本。当提供商公开具有不同费率的类别时，避免按单个组合令牌计数进行计费。

在启用版本或测试版之前进行测试

为普通文本、流式文本、工具调用、结构化输出、拒绝、令牌截断、上下文窗口耗尽、暂停轮次、提示缓存、格式错误的请求、速率限制和中流错误创建合约固定装置。

对于每场比赛，比较HTTP以上的状态。捕获内容块类型和顺序、停止原因、工具标识符和参数、事件序列、使用字段存在、缓存类别和错误形状。存储已批准的结构预期而不是精确的散文输出。

仅当重复执行安全时才使用影子请求。涉及工具、外部副作用、敏感数据或材料成本的请求可能不合适。对于这些工作负载，在受控环境中重播已清理的装置。

预测：新版本和测试版功能将继续添加响应变体和事件。与围绕固定枚举和全局默认值构建的网关相比，围绕功能记录和附加解析设计的网关通常会吸收这些更改，并且紧急工作量更少。

安全地推出和停用功能

通过测试、内部、选择加入、金丝雀、可用、弃用和阻止状态来提升功能。在金丝雀期间，比较状态分布、停止原因、内容块序列、工具行为、使用字段、延迟和缓存结果。在流量开始之前定义回滚阈值。

退休应该分阶段进行：

1. 在现有分配继续的同时阻止新租户采用。
2. 识别受影响的租户、密钥、模型和最近的请求模式。
3. 提供替换的兼容性报告或测试端点。
4. 对已接受的请求发出警告并发布严格的截止日期。
5. 需要明确的例外情况，包括所有者和到期日期。
6. 阻止该功能并保留注册表记录以进行历史审核和结算解释。

固定可提高再现性，但会扩展测试矩阵。网关范围的版本减少了操作变体，但将不相关的租户耦合到一个迁移计划。广泛的测试版传递加速了功能访问，但削弱了成本、驻留和支持保证。对于多租户服务，明确的每租户策略通常是合理的中间立场。

实施清单

• 要求每个租户或API密钥都有版本政策。
• 维护测试版本和 Beta 功能记录。
• 在调度之前拒绝格式错误、未知或未经授权的功能。
• 仅在解决完整协议请求后才选择路由。
• 保留原生内容块、停止原因、使用字段和流。
• 安全转发附加流事件并保留其事件名称。
• 记录有关使用和审核事件的请求协议值和有效协议值。
• 在更改默认值之前运行合约装置和受控金丝雀。
• 通过谨慎的采用控制而不是静默重写来淘汰旧功能。

关键的设计决策很简单：版本和 Beta 标头是政策输入。一旦网关承认、路由、测试和计量它们作为功能，本机 API 兼容性就变得可控，无需假装实验行为是普通的 HTTP 元数据。

相关阅读

• 考虑最终使用、取消和部分流式传输响应