智能路由
1 概述
智能路由用于根据请求内容自动匹配并选择合适的模型，实现请求的分类转发与模型调度。智能路由提供两种决策模式：本地/向量模式（本地规则 + 向量相似度）与 模型决策模式（调用外部决策模型），同一时间仅运行其中一种，切换模式时另一种模式的既有配置会被保留。
智能路由包含三个模块：
- 样本管理：维护用于请求分类的样本数据，支持设置样本标签以及单样本阈值（本地/向量模式使用）。
- 决策日志：可查看每一次请求的路由分类、决策来源、决策提供商与模型、选中模型和置信度等相关信息。
- 统计：支持按照标签、来源、模型、Token 维度查看决策分布情况。
三者的关系为"样本 → 决策 → 统计"：样本提供了判定依据，决策是依据样本实时完成的路由选择，统计则对大量决策结果做汇总呈现。其中样本管理是核心，样本的质量直接影响智能路由的准确度。
智能路由的开关、路由模式以及模型组等判定参数在「网关设置 → 智能路由」中配置，详见网关设置。
1.1 两种路由模式
- 本地/向量模式：通过预置的分类样本识别请求的复杂度，结合本地规则、向量相似度等来源作出路由决策，将请求分流到简单或复杂模型组。适合"轻量模型 / 高能力模型"的二级分流，且分类边界长期稳定、已积累代表性样本的场景。即使向量服务暂时不可用，网关仍可使用本地复杂度规则完成基础判断。
- 模型决策模式：调用外部决策模型（1Panel-laya-server），面向管理员自定义的多个业务目标（2~10 个）完成语义决策。业务应用统一使用虚拟模型名发起请求，由决策模型根据当前请求在已配置目标中完成结构化选择，网关负责权限校验、候选模型筛选、模型组调度、失败兜底、日志和统计。适合在通用问答、代码分析、内容创作、翻译等多个专长模型组之间选择，或路由目标随业务变化、希望通过自然语言定义快速调整策略的场景。
两种模式不会互相替代，可根据路由维度、目标数量、现有数据和外部服务边界选择更合适的模式。决策日志中的「决策来源」列会标注每条请求实际由本地规则、embedding 还是模型决策作出判定。
2 样本管理
样本管理用于本地/向量模式。启用模型决策模式时不需要维护路由样本，其路由目标在「网关设置 → 智能路由」中定义，参见本文第 5 节。
样本管理用于维护请求分类所需的路由样本。可在此查看、添加、批量导入样本，构建样本向量，并通过"决策预览"验证路由效果。系统根据样本与请求的相似度对请求进行分类，分类结果决定请求被路由到简单或复杂模型。
2.1 样本列表
进入智能路由后默认显示样本管理页。样本列表按分页展示全部样本，包含标签、样本文本、向量与操作等信息。
2.2 添加样本
要让智能路由"认识"你的典型请求，就需要把这类请求作为样本录入系统。样本是所有判定的参照物，因此添加样本是使用智能路由的第一步。点击「添加样本」按钮，在弹出的表单中填写以下内容：
-
标签：选择该样本的分类标签。标签决定了该样本代表"简单"还是"复杂"等类别，是后续判定归类的依据。
-
样本文本：填写用于匹配的文本内容，最大支持 65536 个字符。文本应尽量贴近真实请求的典型表达，覆盖越全，判定越准。
-
单样本单值：为该样本补充一个单值，可通过「+」「-」进行调整，用于提升匹配精度，可理解为对该样本重要程度或特征的量化补充。
-
备注：填写对该样本的补充说明（选填），便于日后理解该样本的用途。
-
保存后生成向量：勾选后，保存样本的同时自动生成对应的向量。
2.3 批量添加
当样本数量较多（例如历史请求已积累了成百上千条）时，逐条录入效率极低。批量添加可一次性导入多条样本，快速建立样本库，从而缩短"从无到有"的准备周期。
点击「批量添加」按钮，可一次导入多条样本。批量添加表单包含标签、样本文本等字段，并支持「保存后生成向量」选项，便于一次性录入大量样本，无需逐条操作。
2.4 决策预览
单击 决策预览，可输入一条请求样本，先查看路由决策的预判结果，确认无误后再决定是否添加为正式样本，以便在正式启用前及时发现样本或标签配置的问题，避免不当策略上线。
2.5 构建向量
计算机无法直接比较两段文字的"相似度"，需要先把文本转换为向量（一组数值），才能进行语义匹配。样本未经向量化，就无法参与智能判定。因此构建向量是样本真正"生效"的必经步骤。
页面提供以下向量构建操作：
-
构建选中向量：勾选列表中的样本后，为选中的样本构建向量。
-
构建全部向量：为列表中的全部样本构建向量。
向量构建完成后，样本才能参与智能路由的匹配判定。
2.6 编辑与删除
-
编辑：在「操作」列点击编辑，可修改样本的标签、样本文本、单样本单值及备注等内容。当业务表达变化时及时修改样本，可保证判定依据不过时。
-
删除：移除不再需要的样本。删除后将不再参与路由判定，请确认后操作。
3 决策日志
智能路由的决策过程由系统自动完成，有别于人工可逐条核对的固定规则。若仅查看决策结果，通常难以判断其选型依据；一旦出现选错模型或路由异常的情况，缺乏记录将难以定位原因。决策日志详细留存每一次决策的完整信息，使路由过程可追溯、可审查，并为后续的策略优化提供依据。
决策日志列表包含 Request ID、路由分类、决策来源、决策提供商与模型、选中模型、置信度、请求类型、决策耗时、决策时间等列。「决策来源」标注该次判定由本地规则、embedding 还是模型决策作出：本地/向量模式的来源为本地规则或 embedding，模型决策模式的来源为模型决策，其「决策提供商与模型」列显示为 1Panel-laya-server。
3.1 决策日志筛查
列表顶部提供筛选与搜索能力，可按全部分类、全部来源、全部请求类型、全部决策提供商下拉过滤，填写选中模型，并按 Request ID / 模型 / 文本 搜索，便于快速定位某次决策。
3.2 决策日志查看
点击某条记录的「查看」，可打开决策详情面板，查看该次请求的完整决策信息，包括请求的规范化文本、实际置信度、决策来源等，以及用于本次匹配的 Top K 命中样本（即参与判定的最相关的若干条样本）。通过详情可清楚了解本次路由决策的依据与结果，例如当请求被误分时，可据此判断是样本缺失还是阈值设置不当。
4 统计
样本与路由策略是否有效，无法凭主观判断，需以实际数据为依据。统计页面将大量决策结果予以汇聚，用于回答"路由效果表现如何、哪些方面需要优化"等问题，从而为样本与策略的持续迭代提供量化依据。
- 总览指标：筛选区下方以卡片形式展示所选时间范围内的核心指标，包含决策数、真实请求数、失败数、总 Token、平均 Token、累计耗时，直观展示智能路由决策运行的整体概况。
- 分布表格：总览卡片下方按多个维度展示用量分布，分布维度包含按标签分布、按来源分布、按模型分布、按总 Token 分布。可从整体上观察路由分类、请求来源、模型选用等维度的占比构成。通过上述数据可识别规律与异常，例如某类样本占比过高、某模型的失败率出现异常等，从而为样本优化提供参考。
- 模型决策扩展指标：启用模型决策模式后，可按决策提供商维度观察决策命中与回落情况，用于分析各路由目标的命中分布与回退比例。
说明：统计页支持切换时间维度查看不同周期的数据，包括近 24 小时、近 7 天与近 30 天。
5 模型决策模式配置
模型决策模式的启用与路由目标定义均在「网关设置 → 智能路由」中完成，配置界面见网关设置 · 智能路由。本节说明完整配置流程与调优方法。
5.1 启用模型决策模式
- 进入管理端「网关设置」→「智能路由」标签，打开「路由策略」的「状态」开关；
- 在「路由模式」中点击 模型决策（与「本地/向量」并列，二选一）；
- 确认「虚拟模型名称」。客户端使用该模型名发起文本请求时即触发智能路由。
5.2 配置模型决策服务与兜底模型组
「模型决策」块初始显示为「未启用」，配置以下项后启用：
- 决策提供商与模型：显示为
1Panel-laya-server / auto，即网关集成的外部决策服务与决策模型，无需修改。 - 1Panel-laya-server 服务地址：填写外部决策服务的地址。
- 1Panel-laya-server API Key：填写决策服务的访问凭据。模型决策为外部服务，启用前请结合业务的数据合规要求评估（数据边界见 5.5）。
- 兜底模型组：当决策模型判定为其他目标，或决策失败、不可用时，请求会调用此模型组。
- 测试连接：保存后点击「测试连接」检查服务地址与凭据是否可用。
5.3 定义路由目标
模型决策的路由目标数量为 2–10 个。在「路由目标」列表中点击添加，每个路由目标包含以下字段：
| 字段 | 说明 |
|---|---|
| 目标名称 | 直观命名，例如「简单问答与基础处理」「复杂推理与代码分析」 |
| 关联模型组 | 该目标对应的模型组，命中后请求由该模型组承接 |
| 适用说明 | 描述应进入该目标的任务类型、难度和场景 |
| 排除说明 | 重点写容易混淆、但不应进入该目标的情况 |
示例：目标「简单问答与基础处理」关联"简单模型"，适用说明填写"适用于不需要复杂推理的请求，包括日常寒暄、闲聊、事实问答、简单解释、翻译、改写、摘要、格式转换和基础代码说明"，排除说明填写"不适用于系统设计、多方案比较、复杂代码修改、跨模块排错、数学证明、长上下文分析或需要多步推理的请求"。目标「复杂推理与代码分析」则关联"复杂模型"，适用与排除说明与之互补。
编写目标定义时建议：目标名称直观；适用说明覆盖任务类型与场景；排除说明针对易混淆情形，与互补目标的适用说明相互呼应。
5.4 测试模型决策
配置完成后，点击「测试模型决策」按钮，在对话框中输入请求样本，可查看命中的目标名称、置信度与决策结果，快速检查目标描述是否清晰。若发现请求被分到不期望的目标，可回头调整该目标（或易混淆目标）的适用说明与排除说明。
5.5 兜底、熔断与数据边界
- 自动兜底：当决策模型判定为其他目标，或决策服务失败、超时、限流、不可用时，网关自动将请求交由兜底模型组处理。
- 数据边界：模型决策为外部服务，请求内容会发往 1Panel-laya-server。管理员应根据自身业务的数据合规要求，决定是否启用外部决策服务，并务必配置兜底模型组。
5.6 持续优化
决策日志与统计页面记录决策来源、决策提供商与模型、选中模型、置信度、决策耗时等信息。可据此观察各类请求的分布，定位边界不清的目标，持续优化适用说明与排除说明。
6 注意事项
-
样本质量直接决定路由准确度：智能路由依赖样本文本进行匹配，请确保样本标签准确、内容覆盖到位，并定期补充与更新。
-
样本需向量化后才能参与判定：新增或修改样本后，需构建对应向量，否则无法进入智能匹配。
-
使用决策预览验证效果：正式调整样本策略前，建议先通过"决策预览"验证路由结果是否符合预期。
-
谨慎删除样本：删除样本后即不再参与路由判定，确认无需使用后再执行。
-
模式切换互不影响：同一时间仅运行一种路由模式，切换模式时另一模式的既有配置会被保留，可随时切回。
-
模型决策目标定义质量决定决策准确度：适用说明与排除说明覆盖不全、目标过多（接近 10 个上限）都可能导致路由边界模糊，建议结合「测试模型决策」与决策日志持续校准。
-
模型决策依赖外部决策服务：模型决策模式需配置 1Panel-laya-server 服务地址与 API Key，且请求内容会外发至该服务，请按业务数据合规要求评估后启用，并务必配置兜底模型组。