Dify 意图分类节点总翻车?从 33% 失败率到兜底不崩——可靠性与韧性的三层加固

1. 业务场景

我们交付过一类很典型的 AI 应用:企业网络设备的故障诊断助手。一线工程师在对话框里输入自然语言问题,比如「端口 down 了怎么排查」「OSPF 邻居卡在 ExStart」「怎么配置 VLAN 10」——应用需要先判断这个问题属于哪一类(故障诊断 / 配置查询 / 其他),再路由到对应的处理链路:故障类去检索排障手册,配置类去检索配置指导,闲聊类直接引导。

这个「先判断类型、再分派任务」的环节,就是意图分类。

Dify 里有一个原生节点叫意图分类(question-classifier),用大模型判断用户问题属于预定义的哪一类,输出一个 JSON,然后按分类结果走不同的分支。整个应用的路由正确性,全押在这个节点上。

2. 场景痛点

意图分类节点有两个层次的失效方式,后果完全不同:

第一层:分错类。 故障问题被分到配置分支,检索出来的全是配置命令,答非所问。工程师看了一眼,觉得这助手「不太行」。

第二层:节点直接报错。 这比分错类更糟——不是答得不好,而是整个对话直接中断,用户看到一段报错堆栈。

我们遇到的就是第二层。分享页(对外开放的对话界面)上,用户提问后,回答区域出现:

状态:FAIL

错误:could not find json block in the output.

意图分类节点执行失败,整个工作流中断。客户 demo 的时候当着客户的面报错,体验是灾难级的。

更麻烦的是:这个问题概率性出现——同一句话,有时正常,有时报错。你测试的时候可能连续试十次都是好的,偏偏客户演示那一次就翻了车。

3. 方案:三层加固,可靠性与韧性分开治

排查后发现,报错根因是:大模型(deepseek-v4-flash)偶尔不按指令输出 JSON。指令里明明写了「严格只输出一个 JSON 对象」,模型有时就是会输出一段带解释的文字,解析器找不到 JSON 块,直接报错。

关键认知:这是 LLM 的概率性漂移,不是配置错误,也不是提示词写得不够好。 我们当时的指令已经写得很硬(判定标准 + 示例 + 输出格式约束),但模型仍然偶发不听话。实测数据:

• 同一问法通过 API 连续调用 23 次,0 次失败

• 分享页真实使用中,最近 6 次分类执行 2 次失败——失败率 33%

同一个问题,API 怎么调都不出错,分享页却经常失败。这说明失败和问题内容无关,是纯概率事件——你永远无法预测哪一次会撞上。

既然概率无法根除,思路就要转换:可靠性靠压制,韧性靠兜底。

• 可靠性(降低出错概率):把指令写死、把采样参数调稳,让模型尽量每次都输出合法 JSON

• 韧性(出错后系统仍然可用):配置自动重试,一次失败自动重来

• 兜底(重试也失败时,用户体验依然体面):接一条失败分支,分类失败时走友好引导文案,而不是把报错堆栈甩给用户

这三层缺一不可——我们最初只做了前两层,以为「配过了」,结果漏了第三层,分享页照样裸奔报错。下面逐层说。

4. 整体架构:意图分类在流程中的位置

实线是正常路由:三类问题各走各的链路。虚线是失败兜底路由:分类节点报错时,不中断工作流,而是走 fail-branch 出边,接到引导节点,用户看到的是「请换个说法描述您的问题」,而不是一段报错。

5. 关键配置

5.1 第一层:指令硬约束(可靠性)

意图分类节点的指令(instruction)要写全三件套:判定标准 + 完整示例 + 输出格式硬约束。注意示例必须给完整形态,不能给占位符——模型照着完整示例输出,比照着「类似这样」的描述输出稳定得多。

判断用户问题的类型并输出 JSON。

判定标准:

- problem(问题询问):设备故障现象、告警信息、异常状态

- config(配置查询):如何配置、参数设置、部署步骤

- other(其他):与网络设备无关、闲聊、无法判断

判定规则:

1. 以问题的核心诉求为准

2. 不确定 → other

示例:

「端口 down 了怎么排查」→ problem

「怎么配置 VLAN 10」→ config

「你是谁」→ other

严格只输出一个 JSON 对象,不要输出 JSON 以外的任何文字:

{"category_id": "cls_problem", "category_name": "problem"}

或 {"category_id": "cls_config", "category_name": "config"}

或 {"category_id": "cls_other", "category_name": "other"}

禁止输出解释、标点、markdown 代码块或任何非 JSON 内容。

5.2 第二层:自动重试(韧性)

给分类节点配置重试,一次失败自动重新调用模型。Dify 1.16 节点级配置:

retry_config:

  retry_enabled: true

  max_retries: 2

  retry_interval: 1000

重试有没有生效,有个简单的判断方法:看失败时的耗时。单次分类调用约 1.9 秒;如果一次失败运行耗时 5-6 秒,大约是正常的 3 倍,说明重试触发了、但 2 次重试也全部失败。这时候要知道:重试救不了概率——模型连续三次都不输出 JSON,重试只是把「必现」变成「概率更小」,不是根除。

5.3 第三层:失败分支(兜底)

给分类节点设置失败策略,指向一条兜底边:

# 节点配置

error_strategy: fail-branch

# 出边

sourceHandle: fail-branch  # 指向已有引导节点

三层配置放在一起对照:

6. 运行验证

修复前,最近 6 次分类执行 2 次失败(33%),失败时整个对话中断、用户看到报错堆栈。

三层加固后:

• 正常分类不受影响:故障类、配置类问题都能正确路由,回答正常

• 反复实测触发概率类问题时,即使模型再次不输出 JSON,重试耗尽后走 fail-branch 兜底,用户看到的是引导文案,工作流不再中断

• 兜底文案沿用「其他」分类的引导语:「请描述设备故障现象(如端口 down、告警内容),或说明要配置的功能(如 VLAN、OSPF、SSH),我会给出诊断或配置步骤」——对分类失败场景也说得通,不用单独造一套文案

一句话总结效果:从「偶尔整个对话崩掉」变成「偶尔回答不如预期,但对话永远不崩」。 后者才是可对外交付的状态。

7. 实战坑表

8. 总结与适用边界

核心结论:意图分类节点的可靠性靠压制概率,韧性靠重试与兜底——三层缺一不可。 分错类可以接受(它只是答得不好),但节点报错中断对话不可接受(它是当着客户面翻车)。

适用场景:

• 意图分类节点(qestion-classifier)路由关键业务链路时,三层加固是标配

• 对外展示的 demo 应用,兜底层必须有——客户演示时最怕的永远是「当场报错」

不适用/需注意:

• fail-branch 是 graphon 内置节点(意图分类等)的能力,插件化节点(如知识库检索)不支持失败分支——检索类节点的失败只能靠重试

• 三层加固降低的是「对话中断」的概率,不是「分错类」的概率;分错类要靠指令质量和分类标准设计,那是另一个话题

本文基于真实项目交付经验撰写(Dify 1.16.x 环境)。文中数据均来自我们自己的实测记录(失败率统计、耗时对比、修复前后行为对比),不构成任何平台的官方结论。