BFE mod_ai_route 模块基础配置指南:mod_ai_route.conf 详解
BFE mod_ai_route 模块基础配置指南:mod_ai_route.conf 详解
导读
mod_ai_route.conf 是 BFE 开源七层负载均衡器中 AI 路由模块(mod_ai_route)的基础配置文件,用于指定 AI 路由规则文件的路径并控制调试日志开关。本文以该配置文件为骨架,结合仓库内源码实现、真实部署配置与测试用例,系统讲解其配置项含义、校验逻辑、加载与热更新流程,以及与其配套的 ai_route.data 路由规则文件的格式规范,帮助你快速完成 AI 网关场景下的路由配置落地。
一、mod_ai_route 模块与配置文件的作用
mod_ai_route 是 BFE 面向 AI 网关场景的路由模块:它根据请求中携带的 API Key(ClientApiKey)查表,将请求路由到对应的 AI 集群与模型。模块的入口定义在 bfe_modules/mod_ai_route/mod_ai_route.go,模块名常量为 "mod_ai_route"。
mod_ai_route.conf 正是该模块的“总开关”配置文件,它本身不承载路由规则,只负责回答两个问题:
- 路由规则文件在哪里(
[Basic]段的RouteRulePath); - 是否输出调试日志(
[Log]段的OpenDebug)。
路由规则本体存放在由 RouteRulePath 指向的 JSON 数据文件(如 ai_route.data)中。
在 BFE 的配置目录体系中,模块配置文件约定位于 conf/mod_ai_route/ 下,仓库自带的真实示例为 conf/mod_ai_route/mod_ai_route.conf。
二、配置项总览
原文档给出的配置项说明如下表,两个配置项分属 [Basic] 与 [Log] 两个小节:
| 配置项 | 类型 | 含义 | 是否必填 | 补充说明 | 生效条件 |
|---|---|---|---|---|---|
Basic.RouteRulePath |
String | AI 路由规则文件的路径 | 是 | 无 | 类型为 FilePath;文件必须存在且可读 |
Log.OpenDebug |
Boolean | 是否开启调试日志 | 否 | 默认 False |
无 |
其中 FilePath 公共类型在 docs/en_us/configuration/00-common.md#3-filepath 中定义,要点如下:
- 类型为 String;
- 支持相对路径(相对于 BFE 配置根目录解析)或绝对路径(以
/开头); - 运行时被引用的文件必须存在且可读;
- 若未配置则回退到对应的默认值(对本模块而言,
RouteRulePath必填,不存在默认值)。
三、配置示例与真实部署文件
原文档给出了最简配置示例,采用 INI 风格(由 gopkg.in/gcfg.v1 解析):
[Basic]
RouteRulePath = ../data/mod_ai_route/ai_route.data
[Log]
OpenDebug = true
仓库中随项目发布的真实配置 conf/mod_ai_route/mod_ai_route.conf 内容如下,注意其小节名采用了小写形式(gcfg 解析不区分大小写,Basic 与 basic 等价):
[basic]
RouteRulePath = ../conf/mod_ai_route/ai_route.data
[log]
OpenDebug = false
两点实操提示:
- 路径写法:示例中的
../data/mod_ai_route/ai_route.data是相对路径,实际解析时会以 BFE 配置根目录为基准处理(见下文源码解析);生产环境也常直接配置绝对路径。 - 生产建议:
OpenDebug默认关闭;只有排查路由未命中、规则编译失败等问题时,才临时开启调试日志以观察api key empty、no route hit for apiKey[...]等调试输出。
四、配置加载与校验的源码级解析
mod_ai_route 的配置结构体与加载函数定义在 bfe_modules/mod_ai_route/conf_load.go:
type ConfModAiRoute struct {
Basic struct {
RouteRulePath string // path for ai route rule
}
Log struct {
OpenDebug bool
}
}
func ConfLoad(filePath string, confRoot string) (*ConfModAiRoute, error) {
var cfg ConfModAiRoute
if err := gcfg.ReadFileInto(&cfg, filePath); err != nil {
return &cfg, err
}
if err := cfg.Check(confRoot); err != nil {
return &cfg, err
}
return &cfg, nil
}
加载分两步:先用 gcfg.ReadFileInto 将 INI 内容解析进结构体,再调用 Check 做语义校验。校验逻辑 ConfModAiRouteCheck 是本模块唯一强校验点:
func ConfModAiRouteCheck(cfg *ConfModAiRoute, confRoot string) error {
if cfg.Basic.RouteRulePath == "" {
return fmt.Errorf("ConfModAiRouteCheck: RouteRulePath is empty")
}
cfg.Basic.RouteRulePath = bfe_util.ConfPathProc(cfg.Basic.RouteRulePath, confRoot)
return nil
}
关键行为:
RouteRulePath为空直接报错——它没有默认值,是硬性必填项;- 通过
bfe_util.ConfPathProc(位于 bfe_util/conf_path.go)将相对路径拼接到配置根目录confRoot之下,得到最终可用的规则文件路径; OpenDebug为布尔类型,缺省时 Go 零值即为false,与文档声明的默认值一致。
上述校验行为有对应的单元测试支撑,见 bfe_modules/mod_ai_route/conf_load_test.go:
TestConfLoadNormalCase:加载正常配置文件,断言RouteRulePath原样保留、OpenDebug == true;TestConfLoadEmptyRouteRulePath:RouteRulePath为空时加载必须失败;TestConfLoadFileNotFound:配置文件本身不存在时加载必须失败。
测试数据目录 bfe_modules/mod_ai_route/testdata/mod_ai_route/ 中提供了 mod_ai_route.conf(正常)与 mod_ai_route.conf.empty(空路径异常用例)两个样例,可直接对照学习。
五、从配置到生效:模块初始化与热更新链路
配置在模块初始化阶段被消费,调用链集中在 bfe_modules/mod_ai_route/mod_ai_route.go 的 Init 方法中:
confPath := bfe_module.ModConfPath(cr, m.name) // 定位 conf/mod_ai_route/mod_ai_route.conf
m.conf, err = ConfLoad(confPath, cr) // 步骤一:加载并校验配置
openDebug = m.conf.Log.OpenDebug // 步骤二:OpenDebug 写入全局开关
m.loadRouteRuleConf(nil) // 步骤三:按 RouteRulePath 加载规则数据
cbs.AddFilter(bfe_module.HandleFoundProduct, m.routeFoundProductHandler) // 步骤四:注册路由过滤器
各步骤要点:
confPath由bfe_module.ModConfPath(cr, m.name)生成,即配置根目录下的mod_ai_route/mod_ai_route.conf;loadRouteRuleConf读取m.conf.Basic.RouteRulePath指向的文件,调用AiRouteDataLoad(定义在 bfe_modules/mod_ai_route/data_load.go,内部通过bfe_util.LoadJsonFile解析 JSON),再交给routeTable.Update完成规则编译与原子替换;- 路由过滤器挂在
HandleFoundProduct阶段,按 API Key 查表命中后将结果写入请求上下文(SetAiRouteResult,上下文结构定义在 bfe_basic/request_ai_route.go)。
热更新能力:Init 同时向 web monitor 注册了两类处理器(见 bfe_modules/mod_ai_route/mod_ai_route.go 第 136-148 行):
WebHandleMonitor下的mod_ai_route:返回ReqTotal、ReqHitApikey、ReqHitEntity、ReqHitGlobal、ReqMiss、ReqFallback等请求统计指标;WebHandleReload下的mod_ai_route:可通过管理接口传入path参数重新加载指定规则文件,不传时回退到Basic.RouteRulePath。这意味着修改ai_route.data后无需重启 BFE 即可生效;若需更换规则文件路径本身,则仍要改配置并重启。
六、配套的规则数据文件(ai_route.data)
RouteRulePath 指向的文件格式由 bfe_modules/mod_ai_route/route_rule.go 中的 DTO 定义,顶层字段为 Version、route_rules 与 ApikeyRouteTableBindings。仓库自带的示例 conf/mod_ai_route/ai_route.data 如下:
{
"Version": "20260720150000",
"route_rules": {
"global_default": {
"type": "global",
"owner": "global",
"rules": [
{
"name": "global-default",
"Cond": "default_t()",
"targets": [
{
"ClusterName": "cluster_global",
"Model": "",
"Weight": 100
}
],
"fallbacks": []
}
]
}
},
"ApikeyRouteTableBindings": {
"default_api_key": [
"global_default"
]
}
}
从源码可以确认以下规则:
- 路由表类型
type仅支持apikey、entity、global三种(常量定义于 bfe_modules/mod_ai_route/route_rule.go);为兼容 ai-gateway-api 的 InnerAPI 字段名,UnmarshalJSON同时接受大驼峰字段RouteRules,并把"api_key"归一化为"apikey"; - 规则校验(
ValidateRouteTable):每条规则的name非空、Cond非空且能通过条件编译(condition.Build)、targets非空、所有 target 的Weight之和必须等于 100,否则加载直接失败; - 命中逻辑(bfe_modules/mod_ai_route/route_table.go):
Search按 API Key 找到绑定的一组路由表,依序调用Match(条件表达式匹配)返回首个命中的规则,规则中的targets与fallbacks即携带集群与模型信息供后续负载均衡使用。
测试数据目录 bfe_modules/mod_ai_route/testdata/ 还提供了 ai_route.data.invalid_weight、ai_route.data.invalid_cond、ai_route.data.empty_targets 等异常样例,可用于验证上述校验逻辑。
七、配置检查清单
部署 mod_ai_route 时,建议按以下顺序自检:
conf/mod_ai_route/mod_ai_route.conf存在且被正确挂载到配置根目录;[Basic] RouteRulePath非空,指向的文件存在、可读,且为合法 JSON;- 规则文件中的路由表类型合法(
apikey/entity/global),每条规则的Cond可编译、targets非空且权重合计为 100; - 请求侧确保已提取到
ClientApiKey(若 API Key 为空,模块会直接跳过路由,见 bfe_modules/mod_ai_route/mod_ai_route.go 的routeFoundProductHandler); - 如需排查问题,临时将
OpenDebug置为true并观察api key empty、no route hit等调试日志,问题解决后恢复为false。
完成以上步骤,即可让 mod_ai_route 依据 mod_ai_route.conf 完成规则文件加载、按 API Key 路由分发,并支持通过管理接口进行规则热更新。