企业官网建设流程全解析

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

导读

本文基于 semantic-router 开源仓库中的 User Feedback 信号文档，系统讲解这一学习型信号族如何从多轮对话中识别用户的纠正、不满与升级反馈，并将其暴露为路由决策可消费的信号。读完本文，你将掌握user_feedbacks的声明方式、feedback_detector模型的配置与初始化约束、NO_FEEDBACK标签与置信度阈值带来的"弃权（abstention）"语义，以及如何与决策的on_unknown策略、模型升级路由和插件联动，构建"首轮便宜、纠错升级、安全兜底"的多轮路由方案。

一、信号概览：从"一句不满"到"一次路由决策"

user-feedback是 semantic-router 中的一类学习型信号（learned signal）：它不像关键字信号那样靠词表匹配，而是依赖一个独立的 ML 分类模型——反馈检测器（feedback detector），对多轮对话中**用户的后续消息（follow-up message）**做分类，检测其中是否包含纠正（correction）、不满（dissatisfaction）或升级（escalation）意图。

该信号族在配置中映射到config/fragments/signal/user-feedback/源片段族，并在routing.signals.user_feedbacks中声明；其底层模型在global.model_catalog.modules.feedback_detector中配置。

学习型属性的核心含义：路由器不预先假设"哪种说法算反馈"，而是由检测模型逐轮判断用户消息属于哪个反馈标签。这使它天然适合表达模糊、多样、非规范化的真实用户语言（例如"你答错了""这不对""再解释清楚一点""重新来"）。

二、主要优势：让路由对用户状态"有感知"

从 user-feedback.md 文档和仓库配置可以归纳出该信号族的四个核心价值：

• 路由器可对错误或不清的答案作出反应：用户表示"答案错误"或"没讲清楚"时，后续轮次不再盲目复用首轮路由。
• 升级行为在路由决策内可见：不满与升级不再隐式发生在路由之外，而是成为可审计、可配置的路由条件。
• 帮助后续轮次切换到更强模型或更安全插件：例如在 feedback 配方 中，wrong_answer信号会触发feedback_verified_recovery（高推理强度的 openai/gpt5.4 车道）或feedback_code_recovery（gemini 修复车道）。
• 同一反馈检测器可跨多条路由复用：检测模型只做一次推理，其结果可以被多条决策规则同时消费，避免为每条路由重复部署模型。

三、解决什么问题：后续轮次 ≠ 首轮路由

多轮对话中最典型的路由陷阱是：首轮路由的模型选择未必适合后续轮次。用户在第一轮得到一个便宜模型的答案，接着表示"这是错的"或"请给证据"；如果路由器无视这条反馈，就会继续把后续消息送入同一条弱路径，形成"失败-重试-再失败"的循环。

user-feedback的价值在于把"用户不满/纠正"这类对话状态信号直接暴露在路由图中：当反馈信号命中时，决策引擎可以按规则把后续轮次切换到更强模型、更安全插件或专门的修复车道，从而打破弱路径的重复。

四、何时使用

在以下场景应启用user-feedback信号：

• 后续纠正应升级到更强模型：用户明确说答案有误，后续轮次应进入修复/验证车道；
• 负面反馈应触发更详尽或更安全的处理：例如对涉及健康、法律等敏感领域的不满，切换到高推理强度模型或加装安全插件；
• 路由器对"答案错误"与"需要澄清"应不同反应：wrong_answer应升级，need_clarification可能只需留在便宜车道重新表述（见 feedback 配方 中的feedback_need_clarification决策，它显式把澄清类后续消息留在qwen/qwen3.5-rocm便宜车道）；
• 对话状态比原始领域更重要：当用户已经表达不满，用户意图比首轮话题领域更能决定该走哪条路由。

五、配置：声明反馈标签与检测模型

5.1 信号声明

user_feedbacks信号在routing.signals下声明，源片段族位于 config/fragments/signal/user-feedback/。文档给出的最小配置如下，该片段与 escalation.yaml 完全一致：

routing: signals: user_feedbacks: - name: wrong_answer description: User indicates the current answer is incorrect. - name: need_clarification description: User asks for a clearer or more detailed follow-up.

name是路由规则中消费的标签（signal name），description帮助人理解该标签的语义。检测模型负责决定每一轮用户消息匹配哪一条标签——这正是"学习型"与"关键字型"信号的差别：关键字信号由配置中的词表决定匹配，而学习信号由模型输出决定匹配。

值得注意的是，上述两个标签（wrong_answer、need_clarification）是四分类模型的完整标签集合。从 feedback_detector.go 的默认标签常量可以看出，四分类模型输出satisfied、need_clarification、wrong_answer、want_different四类，只有后三类是"反馈"，而satisfied用于表示普通后续轮次无反馈。若检测模型包含no_feedback标签（即 Vela 系五分类模型），则"无反馈"被显式建模（详见第八节）。

5.2 检测模型配置

反馈检测器在global.model_catalog.modules.feedback_detector中配置，参考 config/config.yaml：

