BFE AI 协议路径改写之"非标准入口透传":TC-06 用例的技术原理与验证

原创2026-10-11 16:02:581,914 阅读
文章标签:后端网络/通信云原生

BFE AI 协议路径改写之"非标准入口透传":TC-06 用例的技术原理与验证

BFE(Baidu Front End)是百度开源的现代化七层负载均衡器,其 AIConf.ProtocolPaths 特性支持按 AI 协议(openai / anthropic)将客户端入口路径改写为 provider 上游 API 基路径。本文以集成测试设计文档 TC-06 非标准入口透传 为核心,完整还原该用例的前置条件、请求构造、改写计算与断言设计,并结合 ai_path_rewrite.go 等源码与 SC17 场景说明 展开原理级解读,帮助读者理解"标准入口判定"的精确边界,以及 BFE 如何保证非标准入口路径永不改写(透传模式不受影响)。

一、用例所属场景:SC17 AI 协议路径改写

TC-06 是 SC17 场景(AI 协议路径改写,AIConf.ProtocolPaths)的 6 号测试用例。该场景解决的业务问题是:不同 model provider 的上游路径各不相同,且同一 provider 的不同协议(OpenAI 兼容 / Anthropic 兼容)挂在不同前缀下——例如百炼的 OpenAI 兼容端点为 /compatible-mode/v1、Anthropic 兼容端点为 /apps/anthropic;火山方舟按量为 /api/v3、Coding Plan 为 /api/coding/v3。

