企业官网建设流程全解析

• 后端
• API网关
• 模型推理服务
• AI Agent

导读

context是 semantic-router 中的一类启发式信号（heuristic signal）：它不依赖分类器推理，而是直接根据请求的预估 token 量，判断请求是否需要更大的有效上下文窗口，从而把长文档流量路由到支持 32K、128K 甚至更大上下文的模型，同时让短请求留在更便宜、更快的模型上。读完本文，你将掌握routing.signals.context的完整配置语法、闭区间带（band）语义与边界细节、与模型上下文窗口过滤的协作机制，以及如何通过vllm-srCLI 和 Dashboard 校验配置。

什么是 Context 信号

context信号用于检测"需要更大有效上下文窗口"的请求。规则定义在routing.signals.context之下，属于启发式信号家族——它根据 token 窗口需求而非分类器推断进行路由。src/semantic-router/pkg/config/config.go中将其类型常量为SignalTypeContext = "context"，在路由目录（routing_surface_catalog.go）中作为可被决策规则引用的信号类型注册。

解决的问题

两个提示可以询问同一个主题，但需要的上下文窗口截然不同：一个是几行字的问答，另一个是几万字的长文档分析。如果路由只看 domain（领域），长文档可能被送到上下文窗口不够、导致截断或失败的模型上。context通过把"上下文窗口需求"提升为一等路由输入（first-class routing input）解决这个问题。

核心优势

• 显式化长上下文路由：长上下文路由需求不再隐式地埋在模型默认值里，而是成为配置中可见、可维护的规则。
• 成本控制：防止短提示为超尺寸上下文模型支付不必要的成本（长上下文模型通常更贵、更慢）。
• 阈值复用：同一个上下文阈值可以被多个决策规则复用。
• 信号协同：可以很好地与 domain、complexity 等其他信号配合工作，形成多维度的路由决策。

何时使用

满足以下任一场景即可考虑使用context信号：

• 部分路由需要 32K、128K 或更大的上下文支持；
• 长文档流量应使用不同的模型家族（例如专门的 long-context 模型）；
• 希望短请求停留在更便宜或更快的模型上；
• 路由决策依赖上下文规模本身，而非仅依赖主题。

配置语法

在路由器配置文件（YAML）中，信号规则定义如下：

routing: signals: context: - name: long_context min_tokens: 32K max_tokens: 256K description: Requests that need a larger effective context window.

仓库中提供了可直接参考的完整片段：长上下文信号配置示例。

字段说明

name与description的约束、min_tokens/max_tokens的格式正则^[0-9]+(\.[0-9]+)?[KMkm]?$可在 CRD 类型定义 types_route.go 中看到，这也是 Kubernetes 校验与 YAML 解析共用的一份契约。

带（Band）的区间语义

每条规则定义的是一个闭区间 token 带：当min_tokens <= token_count <= max_tokens时匹配。源码实现ContextBounds.Matches可见于 signal_config.go。

关键语义规则

• 两个边界都可选，但至少设置一个。缺省min_tokens视为 0。
• 省略max_tokens即为开区间带（open-ended）：任何不低于min_tokens的请求都匹配，没有上限。通常用它在最后一个带上承接"溢出"流量，使高于最大有界带的请求仍携带上下文信号。对应结构体中的Unbounded字段，诊断输出形如[8000, ∞)。
• min_tokens与max_tokens相等时为精确匹配带，只命中该一个 token 数。边界契约测试 context_classifier_test.go 明确验证了 1000 同时落在[0,1K]与[1K,1K]两个带、而 1001 落在两者之外的行为。
• 所有匹配的规则都会被报告，按配置顺序返回。带之间允许重叠，重叠时两个名称都会出现在x-vsr-matched-context响应头中。该头（连同x-vsr-context-token-count）的定义见 headers.go。
• 带之间的缺口与重叠会在配置加载时记录 warning。缺口内的请求不匹配任何 context 规则。带分析逻辑ContextBandIssues位于 signal_config.go，会返回ContextBandOverlap（含Contains判断外层带是否完整包含内层带）与ContextBandGap两类问题；validator_context_test.go中的TestContextBandIssues验证了 "1001~3999 为缺口、wide 完全包含 narrow" 等场景。
• 验证会拒绝：两个边界均未设置、无法解析、负值、过大值，以及min_tokens大于max_tokens的规则。错误信息统一带routing.signals.context[...]前缀，见 validator_context_test.go。

多带配置示例

routing: signals: context: - name: short_context min_tokens: 0 max_tokens: 8K - name: medium_context min_tokens: 8001 max_tokens: 64K - name: long_context min_tokens: 64001 description: Open-ended band; matches everything above 64K tokens.

该示例中的long_context即开区间带：任何超过 64K token 的请求都会命中它。TestParseYAMLLoadsOpenEndedContextBand（validator_context_test.go）覆盖了此类配置从 YAML 解析到校验的完整链路。

数值解析细节

K/M 后缀

min_tokens/max_tokens接受K与M后缀（1.5K、0.5M）。解析实现TokenCount.Value位于 signal_config.go：K乘 1000，M乘 1,000,000，支持小数（如0.5M= 500000），并拒绝 NaN、Inf 与负数，超过int上限时报 "token count is too large"。

