后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读header_mutation是 semantic-router 中一个路由局部route-local插件它允许你在某条具体路由被命中后对发送给下游模型/后端的请求头执行「添加、更新、删除」三种操作。本文基于 header-mutation.mdv0.3 中文版见 i18n 版本结合仓库中的 YAML 片段、Go 源码与测试讲解该插件的适用场景、完整配置写法、底层执行语义append/set/remove 与 Envoy ext_proc 的对应关系、DSL 表达、校验规则以及安全注意事项读完即可在自己的路由决策中独立配置并验证该插件。一、插件定位路由局部的下游头策略semantic-router 是一个可编程的「模型与算力决策层」每条路由decision除了做语义/关键词/领域等分类决策外还可以挂载一系列插件来改变最终发给后端的请求。header_mutation就是其中用于改写下游请求头的插件。它的核心设计原则是**「局部化」**头策略只作用在被匹配的那条路由上不影响路由器其他路由的流量三种操作增、改、删在同一个插件中完成不需要拆分成多个过滤器变换是显式声明的而不是藏在 Envoy 代理配置或业务应用代码里便于审计与维护。对应到仓库中的真实配置片段即 config/fragments/plugin/header-mutation/tenant-routing.yaml它也是本教程的配套示例。二、它解决什么问题、何时该用在网关/路由器场景中不同路由常常需要携带不同的下游头例如付费租户走 premium 后端需要在其请求头上盖一个X-Tenant-Tier: premium的戳记调试环境希望只对选中流量追加溯源信息下游服务可能期望收到路由专属的标识头。若没有这样的插件你只能把这些逻辑散落在代理配置、服务网格规则或应用代码里导致「某条路由到底改了哪些头」难以追踪。header_mutation把「哪条路由 → 改哪些头」收敛成一个 YAML 声明块紧贴路由定义天然具备可读性和可追溯性。典型使用场景一条路由需要把租户或套餐元数据写入请求头如X-Tenant-Tier下游服务期望路由专用头如X-Route-Source只对选中流量添加调试或溯源provenance头而全量流量不携带这些头。三、配置详解完整 YAML 与参数语义在路由定义中将插件挂在routing.decisions[].plugins下。以下为完整可用的最小示例与原文档及仓库片段一致plugins: - type: header_mutation configuration: add: - name: X-Tenant-Tier value: premium update: - name: X-Route-Source value: semantic-router delete: - X-Debug-Trace参数说明字段类型语义默认/边界typestring固定为header_mutation必填configuration.addHeaderPair[]追加下游请求头若同名头已存在则保留原值见下文 append 语义可选列表可空configuration.updateHeaderPair[]设置/覆盖下游请求头若同名头已存在则覆盖可选列表可空configuration.deletestring[]删除指定名称的请求头可选列表可空其中每个HeaderPair由name头名称与value头值两个字符串字段组成对应源码结构 plugin_config.go 中的HeaderPairtype HeaderPair struct { Name string json:name yaml:name Value string json:value yaml:value }整段插件的配置结构定义在 HeaderMutationPluginConfigtype HeaderMutationPluginConfig struct { Add []HeaderPair json:add,omitempty yaml:add,omitempty Update []HeaderPair json:update,omitempty yaml:update,omitempty Delete []string json:delete,omitempty yaml:delete,omitempty }与主配置文件的对应仓库主配置 config/config.yaml 中真实存在一个header_mutation用例位于premium_route类决策下内容与本教程示例完全一致可直接作为「插件挂载位置」的参照它被放在fallback策略块之后的plugins列表中说明插件与模型选择、fallback 等决策属性平级。四、底层执行语义append、set 与 remove「add」与「update」在语义上并不相同这一点由运行时实现严格保证。核心执行逻辑在 req_filter_header_mutation.go 的 buildHeaderMutationsfor _, mutation : range pluginruntime.HeaderMutations(headerConfig) { if mutation.Operation remove { removeHeaders append(removeHeaders, mutation.Name) continue } header : corev3.HeaderValueOption{Header: corev3.HeaderValue{Key: mutation.Name, RawValue: []byte(mutation.Value)}} if mutation.Operation set { header.AppendAction corev3.HeaderValueOption_OVERWRITE_IF_EXISTS_OR_ADD } setHeaders append(setHeaders, header) }可见三种操作被翻译成两类 Envoy ext_proc 输出remove→ 进入removeHeaders列表最终映射为 Envoy 的 header 删除指令add/update→ 进入setHeaders列表其中update会带上OVERWRITE_IF_EXISTS_OR_ADD的 AppendAction已存在则覆盖不存在则追加而add不设置该标记即纯追加语义。操作顺序与类型映射由 pluginruntime/headers.go 的 HeaderMutations 生成严格保持配置声明的顺序先 add、再 update、最后 delete且以显式的operation字段append/set/remove对外暴露for _, header : range policy.Add { result append(result, HeaderMutation{Name: header.Name, Value: header.Value, Operation: append}) } for _, header : range policy.Update { result append(result, HeaderMutation{Name: header.Name, Value: header.Value, Operation: set}) } for _, name : range policy.Delete { result append(result, HeaderMutation{Name: name, Operation: remove}) }这解释了文档中「add、update、delete 在一个插件中统一支持」背后的真实差异add是追加保留可能存在的同名旧值update是覆盖或新建delete是移除。五、校验规则什么配置会被拒绝配置不是随便写都能通过校验的。在 Kubernetes 配置转换路径中k8s/converter.go 的 validateHeaderMutationPluginConfig 定义了以下约束至少声明一种操作add、update、delete三者全空时直接报错header_mutation plugin must specify at least one of: add, update, delete头名称不能为空add与update中的每一项name字段缺失或为空时分别报header_mutation add/update: header name cannot be empty配置解码使用DisallowUnknownFields()意味着未知字段会被拒绝避免拼写错误悄悄失效。此外从源码结构看decision_reliability.go配置加载阶段还有一道「可靠性头保护」如果某个决策块自己声明了 reliability 相关头由该决策的 reliability 块独占写入加载器会从header_mutation的 add/update/delete 中剔除并告警防止插件与可靠性机制互相覆盖。这意味着不要把可靠性机制专用的头名放进插件配置。六、DSL 表达在 .dsl 路由描述中声明除了 YAMLsemantic-router 的 DSL 也能描述该插件。DSL 编译器在 compiler_plugin_configs.go 的 compileHeaderMutationPluginConfig 中把add、update、delete三个字段直接映射到配置结构func (c *Compiler) compileHeaderMutationPluginConfig(fields map[string]Value) config.HeaderMutationPluginConfig { return config.HeaderMutationPluginConfig{ Add: compileHeaderPairs(fields[add]), Update: compileHeaderPairs(fields[update]), Delete: stringArrayValue(fields[delete]), } }其中add/update需要每个元素是包含name与value字符串字段的对象见 compileHeaderPairs反向生成 DSL 文本时decompiler_plugin_emit.go 的 emitHeaderMutationPluginConfig 会按add: [{ name: ..., value: ... }]、update: [...]、delete: [...]的格式输出。DSL 解析器还接受连字符别名header-mutation统一规范化为header_mutation见 dsl/parser.go。对应测试覆盖在 dsl_test.go 的 header_mutation 用例可在本地运行go test ./pkg/dsl/...验证 DSL 编解码往返。七、预览与调试用 API 验证改动计划如果你在使用 Dashboard/API Server 管理配置可以直接预览该插件产生的有序 Envoy 头操作无需真正把配置下发到代理端点POST /api/v1/plugins/header_mutation/preview路由注册见 route_plugin_previews.go请求体提供一个候选configurationadd/update/delete或通过bindingrecipedecision引用已激活配置响应返回mutations数组——即 pluginruntime.HeaderMutation 的有序列表每项含name、value、operationappend/set/remove三要素保证与 Envoy 实际收到的顺序与语义一致见 headers.go 注释权限头值属于敏感数据查看值需要secret_view权限无权限时预览响应会把非 remove 操作的值打码values_redacted标记实现见 handleHeaderMutationPreview。这样你在写正式配置前就能确认「哪条路由、按什么顺序、改哪些头」是否符合预期。八、安全注意事项原文档特别强调头的值是静态配置不是模板。也就是说头值不允许做请求元数据插值/模板展开配置里写什么下游就收到什么严禁用不受信任的请求元数据去制造身份或授权类头例如凭客户端输入动态拼出Authorization、X-Api-Key之类的凭据头否则会引入头注入与越权风险与这一点相呼应仓库中shadow_dispatch插件的forward_headers默认不允许转发自定义凭据头见 plugin_config.go 中 ForwardHeaders 的注释说明「头 信任边界」是整体设计共识。九、实践建议小结把「租户/套餐/路由来源」等元数据写入下游头时优先用header_mutation而不是改代理配置保持路由逻辑自包含明确区分add追加与update覆盖按需选用避免同名头叠加造成下游解析歧义至少声明一种操作且每个头名非空否则配置会被校验器拒绝不要碰 reliability 机制独占的头名也不要通过该插件注入动态凭据上线前用/api/v1/plugins/header_mutation/preview预览有序变更计划再做真实验证。通过 config/fragments/plugin/header-mutation/tenant-routing.yaml 这一最小示例起步配合 config/config.yaml 中的真实挂载位置、extproc 实现 与 k8s 校验逻辑你就能在语义路由决策中精确、可控地管理下游请求头。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 路由级 Header 变更插件 header_mutation 实战指南为下游添加、更新、删除请求头semantic router 路由级 Header 变更插件 header_mutation 实战指南为下游添加、更新、删除请求头 导读 header_mu后端API网关模型推理服务AI Agentsemantic-router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数semantic router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数 request_params 是 seman后端API网关模型推理服务AI Agentsemantic-router 插件机制实战指南在决策命中后为路由挂载可编程行为semantic router 插件机制实战指南在决策命中后为路由挂载可编程行为 本文围绕 semantic router 的 Plugins插件机制展开后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 16:29:17 · 阅读 1.2k semantic-router header_mutation 插件实战指南：在路由决策中增、改、删下游请求头
后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读header_mutation是 semantic-router 中一个路由局部route-local插件它允许你在某条具体路由被命中后对发送给下游模型/后端的请求头执行「添加、更新、删除」三种操作。本文基于 header-mutation.mdv0.3 中文版见 i18n 版本结合仓库中的 YAML 片段、Go 源码与测试讲解该插件的适用场景、完整配置写法、底层执行语义append/set/remove 与 Envoy ext_proc 的对应关系、DSL 表达、校验规则以及安全注意事项读完即可在自己的路由决策中独立配置并验证该插件。一、插件定位路由局部的下游头策略semantic-router 是一个可编程的「模型与算力决策层」每条路由decision除了做语义/关键词/领域等分类决策外还可以挂载一系列插件来改变最终发给后端的请求。header_mutation就是其中用于改写下游请求头的插件。它的核心设计原则是**「局部化」**头策略只作用在被匹配的那条路由上不影响路由器其他路由的流量三种操作增、改、删在同一个插件中完成不需要拆分成多个过滤器变换是显式声明的而不是藏在 Envoy 代理配置或业务应用代码里便于审计与维护。对应到仓库中的真实配置片段即 config/fragments/plugin/header-mutation/tenant-routing.yaml它也是本教程的配套示例。二、它解决什么问题、何时该用在网关/路由器场景中不同路由常常需要携带不同的下游头例如付费租户走 premium 后端需要在其请求头上盖一个X-Tenant-Tier: premium的戳记调试环境希望只对选中流量追加溯源信息下游服务可能期望收到路由专属的标识头。若没有这样的插件你只能把这些逻辑散落在代理配置、服务网格规则或应用代码里导致「某条路由到底改了哪些头」难以追踪。header_mutation把「哪条路由 → 改哪些头」收敛成一个 YAML 声明块紧贴路由定义天然具备可读性和可追溯性。典型使用场景一条路由需要把租户或套餐元数据写入请求头如X-Tenant-Tier下游服务期望路由专用头如X-Route-Source只对选中流量添加调试或溯源provenance头而全量流量不携带这些头。三、配置详解完整 YAML 与参数语义在路由定义中将插件挂在routing.decisions[].plugins下。以下为完整可用的最小示例与原文档及仓库片段一致plugins: - type: header_mutation configuration: add: - name: X-Tenant-Tier value: premium update: - name: X-Route-Source value: semantic-router delete: - X-Debug-Trace参数说明字段类型语义默认/边界typestring固定为header_mutation必填configuration.addHeaderPair[]追加下游请求头若同名头已存在则保留原值见下文 append 语义可选列表可空configuration.updateHeaderPair[]设置/覆盖下游请求头若同名头已存在则覆盖可选列表可空configuration.deletestring[]删除指定名称的请求头可选列表可空其中每个HeaderPair由name头名称与value头值两个字符串字段组成对应源码结构 plugin_config.go 中的HeaderPairtype HeaderPair struct { Name string json:name yaml:name Value string json:value yaml:value }整段插件的配置结构定义在 HeaderMutationPluginConfigtype HeaderMutationPluginConfig struct { Add []HeaderPair json:add,omitempty yaml:add,omitempty Update []HeaderPair json:update,omitempty yaml:update,omitempty Delete []string json:delete,omitempty yaml:delete,omitempty }与主配置文件的对应仓库主配置 config/config.yaml 中真实存在一个header_mutation用例位于premium_route类决策下内容与本教程示例完全一致可直接作为「插件挂载位置」的参照它被放在fallback策略块之后的plugins列表中说明插件与模型选择、fallback 等决策属性平级。四、底层执行语义append、set 与 remove「add」与「update」在语义上并不相同这一点由运行时实现严格保证。核心执行逻辑在 req_filter_header_mutation.go 的 buildHeaderMutationsfor _, mutation : range pluginruntime.HeaderMutations(headerConfig) { if mutation.Operation remove { removeHeaders append(removeHeaders, mutation.Name) continue } header : corev3.HeaderValueOption{Header: corev3.HeaderValue{Key: mutation.Name, RawValue: []byte(mutation.Value)}} if mutation.Operation set { header.AppendAction corev3.HeaderValueOption_OVERWRITE_IF_EXISTS_OR_ADD } setHeaders append(setHeaders, header) }可见三种操作被翻译成两类 Envoy ext_proc 输出remove→ 进入removeHeaders列表最终映射为 Envoy 的 header 删除指令add/update→ 进入setHeaders列表其中update会带上OVERWRITE_IF_EXISTS_OR_ADD的 AppendAction已存在则覆盖不存在则追加而add不设置该标记即纯追加语义。操作顺序与类型映射由 pluginruntime/headers.go 的 HeaderMutations 生成严格保持配置声明的顺序先 add、再 update、最后 delete且以显式的operation字段append/set/remove对外暴露for _, header : range policy.Add { result append(result, HeaderMutation{Name: header.Name, Value: header.Value, Operation: append}) } for _, header : range policy.Update { result append(result, HeaderMutation{Name: header.Name, Value: header.Value, Operation: set}) } for _, name : range policy.Delete { result append(result, HeaderMutation{Name: name, Operation: remove}) }这解释了文档中「add、update、delete 在一个插件中统一支持」背后的真实差异add是追加保留可能存在的同名旧值update是覆盖或新建delete是移除。五、校验规则什么配置会被拒绝配置不是随便写都能通过校验的。在 Kubernetes 配置转换路径中k8s/converter.go 的 validateHeaderMutationPluginConfig 定义了以下约束至少声明一种操作add、update、delete三者全空时直接报错header_mutation plugin must specify at least one of: add, update, delete头名称不能为空add与update中的每一项name字段缺失或为空时分别报header_mutation add/update: header name cannot be empty配置解码使用DisallowUnknownFields()意味着未知字段会被拒绝避免拼写错误悄悄失效。此外从源码结构看decision_reliability.go配置加载阶段还有一道「可靠性头保护」如果某个决策块自己声明了 reliability 相关头由该决策的 reliability 块独占写入加载器会从header_mutation的 add/update/delete 中剔除并告警防止插件与可靠性机制互相覆盖。这意味着不要把可靠性机制专用的头名放进插件配置。六、DSL 表达在 .dsl 路由描述中声明除了 YAMLsemantic-router 的 DSL 也能描述该插件。DSL 编译器在 compiler_plugin_configs.go 的 compileHeaderMutationPluginConfig 中把add、update、delete三个字段直接映射到配置结构func (c *Compiler) compileHeaderMutationPluginConfig(fields map[string]Value) config.HeaderMutationPluginConfig { return config.HeaderMutationPluginConfig{ Add: compileHeaderPairs(fields[add]), Update: compileHeaderPairs(fields[update]), Delete: stringArrayValue(fields[delete]), } }其中add/update需要每个元素是包含name与value字符串字段的对象见 compileHeaderPairs反向生成 DSL 文本时decompiler_plugin_emit.go 的 emitHeaderMutationPluginConfig 会按add: [{ name: ..., value: ... }]、update: [...]、delete: [...]的格式输出。DSL 解析器还接受连字符别名header-mutation统一规范化为header_mutation见 dsl/parser.go。对应测试覆盖在 dsl_test.go 的 header_mutation 用例可在本地运行go test ./pkg/dsl/...验证 DSL 编解码往返。七、预览与调试用 API 验证改动计划如果你在使用 Dashboard/API Server 管理配置可以直接预览该插件产生的有序 Envoy 头操作无需真正把配置下发到代理端点POST /api/v1/plugins/header_mutation/preview路由注册见 route_plugin_previews.go请求体提供一个候选configurationadd/update/delete或通过bindingrecipedecision引用已激活配置响应返回mutations数组——即 pluginruntime.HeaderMutation 的有序列表每项含name、value、operationappend/set/remove三要素保证与 Envoy 实际收到的顺序与语义一致见 headers.go 注释权限头值属于敏感数据查看值需要secret_view权限无权限时预览响应会把非 remove 操作的值打码values_redacted标记实现见 handleHeaderMutationPreview。这样你在写正式配置前就能确认「哪条路由、按什么顺序、改哪些头」是否符合预期。八、安全注意事项原文档特别强调头的值是静态配置不是模板。也就是说头值不允许做请求元数据插值/模板展开配置里写什么下游就收到什么严禁用不受信任的请求元数据去制造身份或授权类头例如凭客户端输入动态拼出Authorization、X-Api-Key之类的凭据头否则会引入头注入与越权风险与这一点相呼应仓库中shadow_dispatch插件的forward_headers默认不允许转发自定义凭据头见 plugin_config.go 中 ForwardHeaders 的注释说明「头 信任边界」是整体设计共识。九、实践建议小结把「租户/套餐/路由来源」等元数据写入下游头时优先用header_mutation而不是改代理配置保持路由逻辑自包含明确区分add追加与update覆盖按需选用避免同名头叠加造成下游解析歧义至少声明一种操作且每个头名非空否则配置会被校验器拒绝不要碰 reliability 机制独占的头名也不要通过该插件注入动态凭据上线前用/api/v1/plugins/header_mutation/preview预览有序变更计划再做真实验证。通过 config/fragments/plugin/header-mutation/tenant-routing.yaml 这一最小示例起步配合 config/config.yaml 中的真实挂载位置、extproc 实现 与 k8s 校验逻辑你就能在语义路由决策中精确、可控地管理下游请求头。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 路由级 Header 变更插件 header_mutation 实战指南为下游添加、更新、删除请求头semantic router 路由级 Header 变更插件 header_mutation 实战指南为下游添加、更新、删除请求头 导读 header_mu后端API网关模型推理服务AI Agentsemantic-router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数semantic router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数 request_params 是 seman后端API网关模型推理服务AI Agentsemantic-router 插件机制实战指南在决策命中后为路由挂载可编程行为semantic router 插件机制实战指南在决策命中后为路由挂载可编程行为 本文围绕 semantic router 的 Plugins插件机制展开后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考