AIConf.ProtocolPaths 允许按协议声明上游 API 基路径(即该协议官方 SDK base_url 的 path 部分),BFE 在转发时将客户端入口路径改写为 provider 专属前缀。完整的设计背景与公式推导见 ai_protocol_paths.md,SC17 场景共包含 8 个测试用例(TC-01 至 TC-08),覆盖:

  • openai / anthropic 两种协议分别按配置改写(含双协议 cluster 独立改写,TC-03);
  • cluster 级 fallback 时按原始客户端路径重算上游路径(TC-04);
  • 未配置 ProtocolPaths 时请求路径逐字节透传(TC-05,向后兼容);
  • 非标准入口路径永不改写(TC-06,本文主题);
  • openai 无 /v1 入口改写为与 /v1 入口相同结果(TC-07 / TC-08,issue #1379)。

TC-06 的定位是上述场景验证清单中的第 4 条:"非标准入口路径(provider 原生路径、/v10/xxx、gemini 风格路径)与未命中 openai 标准端点的路径永不被改写(透传模式不受影响)"。它是整个改写特性的边界安全网——保证特性只作用于标准 /v1/... 入口,绝不误伤其他路径。

二、测试目的与两类"非标准入口"

TC-06 的测试目的是:验证 ProtocolPaths 已配置时,非标准入口路径仍永不改写。用例聚焦两类典型场景:

  1. provider 原生路径:/compatible-mode/v1/chat/completions——客户端按 provider 原生路径访问的透传模式不受影响。注意该路径虽形似标准入口(内含 /v1 段),但整条路径不以 /v1 开头,因此不被判定为标准入口;
  2. 形似但不匹配的前缀:/v10/xxx——标准入口判定要求 reqPath == "/v1" 或以 "/v1/" 开头,/v10 只是与 /v1 共享字符前缀,前缀判定不会误伤。

用一句话概括:改写特性存在时,只有"标准 /v1 入口"被改写,其余所有路径一律原样透传。

三、运行模式与前置条件

TC-06 采用单组件模式:仅启动真实 bfe 进程,不涉及 ai-gateway-api 与 conf-agent。AIConf.ProtocolPaths 由测试代码经 BFEConfigBuilder 直接写入生成的 cluster_conf.data(场景说明的"运行模式"一节明确说明,参见 场景说明.md)。

测试环境的 cluster_primary 配置如下(AIConf 形态与 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough 的构造完全一致):

{
    "Type": 0,
    "ModelProtocols": ["openai", "anthropic"],
    "ProtocolPaths": {"openai": "/api/v3"}
}

关键配置语义:

  • ModelProtocols: ["openai", "anthropic"]:声明 cluster 支持的协议。场景说明强调,所有测试例的 cluster_primary / cluster_fallback 均声明这两个协议,否则 anthropic 请求会在协议匹配处被 PROVIDER_PROTOCOL_MISMATCH 拒绝;
  • ProtocolPaths: {"openai": "/api/v3"}:openai 协议的上游基路径为 /api/v3(火山方舟按量的 SDK base_url path 形态)。该配置是"改写已就绪"的证据——TC-06 要验证的正是在改写开关已打开的情况下,非标准路径依然透传;
  • cluster_fallback 在本用例不配置 ProtocolPaths,且断言其命中数为 0。

另外,测试环境还启动 cluster_default mock 后端(basic 路由引用,测试断言不命中),其细节同样可见于 场景说明.md 的"涉及的 BFE 配置文件"一节。

四、BFE 请求构造

TC-06 按序发送 2 次 openai 风格请求,均为 POST,Host 为 api.example.org,认证头为 Authorization: Bearer ak_user_a(ak_user_a 用于 mod_ai_route 的 apikey 级路由查找,命中 default_t() 规则 → cluster_primary,fallback → cluster_fallback):

序号 请求路径 判定
1 /compatible-mode/v1/chat/completions 非标准入口(不以 /v1 开头)
2 /v10/xxx 非标准入口(/v10 不等于 /v1,前缀判定不匹配)

测试代码中,这两条请求通过 sendRequest(path, authHeader, body) 发送(参见 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough),请求体为 openai 风格的 {"model":"test-model","messages":[{"role":"user","content":"hello"}]}。

五、改写计算:为什么这两条路径"永不改写"

两条请求均不满足 isStandardV1Prefix,落入透传分支:upstream = reqPath。这一点需要结合源码逐层理解。

5.1 入口判定:isStandardV1Prefix

改写公式的入口判定实现在 ai_path_rewrite.go 中:

// isStandardV1Prefix reports whether reqPath is exactly "/v1" or starts
// with "/v1/". Paths like "/v10/xxx" do not match.
func isStandardV1Prefix(reqPath string) bool {
	return reqPath == "/v1" || strings.HasPrefix(reqPath, "/v1/")
}

关键点在于 strings.HasPrefix(reqPath, "/v1/") 的写法:它要求 /v1 之后必须紧跟 /。因此:

  • /v10/xxx 虽然以 /v1 开头,但第 4 个字符是 0 而非 /,HasPrefix("/v10/xxx", "/v1/") 为 false,且 reqPath != "/v1",故判定为非标准入口;
  • /compatible-mode/v1/chat/completions 以 /c 开头,前缀判定直接不成立,同样落入非标准分支。

对比之下,若误用 strings.HasPrefix(path, "/v1")(缺少末尾斜杠)实现,/v10/xxx 会被 /v1 命中并改写成 /api/v3/0/xxx——这正是 TC-06 的"改写计算"一节所警示的实现错误:"第二条若误用 strings.HasPrefix(path, "/v1") 实现,会被 /v10 命中并改写成 /api/v3/0/xxx——本用例的断言能暴露该实现错误。"也就是说,本用例的存在价值之一就是以断言捕获这种边界实现缺陷。

5.2 透传分支:rewriteUpstreamPath

整体改写函数 rewriteUpstreamPath 依次经过三道拦截,任何一道命中即返回原路径:

func rewriteUpstreamPath(reqPath string, authStyle string, aiConf *cluster_conf.AIConf) string {
	if aiConf == nil {
		return reqPath
	}
	base, ok := aiConf.ProtocolPaths[authStyle]
	if !ok {
		return reqPath
	}
	if authStyle == bfe_basic.AuthStyleAnthropic {
		if !isStandardV1Prefix(reqPath) {
			return reqPath
		}
		return base + reqPath
	}
	// openai 分支:精确 /v1、/v1/ 或剥离 /v1 后命中标准端点才改写
	if reqPath == "/v1" || reqPath == "/v1/" {
		return base
	}
	rest := bfe_basic.StripV1Prefix(reqPath)
	if !bfe_basic.IsOpenAIEndpoint(rest) {
		return reqPath
	}
	return base + rest
}

对 TC-06 的两条 openai 风格请求(authStyle == "openai",base = "/api/v3")逐一推演:

  1. /compatible-mode/v1/chat/completions:既不是 /v1 也不是 /v1/;StripV1Prefix 仅剥离开头的 /v1/ 前缀,该路径开头是 /compatible-mode,剥离步骤恒等返回原路径;IsOpenAIEndpoint("/compatible-mode/v1/chat/completions") 无法命中 openai_endpoint.go 中 openAIEndpointModes 表的任何标准端点(端点匹配要求路径本身以 /chat/completions 等标准端点开头,或剥离 /v1 后匹配)——最终透传,upstream = /compatible-mode/v1/chat/completions;
  2. /v10/xxx:不满足 isStandardV1Prefix(见 5.1 节);即便继续走到 StripV1Prefix,/v10/xxx 也不以 /v1/ 开头,剥离恒等;IsOpenAIEndpoint("/v10/xxx") 为 false(既不在端点表中,也不以任何端点 + / 开头)——最终透传,upstream = /v10/xxx。

值得注意的还有 openai_endpoint.go 中 StripV1Prefix 的注释明确写到的边界语义:"paths without the prefix (including /v10/xxx and provider-native paths such as /compatible-mode/v1/chat/completions) are returned unchanged"。该函数被 DetectModeFromPath(计费模式识别)与 bfe_server 路径改写共享,保证"端点兼容性判定"与"计费模式识别"对标准端点的认定永远一致。

5.3 openai 与 anthropic 的入口判定差异

值得注意的是,两条透传分支的入口判定在源码中有两处独立的实现:

  • anthropic 分支:直接调用 isStandardV1Prefix,只改写 /v1 或 /v1/...(Anthropic SDK 自行拼接 /v1/messages,故基路径不含 /v1 尾);
  • openai 分支:不调用 isStandardV1Prefix,而是"精确 /v1、/v1/ 返回基路径;否则 StripV1Prefix + IsOpenAIEndpoint 双条件"(OpenAI SDK 向含 /v1 尾的 base_url 拼接 /chat/completions 等资源路径,客户端入口可能带也可能不带 /v1 前缀,issue #1379)。

但两分支对 TC-06 两类路径的结论一致:非标准入口一律透传。这正是设计文档 ai_protocol_paths.md 第 4.2 节"三个要点"中的第一条:"本特性依赖'网关对外入口 = /v1/...'这一约定……客户端直连 provider 原生路径(透传模式)不受影响——非 /v1 开头的路径一律透传"。

5.4 改写只落在 outreq 的私有 URL 拷贝

最后一步保障来自 applyAIProtocolPathRewrite:即使发生改写,结果也只写入 outreq 的私有 URL 拷贝(u := *outreq.URL; u.Path = newPath; u.RawPath = ""),入站请求 URL 永不修改,因此每次 cluster attempt(包括 fallback)都从原始客户端路径重新计算(参见 ai_path_rewrite.go 的 applyAIProtocolPathRewrite 与 reverseproxy.go 中 doSingleAIForward 调用点 applyAIProtocolPathRewrite(outreq, aiMeta.AuthStyle, cluster.AIConf))。TC-06 的两条透传路径改写前后相等,applyAIProtocolPathRewrite 直接提前返回,共享 URL 指针,行为与未配置特性时逐字节一致。

六、预期结果与断言设计

TC-06 的预期结果如下:

断言 预期
两次响应状态码 200
cluster_primary 后端收到的路径序列 [/compatible-mode/v1/chat/completions, /v10/xxx],与请求路径逐一相等
cluster_fallback 命中数 0

对应的实现为 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough:

  • 通过 assertStatus(t, e, resp, respBody, http.StatusOK) 断言两次响应均为 200;
  • 通过 assertPaths(t, e.backends[clusterPrimary], []string{"/compatible-mode/v1/chat/completions", "/v10/xxx"}) 断言 cluster_primary 后端按序收到两条与原请求路径逐一相等的路径(透传),这是本用例最核心的断言;
  • 用例未显式断言 cluster_fallback 命中数为 0,但路由设计保证请求命中 cluster_primary 且 primary 返回 200,fallback 不会触发。

其中 mock 后端的路径观测点 URLPaths() 实现在 mock_backend.go(func (b *MockBackend) URLPaths() []string,返回所有观测到的请求 URL 路径的深拷贝),是 场景说明.md 所述"新增 URLPaths() 观测点记录后端收到的请求路径"的落地。

七、TC-06 在整个 SC17 场景中的价值

将 TC-06 与相邻用例对比,可以更清晰地看出其独特价值:

用例 配置形态 验证点
TC-01 {openai: /compatible-mode/v1} 标准 /v1/chat/completions 入口被改写
TC-05 无 AIConf(nil) 未配置时全路径透传(向后兼容)
TC-06 {openai: /api/v3} 配置已打开时,非标准入口仍透传
TC-07 {openai: /compatible-mode/v1} 无 /v1 入口与 /v1 入口改写结果相同

TC-05 与 TC-06 看似都在验证"透传",但语义截然不同:TC-05 验证的是特性关闭时的默认行为(cluster.AIConf == nil → rewriteUpstreamPath 第一分支直接返回原路径);TC-06 验证的是特性开启时改写公式的边界不变量——ProtocolPaths 只对"标准 /v1 入口"生效,对 provider 原生路径与形似前缀(/v10/xxx)绝不误伤。

这一"永不改写"保证具有重要的业务含义:

  • 透传模式不受影响:客户端直连 provider 原生路径的存量调用方式,在配置了 ProtocolPaths 后行为不变,无需迁移;
  • 实现缺陷可被暴露:若标准入口判定实现不当(如 strings.HasPrefix(path, "/v1") 缺少末尾斜杠),TC-06 的路径序列断言会立即失败,将 /v10/xxx 被错误改写为 /api/v3/0/xxx 的实现错误暴露在测试期而非线上。

设计文档 ai_protocol_paths.md 第 4.3 节场景验证表也明确列出该边界:"边界:/v1 精确值与 /v1/ 前缀才进入改写;/v10/xxx、gemini 风格 /v1beta/... 一律透传。"TC-06 正是该边界声明的可执行化验证。

八、运行方式

SC17 场景的集成测试整体运行方式见 场景说明.md 的"运行方式"一节:

go test ./tests/integration/implementation/scenario-SC17-ai-protocol-paths-rewrite/ -v

该命令会依次执行 TC-01 至 TC-08 全部用例(对应 sc17_ai_protocol_paths_rewrite_test.go 中的 TestTC01 至 TestTC08 各测试函数),其中 -v 用于输出每个用例的执行详情。测试框架负责启动真实 bfe 进程与 mock 后端、动态生成 cluster_conf.data 与 cluster_conf/cluster_table.data(后端地址动态写入),并按用例注入不同 AIConf。

总结

TC-06 非标准入口透传是 SC17 AI 协议路径改写场景的边界守护用例。它用两个精心构造的请求(provider 原生路径 /compatible-mode/v1/chat/completions 与形似前缀 /v10/xxx)验证了改写公式的不变量:ProtocolPaths 已配置时,非标准入口路径仍永不改写。其背后是 ai_path_rewrite.go 中 isStandardV1Prefix 的精确前缀判定(/v1 或 /v1/ 开头)、openai_endpoint.go 中 StripV1Prefix 与 IsOpenAIEndpoint 的标准端点白名单,以及"改写只落 outreq 私有 URL 拷贝、入站路径永不污染"的正确性设计。理解 TC-06,就等于理解了 BFE 协议路径改写特性"只改标准、绝不误伤"的完整边界。

登录后查看全文
bfe