BFE AI 网关 Claude 协议支持实战:TC-02 Anthropic 风格转发全链路解析

原创2026-10-11 20:24:541,403 阅读
文章标签:后端网络/通信云原生

BFE AI 网关 Claude 协议支持实战:TC-02 Anthropic 风格转发全链路解析

本文围绕 BFE(百度开源七层负载均衡器,具备 AI 网关能力)集成测试场景 SC06「Claude 协议支持」中的 TC-02 用例,讲解 Anthropic 风格请求从协议识别、路由绑定、认证头注入到 anthropic-version 自动补齐的完整转发链路。读者将掌握 BFE 如何区分 OpenAI 与 Anthropic 两种请求风格、如何通过 AIConf.ModelProtocols 做协议一致性校验,以及如何配置集群与路由表复现该用例并验证上游收到的头部。

一、用例定位:TC-02 在 SC06 场景中的角色

TC-02(Anthropic 风格转发)属于集成测试场景 SC06 Claude 协议支持。SC06 场景验证 BFE AI 网关自 v0.5 起对 Anthropic Claude Messages API 的完整支持,覆盖协议识别、认证头注入、版本头补齐、协议匹配拒绝与 usage 字段解析等多个维度。

TC-02 的核心验证点是:

  • Anthropic 风格请求被正确路由到仅支持 anthropic 协议的集群 cluster_anthropic_only;
  • BFE 使用 x-api-key 头向 upstream 注入集群 key(而非 OpenAI 风格的 Authorization: Bearer);
  • 自动补 anthropic-version: 2023-06-01 版本头;
  • 客户端原始 Authorization 头不被透传污染。

该用例的运行模式为单组件模式:仅启动真实 bfe 进程,不涉及 ai-gateway-api 与 conf-agent,因此可以独立复现、独立验证,是理解 BFE 协议适配层行为的最小闭环。

二、前置条件与运行环境

根据 TC-02 用例文档,复现该用例需要满足:

  1. 已编译 bfe 可执行文件(仓库根目录执行 make 或 go build 产出);
  2. mock 后端 cluster_anthropic_only 已启动,返回 200;
  3. 临时 BFE 配置已生成并加载:cluster_anthropic_only 配置 ModelProtocols = ["anthropic"],Key 为 anthropic-key;
  4. ai_route.data 中 apikey_ak_user_a 命中 user_a-anthropic,target 为 cluster_anthropic_only。

对应场景涉及的 BFE 配置文件如下:

文件 说明
bfe.conf 启用 EnableAiGateway,加载 mod_ai_route
mod_ai_route/mod_ai_route.conf 指定 ai_route.data 路径
mod_ai_route/ai_route.data 定义 apikey 级路由规则,按 Host 路由到不同 cluster
server_data_conf/host_rule.data 声明 ai_product 产品线对应的 Host
server_data_conf/route_rule.data 默认路由(本用例不命中)
cluster_conf/cluster_conf.data 运行时根据 mock 后端与 AIConfs 动态生成
cluster_conf/gslb.data GSLB 权重配置
cluster_conf/cluster_table.data 运行时根据 mock 后端地址动态生成

三、集群与路由配置构造

3.1 集群 AIConf

TC-02 的集群配置如下:

{
    "AIConf": {
        "Type": 0,
        "ModelProtocols": ["anthropic"],
        "Keys": [
            {"Name": "anthropic-key", "Key": "sk-anthropic-key", "Weight": 100}
        ]
    }
}

关键参数说明:

  • ModelProtocols:声明该集群 provider 支持的模型访问协议。["anthropic"] 表示仅支持 Anthropic 协议,请求协议不在列表内时 BFE 直接拒绝(详见下文第四节)。该字段来源于 ai-gateway-api 的 provider.model_protocols 配置。
  • Keys:集群级上游凭证列表,支持多 Key 加权轮换。TC-02 仅配置单 Key,Weight: 100 表示全量权重;Key 字段为注入 upstream 的真实凭证 sk-anthropic-key。
  • Type: 0:AI 集群类型标识(0 为常规 AI 转发类型)。

3.2 路由表设计

ai_route.data 中为 API Key ak_user_a 绑定 apikey 级路由表:

{
    "ApikeyRouteTableBindings": {
        "ak_user_a": ["apikey_ak_user_a"]
    }
}

路由规则 apikey_ak_user_a 内定义三条按 Host 区分的规则(SC06 场景通用设计):

规则名 条件 targets fallbacks
user_a-openai req_host_in("openai.example.org") cluster_openai_only 无
user_a-anthropic req_host_in("anthropic.example.org") cluster_anthropic_only 无
user_a-both req_host_in("both.example.org") cluster_both_protocols 无