YAML 1.1 类型转换陷阱

带限值在解析前会先经过路由器 YAML 解码器的类型化（遵循 YAML 1.1 规则）：

• 0123按八进制解析为 83；
• 0x10按十六进制解析为 16；
• 1_000解析为 1000；
• 1:30不是数字。

引用（quote）一个值可以保持其字面含义，例如'0123'就是 123。vllm-srCLI 应用相同的类型化逻辑，因此其校验结果与路由器从转发文件加载的结果一致。

环境变量引用

带限值可以引用环境变量，如${CTX_MIN}。路由器在配置加载时展开它，因此 CLI 接受该带但会给出 warning 而不是直接校验它。

源码级实现：Token 计数与请求上下文估计

字符启发式计数器

默认计数使用字符启发式而非完整 tokenize：CharactersPerToken = 4（散文约 4 字节/token）。CharacterBasedTokenCounter.CountTokens计算len(text)（字节数）除以 4 并向上取整，是 O(1) 操作；对 UTF-8 多语言文本，字节数高于字符数，会得到保守（偏高）的估计。实现见 context_classifier.go。

请求上下文估计公式

路由准入前会基于请求 envelope 做内容无关的上下文估计，公式（见 request_context_estimate.go）：

ceil(TextBytes / 4) + StructuredBytes + 8192 * ImageCount + FramingTokens + OutputTokenReserve

各组成含义（同一文件顶部常量）：

• 散文文本按 4 字节/token；
• schema、工具参数等结构化 JSON 按 1 字节/token估算（标点密集的 payload 比散文 token 化更密）；
• 每张图片预留8K token的保守预算；
• chat 模板的 role/控制 token 预留：每条消息 4、工具调用 8、工具定义 8；
• 输出 token 预留取自请求的max_tokens/max_completion_tokens。

该估计同时解析 OpenAI Chat Completions 与 Anthropic Messages 两种 envelope（EstimateOpenAIRequestContext/EstimateAnthropicRequestContext），通过gjson直接消费原始 JSON，保留超过 2^53 的整数字面量精度。对消息角色、名称、tool_calls、function_call、response_format 等逐项计入，未知的结构化内容按原始词法表示计入，而非静默丢弃。

分类器与 Token Floor

ContextClassifier.Classify会计算 token 数并依次比对所有已编译规则；ClassifyWithTokenFloor还会把校准后的文本估计与请求 envelope 的保守下限（TokenFloor）取较大值，用于覆盖工具 schema、结果与图片 payload 等不会复制进信号文本的部分。规则在构造时预编译为compiledContextRule（ok=false的规则保留名称用于诊断但永不匹配），热路径不做字符串解析。见 context_classifier.go。

决策引擎中的引用

context 信号以type: context+name: <rule_name>的形式被决策规则引用，例如validator_context_test.go中的 YAML 片段：

decisions: - name: overflow_route rules: operator: AND conditions: - type: context name: overflow_context modelRefs: - model: model-b use_reasoning: false

决策引擎的匹配行为由 engine_context_test.go 验证（"matches" 与 "no match" 两种用例）。

与模型上下文窗口的交互：依赖与限制

context 带只是路由信号，不会改变模型的上下文窗口上限——路由器在过滤候选模型时仍会单独强制执行窗口限制：

• token 估计依赖请求表示，不保证后端一定接受最终 prompt；
• 冷启动时散文按约 4 字节/token 估算，随后路由器仅对文本至少 4 KiB 的请求从 provider 上报的 prompt usage 学习真实比例；更短的请求中 chat-template 开销占主导，报告数量不可靠；
• 请保持模型卡上的上下文窗口准确，并为生成输出预留空间；
• 选路前，路由器会移除那些配置的、正的上下文窗口小于预估请求的决策候选；
• 缺失上下文元数据的候选仍保持资格（向后兼容）；若所有候选的窗口都已知不足，路由器会拒绝请求而不是把它转发给不合格的后端。

验证与工具链一致性

Router、vllm-srCLI 与 Dashboard 应用相同的校验规则：一个通过vllm-sr config validate的带，在路由器中也能正常加载。这意味着你可以在部署前用 CLI 先行校验 context 带配置，再同步给路由器和 Dashboard，三端行为保持一致。配置校验相关的测试（接受/拒绝用例全集）见 validator_context_test.go。

完整实战示例

综合以上内容，一份覆盖"短、中、长、溢出"四档的典型配置：

routing: signals: context: - name: short_context min_tokens: 0 max_tokens: 8K description: Short queries stay on the fast/cheap model. - name: medium_context min_tokens: 8001 max_tokens: 64K description: Medium documents go to the 64K model family. - name: long_context min_tokens: 64001 max_tokens: 256K description: Long documents need a 256K context model. - name: overflow_context min_tokens: 256001 description: Everything above the largest bounded band.

配合决策规则引用type: context信号名，即可在 Router、vllm-srCLI 与 Dashboard 三端获得一致的长上下文路由行为。注意在最后一个开区间带之前仔细设计边界，利用配置加载时的 overlap/gap warning 及早发现带之间的缺口。

• 后端
• API网关
• 模型推理服务
• AI Agent