BFE AI 网关 Claude 协议支持实战:TC-02 Anthropic 风格转发全链路解析
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 用例文档,复现该用例需要满足:
- 已编译
bfe可执行文件(仓库根目录执行make或go build产出); - mock 后端
cluster_anthropic_only已启动,返回 200; - 临时 BFE 配置已生成并加载:
cluster_anthropic_only配置ModelProtocols = ["anthropic"],Key 为anthropic-key; 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_onlymock 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 决定,规则如下:
- 请求路径以
/v1/messages开头 →anthropic(TC-02 即命中此规则); - 存在
x-api-key且不存在Authorization→anthropic; - 否则默认
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)中依次执行:
- 兜底识别:
AuthStyle为空或 unknown 时调用DetectAuthStyle; - 协议匹配校验(L1534-L1543):调用
clusterSupportsAuthStyle(cluster.AIConf.ModelProtocols, aiMeta.AuthStyle),不匹配时返回 400 与错误码PROVIDER_PROTOCOL_MISMATCH(消息格式如request protocol anthropic not supported by cluster provider (model_protocols=[openai])),upstream 不被调用; - 认证注入(L1625-L1629):按协议风格调用
adapter.InjectAuth(outreq, selectedKey.Key)——Anthropic 风格写入x-api-key: sk-anthropic-key; - 补充头注入(L1632-L1638):遍历
adapter.ExtraHeaders(),仅当请求未携带该头时才设置——即客户端显式传anthropic-version时不被覆盖(SC06 TC-07 的验证点); - 继续执行模型映射、路径改写与 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,与 OpenAIprompt_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。