TC-02 命中的是 user_a-anthropic 规则:请求 Host 为 anthropic.example.org 时,目标集群为 cluster_anthropic_only。

路由查找在 mod_ai_route 模块的 routeFoundProductHandler 中执行(mod_ai_route.go):先通过 AiBasicInfo.ClientApiKey 取客户端 key,再调用 routeTable.Search(apiKey, req) 匹配规则,命中后通过 req.SetAiRouteResult(result) 将路由结果写入请求上下文。

四、BFE 请求构造与预期结果

4.1 请求构造

向 BFE 发送 1 次 POST 请求:

字段 值
Host anthropic.example.org
Path /v1/messages
x-api-key ak_user_a
Body {"model":"claude-3-5-sonnet","messages":[{"role":"user","content":"hi"}]}

注意:客户端携带的 x-api-key: ak_user_a 是客户端自身标识(用于路由查找与鉴权),并非最终注入上游的凭证;BFE 会将其替换为集群配置中的 sk-anthropic-key。

4.2 预期结果

  • 响应状态码:200;
  • cluster_anthropic_only mock backend 命中 1 次;
  • upstream 收到的 x-api-key 头为 sk-anthropic-key;
  • upstream 收到的 anthropic-version 头为 2023-06-01;
  • upstream 未收到 Authorization 头。

4.3 清理

停止 bfe 进程与 mock 后端,删除临时目录(对应集成测试框架中 testEnv.Close() 的行为:先 stopBFE(),再逐个 backend.Close())。

五、源码级原理:Anthropic 风格转发链路

TC-02 验证的转发链路在源码层由三部分组成:协议识别(detect.go)、协议适配器(anthropic 适配器)与转发主路径(reverseproxy.go)。

5.1 协议识别:路径优先,头兜底

请求进入 BFE 后,协议风格由 detect.go 的 DetectProtocol 决定,规则如下:

  1. 请求路径以 /v1/messages 开头 → anthropic(TC-02 即命中此规则);
  2. 存在 x-api-key 且不存在 Authorization → anthropic;
  3. 否则默认 openai。

该识别仅依赖请求路径与请求头,不依赖用户路由表条件,识别结果写入 AiBasicInfo.AuthStyle。识别与 key 提取由 DetectProtocolAndKey 完成(detect.go),其优先级为 Authorization: Bearer > x-api-key > x-goog-api-key,即双头并存时 OpenAI 风格优先——这正是 SC06 中 TC-06 的验证点。

5.2 协议适配器:Anthropic 认证注入与版本头

bfe_model_protocol/anthropic 包实现 Anthropic 协议适配器,核心方法:

  • InjectAuth(auth.go):将上游凭证写入 x-api-key 头,空 key 为空操作;
  • ExtraHeaders(anthropic.go):返回 {"anthropic-version": "2023-06-01"}——即 Claude Messages API 要求的版本头默认值;
  • ExtractUsageFields(usage.go):委托 utils.ParseAnthropicUsageFields 解析 Claude 响应 usage;
  • IsStreamTerminal / IsFinalUsageEvent(stream.go):message_stop 结束流,message_delta 携带最终 usage。

适配器为无状态单例,通过 registry.go 在 init() 时注册(openai / anthropic / gemini)。modelprotocol.Get(protocol) 按协议名取适配器,未知协议回落 openai;Supports(protocols, p) 做协议支持判断,空列表默认仅支持 openai,保证旧集群向后兼容。

5.3 转发主路径:协议校验与头部注入

在 doSingleAIForward()(reverseproxy.go)中依次执行:

  1. 兜底识别:AuthStyle 为空或 unknown 时调用 DetectAuthStyle;
  2. 协议匹配校验(L1534-L1543):调用 clusterSupportsAuthStyle(cluster.AIConf.ModelProtocols, aiMeta.AuthStyle),不匹配时返回 400 与错误码 PROVIDER_PROTOCOL_MISMATCH(消息格式如 request protocol anthropic not supported by cluster provider (model_protocols=[openai])),upstream 不被调用;
  3. 认证注入(L1625-L1629):按协议风格调用 adapter.InjectAuth(outreq, selectedKey.Key)——Anthropic 风格写入 x-api-key: sk-anthropic-key;
  4. 补充头注入(L1632-L1638):遍历 adapter.ExtraHeaders(),仅当请求未携带该头时才设置——即客户端显式传 anthropic-version 时不被覆盖(SC06 TC-07 的验证点);
  5. 继续执行模型映射、路径改写与 cluster 转发。

对比 OpenAI 适配器(openai/auth.go)的 InjectAuth 生成 Authorization: Bearer <key>,而 ExtraHeaders 返回 nil——这解释了 TC-02 中 upstream「未收到 Authorization 头」的预期:Anthropic 适配器只写 x-api-key,且上游出站请求基于客户端请求复制构造,客户端本身未带 Authorization,因此不会出现该头。