global: model_catalog: modules: feedback_detector: enabled: true model_ref: feedback_detector max_sequence_length: 0 use_cpu: true feedback_mapping_path: ''

各参数含义如下：

标签映射文件支持idx_to_label/label_to_idx或id2label/label2id两种字段形态（见feedbackMappingFile结构体），加载后会对齐模型配置做校验（ValidateLabelMappingAgainstModelConfig），并通过normalizeFeedbackLabel把诸如SAT、NEED_CLARIFICATION、WRONG_ANSWER等模型原生标签统一为satisfied、need_clarification、wrong_answer、want_different、no_feedback的标准形态。

5.3 初始化失败语义：信号依赖 vs 独立诊断 API

文档明确指出两类模型的初始化约束差异：

• 被可达路由决策依赖的模型必须成功初始化，否则 Router 启动失败——因为若检测器不可用，所有依赖该信号的决策都无法可靠评估；
• 仅被独立诊断 API 使用的模型（例如单独调用分类接口排查问题的场景）允许初始化失败，不会因此阻止无关路由启动。

这一约束与"信号是学习型、路由决策依赖其输出"的定位一致，也与配置校验器中的提示相呼应：当条件依赖的模型后端失败时，条件会被评估为 unknown，并需要rules.on_unknown或条件的on_error策略兜底（见 validator_decision_unknown.go）。

六、检测器工作原理：从文本到反馈标签

反馈检测的核心实现在 feedback_detector.go：

1. 初始化：Initialize()要求ModelID非空；随后根据FeedbackMappingPath选择从映射文件或从服务模型读取标签分布（useServedLabels），建立label_to_idx/idx_to_label双向映射，最后初始化推理后端。
2. 分类：Classify(ctx, text)对用户后续消息文本做一次序列分类推理，从概率分布中取 argmax 得到类别与置信度（deriveArgmax），并经过 admission 门控（admitModelInference，对应部署准入控制）。
3. 阈值决策：resultForPrediction依据配置阈值（默认 0.5，见Classify中if threshold <= 0 { threshold = 0.5 }）决定最终反馈标签与Abstained标志（详见第八节）。
4. 空输入保护：对空白文本直接返回错误feedback classification requires non-empty input，不会产生虚假反馈。

从调用链看，该信号在分类流水线中的评估还受一个前置门控约束：shouldEvaluateUserFeedbackSignal(hasPriorAssistantReply bool)要求本轮回合之前已存在助手回复才评估用户反馈信号（见 feedback_signal_gate.go 及 feedback_signal_gate_test.go 的测试断言）。这符合直觉：用户反馈只能发生在助手已经给出过回答之后，首条用户消息不存在"反馈"语义。

七、在路由决策中消费反馈信号

user_feedbacks信号与关键字、reask、projection、domain 等信号一样，可作为决策规则的type: user_feedback条件。以 feedback 配方 为例，可以直观看到反馈信号如何参与多级升级策略：

routing: decisions: - name: feedback_verified_recovery priority: 240 rules: operator: AND conditions: - operator: OR conditions: - type: projection name: feedback_verified_escalate - type: reask name: persistently_dissatisfied - type: user_feedback name: wrong_answer - type: keyword name: frustration_feedback_markers - operator: OR conditions: - type: projection name: feedback_needs_evidence - type: keyword name: verification_markers - operator: NOT conditions: - operator: OR conditions: - type: keyword name: code_error_markers - type: domain name: computer science modelRefs: - model: openai/gpt5.4 use_reasoning: true reasoning_effort: high

这段配置展示了几种典型用法：

• type: user_feedback+name: wrong_answer：显式不满直接触发高优先级（priority: 240）决策；
• 反馈信号与projection（加权评分映射）、reask（重复提问）信号正交组合：多种不满证据叠加提高升级确定性；
• modelRefs指定升级到高推理强度模型（openai/gpt5.4，reasoning_effort: high）；
• plugins通过header_mutation写入X-Feedback-Lane: verified-recovery等响应头，把"当前处于反馈恢复车道"这一事实暴露给下游观测与审计。

同配方中feedback_need_clarification（priority: 180）则演示差异化反应：need_clarification命中时只要上下文较短且没有更强的升级信号（如persistently_dissatisfied、wrong_answer、验证类关键字），就留在便宜车道qwen/qwen3.5-rocm并开启响应缓存——"需要澄清"不等于"答案错误"。

配方的user_feedbacks声明与文档一致：

signals: user_feedbacks: - name: wrong_answer description: Explicit correction or dissatisfaction. - name: need_clarification description: Explicit request to restate the answer more clearly.

八、NO_FEEDBACK 标签与置信度阈值：弃权（abstention）语义

这是该文档在 v0.3 版本中最关键的语义升级：含NO_FEEDBACK标签的模型可以识别"普通后续任务"。

8.1 五分类模型：显式的无反馈类别

Vela 系检测模型在四分类之外增加no_feedback类别（默认标签常量FeedbackLabelNoFeedback，见 feedback_detector.go），把"这不是反馈"从"闭集假设的剩余项"中显式剥离。其行为契约（见 feedback_abstention_test.go 的TestVelaFeedbackKeepsNegativeAndUncertainPredictionsDistinct）：

