BFE mod_ai_route 模块基础配置指南:mod_ai_route.conf 详解

原创2026-10-08 23:38:281,840 阅读
文章标签:后端网络/通信云原生

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 正是该模块的“总开关”配置文件,它本身不承载路由规则,只负责回答两个问题:

  1. 路由规则文件在哪里([Basic] 段的 RouteRulePath);
  2. 是否输出调试日志([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
}

关键行为:

  1. RouteRulePath 为空直接报错——它没有默认值,是硬性必填项;
  2. 通过 bfe_util.ConfPathProc(位于 bfe_util/conf_path.go)将相对路径拼接到配置根目录 confRoot 之下,得到最终可用的规则文件路径;
  3. 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 时,建议按以下顺序自检:

  1. conf/mod_ai_route/mod_ai_route.conf 存在且被正确挂载到配置根目录;
  2. [Basic] RouteRulePath 非空,指向的文件存在、可读,且为合法 JSON;
  3. 规则文件中的路由表类型合法(apikey/entity/global),每条规则的 Cond 可编译、targets 非空且权重合计为 100;
  4. 请求侧确保已提取到 ClientApiKey(若 API Key 为空,模块会直接跳过路由,见 bfe_modules/mod_ai_route/mod_ai_route.go 的 routeFoundProductHandler);
  5. 如需排查问题,临时将 OpenDebug 置为 true 并观察 api key empty、no route hit 等调试日志,问题解决后恢复为 false。

完成以上步骤,即可让 mod_ai_route 依据 mod_ai_route.conf 完成规则文件加载、按 API Key 路由分发,并支持通过管理接口进行规则热更新。

登录后查看全文
bfe