FEATURED · 精选文章

Higress model-router 插件实战:基于 LLM model 参数与自动路由的智能分发指南

发布时间 / 2026/9/16 13:00:15
来源 / 创域科博编辑部
栏目 / 资讯中心
Higress model-router 插件实战:基于 LLM model 参数与自动路由的智能分发指南 Higress model-router 插件实战基于 LLM model 参数与自动路由的智能分发指南【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本篇技术指南以 Higress 开源仓库中model-router插件为核心围绕其基于 LLM 协议model参数的三种路由模式模型名直传、provider 提取、自动路由展开结合 插件实现源码 与 单元测试 讲解配置字段、执行原理与边界行为。读完本文你将掌握如何利用该插件为多个模型提供方共享同一网关入口并通过请求头实现按模型、按提供方乃至按用户消息内容的路由分发。插件定位与运行属性model-router是 Higress 官方维护的 Go 语言 WASM 插件实现位于 plugins/wasm-go/extensions/model-router版本号为2.0.2见 VERSION。其核心能力是从 LLM 协议请求体中解析model参数并将其映射为请求头供后续网关路由规则如基于 header 的匹配使用同时可按需改写请求体中的model字段。从插件声明main.go可以看到它的关键运行属性属性值插件名称model-router执行阶段认证阶段Authentication phase执行优先级900请求体缓冲上限100 MBDefaultMaxBodyBytes重建缓冲上限200 MBWithRebuildMaxMemBytes插件在认证阶段执行意味着它在身份校验、路由匹配的早期即可完成 model 参数的解析与 header 注入后续的路由规则可以直接消费这些 header。由于需要读取并可能改写请求体插件在处理请求头时会先检查路径后缀是否命中命中后移除content-length头并申请 100 MB 的请求体缓冲见 main.go。配置字段详解插件的全部配置通过 JSON 结构传入字段定义与默认值如下表与 README_EN.md 一致并补充源码解析细节名称数据类型填写要求默认值描述modelKeystring选填model请求 body 中 model 参数的位置JSON 路径addProviderHeaderstring选填-从 model 参数解析出的 provider 名字写入哪个请求 headermodelToHeaderstring选填-将完整 model 参数直接写入哪个请求 headerenableOnPathSuffixarray of string选填见下文仅对这些路径后缀的请求生效可配置为*匹配所有路径keepOriginalModelNamebool选填false配合addProviderHeader使用设为true时仍提取 provider 写入 header但不改写请求体中的 model 字段autoRoutingobject选填-自动路由配置基于用户消息内容详见后文enableOnPathSuffix的默认值在源码中硬编码见 main.go覆盖了 OpenAI 兼容协议的主流接口路径[/completions, /embeddings, /images/generations, /audio/speech, /fine_tuning/jobs, /moderations, /image-synthesis, /video-synthesis, /rerank, /messages, /responses]注意源码默认值比文档表格多出/responses这是 OpenAI Responses API 的路径后缀。文档中描述为/completions,/embeddings,/images/generations,/audio/speech,/fine_tuning/jobs,/moderations,/image-synthesis,/video-synthesis,/rerank,/messages实际生效范围以源码为准。路径匹配时插件会先剔除 URL 中的查询参数再做后缀比较main.go因此/v1/chat/completions?streamtrue也能正确命中/completions后缀这一点有专门测试TestOnHttpRequestHeaders_PathWithQueryStripped锁定main_extra_test.go。若配置为*则对所有路径生效。模式一基于 model 参数直接路由这是最基础的使用方式将请求体中的 model 参数原样提取并写入指定请求头供后续路由匹配使用。配置modelToHeader: x-higress-llm-model处理效果假设原始 LLM 请求体为{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: What is the GitHub address of the Higress projects main repository? }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }经过插件处理后会新增请求头可用于路由匹配x-higress-llm-model: qwen-long请求体保持不变。源码中该逻辑位于 main.gomodelToHeader配置非空时直接用gjson读取modelKey路径的值并写入 header。典型应用网关侧配置 header 匹配路由将不同模型名的请求分发到不同的上游服务若网关后端是支持按 header 识别模型的服务此模式可保证请求体与路由目标完全一致不产生任何改写。模式二提取 provider 字段用于路由当网关需要按「模型提供方」分流例如同一个入口同时代理 DashScope、OpenAI 等多个上游时可以让客户端在 model 参数中通过/分隔符同时携带 provider 与模型名。注意这种模式要求客户端在 model 参数中通过/分隔的方式来指定 provider例如dashscope/qwen-long。配置addProviderHeader: x-higress-llm-provider处理效果原始请求体{ model: dashscope/qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: What is the GitHub address of the Higress projects main repository? }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }插件处理后新增请求头x-higress-llm-provider: dashscope同时请求体被改写为model 字段只剩模型名部分{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: What is the GitHub address of the Higress projects main repository? }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }底层实现源码使用strings.SplitN(modelValue, /, 2)将 model 值切分为 provider 与 model 两部分main.go若切分得到两段则把第一段写入addProviderHeader指定的 header第二段通过sjson.SetBytes回写请求体中的 model 字段若 model 值不包含/只有一段则只记录 debug 日志既不设置 provider header 也不改写请求体。这一不对称行为有测试TestHandleJsonBody_ModelWithoutSlash_AddProviderConfigured和TestHandleMultipartBody_ModelWithoutSlash专门验证main_extra_test.go。值得注意的是modelToHeader与addProviderHeader可以同时配置前者写入完整 model 值含 provider 前缀后者写入拆分后的 provider 值。测试TestOnHttpRequestBody_JSON验证了model: openai/gpt-4o时x-model: openai/gpt-4o与x-provider: openai会同时出现main_test.go。模式三保留原始模型名keepOriginalModelName问题背景当使用 AI 模型聚合平台如百炼/DashScope接入第三方厂商模型时部分模型名称本身包含/例如MiniMax/MiniMax-M2.7但它并不是provider/model格式。此时若直接使用addProviderHeader插件会把MiniMax-M2.7误判为模型名并改写请求体中的 model 字段导致上游无法识别模型。配置addProviderHeader: x-higress-llm-provider keepOriginalModelName: true处理效果以 model 为MiniMax/MiniMax-M2.7为例经过插件后请求头x-higress-llm-provider设置为MiniMaxprovider 提取能力保留请求体中的 model 字段保持为MiniMax/MiniMax-M2.7不被改写。源码在拆分出 provider 后判断config.keepOriginalModelName为true时跳过sjson.SetBytes改写逻辑main.go。对应测试TestKeepOriginalModelName同时覆盖了 JSON 与 multipart 两种请求体格式main_test.go。模式四自动路由基于用户消息内容该能力已完整实现在 main.go 中并配套了大量单元测试当请求中的 model 参数设置为higress/auto时插件会自动分析用户消息内容根据配置的正则规则选择合适的模型进行路由。autoRouting 配置结构autoRouting为 object 类型包含以下子字段名称数据类型填写要求默认值描述enablebool必填false是否启用自动路由功能defaultModelstring选填-当没有规则匹配时使用的默认模型rulesarray of object选填-路由规则数组按顺序匹配rules中每条规则包含名称数据类型填写要求描述patternstring必填正则表达式用于匹配用户消息内容modelstring必填匹配成功时设置的模型名称写入x-higress-llm-model请求头配置示例autoRouting: enable: true defaultModel: qwen-turbo rules: - pattern: (?i)(画|绘|生成图|图片|image|draw|paint) model: qwen-vl-max - pattern: (?i)(代码|编程|code|program|function|debug) model: qwen-coder - pattern: (?i)(翻译|translate|translation) model: qwen-turbo - pattern: (?i)(数学|计算|math|calculate) model: qwen-math工作原理当检测到请求体中的 model 参数值为higress/auto源码常量AutoModelPrefix时触发自动路由逻辑从请求体的messages数组中提取最后一个role为user的消息内容extractLastUserMessage见 main.go按配置的规则顺序依次使用正则表达式匹配用户消息matchAutoRoutingRule匹配成功时将对应的 model 值设置到x-higress-llm-model请求头并同步改写请求体中的 model 字段如果所有规则都未匹配则使用defaultModel配置的默认模型如果未配置defaultModel且无规则匹配则不设置路由头会记录警告日志。使用示例客户端请求{ model: higress/auto, messages: [ { role: system, content: 你是一个有帮助的助手 }, { role: user, content: 请帮我画一只可爱的小猫 } ] }由于用户消息中包含「画」关键词匹配到第一条规则插件会设置请求头x-higress-llm-model: qwen-vl-max测试TestAutoRoutingIntegration完整验证了这一链路包括关键词命中画/代码、未命中回退默认模型、未配置默认模型时不设置路由头、以及 model 非higress/auto时不触发自动路由main_test.go。支持的消息格式自动路由支持两种常见的 content 格式字符串格式标准文本消息{ role: user, content: 用户消息内容 }数组格式多模态消息如包含图片{ role: user, content: [ {type: text, text: 用户消息内容}, {type: image_url, image_url: {url: ...}} ] }对于数组格式插件会提取最后一个type为text的内容进行匹配见 main.go。extractLastUserMessage的相关边界行为多条 user 消息取最后一条、无 user 消息返回空、数组多段文本取最后一段均有测试覆盖main_test.go。正则表达式说明规则按配置顺序依次匹配第一个匹配成功的规则生效有测试验证「图片」与「代码」同时命中时优先前者见TestMatchAutoRoutingRule的 first matching rule wins 用例支持标准 Go 正则语法推荐使用(?i)标志实现大小写不敏感匹配使用|可以匹配多个关键词非法正则编译失败与空 pattern/model 的规则会在配置解析阶段被跳过并记录警告日志main.go相关行为由TestParseConfigAutoRouting验证。请求体格式支持与容错行为插件根据content-type分发处理逻辑main.goContent-Type处理方式application/json走handleJsonBody解析 JSON 并可能改写 model 字段multipart/form-data走handleMultipartBody逐 part 解析改写名为modelKey的表单字段其他类型直接放行ActionContinue不注入任何 headermultipart 场景下插件使用mime/multipart逐 part 读取并重建请求体仅改写modelKey对应的字段其余字段如prompt、文件字段原样保留——测试TestOnHttpRequestBody_Multipart验证了这一点main_test.go。插件的容错遵循「fail-open」原则任何异常都不阻断请求非法 JSON 请求体记录错误日志后直接放行不注入 headerTestHandleJsonBody_InvalidJson_PassThroughmultipart 的 content-type 解析失败、缺少 boundary、part 头损坏均记录日志后放行TestHandleMultipartBody_BadContentType、TestHandleMultipartBody_NoBoundary、TestHandleMultipartBody_NextPartError请求体缺失 model 参数不做任何处理TestOnHttpRequestBody_JSON的 no change when model not provided 用例。以上容错测试均位于 main_extra_test.go。构建与使用方式该插件属于 Higress 的 Go 语言 WASM 插件目录内 Makefile 提供了构建命令GOOSwasip1 GOARCHwasm go build -buildmodec-shared -o main.wasm main.go在网关侧通过 WasmPlugin 资源配置插件model-router并挂载到目标路由/域名即可生效。插件目录中的 go.mod 声明了依赖依赖higress-group/proxy-wasm-go-sdk与higress-group/wasm-goSDK以及tidwall/gjson、tidwall/sjson用于 JSON 读写。发布清单 catalog.json 显示model-router归类为 managed 插件logicalId 为model-router消费方包括 Higress 控制台higress-console因此你也可以直接在 Higress 控制台的插件市场中搜索「model-router」进行可视化配置。总结model-router插件为多模型、多提供方的 LLM 网关场景提供了三种互补的路由手段modelToHeader用于按模型名精确路由addProviderHeader用于按提供方分流并自动归一化请求体autoRouting则进一步实现「按用户消息内容智能选模」的自动路由。配合enableOnPathSuffix的路径收敛与 100 MB 的请求体缓冲上限插件既能覆盖主流 OpenAI 兼容接口也能安全处理大体积的多模态请求。若需继续深入了解插件的测试细节与边界行为可直接阅读 main.go、main_test.go 与 main_extra_test.go。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
RELATED — 相关阅读

相关资讯

LATEST — 最新资讯

最新发布

TODAY — 本日精选

新闻

WEEKLY — 本周精选

新闻

MONTHLY — 本月精选

新闻