5.4 Usage 字段解析(TC-08 关联)

TC-02 的响应体包含 Claude usage 字段。ParseAnthropicUsageFields(usage_parse.go)的解析要点:

  • usage.input_tokens → PromptTokens、usage.output_tokens → CompletionTokens;
  • cache_read_input_tokens / cache_creation_input_tokens 分别归一化到 CacheReadTokens / CacheWriteTokens;
  • 归一化:Anthropic 的 input_tokens 仅含 cache miss 的 fresh token,因此 PromptTokens = input_tokens + cache_read + cache_creation,与 OpenAI prompt_tokens 语义对齐;
  • 流式 message_start 的初始 usage 嵌套在 message.usage.*,代码同时接受该路径;
  • Claude 响应无 total_tokens 时,UsedQuota 由归一化后的 input + output 推导。

该归一化保证配额扣减、成本计算与访问日志(如 ai_input_tokens / ai_output_tokens / ai_total_tokens)对两种协议语义一致。

六、集成测试实现与断言策略

TC-02 的自动化实现在 sc06_claude_protocol_test.go 的 TestTC02_AnthropicStyleForwarded(L193-L222):

resp, body, err := e.sendRequest(hostAnthropic, pathAnthropic, "x-api-key", apiKey, anthropicBody())
// 断言 1:状态码 200
// 断言 2:cluster_anthropic_only 命中 1 次
// 断言 3:backend.XApiKeyHeaders()[0] == "sk-anthropic-key"
// 断言 4:backend.AuthHeaders()[0] == ""(无 Authorization)
// 断言 5:backend.AnthropicVersions()[0] == "2023-06-01"

测试环境构造(newTestEnv,L55-L111)要点:

  • mock 后端通过 common.NewMockBackend 创建,cluster_anthropic_only 默认返回 200 与 Claude 格式响应体;
  • AIConfs 以 map 形式注入 BFEConfigBuilder,运行时动态生成 cluster_conf.data 与 cluster_table.data;
  • 启动真实 bfe 进程,通过 127.0.0.1:<port> 发送请求。

对应的公共测试基础设施扩展:SC06 场景为 mock_backend.go 新增了 x-api-key 与 anthropic-version 头记录能力,并提供 XApiKeyHeaders()(L217-L221)与 AnthropicVersions()(L231-L235)查询方法——这正是本用例断言上游头部是否正确的数据来源。

七、边界与失败路径(SC06 场景视角)

TC-02 展示的是「风格匹配、转发成功」的正向路径,SC06 场景中的相邻用例覆盖了同一机制的反向边界:

用例 场景 预期
TC-03 Anthropic 请求命中 OpenAI-only 集群 400 PROVIDER_PROTOCOL_MISMATCH,upstream 0 命中
TC-04 OpenAI 请求命中 Anthropic-only 集群 400 PROVIDER_PROTOCOL_MISMATCH,upstream 0 命中
TC-05 多协议集群(["openai","anthropic"])同时支持两种请求 按风格注入对应头部
TC-06 双头并存(Authorization + x-api-key) Authorization 优先,按 OpenAI 风格处理
TC-07 客户端显式传 anthropic-version BFE 不覆盖,原值透传
TC-08 Claude usage 字段解析 input_tokens / cache 字段被接受,响应正常

这些用例共同印证一个设计原则:BFE 对 Claude 协议不做协议翻译(content[] 与 choices[] 结构差异对网关透明),只解决三个核心差异——认证头、版本头与 usage 字段,且默认行为保持 OpenAI 兼容(ModelProtocols 为空时仅支持 openai),不破坏现有 OpenAI/DeepSeek 集群。

八、风险提示与配置前提

复现或生产使用 TC-02 涉及的能力时,需注意:

  • AIConf.ModelProtocols 必须显式声明 anthropic:若留空,默认仅支持 openai,Anthropic 请求会在协议匹配处被 PROVIDER_PROTOCOL_MISMATCH 拒绝(参见 TC-02-anthropic协议路径改写 中的说明);
  • anthropic-version 默认值选择长期支持版本 2023-06-01,客户端显式传值时以客户端为准;
  • 协议识别不依赖 model 名或 provider 名(provider 名称是用户自定义的),只依赖路径/头与 ModelProtocols 显式配置;
  • 若线上需要恢复旧行为,需回滚代码并重新发版,影响面仅涉及 AI 网关路径。

上述设计决策与失败处理的完整论证可参考 claude_protocol_support.md,协议适配层收敛说明见 model_protocol_adapter.md。

登录后查看全文
bfe