后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载routing.projections是 semantic-router 位于原始信号检测与最终决策匹配之间的协调层信号回答「匹配了什么」决策回答「哪条路由应胜出」投影则负责回答「如何把若干信号结果协调成可复用的路由事实」。本文基于 projection 教程概览 及其子教程Partitions、Scores、Mappings结合仓库中的 balance 配方 与 分类器源码完整讲解分区的胜者解析、分数的加权聚合、映射的命名档位与sigmoid_distance置信度校准并给出可直接复用的 YAML 与 DSL 配置。读完本文你将能够在竞争信号间解析唯一胜者、把多个弱信号合成连续路由分数、把阈值策略集中定义为可复用命名结果并在决策规则中用type: projection引用它们。一、为什么需要投影信号与决策之间的缺口在 semantic-router 中信号routing.signals刻意保持狭窄关键词、嵌入、领域分类或上下文检测各自只给出局部事实决策routing.decisions刻意是布尔性的把这些事实组合成路由规则。二者之间天然存在三个实际缺口多个领域或嵌入信号可能同时匹配但路由只需要一个胜者多个弱信号合起来可能表示「请求很难」或「回答需核验」单一信号无法表达同一套阈值逻辑需要在多条决策中复用而不应到处复制数值比较。没有投影时这类协调逻辑会被塞进决策、在路由间重复或混回检测层。routing.projections把协调提升为独立的一层带来四个主要优势将信号协调与决策逻辑分离两层都可读一条加权或阈值策略可被多条决策复用提供命名路由档位如balance_simple、verification_required避免散落数值比较在竞争的领域或嵌入通道间显式选出胜者。二、三层流水线信号 → 投影 → 决策把整条路由流水线想象为三层routing.signals从请求中提取可复用事实routing.projections协调或聚合这些事实routing.decisions用布尔策略匹配并选择路由。投影层内部又分为三个子层各自职责明确partitions协调已有的domain或embedding匹配保留一个胜者scores将匹配信号聚合成一个连续数值mappings将该数值变成命名的投影输出。决策层在使用上有两条重要边界当前实现约束决策不直接引用分区名决策不直接引用分数名。只有mapping.outputs[*].name会成为决策可见的projection(...)目标。决策对原始信号仍用原生类型引用如domain、embedding、keyword对投影输出则统一通过type: projection引用。从源码看这一边界在 classifier_projections.go 中得到落实投影执行结果只把mapping.outputs[*].name写入results.MatchedProjectionRules与SignalConfidences键格式为projection:output_name分区名与分数名不会以投影身份暴露给决策层。运行时流程当前运行时中投影在信号提取之后、决策评估之前按序执行基础信号在routing.signals下运行routing.projections.partitions归约竞争的domain或embedding匹配routing.projections.scores根据匹配信号与置信度计算数值routing.projections.mappings产生如balance_reasoning、verification_required等命名输出决策组合原始信号与上述命名输出。因此可以直观理解分区更「靠近信号」映射更「靠近决策」。在源码层面applyProjections 会先对分数做拓扑排序topologicalScoreOrder再按序计算每个分数并立即消费它的映射——这保证当分数 A 引用另一个分数 B 的输出作为输入时嵌套投影B 一定先于 A 求值。每个映射按source分组分数求值完成后对应映射随即被应用最后合并成一条投影追踪ProjectionTrace供可观测性使用。当前约定仓库在编写与运行时使用统一的投影命名DSL 使用PROJECTION partition、PROJECTION score、PROJECTION mapping规范运行时配置将同一约定存于routing.projections.partitions、scores、mappings。当前实现支持的能力为exclusive或softmax_exclusive的分区、method: weighted_sum的分数、method: threshold_bands的映射以及可选的method: sigmoid_distance映射校准。三、Partitions在竞争信号间解析唯一胜者3.1 解决的问题没有分区时请求可能同时匹配多个相近领域或嵌入通道对路由往往不理想通常应有一个主领域胜者而非四个部分匹配的领域意图通道通常应先收敛为最佳嵌入类别再供决策评估若每个决策都要防御重叠匹配路由规则会变得难以推理。分区在信号提取之后、决策评估之前协调检测器结果。3.2 运行时行为与约束从 classifier_signal_group_resolution.go 与 classifier_signal_groups.go 的实现可以确认以下规则分区仅接受domain或embedding成员signalGroupMembersForType只对这两个类型解析成员同一分区内所有成员必须类型相同default必填且必须出现在members中若多个成员匹配运行时保留一个胜者先把其他竞争者的置信度从匹配集合中删除再把胜者的置信度写回键格式为domain:name/embedding:name若无任何成员匹配运行时把default合成进匹配集合applySignalGroupDefaultFallback会显式追加默认成员并记录追踪。支持的两种语义exclusive保留最高置信胜者不变softmax_exclusive胜者相同但用temperature对候选置信度做 softmax 重归一softmaxScores实现为exp((score - maxScore) / temperature)归一化temperature 0时回退为 1.0。两条实际后果决策仍用原生类型引用胜者如type: domain或type: embedding决策不引用分区名本身。因此分区与映射意义上的「命名投影输出」不同它们是对已有信号名的协调而非新命名输出。3.3 规范 YAML 示例routing: projections: partitions: - name: balance_domain_partition semantics: softmax_exclusive temperature: 0.10 members: [law, business, health, history, other] default: other - name: balance_intent_partition semantics: softmax_exclusive temperature: 0.18 members: [code_general, architecture_design, research_synthesis, general_chat_fallback] default: general_chat_fallback3.4 DSL 写法PROJECTION partition balance_intent_partition { semantics: softmax_exclusive temperature: 0.18 members: [code_general, architecture_design, research_synthesis, general_chat_fallback] default: general_chat_fallback }3.5 配置字段速查字段含义name配置与 DSL 中的分区标识semantics胜者选择模式exclusive或softmax_exclusivetemperature仅对softmax_exclusive有意义值越低胜者越「果断」members要协调的已有domain或embedding信号名default无成员匹配时的回退成员会被合成进匹配集合3.6 使用决策何时使用路由前请求应有一个主导领域若干嵌入通道代表互斥意图应收敛为单一胜者希望下游决策保持简单直接读取胜出的原始信号。何时不用多个成员应对决策独立可见分组混合了不应相互竞争的不相关概念需要可复用的命名档位如balance_reasoning——那属于映射而非分区。设计说明原始检测器定义放在routing.signals分区只协调它们将属于同一路由问题的成员归组同一领域族或同一嵌入族当无成员清晰胜出时若下游仍需稳定回退请添加default若在嵌入分区上使用softmax_exclusive当成员质心过于接近难以区分时原生 DSL 校验可能发出警告。四、Scores把多个弱信号合成一个连续分数4.1 解决的问题决策适合可读布尔逻辑却不适合表达「从上下文长度取一点、从推理标记取一点、对极简单请求减权再判断属于哪一档」这类数值混合。分数在信号与决策策略之间提供显式数值层一条路由依赖多个弱信号而非单一决定性检测器、学习型与启发式证据应贡献同一路由结果、希望数值聚合留在决策层之外时都适合使用分数。4.2 运行时行为当前实现仅支持method: weighted_sum。每个输入贡献weight * input_valueinput_value取决于value_source省略或binary信号匹配用match未匹配用missconfidence使用匹配置信度未匹配为0raw使用SignalValues中的原始数值如计数或度量值缺失时为0。当前默认值为match 1.0、miss 0.0。校验器要求每个输入引用routing.signals中已声明的信号从 projectionMatchAccessors 的映射表可以看到当前支持的输入类型包括keyword、embedding、domain、fact_check、user_feedback、preference、language、context、structure、complexity、modality、authz、jailbreak、pii以及投影自身的projection类型支持分数链式组合。两个值得注意的源码级细节负权重有效projectionScoreValue直接累加weight * input_value负权重会在信号匹配时主动拉低分数例如「明显简单请求」weight 0的输入会被直接跳过不参与求值。失败输入不会被当作 0projectionScoreHasFailedInput会检查输入信号是否存在错误SignalErrors一旦有输入失败该分数及其映射输出会统一标记projection_input_failed并删除而不是把不可用的风险检测器当成低风险档位——这是为了避免在决策的on_unknown策略运行之前就错误地落入低风险区间见 classifier_projections.go 的注释与recordProjectionFailure。分数是内部投影状态决策不直接引用分数名下一步由映射消费。4.3 规范 YAML 示例routing: projections: scores: - name: difficulty_score method: weighted_sum inputs: - type: keyword name: simple_request_markers weight: -0.28 - type: context name: long_context weight: 0.18 - type: keyword name: reasoning_request_markers weight: 0.22 value_source: confidence - type: embedding name: agentic_workflows weight: 0.18 value_source: confidence - type: complexity name: general_reasoning:hard weight: 0.224.4 DSL 写法PROJECTION score difficulty_score { method: weighted_sum inputs: [ { type: keyword, name: simple_request_markers, weight: -0.28 }, { type: context, name: long_context, weight: 0.18 }, { type: keyword, name: reasoning_request_markers, weight: 0.22, value_source: confidence }, { type: embedding, name: agentic_workflows, weight: 0.18, value_source: confidence }, { type: complexity, name: general_reasoning:hard, weight: 0.22 } ] }4.5 配置字段速查字段含义name分数标识method当前为weighted_suminputs[].type读取的信号族inputs[].name已声明的信号名inputs[].weight贡献系数负权重降低分数inputs[].value_sourcebinary、confidence或raw行为inputs[].match/inputs[].miss二值模式下的显式取值4.6 使用决策何时使用多个弱指标应合成为单一难度或升级信号同一加权故事要在多条路由间复用希望在一处集中调节路由敏感度。何时不用单一原始信号已能干净决定路由规则用普通布尔逻辑即可保持可读需要立即可见的决策输出名——分数仍需映射。设计说明保持分数名稳定因为routing.projections.mappings[*].source依赖它们记录每个权重的理由尤其在混合置信型学习信号与启发式信号时数值聚合优先用分数让routing.decisions专注可读布尔组合当匹配信号应主动降低档位时如 balance 对明显简单请求使用负权重。五、Mappings把分数变成决策可见的命名档位5.1 解决的问题分数作为内部信号有用但决策规则不应依赖每个人记住「0.82 表示推理档」或「0.35 表示需核验」。映射把数值阈值转为可复用策略名带来两点收益一个分数可供给多条决策阈值策略集中在一处而非在路由间重复。这也是投影对决策可见的环节——当前实现中决策只能引用mapping.outputs[*].name不能引用分数名或分区名。5.2 运行时行为当前实现仅支持method: threshold_bands。每个输出用以下边界声明一条或多条lt、lte、gt、gte。重要运行时细节由 classifier_projection_outputs.go 的matchProjectionOutput/projectionOutputMatches实现确认按顺序检查输出首个匹配的输出胜出若无输出匹配映射不产生任何结果可选calibration为匹配的投影输出计算置信度。当前支持的校准方法为sigmoid_distance根据分数与最近阈值边界的距离推导置信度。其实现为confidence 1 / (1 exp(-slope * distance))其中distance取分数到该输出各边界gt/gte/lt/lte绝对距离中的最小值无任何边界时距离取 1.0slope默认为 12.0仅当calibration.slope 0时才覆盖默认值。slope 越大分数离边界越远时置信度越快逼近 1。5.3 规范 YAML 示例含决策引用routing: projections: mappings: - name: difficulty_band source: difficulty_score method: threshold_bands calibration: method: sigmoid_distance slope: 10.0 outputs: - name: balance_simple lt: 0.18 - name: balance_medium gte: 0.18 lt: 0.48 - name: balance_complex gte: 0.48 lt: 0.82 - name: balance_reasoning gte: 0.82 decisions: - name: reasoning_deep priority: 250 rules: operator: AND conditions: - type: domain name: math - type: projection name: balance_reasoning5.4 DSL 写法PROJECTION mapping difficulty_band { source: difficulty_score method: threshold_bands calibration: { method: sigmoid_distance, slope: 10 } outputs: [ { name: balance_simple, lt: 0.18 }, { name: balance_medium, gte: 0.18, lt: 0.48 }, { name: balance_complex, gte: 0.48, lt: 0.82 }, { name: balance_reasoning, gte: 0.82 } ] } ROUTE reasoning_deep { PRIORITY 250 WHEN domain(math) AND projection(balance_reasoning) MODEL google/gemini-3.1-pro }5.5 配置字段速查字段含义name映射标识source读取的分数名method当前为threshold_bandscalibration可选的匹配输出置信度模型outputs[].name决策可见的投影名outputs[].lt/lte/gt/gte该输出的阈值边界5.6 使用决策何时使用多条路由应共享同一套档位名希望决策规则可读如projection(verification_required)阈值策略应集中、可审计。何时不用决策应直接引用原始信号分数仅作诊断不参与路由策略尚未定义映射应读取的分数。设计说明输出名应面向策略使决策读起来像路由意图而非阈值算术保持阈值档位单调、有序、易审计决策用type: projection消费命名输出避免在多处重复数值阈值除非有意依赖顺序行为否则避免重叠档位——运行时返回首个匹配输出。六、端到端实战balance 配方中的投影复用文档中强调「该配方重要之处在于投影在多条路由间复用而非单一玩具示例」。仓库中的 config/recipes/balance/config.yamlrouting.projections段约第 1356–1758 行正是这一理念的生产级体现其投影设计如下balance_domain_partitionsemantics: softmax_exclusive、temperature: 0.1、default: other在 14 个路由域biology、business、chemistry、computer science、economics、engineering、health、history、law、math、other、philosophy、physics、psychology中解析唯一领域胜者balance_intent_partitionsemantics: softmax_exclusive、temperature: 0.18、default: general_chat_fallback在 17 个嵌入意图通道agentic_workflows、architecture_design、code_general、fast_qa_en/zh、health_guidance、research_synthesis 等中解析唯一胜者difficulty_scoreweighted_sum约 40 个输入混合简洁性负权重-0.26/-0.18、上下文长度short_context -0.1、long_context 0.18、结构证据ordered_workflow 0.12、numbered_steps 0.08 等、推理/代码关键词value_source: confidence与嵌入意图reasoning_general_en/zh 0.18、agentic_workflows 0.2 等以及复杂度档位math_task:hard 0.22、legal_risk:hard 0.18等difficulty_bandthreshold_bandssigmoid_distanceslope10输出balance_simple 0.18、balance_medium0.18–0.48、balance_complex0.48–0.82、balance_reasoning≥ 0.82verification_pressure与verification_bandslope12混合事实核查需求、引用请求、高风险领域与纠正反馈产出verification_required≥ 0.35等可复用核验输出另有feedback_correction_pressure→feedback_correction_band、feedback_clarification_pressure→feedback_clarification_band、urgency_pressure→urgency_band等成对设计分别产出feedback_correction_verified、feedback_clarification_overlay、urgency_elevated等命名输出。配方中的决策大量复用这些档位例如premium_legal优先级 260在第二组条件中用verification_requiredtype: projection与premium_legal_analysisembedding、legal_risk:medium/hardcomplexity做 OR 组合reasoning_deep优先级 250用balance_reasoning、balance_medium、balance_complex投影档位与domain/embedding/keyword原始信号一起构造多层 AND/OR/NOT 规则feedback_wrong_answer_verified优先级 232直接把feedback_correction_verified作为独立投影条件medium_code_general、medium_explainer、medium_creative等低成本路由则以balance_simple/balance_medium投影档位作为是否「升级/降级」的关键开关。可以看到同一套阈值与加权故事在十余条决策间被反复引用却只在routing.projections中定义一次——这正是投影层设计的核心收益。七、完整规范形态YAML 与 DSL 对照下面是一份可直接复制的最小完整示例覆盖 signals → projectionspartition score mapping→ decisions 的完整链路routing: signals: embeddings: - name: technical_support threshold: 0.75 candidates: [installation guide, troubleshooting] - name: account_management threshold: 0.72 candidates: [billing issue, subscription change] context: - name: long_context min_tokens: 4000 max_tokens: 200000 projections: partitions: - name: support_intents semantics: exclusive members: [technical_support, account_management] default: technical_support scores: - name: request_difficulty method: weighted_sum inputs: - type: embedding name: technical_support weight: 0.18 value_source: confidence - type: context name: long_context weight: 0.18 mappings: - name: request_band source: request_difficulty method: threshold_bands outputs: - name: support_fast lt: 0.25 - name: support_escalated gte: 0.25PROJECTION partition support_intents { semantics: exclusive members: [technical_support, account_management] default: technical_support } PROJECTION score request_difficulty { method: weighted_sum inputs: [ { type: embedding, name: technical_support, weight: 0.18, value_source: confidence }, { type: context, name: long_context, weight: 0.18 } ] } PROJECTION mapping request_band { source: request_difficulty method: threshold_bands outputs: [ { name: support_fast, lt: 0.25 }, { name: support_escalated, gte: 0.25 } ] }之后即可在routing.decisions[*].rules.conditions[*]中用type: projectionname: support_escalated引用该档位而无需在任何决策中复制0.25这个数值。八、控制台与 DSL 双向工作流仓库附带的管理控制台直接暴露同一投影约定Config - Projections以规范配置形式管理分区、分数与映射Config - Decisions可用条件类型projection引用映射输出DSL - Visual将Projection Partitions、Projection Scores、Projection Mappings与信号、路由、模型、插件并列展示为可编辑实体。原始导入/导出仍可将当前路由器 YAML 反编译为仅路由 DSL并将编辑后的 DSL 再编译回规范 YAML因此无论是配置驱动还是 DSL 驱动的工作流投影的定义方式都是一致的。九、决策速查何时使用 / 何时不用投影使用投影竞争的领域或嵌入通道应收敛到单一胜者→ partitions路由难度或核验压力分散在多个弱信号上→ scores多条决策应共享同一套simple / medium / complex等分层逻辑→ mappings希望阈值策略集中在一处而不是在路由规则中复制粘贴。跳过投影单一原始信号已清晰表达路由条件多个匹配应对决策独立可见决策用普通布尔组合即可保持可读且不需要共享加权逻辑。十、配套教程与源码索引Projection 教程概览投影在信号与决策之间的定位、运行时流程与当前约定Partitions 教程独占领域或嵌入胜者选择Scores 教程对匹配信号加权聚合Mappings 教程命名路由档位与type: projection的决策引用balance 配方配置投影在生产级多决策复用中的真实形态classifier_projections.go投影执行入口、拓扑排序与失败传播classifier_projection_inputs.goweighted_sum求值、三种value_source与输入信号族映射classifier_projection_outputs.gothreshold_bands首个匹配、sigmoid_distance置信度校准classifier_signal_group_resolution.go分区的胜者选择、默认成员合成与 softmax 重归一classifier_projections_test.go投影输出、置信度初始化与raw值源的测试用例。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router Projection 投影层完全指南从信号协调到可解释的决策输出semantic router Projection 投影层完全指南从信号协调到可解释的决策输出 Projection投影是 semantic route后端API网关模型推理服务AI Agentsemantic-router 分区Partitions实战用投影协调 domain 与 embedding 信号收敛路由胜者semantic router 分区Partitions实战用投影协调 domain 与 embedding 信号收敛路由胜者 本文聚焦 semanti后端API网关模型推理服务AI Agentsemantic-router Mappings 指南把投影分数转换为可复用的命名路由档位semantic router Mappings 指南把投影分数转换为可复用的命名路由档位 导读 本文讲解 semantic router 中 routing后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考