后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读在 semantic-router 的决策层中模型路由决定了请求由哪个后端服务处理但客户端仍然可以通过max_tokens、n、logprobs等请求参数放大推理成本或提取模型内部的 token 分布信息。request_params是一个路由局部插件route-local plugin它在决策匹配完成后、请求正文转发给后端之前对 OpenAI Chat Completions 请求参数进行校验与裁剪按路由限制昂贵参数、屏蔽敏感参数、并可选地剥离未知的顶层 JSON 字段。读完本文你将掌握该插件的配置语法YAML 与 DSL 两种形式、每个参数的含义与取值约束以及它在 extproc 请求处理链路中的底层执行原理与可观测性指标。概览request_params 是什么request_params是附着在routing.decisions[].plugins下的一个决策级插件作用于 OpenAI Chat Completions 请求正文。它不是一个通用的 JSON schema 防火墙也不承担调用方鉴权的职责而是一组有界的请求字段强制策略阻塞参数、输出 token 上限、补全数量上限以及未知字段剥离。从配置模型看该插件的完整字段由 RequestParamsPluginConfig 定义字段类型作用blocked_params[]string需要被阻塞/剥离的参数名列表max_tokens_limit*intmax_tokens允许的最大值超出的请求会被钳制cap到该值max_n*intn补全数量允许的最大值超出的会被钳制到该值strip_unknownbool为true时移除不在 OpenAI 规范中的字段default_max_tokensOutputTokenDefault仅当调用方完全未提供输出上限时生效的默认值可为固定正整数或auto其中default_max_tokens在原文档的基础示例中未出现但源码已完整支持它可以是一个正整数也可以是字符串auto表示延迟到提供方渲染完整输入后再决定输出上限。其合法性校验由 output_token_default.go 完成——必须是正整数或auto否则校验直接失败。解决什么问题成本放大与 logits 泄露模型路由可以限制“哪个后端服务请求”但客户端仍可通过请求参数做两件路由无法直接干预的事放大成本把max_tokens调得极大、把n调成多次补全一次请求就能产生数倍于预期的 token 消耗提取 logits请求logprobs/top_logprobs会暴露 token 分布logits对某些层级或路由这属于不应开放的能力。request_params的定位就是在决策匹配之后、转发后端之前对请求正文强制施加“按决策的限制”。从源码链路看它实际发生在请求体路由处理request body routing阶段即决策已选定VSRSelectedDecision之后才执行与文档描述的时序完全一致。何时使用符合以下任一场景就适合为该决策或该层级挂载request_params某个层级或路由不允许请求logprobs或多次补全n 1需要对max_tokens或n设置与客户端输入无关的硬上限防止超卖算力未知 JSON 字段不应被转发给后端例如不允许客户端透传未来才可能新增的字段或带私有扩展字段的客户端。配置详解YAML 与 DSL 两种写法YAML 配置在routing.decisions[].plugins下添加该插件plugins: - type: request_params configuration: blocked_params: - logprobs - top_logprobs max_tokens_limit: 500 max_n: 1 strip_unknown: true语义说明blocked_params命中列表中的参数会被直接移除无论客户端传了什么值而非钳制max_tokens_limit: 500请求若显式携带更大的max_tokens会被钳制为 500max_n: 1请求若携带n 1会被钳制为 1strip_unknown: true剥离不在 OpenAI 规范中的顶层字段。仓库还提供了官方完整示例片段 config/fragments/plugin/request-params/budget-tier.yaml内容即上述配置的独立 fragment 形式可直接作为预算层级budget tier决策的插件片段复用。DSL 配置在语义路由 DSL 中同一插件可写成PLUGIN request_params { blocked_params: [logprobs, top_logprobs] max_tokens_limit: 500 max_n: 1 strip_unknown: true }从 DSL 编译器实现看compileRequestParamsPluginConfig 对字段做了一一映射default_max_tokens必须解析为正整数或字符串auto否则编译期直接报错request_params.default_max_tokens must be a positive integer or autoblocked_params按字符串数组解析max_tokens_limit、max_n按整数解析strip_unknown按布尔解析。这也说明 DSL 与 YAML 是同一套插件配置的双面表达最终都汇入RequestParamsPluginConfig。补充default_max_tokens 的用法若希望“调用方没给输出上限时由路由兜底一个默认值”可以这样配置plugins: - type: request_params configuration: default_max_tokens: 4096 max_tokens_limit: 8192固定整数调用方未携带输出上限时将其默认设为该值auto调用方未携带上限时延迟到提供方渲染完完整模型输入后再决定输出上限。request_params_validation_test.go 验证了该字段的严格性default_max_tokens取0、-1、1.5乃至拼写错误的default_max_token都会被拒绝同时验证了该字段在 YAML 解析、canonical 配置导出、再解析的往返round-trip中不丢失。源码级原理请求到达后的完整调用链request_params不是魔法它在 extprocEnvoy 外部处理器请求链路中按以下顺序执行入口解码与未知字段策略请求正文首先经过协议编解码器protocolcodec解码为中性请求表示。解码器在入口处即执行配置的未知字段策略——req_filter_request_params_test.go 中TestProtocolCodecRejectsUnknownFieldsBeforeRequestParamPlugins明确验证带未知字段如future_field的 wire 请求在到达 request_params 插件之前就会被拒绝。这也是strip_unknown语义在实现层的落点。决策匹配路由为请求选定决策VSRSelectedDecision。请求体路由处理在 processor_req_body_routing.go 中applyDispatchRequestParams检查当前决策是否配置了request_params若有则调用applySemanticRequestParams。插件执行applySemanticRequestParams 调用 pluginruntime 的ApplyRequestParams并根据执行结果记录指标。核心策略引擎ApplyRequestParams 规定了执行顺序先移除显式阻塞的参数再应用输出默认值default最后应用上限cap。这一步保证“被阻塞的输出参数先被清空再由默认值与上限兜底”例如TestRequestParamsBlockedOutputIsDefaultedBeforeCap验证max_tokens被阻塞后若default_max_tokens100、max_tokens_limit50最终请求携带的是 50且n3被钳制为 1。字段级变更最终落到 request_mutations.go 中的DefaultOutputTokens、CapOutputTokens、CapCandidateCount、BlockRequestField等纯函数。可阻塞参数一览从 BlockRequestField 的 switch 分支可以推断出当前实现支持阻塞的完整参数词汇表均映射到中性请求 IR 的对应字段采样类frequency_penalty、presence_penalty、temperature、top_p、min_p、top_k、repetition_penalty、seed、stop输出类max_tokens/max_completion_tokens/max_output_tokens三者归一化到同一输出上限字段、n/candidate_count、response_format/output_format工具类tools、tool_choice、parallel_tool_calls缓存与推理类cache_salt、prompt_cache_key、reasoning_effort、reasoning_budget_tokens其他metadata、store、stream注意两个特例model与messages是请求的必备语义字段列入blocked_params会直接返回错误required semantic field model cannot be blocked而不是被静默移除未知的客户端字段名走default分支它们本来就无法进入中性 IR入口编解码器已按未知字段策略处理因此返回“未变更”不会产生副作用。上限钳制的实现细节CapOutputTokens只对显式携带的max_tokens生效且从不凭空发明上限见 request_mutations.go若请求使用auto输出且配置了max_tokens_limit则该 limit 会被记录为 automatic output cap。CapCandidateCount对应n补全数量limit未配置或请求未携带n时不做任何改动request_mutations.go。DefaultOutputTokens仅在调用方没有任何有效输出上限时才写入默认值模型容量元数据永远不会被当作提供方默认值。可观测性请求参数策略指标每次插件执行都会记录 Prometheus 指标实现见 request_params_metrics.go按决策decision维度聚合指标名维度含义sr_request_params_blocked_totaldecision,param被阻塞的请求参数总数按参数维度细分sr_request_params_max_tokens_capped_totaldecisionmax_tokens被钳制的次数sr_request_params_max_n_capped_totaldecisionn被钳制的次数值得注意的实现细节钳制计数器刻意不带“原始值/钳制值”作为 label以避免 Prometheus 由客户端任意输入产生无界基数unbounded cardinality——这与上游decision/param维度一样是生产可观测性的务实取舍。指标记录逻辑位于 req_filter_semantic_mutations.go与插件执行同处一个函数确保“执行即埋点”。验证与测试依据仓库为request_params提供了多层测试覆盖可作为行为契约req_filter_request_params_test.gonil决策不改变请求阻塞与钳制在“中性字段”上的组合效果未知字段在入口被协议编解码器拒绝。request_params_validation_test.godefault_max_tokens的取值校验、canonical 配置往返、旧配置如仅strip_unknown: true不推断出默认值。request_params_test.go验证“阻塞优先于默认值与上限”的执行顺序以及prompt_cache_key可被阻塞清空。边界与注意事项文档与源码共同强调的几条边界务必在接入前确认它不是通用 JSON schema 防火墙也不是鉴权机制——不要用它替代认证/授权在启用strip_unknown之前请针对会添加提供商专用字段的客户端进行测试有些客户端会在请求中写入私有扩展字段开启剥离后这些字段将不再透传给后端可能导致后端行为差异阻塞model/messages会直接报错它们是请求必备字段default_max_tokens仅接受正整数或auto且只在调用方未提供输出上限时生效不会覆盖显式值插件是决策局部的它只对该决策生效不同决策如不同预算层级可以配置完全不同的参数策略这正是 budget-tier 场景的用法。小结request_params用一组简洁的声明式配置把“成本上限”“敏感参数屏蔽”“未知字段剥离”三件事按决策粒度固化在语义路由器中且全部发生在请求转发后端之前。配合sr_request_params_*系列指标你可以持续观察每个决策的阻塞与钳制行为从而在不信任客户端输入的前提下为每个路由层级建立可预期的成本与安全边界。完整的可运行配置片段见 config/fragments/plugin/request-params/budget-tier.yaml。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数semantic router request_params 插件实战为每条路由硬性约束 OpenAI 请求参数 request_params 是 seman后端API网关模型推理服务AI Agentsemantic-router header_mutation 插件实战指南在路由决策中增、改、删下游请求头semantic router header_mutation 插件实战指南在路由决策中增、改、删下游请求头 导读 header_mutation 是 sem后端API网关模型推理服务AI Agentsemantic-router 上下文信号context实战按 token 窗口需求为长上下文请求路由semantic router 上下文信号context实战按 token 窗口需求为长上下文请求路由 导读 context 是 semantic r后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
