higress/plugins/wasm-go/extensions/model-router/README.md

功能说明

model-router插件实现了基于LLM协议中的model参数路由的功能

配置字段

名称	数据类型	填写要求	默认值	描述
modelKey	string	选填	model	请求body中model参数的位置
addProviderHeader	string	选填	-	从model参数中解析出的provider名字放到哪个请求header中
modelToHeader	string	选填	-	直接将model参数放到哪个请求header中
enableOnPathSuffix	array of string	选填	["/completions","/embeddings","/images/generations","/audio/speech","/fine_tuning/jobs","/moderations","/image-synthesis","/video-synthesis","/rerank","/messages"]	只对这些特定路径后缀的请求生效，可以配置为 "*" 以匹配所有路径
autoRouting	object	选填	-	自动路由配置，详见下方说明

autoRouting 配置

名称	数据类型	填写要求	默认值	描述
enable	bool	必填	false	是否启用自动路由功能
defaultModel	string	选填	-	当没有规则匹配时使用的默认模型
rules	array of object	选填	-	路由规则数组，按顺序匹配

rules 配置

名称	数据类型	填写要求	描述
pattern	string	必填	正则表达式，用于匹配用户消息内容
model	string	必填	匹配成功时设置的模型名称，将设置到 x-higress-llm-model 请求头

运行属性

插件执行阶段：认证阶段 插件执行优先级：900

效果说明

基于 model 参数进行路由

需要做如下配置：

modelToHeader: x-higress-llm-model

插件会将请求中 model 参数提取出来，设置到 x-higress-llm-model 这个请求 header 中，用于后续路由，举例来说，原生的 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

提取 model 参数中的 provider 字段用于路由

注意这种模式需要客户端在 model 参数中通过/分隔的方式，来指定 provider

需要做如下配置：

addProviderHeader: x-higress-llm-provider

插件会将请求中 model 参数的 provider 部分（如果有）提取出来，设置到 x-higress-llm-provider 这个请求 header 中，用于后续路由，并将 model 参数重写为模型名称部分。举例来说，原生的 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
}

自动路由模式（基于用户消息内容）

当请求中的 model 参数设置为 higress/auto 时，插件会自动分析用户消息内容，并根据配置的正则规则选择合适的模型进行路由。

配置示例：

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"

工作原理

1. 当检测到请求体中的 model 参数值为 higress/auto 时，触发自动路由逻辑
2. 从请求体的 messages 数组中提取最后一个 role 为 user 的消息内容
3. 按配置的规则顺序，依次使用正则表达式匹配用户消息
4. 匹配成功时，将对应的 model 值设置到 x-higress-llm-model 请求头
5. 如果所有规则都未匹配，则使用 defaultModel 配置的默认模型
6. 如果未配置 defaultModel 且无规则匹配，则不设置路由头（会记录警告日志）

使用示例

客户端请求：

{
    "model": "higress/auto",
    "messages": [
        {
            "role": "system",
            "content": "你是一个有帮助的助手"
        },
        {
            "role": "user",
            "content": "请帮我画一只可爱的小猫"
        }
    ]
}

由于用户消息中包含"画"关键词，匹配到第一条规则，插件会设置请求头：

x-higress-llm-model: qwen-vl-max

支持的消息格式

自动路由支持两种常见的 content 格式：

1. 字符串格式（标准文本消息）：

{
    "role": "user",
    "content": "用户消息内容"
}

2. 数组格式（多模态消息，如包含图片）：

{
    "role": "user",
    "content": [
        {"type": "text", "text": "用户消息内容"},
        {"type": "image_url", "image_url": {"url": "..."}}
    ]
}

对于数组格式，插件会提取最后一个 type 为 text 的内容进行匹配。

正则表达式说明

• 规则按配置顺序依次匹配，第一个匹配成功的规则生效
• 支持标准 Go 正则语法
• 推荐使用 (?i) 标志实现大小写不敏感匹配
• 使用 | 可以匹配多个关键词