- 后端
- API网关
- 模型推理服务
- AI Agent
【免费下载链接】semantic-router
An open, programmable decision layer for models and compute.
本文围绕 semantic-router 官方文档中的 Complexity 信号展开，介绍这一「学习型」信号如何通过难/易候选示例的嵌入相似度，估计请求需要更强推理还是更便宜的简易路径，并给出完整配置、边界判定原理、多模态扩展与源码级实现佐证。读完本文，你将掌握
routing.signals.complexity的完整配置方法、threshold 与边界对的语义差异、决策规则中的引用方式，以及本地原型评分与远程评分后端两条执行路径的取舍。
一、为什么需要单独估计「复杂度」：领域不等于难度
在路由系统中，最常见的分类维度是主题（domain）：把「法律咨询」路由到法律模型、「数学证明」路由到推理模型。但仅凭主题无法判断是否需要强推理——同一个领域内，两个问题的推理深度可能差异很大：
- 「什么是牛顿第二定律」与「推导并证明动量守恒在变质量系统下的成立条件」同属物理领域，但前者一问即答，后者需要多步推理；
- 「把这句话改得更简洁」与「分析这个 3000 行函数的根因」同属文本处理场景，成本与延迟差异巨大。
如果路由只依赖领域分类，简单请求会被过度升级（成本浪费），复杂请求会被留在廉价模型（质量受损）。semantic-router 的complexity信号正是为解决这一问题而生：它通过示例驱动的规则直接估计任务难度，而不依赖主题推断。这条设计把「推理升级」与「领域分类」彻底解耦，使同一套复杂度策略可以被多条决策复用，难/易示例随时间调参也相对简单——这是该信号族最核心的优势。
二、该信号的定位与适用场景
complexity属于学习型（learned）信号族：分类器用嵌入相似度将请求与难/易候选示例比较，而不是靠正则或关键字硬编码。它映射到config/fragments/signal/complexity/，在routing.signals.complexity中声明。
在以下场景优先使用complexity：
- 部分提示需要更强推理或更长思维链，但无法靠主题识别；
- 简单流量应留在更便宜模型，复杂提示应升级到更强模型；
- 希望升级策略独立于领域，同一策略在多条决策间复用；
- 多模态推理请求（如带截图、带图像的 CUA 请求）与简单提示需要不同处理。
仓库中一个典型的复杂度片段位于 config/fragments/signal/complexity/escalation.yaml，它定义了名为needs_reasoning的规则：把「多步推理、综合权衡、根因分析」类请求标记为 hard，把「简短回答、快速摘要、简单改写」类请求标记为 easy。
三、完整配置：规则结构逐字段拆解
官方文档给出的最小配置如下，它在routing.signals.complexity下声明一条规则：
routing: signals: complexity: - name: needs_reasoning threshold: 0.75 description: Escalate multi-step reasoning or synthesis-heavy prompts. hard: candidates: - solve this step by step - compare multiple tradeoffs - analyze the root cause easy: candidates: - answer briefly - quick summary - simple rewrite对照源码中 ComplexityRule 结构体 与ComplexityCandidates（同文件 L479-L482），各字段含义如下：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 规则名，最终以rule:verdict（如needs_reasoning:hard）的形式供决策条件引用 |
threshold | float32 | 二选一 | 对称阈值简写。本地 margin 以 0 为中心的有符号值：hard 边界为+threshold，easy 边界为-threshold |
hard_above/easy_below | float64 | 二选一 | 显式边界对：分数越高越难时使用（见「边界判定」一节） |
hard_below/easy_above | float64 | 二选一 | 显式边界对：分数越低越难时使用 |
description | string | 否 | 规则说明，会注入决策任务路径的问题描述 |
hard.candidates | []string | 是 | 困难示例库，启动时预计算嵌入 |
easy.candidates | []string | 是 | 简单示例库，启动时预计算嵌入 |
hard.image_candidates/easy.image_candidates | []string | 否 | 多模态图片候选（本地路径或>complexity_model: backend: protocol: http_classify contract: score.v1 # 或 label_distribution.v1 ...
启动校验保证： 另外还有一条决策任务路径：当 complexity 信号绑定到 八、在决策规则中引用 complexity：完整实战示例仓库 config/recipes/balance/config.yaml 中，
注意：决策规则中引用复杂度判定时，条件写法为： 其中 九、调参实践与注意事项
十、源码路径速查
赞
【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute. 项目地址：https://gitcode.com/gh_mirrors/sem/semantic-router 相关推荐
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING 延伸阅读更多一线实战笔记与深度复盘，助您持续精进 |
