后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读preference是 Semantic RoutervSR中的一类学习型信号learned signal它从一组人工编写的示例examples与分类器设置中推断出用户的回答风格偏好如“想要简洁回答”或“想要详尽推演”并把推断结果作为具名路由输入暴露给决策引擎。本文以 v0.3 Preference Signal 文档 为骨架完整讲解它的配置方式、use_contrastive默认行为、prototype_scoring参数矩阵并结合 preference_classifier.go、contrastive_preference_classifier.go、prototype_bank.go 等源码揭示对比学习匹配的完整链路。读完本文你将能够在 v0.3 配置中声明偏好信号、用示例锚定风格类别、理解对比模式与外部 LLM 模式的取舍并把偏好信号接入路由决策条件。什么是 Preference Signal解决的问题同一话题不同风格即使用户询问的是相同主题不同人也往往想要截然不同的回答方式有人希望“一句话讲完”有人要求“逐步推演、不要跳过任何步骤”。如果这种风格偏好只在生成链路的下游处理例如由模型提示词临时体现那么路由层就无法据此选择更合适的模型或插件栈——因为路由发生在模型调用之前。preference信号解决的就是这个问题把推断出的风格偏好作为命名路由输入named routing input暴露出来让决策引擎在模型选择model choice与插件选择plugin choice两个层面都看到“这位用户想要什么风格”的事实。关键优势不硬编码用户状态偏好检测结果独立于决策产出无需在路由逻辑中手工维护“用户 A 喜欢简洁”之类的状态机检测与路由解耦偏好检测只负责产出信号不关心最终路由结果二者可以独立演进示例驱动的风格检测支持“简洁 vs 详尽”这类语义风格判断而不是简单的关键词匹配策略复用一条偏好策略可以被多个决策decision同时引用一处定义、多处生效。从源码结构看这一设计体现在 classifier_signal_preference_support.go 中信号计算函数只负责产出preference:名称这一命名信号及其置信度/边界值写入SignalResults后路由决策层再按规则消费见recordPreferenceSignalValues。何时使用一部分用户偏好极简回答另一部分用户需要高细节输出路由行为需要适配稳定的风格偏好而非单次请求的临时倾向希望偏好检测在多个决策之间保持可复用风格信号需要同时影响模型选择与插件选择。配置总览1. 在 routing.signals.preferences 声明偏好规则源片段族位于 config/fragments/signal/preference/仓库自带的可复用示例 power-user.yaml 内容如下routing: signals: preferences: - name: terse_answers description: Users who prefer short, direct responses. examples: - keep it concise - bullet points only - answer in one paragraph threshold: 0.7字段说明对应 signal_config.go 中的PreferenceRule结构字段类型说明namestring规则名称也是信号名称路由条件里用type: preference, name: name引用descriptionstring规则语义描述在对比模式下会连同 examples 一起参与嵌入examples[]string训练锚点training anchors非字面关键词规则thresholdfloat32该规则的相似度阈值匹配得分低于阈值时判定为不匹配⚠️重要语义把examples视作偏好检测器的训练锚点而不是字面关键词规则。例如keep it concise这类例子在嵌入空间里“语义靠近”的请求如 “Please keep your reply short and to the point”才会命中而不是要求用户请求里出现这几个单词。threshold的默认值语义可参考源码在 contrastive_preference_classifier.go 中若threshold 0且BestScore threshold分类器返回ErrPreferenceBelowThreshold“preference below threshold”信号视为不匹配当threshold未设置0时该检查被跳过。在 e2e/profiles/preference-routing/values.yaml 的实战配置中terse_answers与detailed_answers都使用了threshold: 0.6并用margin_threshold: 0.05追加一道“歧义否决”门槛。2. 可选在 global.model_catalog 覆盖偏好分类器行为global: model_catalog: modules: classifier: preference: use_contrastive: false # optional override; default is true prototype_scoring: enabled: true cluster_similarity_threshold: 0.9 max_prototypes: 8 best_weight: 0.75 top_m: 2 margin_threshold: 0.05对应源码类型为 model_config_types.go 中的PreferenceModelConfigUseContrastive、EmbeddingModel、PrototypeScoring以及 prototype_scoring_config.go 中的PrototypeScoringConfig。3. use_contrastive 默认值v0.3 的新行为文档明确说明如果global.model_catalog.modules.classifier.preference.use_contrastive被省略vSR 默认将其视为true。这意味着一个像 config/recipes/balance/config.yaml 这样的 profile只要声明了偏好信号就无需额外追加全局 classifier 块——除非你想显式禁用对比模式。源码层面的执行契约选择逻辑在 preference_execution.go 中PreferenceUsesPrototypes()规则带 examples、显式指定了embedding_model、或显式use_contrastive: true时返回 true走向量原型对比路径PreferenceUsesDecisionTask()description-only 规则默认走原生 decision-task 判定显式外部分类器保留自己的执行契约优先级关系见 preference_execution_test.go 的测试矩阵explicit prototypes override external、native binding overrides external等用例保证了多种配置组合下的契约选择一致性。初始化链路在 classifier_preference_lifecycle.go先判断是否走 decision task否则读取PreferenceModel.WithDefaults()把UseContrastive指向PreferenceUsesPrototypes()的判定结果再调用NewPreferenceClassifierWithProvider实例化对应实现对比模式默认嵌入模型为mmbert可远程嵌入后端。对比模式Contrastive工作原理在对比模式下路由器的处理流程是嵌入 → 原型压缩 → 相似度打分 → 阈值/边界裁决。第一步预加载规则嵌入contrastive_preference_embeddings.go 中的preloadRuleEmbeddings会收集每条规则的 description 全部 examples见 contrastive_preference_scoring.go 的collectExamples然后并发地worker 数为runtime.NumCPU() * 2把它们嵌入为向量日志输出[Preference Contrastive] preloaded N/M example embeddings using model...。第二步原型库prototype bank压缩嵌入完成后调用rebuildRuleBanks()对每条规则构建一个prototypeBank。构建逻辑在 prototype_bank.go对嵌入后的例子做去重dedupePrototypeExamples计算例子之间的余弦相似度矩阵prototype_clustering.go以cluster_similarity_threshold默认 0.9为阈值做贪心聚类把语义冗余的例子合并每个簇选出medoid最代表该簇的例子作为原型并按ClusterSize、AvgSimilarity降序、文本序兜底排序若原型数超过max_prototypes默认 8截断保留前 N 个。若prototype_scoring.enabled: false则跳过聚类压缩把每个例子原样作为原型uncompressedPrototypeRepresentatives。第三步打分公式查询请求被嵌入后与每条规则的每个原型计算余弦相似度打分逻辑在 prototype_scoring.goscore best_weight × best (1 - best_weight) × supportbest与规则原型库的最高相似度supportTop-M 个最高相似度的平均值top_m默认 2best_weight默认 0.75权重越大越依赖“最强单原型”越小越依赖“整体支持度”取值会被夹在 [0, 1]。最终规则得分即PreferenceRuleScore.Score排序取最高者为BestRule次高者为RunnerUpMargin BestScore - RunnerUpScorecontrastive_preference_scoring.go。第四步阈值与 margin 双重裁决contrastive_preference_classifier.go 的Classify依次检查最佳规则得分低于其threshold→ 拒绝ErrPreferenceBelowThresholdmargin_threshold 0且Margin margin_threshold→ 拒绝“勉强获胜”的模糊结果。文档强调的margin_threshold作用正在于此拒绝模糊赢家而不是硬凑一个弱匹配。在 e2e/profiles/preference-routing/values.yaml 中注释给出了实战理由“Off by default; set explicitly so an ambiguous query that narrowly favors one rule over the other still counts as no match rather than a weak, coincidental win.”信号产出与观测命中后classifier_signal_preference_support.go 会把结果写进SignalResultspreference:name匹配规则名同时进入MatchedPreferenceRulesSignalValues[preference:name]置信度SignalValues[preference:name:margin]胜出边界以及每条规则的:best、:support、:prototype_count明细便于调试与观测。信号提取延迟与置信度会写入results.Metrics.Preference供监控与调参使用。路由决策中的使用方式偏好信号在routing.decisions[].rules.conditions中以type: preference引用。e2e 配置 e2e/profiles/preference-routing/values.yaml 给出了两个完整的对照决策routing: decisions: - name: terse_preference_routing description: Route requests whose preference signal matches terse_answers. priority: 100 rules: operator: AND conditions: - type: preference name: terse_answers modelRefs: - model: general-expert use_reasoning: false - name: detailed_preference_routing description: Route requests whose preference signal matches detailed_answers. priority: 90 rules: operator: AND conditions: - type: preference name: detailed_answers modelRefs: - model: general-expert use_reasoning: false - name: default-route description: Fallback route for requests matching no preference rule. priority: 10 rules: operator: AND conditions: [] modelRefs: - model: general-expert use_reasoning: false注意两点决策按priority从高到低匹配未命中任何偏好规则的请求会落到default-routeconditions 为空这样的兜底决策在真实部署中每个偏好决策还可以挂不同的modelRefs如简洁偏好走低成本快速模型、详尽偏好走高成本强推理模型以及不同的插件栈这正是文档所说“风格信号影响模型选择与插件选择”的落地方式。e2e 验证用例preference_routing.go 注册了名为preference-routing的端到端用例数据来自 preference_routing_cases.json三个用例完整覆盖了三种结果用例查询期望信号是否命中Terse“Please keep your reply short and to the point, no need to explain further.”terse_answers→terse_preference_routing命中Detailed“Please explain your full reasoning and go through this step by step, dont leave anything out.”detailed_answers→detailed_preference_routing命中No match“Whats the capital of France?”无不应命中任何规则不命中用例通过响应头x-vsr-matched-preference断言实际命中的信号名见 signal_routing_helpers.go用“纯事实性查询没有风格提示词、不应命中任何偏好规则”验证了阈值与 margin 双重门槛确实生效。三种执行模式与选择建议结合 classifier_preference_lifecycle.go 与 preference_execution_test.go偏好信号共有三类执行契约模式触发条件行为对比原型contrastive / prototypes规则带 examples、显式embedding_model、或use_contrastive: true嵌入 原型聚类 相似度打分本地或远程嵌入后端均可原生决策任务decision task仅有 descriptiondescription-only且未绑定外部分类器由决策模型以原生 judgment 判定概率式打分外部 LLM 分类器external配置了model_role: preference的外部模型由外部 LLM 按 system/user prompt 判定classifyExternal选择建议追求可解释、可离线验证、低延迟默认的对比原型模式最合适examples 就是可审计的锚点只有描述、不想维护 examples可以只写 description让其自动走决策任务模式需要强语义判定或跨语言泛化可显式绑定外部 LLM 分类器但注意其延迟与成本明确禁用对比显式写use_contrastive: false省略即默认true这是 v0.3 的关键行为变更。调参实战指南prototype_scoring的默认值在 prototype_scoring_config.go 的WithDefaults()中固化可直接作为调参起点参数默认值调参含义enabledtrue是否启用原型聚类压缩设为false则每个例子独立参与打分cluster_similarity_threshold0.9聚类合并阈值越高越严格、保留更多原型越低压缩越激进max_prototypes8每个规则保留的最大原型数超出截断best_weight0.75最强原型在最终得分中的权重0~1越接近 1 越偏向单点最强匹配top_m2计算 support 时取前 M 个最高相似度margin_threshold00 时归零最佳与次佳的得分差下限0 时拒绝歧义匹配典型调参路径先用默认参数跑通观察prototype_count每个规则实际保留的原型数若 examples 语义高度重合、prototype_count偏多可下调cluster_similarity_threshold或上调max_prototypes限制若出现“弱命中”得分刚好过 threshold 但语义牵强调大margin_threshold如 0.05拒绝歧义若发现某类请求被误判为其他偏好检查该类别的 examples 是否过少适当补充语义多样的锚点例子每条规则独立的threshold用于控制该规则的严格程度——整体偏好检测过松/过紧时优先调整它而不是全局参数。完整的多规则实战样例可参考 e2e/profiles/preference-routing/values.yaml双规则 margin 门槛 兜底路由单规则可复用片段见 power-user.yaml参考基线配置见 config/config.yaml。总结preference信号把“用户的回答风格偏好”变成了一个可路由、可观测、可复用的命名输入声明routing.signals.preferences下的规则用 description examples 作为训练锚点v0.3 默认启用对比模式把每个规则压缩成原型库用余弦相似度 threshold margin 双重门槛做裁决决策层通过type: preference条件选择最合适的模型与插件组合。从 Preference Signal 文档 到 classifier_preference_lifecycle.go、contrastive_preference_classifier.go 与 e2e 用例整条链路既保留了示例驱动的可解释性又提供了工程化的调参与验证手段——这是 v0.3 让“同一话题、不同风格”的差异化路由变得可行、可运维的关键能力。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router Preference Signal 指南用示例与原型打分实现响应风格偏好路由semantic router Preference Signal 指南用示例与原型打分实现响应风格偏好路由 导读 本指南讲解 semantic router后端API网关模型推理服务AI AgentSemantic-Router 偏好路由实战用 LLM 偏好匹配实现精细化意图路由Preference RoutingSemantic Router 偏好路由实战用 LLM 偏好匹配实现精细化意图路由Preference Routing 本文以 semantic rout后端API网关模型推理服务AI Agentsemantic-router 偏好信号路由Preference Signal Routing实战指南用 LLM 与 Embedding 实现细粒度请求路由semantic router 偏好信号路由Preference Signal Routing实战指南用 LLM 与 Embedding 实现细粒度请求路后端API网关模型推理服务AI Agent上一篇CloudCompare插件生态系统如何选择和配置最佳插件组合下一篇Attendize自定义票务模板QR码、Logo和品牌化设计终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考