后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本指南围绕 semantic-router 的 keyword-based routing 展开讲解如何通过显式 keyword rule 与 regex 模式将请求路由到不同模型与决策路径。该能力适用于合规、安全与可解释 AI 场景——例如金融、医疗、政务等对审计追溯有硬性要求的系统可据此在亚毫秒级延迟内实现完全确定性的路由决策。读完本文你将掌握 signals/decisions 配置、AND/OR/NOR 运算符语义、regex/BM25/n-gram 三种匹配方法、置信度计算规则以及如何通过响应头验证路由结果。为什么需要关键词路由ML 黑箱之外的确定路径基于 ML 的 classification 通常是难以审计和解释的黑箱模型为什么把这条查询路由到某个 category外部审计人员无法从模型权重中获得答案。Keyword routing 提供了另一条路线可解释的 decision确切知道为什么一个查询被路由到特定 category因为命中了哪几个关键词监管 compliance审计人员可以逐条验证路由逻辑是否符合 GDPR、HIPAA、SOC2 等要求确定性行为相同的 input 始终产生相同的 output无随机性零 latency无需 model 推理瞬时完成 classification精确控制针对 security、compliance 和业务逻辑编写显式 rule。从源码结构看这一能力由 keyword_classifier.go 中的KeywordClassifier实现每个配置的规则使用 regex默认、BM25 或 n-gram 匹配并按配置顺序依次评估。它不依赖任何 embedding 模型或 GPU因此延迟与吞吐量都可预测。何时使用 Keyword Routing需要 audit trail 的受监管行业金融、医疗、法律需要确定性 PII 检测的security/compliance场景亚毫秒级 latency 至关重要的高吞吐量系统具有清晰 keyword 指示的紧急/优先级路由匹配 regex 模式的结构化数据email、ID、文件路径。配置在 config.yaml 中定义 keyword signal 与 decision在您的config.yaml中添加 keyword signal并用它组合出 decision。以下为 v0.1 参考配置主分支已不再保留旧的完整示例文件可直接使用本页代码片段# 定义 keyword signal signals: keywords: - name: urgent_keywords operator: OR # 匹配任意关键词 keywords: [urgent, immediate, asap, emergency, 紧急] case_sensitive: false - name: sensitive_data_keywords operator: OR keywords: [SSN, social security, credit card, password, 身份证] case_sensitive: false - name: spam_keywords operator: OR keywords: [buy now, free money, click here, 免费领取] case_sensitive: false # 使用 keyword signal 定义 decision decisions: - name: urgent_request description: 路由紧急请求 priority: 100 # 高优先级 rules: operator: OR conditions: - type: keyword name: urgent_keywords modelRefs: - model: openai/gpt-oss-120b use_reasoning: false plugins: - type: system_prompt configuration: system_prompt: 你是一位响应迅速的助手专门处理紧急请求。 - name: sensitive_data description: 路由敏感数据查询 priority: 90 rules: operator: OR conditions: - type: keyword name: sensitive_data_keywords modelRefs: - model: openai/gpt-oss-120b use_reasoning: false plugins: - type: system_prompt configuration: system_prompt: 你是一位具有安全意识的助手专门处理敏感数据。 - name: filter_spam description: 拦截垃圾查询 priority: 95 rules: operator: OR conditions: - type: keyword name: spam_keywords modelRefs: - model: openai/gpt-oss-120b use_reasoning: false plugins: - type: system_prompt configuration: system_prompt: 此查询似乎是垃圾信息。请提供礼貌的回复。配置项的完整字段说明从 signal_config.go 中的KeywordRule结构体可以确认 keyword rule 支持的全部字段字段类型含义默认值namestring规则唯一标识同时用作匹配到的 category 名必填operatorstring逻辑运算符AND/OR/NOR必填keywordsstring[]待匹配的关键词列表必填case_sensitivebool是否大小写敏感falsemethodstring匹配方法regex默认/bm25/ngramregexfuzzy_matchbool是否启用近似匹配Levenshtein 编辑距离falsefuzzy_thresholdint近似匹配允许的最大编辑距离2bm25_thresholdfloat32BM25 方法命中阈值0.1ngram_thresholdfloat32n-gram 方法命中阈值0.4ngram_arityintn-gram 的 n 值3其中case_sensitive在 types_route.go 的 CRD 定义KeywordSignal中默认值为falsedecision 的priority取值范围为 01000默认 0数值越高优先级越高。需要说明的是CRD 层面的KeywordSignal.Operator枚举目前为AND;OR而路由内部实现的KeywordClassifier与 lexical 层同时支持NOR见下文运算符小节。method为regex时关键词会被regexp.QuoteMeta转义后作为字面量匹配为bm25或ngram时则会走 lexical/rule.go 与 lexical/bm25.go、lexical/ngram.go 中的打分逻辑。仓库自带的两个 fragment 文件给出了这三种方法的现成示例config/fragments/signal/keyword/regex.yamlurgent_keywords、sensitive_data_keywords两个 OR 规则均为默认 regex 方法config/fragments/signal/keyword/nlp.yamlcode_keywords使用method: bm25与bm25_threshold: 0.1urgent_keywords使用method: ngram、ngram_threshold: 0.4、ngram_arity: 3。decision 还支持把 keyword signal 与其它类型 signal 组合。例如 config/fragments/decision/and/urgent-business.yaml 演示了operator: AND下同时要求domain: business与keyword: urgent_keywords两个条件同时成立才算命中routing: decisions: - name: urgent_business_route description: Match only when business intent and urgent language appear together. priority: 140 rules: operator: AND conditions: - type: domain name: business - type: keyword name: urgent_keywords modelRefs: - model: qwen2.5:3b use_reasoning: false运算符语义OR / AND / NOROR如果找到任意一个 keyword 则匹配AND仅当找到所有keyword 时才匹配NOR仅当未找到任何keyword 时才匹配排除。这三个运算符在 lexical 层的Rule.decide中严格实现lexical/rule.gocase OR: matched len(keywords) 0 case AND: matched len(keywords) len(r.Keywords) case NOR: return Match{TotalKeywords: len(r.Keywords)}, len(keywords) 0其中 AND 要求所有关键词都命中命中数等于规则关键词总数NOR 在没有任何关键词命中时匹配因此Match.Keywords为空——日志中会以 matched rule with a NOR rule 的形式记录见 keyword_classifier_dispatch.go 的logRuleMatch。同时KeywordClassifier构造时会校验 operator不支持的运算符如unsupported keyword rule operator会直接返回错误避免配置静默失效。值得注意的是keyword 规则按配置文件中定义的顺序依次评估采用 first-match 语义ClassifyWithKeywordsAndCount遇到第一个命中的规则即返回因此urgent_requestpriority 100与filter_spampriority 95同时命中时会先落入配置更靠前的规则若需要多信号组合参与 decision 的 AND/OR/NOT 表达式则使用MatchAll评估全部规则源码注释对此有明确说明。三种匹配方法regex / BM25 / n-gramKeywordClassifier通过method字段选择引擎keyword_classifier.goregex默认每个关键词预编译为正则表达式。字面量关键词经QuoteMeta转义后再编译避免特殊字符被误解析为正则语法显式编写 regex 模式的关键词则原样编译keyword_classifier_regex.go 中的regexPatterns。对于含字母、数字或下划线的字面量关键词还会施加相邻字符边界检查LiteralBoundaries防止 urgent 误匹配 not-urgent 之类的子串连续 CJK 文本则保留子串匹配语义这也解释了配置中紧急、免费领取等中文关键词无需额外转义。bm25基于 BM25 打分命中阈值由bm25_threshold控制默认 0.1适合对关键词做了轻微改写、仍保有一定词法相关度的文本。ngram基于 n-gram 打分默认 arity3、阈值 0.4通过字符级重叠容忍拼写差异适合处理带噪音的短文本。从源码注释可知lexical 包是纯 Go 实现等价替代了此前 nlp-binding 提供的 bm25 2.3.2 与 ngrammatic 0.7.0 两个 Rust crate 的行为——同样的分词器、同样的 float32 打分运算、同样的 AND/OR/NOR 语义因此历史配置中的阈值含义保持一致。另外regex 方法还支持fuzzy_match近似匹配启用后基于 Levenshtein 编辑距离进行容错默认fuzzy_threshold2并预计算关键词的小写形式用于比较。置信度由命中比例动态计算Keyword 路由虽然是确定性匹配但依然会输出一个 01 的置信度供上层决策与可观测性使用。核心公式位于 keyword_classifier.go 的Classifyratio : float64(matchCount) / float64(totalKeywords) confidence : 0.5 (ratio * 0.5)即命中 1/4 个关键词时置信度为 0.6252/4 为 0.753/4 为 0.875全部命中为 1.0。这与 E2E 测试数据 e2e/testcases/testdata/keyword_routing_cases.json 中记录的期望值完全吻合用例查询期望 category期望置信度OR 命中 1 个关键词1/4I need urgent help with my accounturgent_request0.625OR 命中 2 个关键词2/4This urgent emergency needs your help nowurgent_request0.75OR 命中 3 个关键词3/4This is urgent and needs immediate response asapurgent_request0.875OR 命中全部 4 个关键词4/4This urgent emergency requires immediate attention asap pleaseurgent_request1.0AND 两个关键词都命中2/2My SSN and credit card info were stolensensitive_data1.0REGEX 命中 email 模式1/2Please send the report to user.namedomain.com todayregex_pattern_match0.75大小写不敏感URGENT / EmergencyThis is URGENT please helpurgent_request0.625同时在信号求值层classifier_signal_rule_evaluators.go 的evaluateKeywordSignalkeyword 信号作为基于规则的信号其置信度固定记录为 1.0results.Metrics.Keyword.Confidence 1.0并输出匹配的规则名与关键词列表供 decision 组合引擎消费。请求示例与结果可观测性# 紧急请求匹配 urgent curl -X POST http://localhost:8801/v1/chat/completions \ -H Content-Type: application/json \ -d { model: MoM, messages: [{role: user, content: I need urgent help with my account}] } # 敏感数据匹配所有关键词 curl -X POST http://localhost:8801/v1/chat/completions \ -H Content-Type: application/json \ -d { model: MoM, messages: [{role: user, content: My SSN and credit card were stolen}] }路由结果通过响应头对外暴露便于调试与审计。E2E 测试 keyword_routing.go 直接读取以下头部进行断言x-vsr-selected-decision/x-vsr-selected-category命中的 decision / category 名称x-vsr-matched-keywords实际匹配到的关键词列表逗号分隔其常量定义在 headers.go 中VSRMatchedKeywords x-vsr-matched-keywordsx-vsr-selected-confidence本次路由的置信度。该 E2E 用例将查询发送到本地服务测试中使用的模型名为vllm-sr/auto随后校验 category、关键词列表顺序无关地比较与置信度三项是否全部符合预期并以accuracy_rate、keyword_accuracy汇总上报——这正是本文配置在真实集群环境下可被自动验证的落点。在开发与调试阶段这些响应头可以让运维人员直接看到这条请求因为命中了哪些关键词而被路由到哪个决策与 keyword routing 的可解释目标完全一致。真实世界用例1. 金融服务透明合规问题监管机构要求为 audit trail 提供可解释的路由 decision。解决方案Keyword rule 为每个路由 decision 提供清晰的 原因例如SSN keyword → 安全处理器。影响通过了 SOC2 审计实现了 decision 的完全透明。2. 医疗平台合规的 PII 检测问题HIPAA 要求确定性的、可审计的 PII 检测。解决方案AND operator 通过记录的 rule 检测多个 PII 指示符。影响100% 确定性提供符合 compliance 要求的完整 audit trail。3. 高频交易亚毫秒级路由问题实时市场数据路由需要 1ms 的 classification latency。解决方案Keyword matching 提供即时 classification无 ML 开销。影响0.1ms latency可处理 100K 次请求/秒。4. 政府服务可解释的规则问题公民需要了解为什么请求被路由或拒绝。解决方案清晰的 keyword rule 可以用通俗易懂的语言进行解释。影响减少了投诉实现了 decision 制定的透明化。5. 企业安全透明的威胁检测问题Security team 需要了解为什么查询被 flag。解决方案针对威胁模式使用显式的 keyword/regex rule并附带清晰的文档。影响Security team 可以自信地验证和更新 rule。性能优势亚毫秒级 latency无 ML 推理开销高吞吐量单核可处理 100K 次请求/秒成本可预测无需 GPU 或 embedding model零冷启动第一个请求即可实现即时 classification。从实现角度这些优势来源于两点其一regex 关键词在配置加载阶段即完成预编译preppedKeywordRule持有CompiledRegexpsCS/CompiledRegexpsCI运行时只做匹配不做编译其二lexical 层对同一文本的 token 化与 n-gram 计算按文本与 arity 缓存lexical/rule.go 中的Text结构一个请求即使被多个规则检查也只分词一次进一步压低了单请求 CPU 成本。参考与版本说明本文配置片段可直接作为v0.1参考配置使用主分支已经不再保留旧的完整示例文件。若需进一步验证路由行为可运行 e2e/testcases/keyword_routing.go 对应的keyword-routingE2E 用例测试数据见 e2e/testcases/testdata/keyword_routing_cases.json或参考单元测试 keyword_accuracy_test.go 中覆盖的 jailbreak、creative、deep thinking 等真实场景规则。生产环境建议将 keyword 路由与 embedding 等语义信号结合使用确定性规则负责合规边界与硬性拦截语义信号负责模糊意图识别两者通过 decision 组合AND/OR互补。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 关键词路由Keyword Routing实战指南用显式规则实现可解释、可审计、亚毫秒级的智能路由semantic router 关键词路由Keyword Routing实战指南用显式规则实现可解释、可审计、亚毫秒级的智能路由 本指南基于 semant后端API网关模型推理服务AI Agentsemantic-router Keyword Signal 完全指南用关键词规则构建确定性的低延迟路由semantic router Keyword Signal 完全指南用关键词规则构建确定性的低延迟路由 导读 Keyword Signal 是 semant后端API网关模型推理服务AI Agentsemantic-router 关键词信号keyword signal从 YAML 配置到 BM25、n-gram 与正则匹配的实现详解semantic router 关键词信号keyword signal从 YAML 配置到 BM25、n gram 与正则匹配的实现详解 本文基于 sem后端API网关模型推理服务AI Agent上一篇告别重复废话BullshitGenerator语料库清洗完全指南下一篇React Native Geolocation常见问题与解决方案从入门到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考