• NO_FEEDBACK结果不会匹配任何四条反馈规则——普通后续任务不会误触发升级路由；
• 低于配置threshold的预测表示"不确定"，此时遵循决策的on_unknown策略，而不是被当成satisfied；
• 独立分类 API 保留预测标签和概率，并返回abstained: true——不确定性被显式暴露，而不是被吞掉。

对应实现中，resultForPrediction一旦检测到标签集合包含FeedbackLabelNoFeedback，就直接返回原始标签、原始置信度与Abstained: confidence < threshold（见 feedback_detector.go），并保留ConfidenceAvailable: true；分类 API 响应结构体也保留abstained字段（见 classification_handlers_misc.go）。

8.2 四分类模型：保留低置信度回退satisfied

原有四分类模型继续保留其低置信度回退到satisfied的行为。applyThreshold（见 feedback_detector.go）在预测置信度低于阈值时：

1. 尝试从映射中找到satisfied类别索引，返回FeedbackLabelSatisfied及其真实概率（即P(satisfied)）；
2. 若映射中没有satisfied类，或模型没有输出其概率，则保留模型自身的原始预测——因为"一个没有任何支持证据的 satisfied 结论"正是该实现要修复的缺陷。

这与文档中"原有四分类模型继续保留其低置信度回退到satisfied的行为"完全对应：四分类模型仍沿用闭集假设——"不是反馈"只能落在剩余类别里，低置信度按惯例回退为满意；而五分类模型则打破了该闭集假设，把"不确定"与"无反馈"分开处理。

8.3 不确定性与on_unknown策略

对于含NO_FEEDBACK标签的模型，低于阈值的预测会进入决策引擎的 unknown 分支。测试TestFeedbackAbstentionRespectsDecisionUnknownPolicy验证了：仅当abstained == true且决策规则设置on_unknown: rule_on_unknown_match时，unknown 条件才可能匹配；否则不匹配。也就是说，弃权结果不会静默地命中"无反馈"或"满意"规则，而是交给决策的on_unknown策略显式决定走向（匹配、不匹配或报错）。配置校验器也提示：当条件依赖的模型后端失败时条件评估为 unknown，需显式配置rules.on_unknown或条件的on_error（见 validator_decision_unknown.go）。

九、与 reask / projection 信号的协同：完整的反馈恢复链路

学习型user_feedback信号通常与启发式信号配合，构成"显式 + 隐式"的完整不满检测链。feedback 配方 展示了这一协同模式：

• user_feedbacks（学习型）：模型显式识别"答案错误""需要澄清"；
• reasks（启发式）：likely_dissatisfied（用户紧贴重复上一轮）与persistently_dissatisfied（连续重复两轮）捕捉隐式不满；
• keywords（启发式）：frustration_feedback_markers（wrong / 不对 / 重新来）、code_error_markers（traceback / exception）、clarification_feedback_markers（clarify / 讲清楚一点）等词表捕捉浅层信号；
• projections：将user_feedback、reask、keyword、domain、context等信号按权重加权，映射出feedback_recovery_pressure（0.24 以下 retry、0.55 以下 escalate、0.85 以上 verified escalate）与verification_pressure（0.45 以上触发 evidence 需求），从而把多路信号压缩成可路由的连续压力值。

最终，这些信号在决策层组合成一条完整恢复链路：普通澄清 → 便宜车道重述；显式/隐式不满 → 修复车道（gemini）→ 反复不满 + 证据敏感 → 高推理验证车道（gpt5.4），并以priority排序确保升级路径的确定性。

十、最佳实践小结

结合文档、配方与源码，使用user-feedback信号的建议如下：

1. 显式区分"答案错误"与"需要澄清"：wrong_answer应升级到修复/验证车道，need_clarification应留在便宜车道重述，二者路由目标截然不同；
2. 优先选用含NO_FEEDBACK标签的检测模型：它把"无反馈"与"低置信度不确定"分开，配合on_unknown策略避免低质量"满意"结论污染路由；
3. 为依赖该信号的决策配置on_unknown：检测模型初始化失败或预测不确定时，决策行为是显式可预期的；
4. 与 reask、keyword、projection 信号组合：学习信号捕捉语义，启发式信号捕捉浅层/重复模式，投影把多信号压缩为连续压力值，形成强健的不满检测与升级体系；
5. 检查初始化约束：确保被路由依赖的feedback_detector模型能成功初始化；仅用于独立诊断 API 的模型可以容忍初始化失败而不阻塞其他路由。

相关仓库资源

• 信号文档原文：user-feedback.md
• 信号源片段族：config/fragments/signal/user-feedback/，如 escalation.yaml
• 反馈检测器参考配置：config/config.yaml
• 反馈恢复完整配方：config/recipes/feedback/config.yaml
• 检测器核心实现：feedback_detector.go
• 信号评估门控：feedback_signal_gate.go
• 弃权与阈值语义测试：feedback_abstention_test.go
• 决策 unknown 策略校验：validator_decision_unknown.go

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