Higress model-router 插件详解基于 LLM model 参数的智能路由与 Provider 识别【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressmodel-router是 Higress AI 网关中用于实现按 LLM 请求模型参数路由的核心插件它从 OpenAI 兼容协议请求体的model字段中提取模型名或按/分隔的 provider 前缀写入自定义请求头供网关后续的路由匹配使用。本文基于 插件官方文档结合 plugin.cc、plugin.h 与 plugin_test.cc 源码系统讲解其配置字段、两种路由模式、底层处理流程与测试验证帮助你将其直接落地到生产环境。功能说明与适用场景model-router插件实现了基于 LLM 协议中 model 参数路由的功能。在一个典型的 AI 网关部署中多个上游模型服务如 DashScope、OpenAI、各类私有化模型往往挂在同一网关域名下客户端通过请求体中的model字段声明自己要调用的模型。model-router在请求进入认证阶段时拦截请求将model参数提取出来写入请求头如x-higress-llm-model网关即可基于该请求头将请求路由到对应的上游服务。典型应用场景包括模型级路由model: qwen-long的请求路由到通义千问服务model: gpt-4o的请求路由到 OpenAI 服务多供应商分流客户端以dashscope/qwen-long形式指定 provider插件解析出dashscope写入x-higress-llm-provider请求头同时将请求体重写为qwen-long实现按供应商维度路由按路径灰度通过enableOnPathSuffix限定仅对/v1/chat/completions等 LLM 接口路径生效避免影响其他业务接口。配置字段详解插件配置通过 Higress 的WasmPluginCRD 下发支持以下字段名称数据类型填写要求默认值描述modelKeystring选填model请求 body 中 model 参数的位置JSON 字段名或 multipart/form-data 中的表单字段名addProviderHeaderstring选填-从 model 参数中解析出的 provider 名字放到哪个请求 header 中modelToHeaderstring选填-直接将 model 参数放到哪个请求 header 中enableOnPathSuffixarray of string选填[/completions,/embeddings,/images/generations,/audio/speech,/fine_tuning/jobs,/moderations,/image-synthesis,/video-synthesis]只对这些特定路径后缀的请求生效可以配置为*以匹配所有路径其中enableOnPathSuffix的默认值在源码 plugin.h 中定义实际还额外包含了/rerank与/messages两个后缀覆盖了文本生成、向量化、文生图、语音合成、微调任务、内容审核以及 rerank 检索重排等主流 LLM 接口。各字段的源码解析行为配置解析集中在 plugin.cc 的 parsePluginConfig其校验逻辑值得注意modelKey、addProviderHeader、modelToHeader均要求 string 类型类型不匹配时记录LOG_ERROR并返回false导致插件初始化失败enableOnPathSuffix使用JsonArrayIterate逐个校验数组元素任一元素非 string 类型即解析失败所有字段均为选填当modelToHeader与addProviderHeader均为空时插件只做路径与内容类型探测不产生实际改写。运行属性插件执行阶段认证阶段Authentication插件执行优先级900在 Higress 的 Wasm 插件体系里认证阶段属于请求处理早期链路优先级 900 意味着它在同阶段的大多数插件之后执行从而保证后续的路由类插件如基于 header 匹配的流量路由能够读到model-router写入的请求头。若你需要调整执行顺序可在WasmPlugin的matchRules或全局配置中结合 Higress 插件执行优先级规范统一规划。路由模式一基于 model 参数直接路由这是最基础的用法将请求体中的model字段原样写入指定请求头供网关按模型名精确路由。配置如下modelToHeader: x-higress-llm-model假设原始 LLM 请求体为{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }经过该插件处理后请求头将变为可用于路由匹配x-higress-llm-model: qwen-long从源码看这一逻辑位于 onJsonBody插件解析 JSON 请求体后若body_json.contains(model_key)命中则调用replaceRequestHeader(model_to_header, model_value)完成写入。此模式不会改写请求体model字段保持原样透传给上游。路由模式二提取 provider 字段用于路由注意这种模式需要客户端在 model 参数中通过/分隔的方式来指定 provider。当同一个上游服务需要承载多个模型供应商例如企业统一接入 DashScope 与 OpenAI通过 model 前缀区分时可使用 provider 提取模式插件将model中/之前的部分识别为 provider 写入请求头并把请求体重写为/之后的纯模型名。配置如下addProviderHeader: x-higress-llm-provider假设原始 LLM 请求体为{ model: dashscope/qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }经过该插件处理后将添加以下请求头可用于路由匹配x-higress-llm-provider: dashscope同时原始 LLM 请求体将被改写为{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }这一过程同样在 onJsonBody 中完成当add_provider_header非空且model_value中存在/时取/之前部分为 provider 写入请求头取/之后部分回写body_json[model_key]并通过setBuffer将改写后的 JSON 重新写回请求体若 model 参数中不含/则仅记录调试日志不改写请求体。modelToHeader与addProviderHeader可同时配置此时两种请求头都会被写入但只有 provider 模式会触发请求体改写。底层处理流程从源码看插件如何工作路径后缀与 Content-Type 探测插件在请求头阶段onHeader完成三项前置判断路径匹配取请求 URI 去掉查询参数后的部分遍历enableOnPathSuffix做后缀匹配配置*时对所有路径生效未命中任何后缀则直接Continue不进入正文处理JSON 模式Content-Type包含application/json时移除Content-Length头、设置解码缓冲上限默认104857600字节即 100MB返回StopIteration等待正文multipart/form-data 模式解析boundary边界长度须在 1~70 字节之间进入 multipart 流式处理。需要说明的是该逻辑说明插件对 JSON 与 multipart 两类 LLM 请求均做了支持JSON 模式onJsonBody在正文接收完整后一次性解析multipart 模式onMultipartBody则按 boundary 切分 part定位Content-Disposition: form-data; namemodel所在 part提取单行值完成相同的 header 写入与 body 改写文件上传类 part 不受影响。正文缓冲与内存保护PluginContext通过body_total_size_累积正文大小JSON 模式在end_stream时才取全量 body 处理multipart 模式在未找到 model part 时返回StopIterationAndBuffer持续缓存。此外插件在 onHeader 中内置了请求计数阈值 1000与 VM 内存阈值 200MB双重保护达到阈值时通过setFilterState(wasm_need_rebuild, true)触发 Wasm VM 重建防止长驻进程内存膨胀。按路由粒度的规则匹配插件继承自 RouteRuleMatcher因此支持 Higress 标准的_rules_路由级配置语法可按_match_route_精确路由名、_match_route_prefix_路由前缀、_match_domain_域名支持*通配、_match_service_上游服务与_disable_组合下发差异化配置。例如_rules_: - _match_route_: - route-a addProviderHeader: x-higress-llm-provider - _match_route_: - route-b modelToHeader: x-higress-llm-model未命中任何规则时回退到插件顶层全局配置路由级规则支持基于 route_name 与 cluster_name 的精确匹配从 getMatchConfig 可以看到其匹配优先级为 Host、Route、RouteAndService、Service、RoutePrefix 依次判断。测试验证行为即契约该插件配套了完整的单元测试 plugin_test.cc通过 NullVM 模拟 Proxy-Wasm 宿主环境可视为插件行为的契约文档测试用例验证点RewriteModelAndHeaderaddProviderHeader配置下model: qwen/qwen-long被改写为{model:qwen-long}并写入x-higress-llm-provider: qwen请求头ModelToHeadermodelToHeader配置下写入x-higress-llm-model: qwen-long且不触发请求体改写setBuffer调用次数为 0IgnorePath路径为/v1/chat/xxxx不在默认后缀列表中时直接Continue不做任何处理RouteLevelRewriteModelAndHeader_match_route_路由级配置在route-a上生效验证按路由粒度的规则下发RewriteModelAndHeaderMultipartFormData/ModelToHeaderMultipartFormDatamultipart/form-data 请求含文件上传 part中定位 model 表单字段并完成改写验证流式分片缓存与 CRLF 边界处理测试中的核心断言如请求体改写结果{model:qwen-long}与本文档描述的两种路由模式完全一致可用于回归验证。构建与测试入口见 BUILDmodel_router.wasm为正式产物目标model_router_test为单元测试目标。在 Higress 中部署与启用插件以 OCI 镜像形式发布通过WasmPluginCRD 启用参考 Higress 通用插件部署方式示例见 samples/wasmplugin/default-config.yaml 的结构apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: model-router namespace: higress-system spec: url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/model-router:latest defaultConfig: modelToHeader: x-higress-llm-model defaultConfigDisable: false启用后配合 Higress 的路由规则例如基于x-higress-llm-model请求头的 Header 匹配路由或结合x-higress-llm-provider进行供应商级分流即可实现完整的按模型/按供应商路由链路。使用注意事项addProviderHeader依赖客户端以provider/model的/分隔格式传参若 model 参数不含/该模式不会产生 provider 请求头也不会改写请求体modelKey可自定义 JSON 字段名或 multipart 表单字段名适合 model 字段被包装在其他层级需与网关侧约定好实际字段路径的场景请求体大小默认上限为 100MB超大 body 建议关注解码缓冲配置插件对路径后缀默认只覆盖常见 LLM 接口若你的接口路径不同务必显式配置enableOnPathSuffix或使用*本文讲解的为 CWasm实现版本仓库中另有功能更丰富的 Go 版本 model-router额外提供keepOriginalModelName与基于用户消息正则匹配的autoRouting能力可根据运行时选型参考。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Higress model-router 插件详解：基于 LLM model 参数的智能路由与 Provider 识别
Higress model-router 插件详解基于 LLM model 参数的智能路由与 Provider 识别【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressmodel-router是 Higress AI 网关中用于实现按 LLM 请求模型参数路由的核心插件它从 OpenAI 兼容协议请求体的model字段中提取模型名或按/分隔的 provider 前缀写入自定义请求头供网关后续的路由匹配使用。本文基于 插件官方文档结合 plugin.cc、plugin.h 与 plugin_test.cc 源码系统讲解其配置字段、两种路由模式、底层处理流程与测试验证帮助你将其直接落地到生产环境。功能说明与适用场景model-router插件实现了基于 LLM 协议中 model 参数路由的功能。在一个典型的 AI 网关部署中多个上游模型服务如 DashScope、OpenAI、各类私有化模型往往挂在同一网关域名下客户端通过请求体中的model字段声明自己要调用的模型。model-router在请求进入认证阶段时拦截请求将model参数提取出来写入请求头如x-higress-llm-model网关即可基于该请求头将请求路由到对应的上游服务。典型应用场景包括模型级路由model: qwen-long的请求路由到通义千问服务model: gpt-4o的请求路由到 OpenAI 服务多供应商分流客户端以dashscope/qwen-long形式指定 provider插件解析出dashscope写入x-higress-llm-provider请求头同时将请求体重写为qwen-long实现按供应商维度路由按路径灰度通过enableOnPathSuffix限定仅对/v1/chat/completions等 LLM 接口路径生效避免影响其他业务接口。配置字段详解插件配置通过 Higress 的WasmPluginCRD 下发支持以下字段名称数据类型填写要求默认值描述modelKeystring选填model请求 body 中 model 参数的位置JSON 字段名或 multipart/form-data 中的表单字段名addProviderHeaderstring选填-从 model 参数中解析出的 provider 名字放到哪个请求 header 中modelToHeaderstring选填-直接将 model 参数放到哪个请求 header 中enableOnPathSuffixarray of string选填[/completions,/embeddings,/images/generations,/audio/speech,/fine_tuning/jobs,/moderations,/image-synthesis,/video-synthesis]只对这些特定路径后缀的请求生效可以配置为*以匹配所有路径其中enableOnPathSuffix的默认值在源码 plugin.h 中定义实际还额外包含了/rerank与/messages两个后缀覆盖了文本生成、向量化、文生图、语音合成、微调任务、内容审核以及 rerank 检索重排等主流 LLM 接口。各字段的源码解析行为配置解析集中在 plugin.cc 的 parsePluginConfig其校验逻辑值得注意modelKey、addProviderHeader、modelToHeader均要求 string 类型类型不匹配时记录LOG_ERROR并返回false导致插件初始化失败enableOnPathSuffix使用JsonArrayIterate逐个校验数组元素任一元素非 string 类型即解析失败所有字段均为选填当modelToHeader与addProviderHeader均为空时插件只做路径与内容类型探测不产生实际改写。运行属性插件执行阶段认证阶段Authentication插件执行优先级900在 Higress 的 Wasm 插件体系里认证阶段属于请求处理早期链路优先级 900 意味着它在同阶段的大多数插件之后执行从而保证后续的路由类插件如基于 header 匹配的流量路由能够读到model-router写入的请求头。若你需要调整执行顺序可在WasmPlugin的matchRules或全局配置中结合 Higress 插件执行优先级规范统一规划。路由模式一基于 model 参数直接路由这是最基础的用法将请求体中的model字段原样写入指定请求头供网关按模型名精确路由。配置如下modelToHeader: x-higress-llm-model假设原始 LLM 请求体为{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }经过该插件处理后请求头将变为可用于路由匹配x-higress-llm-model: qwen-long从源码看这一逻辑位于 onJsonBody插件解析 JSON 请求体后若body_json.contains(model_key)命中则调用replaceRequestHeader(model_to_header, model_value)完成写入。此模式不会改写请求体model字段保持原样透传给上游。路由模式二提取 provider 字段用于路由注意这种模式需要客户端在 model 参数中通过/分隔的方式来指定 provider。当同一个上游服务需要承载多个模型供应商例如企业统一接入 DashScope 与 OpenAI通过 model 前缀区分时可使用 provider 提取模式插件将model中/之前的部分识别为 provider 写入请求头并把请求体重写为/之后的纯模型名。配置如下addProviderHeader: x-higress-llm-provider假设原始 LLM 请求体为{ model: dashscope/qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }经过该插件处理后将添加以下请求头可用于路由匹配x-higress-llm-provider: dashscope同时原始 LLM 请求体将被改写为{ model: qwen-long, frequency_penalty: 0, max_tokens: 800, stream: false, messages: [{ role: user, content: higress项目主仓库的github地址是什么 }], presence_penalty: 0, temperature: 0.7, top_p: 0.95 }这一过程同样在 onJsonBody 中完成当add_provider_header非空且model_value中存在/时取/之前部分为 provider 写入请求头取/之后部分回写body_json[model_key]并通过setBuffer将改写后的 JSON 重新写回请求体若 model 参数中不含/则仅记录调试日志不改写请求体。modelToHeader与addProviderHeader可同时配置此时两种请求头都会被写入但只有 provider 模式会触发请求体改写。底层处理流程从源码看插件如何工作路径后缀与 Content-Type 探测插件在请求头阶段onHeader完成三项前置判断路径匹配取请求 URI 去掉查询参数后的部分遍历enableOnPathSuffix做后缀匹配配置*时对所有路径生效未命中任何后缀则直接Continue不进入正文处理JSON 模式Content-Type包含application/json时移除Content-Length头、设置解码缓冲上限默认104857600字节即 100MB返回StopIteration等待正文multipart/form-data 模式解析boundary边界长度须在 1~70 字节之间进入 multipart 流式处理。需要说明的是该逻辑说明插件对 JSON 与 multipart 两类 LLM 请求均做了支持JSON 模式onJsonBody在正文接收完整后一次性解析multipart 模式onMultipartBody则按 boundary 切分 part定位Content-Disposition: form-data; namemodel所在 part提取单行值完成相同的 header 写入与 body 改写文件上传类 part 不受影响。正文缓冲与内存保护PluginContext通过body_total_size_累积正文大小JSON 模式在end_stream时才取全量 body 处理multipart 模式在未找到 model part 时返回StopIterationAndBuffer持续缓存。此外插件在 onHeader 中内置了请求计数阈值 1000与 VM 内存阈值 200MB双重保护达到阈值时通过setFilterState(wasm_need_rebuild, true)触发 Wasm VM 重建防止长驻进程内存膨胀。按路由粒度的规则匹配插件继承自 RouteRuleMatcher因此支持 Higress 标准的_rules_路由级配置语法可按_match_route_精确路由名、_match_route_prefix_路由前缀、_match_domain_域名支持*通配、_match_service_上游服务与_disable_组合下发差异化配置。例如_rules_: - _match_route_: - route-a addProviderHeader: x-higress-llm-provider - _match_route_: - route-b modelToHeader: x-higress-llm-model未命中任何规则时回退到插件顶层全局配置路由级规则支持基于 route_name 与 cluster_name 的精确匹配从 getMatchConfig 可以看到其匹配优先级为 Host、Route、RouteAndService、Service、RoutePrefix 依次判断。测试验证行为即契约该插件配套了完整的单元测试 plugin_test.cc通过 NullVM 模拟 Proxy-Wasm 宿主环境可视为插件行为的契约文档测试用例验证点RewriteModelAndHeaderaddProviderHeader配置下model: qwen/qwen-long被改写为{model:qwen-long}并写入x-higress-llm-provider: qwen请求头ModelToHeadermodelToHeader配置下写入x-higress-llm-model: qwen-long且不触发请求体改写setBuffer调用次数为 0IgnorePath路径为/v1/chat/xxxx不在默认后缀列表中时直接Continue不做任何处理RouteLevelRewriteModelAndHeader_match_route_路由级配置在route-a上生效验证按路由粒度的规则下发RewriteModelAndHeaderMultipartFormData/ModelToHeaderMultipartFormDatamultipart/form-data 请求含文件上传 part中定位 model 表单字段并完成改写验证流式分片缓存与 CRLF 边界处理测试中的核心断言如请求体改写结果{model:qwen-long}与本文档描述的两种路由模式完全一致可用于回归验证。构建与测试入口见 BUILDmodel_router.wasm为正式产物目标model_router_test为单元测试目标。在 Higress 中部署与启用插件以 OCI 镜像形式发布通过WasmPluginCRD 启用参考 Higress 通用插件部署方式示例见 samples/wasmplugin/default-config.yaml 的结构apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: model-router namespace: higress-system spec: url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/model-router:latest defaultConfig: modelToHeader: x-higress-llm-model defaultConfigDisable: false启用后配合 Higress 的路由规则例如基于x-higress-llm-model请求头的 Header 匹配路由或结合x-higress-llm-provider进行供应商级分流即可实现完整的按模型/按供应商路由链路。使用注意事项addProviderHeader依赖客户端以provider/model的/分隔格式传参若 model 参数不含/该模式不会产生 provider 请求头也不会改写请求体modelKey可自定义 JSON 字段名或 multipart 表单字段名适合 model 字段被包装在其他层级需与网关侧约定好实际字段路径的场景请求体大小默认上限为 100MB超大 body 建议关注解码缓冲配置插件对路径后缀默认只覆盖常见 LLM 接口若你的接口路径不同务必显式配置enableOnPathSuffix或使用*本文讲解的为 CWasm实现版本仓库中另有功能更丰富的 Go 版本 model-router额外提供keepOriginalModelName与基于用户消息正则匹配的autoRouting能力可根据运行时选型参考。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考