工作流编排
当任务复杂到"一问一答"无法承载时,用可视化工作流把多个节点串成图,让 AI 按流程协同工作。
SparkX 的工作流编辑器基于 AntV X6 实现,采用左侧节点面板 + 中间画布 + 右侧配置抽屉的经典布局。
1. 什么时候需要工作流
单轮 RAG 问答(用户问 → 检索 → 回答)能解决 80% 的问题,但下面这些场景它搞不定:
| 场景 | 为什么需要工作流 |
|---|---|
| 按意图分流 | 售前咨询走 A 智能体、售后走 B 智能体 |
| 多步推理 | 先查知识库 → 再调外部接口补数据 → 最后综合回答 |
| 条件处理 | VIP 用户走人工、普通用户走自助 |
| 多模型协作 | 翻译用 A 模型、总结用 B 模型、合并输出 |
| 知识图谱 + 向量混合 | 同一个问题,同时走图谱检索和向量检索,结果融合 |
💡 一句话:单轮问答用智能体,多步骤/带分支/多协作用工作流。
2. 编辑器界面
进入「编排」菜单,新建或编辑一个工作流,进入全屏编辑器:
编辑器分三个区域:
| 区域 | 作用 |
|---|---|
| 顶部菜单 | 调试、保存、返回 |
| 中间画布 | 节点编排区,可拖拽、缩放、连线 |
| 底部工具栏 | 展开节点面板、居中视图、放大/缩小 |
| 右侧抽屉 | 点击节点后弹出,配置该节点的参数 |
基本操作
- 添加节点:点底部工具栏的
+展开节点面板,点击节点或拖拽到画布 - 连接节点:鼠标悬停节点显示连接点(小圆点),从一个节点的输出点拖到下一个节点的输入点
- 配置节点:单击节点,右侧弹出配置抽屉
- 删除节点:在配置抽屉点「删除节点」(开始节点不可删)
- 删除连线:鼠标悬停连线,出现删除按钮
- 移动画布:空白处拖拽平移;滚轮或底部按钮缩放
3. 节点总览
工作流由节点(Node)和连线(Edge)组成。SparkX 提供 1 个起始节点 + 7 个功能节点,共 8 种:
| 节点 | 图标颜色 | 作用 | 端口 | 是否有内容输出 |
|---|---|---|---|---|
| 开始 | — | 流程起点,提供系统变量 | 单输出 | ✅ |
| 意图分类 | 🟠 橙 | 用模型把问题分到 N 个类别,按类别走不同分支 | 一进多出 | ❌ 仅分流 |
| LLM | 🔵 蓝 | 调用大模型生成内容(工作流的核心) | 一进一出 | ✅ |
| 知识检索 | 🔵 蓝 | 从知识库召回相关文档片段 | 一进一出 | ✅ |
| 知识图谱 | 🟣 紫 | 从知识图谱召回实体/关系 | 一进一出 | ✅ |
| Agent | 🟢 绿 | 调用一个已建好的智能体 | 一进一出 | ✅ |
| 回复 | 🟢 绿 | 把上游变量或自定义文本作为最终回答(流程终点) | 一进一出 | ✅ 给用户 |
| 条件分支 | 🔵 蓝 | 按条件走 IF / ELSEIF / ELSE 分支 | 一进多出 | ❌ 仅分流 |
💡 数据在节点间通过变量传递:每个节点有「输入参数」(引用上游输出)和「输出参数」(产出新变量),下游节点用
{{变量名}}引用。⚠️ 意图分类、条件分支只负责分流,不产出内容;回复节点是终点,负责把内容返回给用户。所以这两类分流节点的每条分支,末端都必须接到一个回复节点(中间可夹 LLM/Agent 等),否则用户收不到回答。详见 4.7 回复节点。
4. 各节点详解
4.1 开始节点(Start)
流程的固定起点,不可删除。提供一组系统变量供下游使用。
无需配置,自带 4 个系统输出变量:
| 变量 | 含义 |
|---|---|
sys.question |
用户问题(最常用) |
sys.time |
当前时间 |
sys.ip |
用户 IP |
sys.workflowId |
当前编排 ID |
下游所有节点引用用户问题时,都用 {{sys.question}}。
4.2 意图分类节点(Purpose)
用大模型把用户问题归到预设的几个类别,每个类别对应一条下游分支。
适合"按意图分流"的场景,例如:售前 / 售后 / 投诉 三类走不同处理流程。
配置项
| 配置 | 说明 |
|---|---|
| 查询内容 | 输入参数,通常引用 {{sys.question}}(用户问题) |
| 模型 | 用哪个对话模型做分类(选小快模型即可,如 qwen-turbo) |
| 温度 | 分类任务建议设 0(要稳定,不要创造性) |
| 意图分类 | 预设的类别清单,可增删 |
分支机制(重点)
- 每加一个分类,节点右侧自动多一个输出端口
- 端口从上到下依次对应「分类1、分类2、分类3…」
- 运行时,模型判断属于哪个分类,就只触发对应的那一条分支
⚠️ 每次只触发一条分支。连线时务必按「分支N」顺序对应右侧第 N 个端口,接错会导致流程跑错。
输出变量
| 变量 | 含义 |
|---|---|
sys.purposeName |
命中的分类名(下游可引用) |
4.3 LLM 节点(核心)
调用大模型生成内容,是工作流里最常用的节点。
配置项
| 配置 | 说明 |
|---|---|
| 模型 | 选对话模型 |
| 温度 | 0~2,知识问答建议 0~0.3 |
| 上下文轮数 | 携带多少轮历史对话(0~10) |
| 角色设置(System) | 系统提示词,定义模型人设和约束 |
| 用户提示词 | 用户侧指令,可用 {{变量}} 引用上游输出 |
召回重排(关键设计)
SparkX 把重排统一放在 LLM 节点做,而不是放在检索节点。
| 配置 | 说明 |
|---|---|
| 重排模型 | 选重排模型对召回结果精排;留空 = 不重排 |
| 重排数量 | 重排后保留几条(topRank,1~10) |
为什么这样设计:一个 LLM 节点可能融合多个检索节点(向量 + 图谱)的结果,统一在这里重排,避免各检索节点各自重排的重复和不一致。
提示词变量引用(重点)
用户提示词里用 {{变量}} 引用上游节点输出:
请根据以下知识库信息回答用户问题。
知识库信息:
{{sys.result}} ← 引用知识检索节点的输出
用户问题:
{{sys.question}} ← 引用开始节点的用户问题
⚠️ 配了用户提示词后,必须显式引用召回变量(如
{{sys.result}}),否则检索内容进不了 prompt。
默认提示词
新建 LLM 节点会预填一套知识库问答提示词(systemMsg 约束"只依据知识库、不得编造";userPrompt 引用 {{sys.result}} + {{sys.question}}),开箱即用,可按需修改。
输出变量
| 变量 | 含义 |
|---|---|
sys.content |
模型生成的内容 |
4.4 知识检索节点(Dataset)
从知识库召回相关文档片段,本身不生成回答,结果交给下游 LLM 处理。
配置项
| 配置 | 说明 |
|---|---|
| 查询内容 | 输入参数,通常引用 {{sys.question}} |
| 知识库 | 多选要检索的库 |
| 限定文档 | 每个库可单独限定具体文档(留空 = 检索整库) |
| 相似度 | 向量相似度阈值(0~1,默认 0.2) |
| 召回数量 | 向量召回的候选数(topRank,1~10,默认 3) |
关于"限定文档"
选了知识库后,每个库下面会单独出现一个文档选择框,可以精确到某几篇文档检索。不选则检索该库全部文档。
💡 检索节点只负责召回,不重排——重排统一交给下游的 LLM 节点。
输出变量
| 变量 | 含义 |
|---|---|
sys.result |
检索到的文档片段(拼接后) |
4.5 知识图谱节点(Graph)
从知识图谱召回实体和关系,擅长回答"A 和 B 有什么关系""列出所有 X"这类问题。
配置项
| 配置 | 说明 |
|---|---|
| 查询内容 | 输入参数,引用用户问题 |
| 知识库 | 绑定一个知识库 |
| 限定文档 | 可选具体文档 |
| 召回数量 | 召回的图谱片段数(默认 5) |
输出变量
| 变量 | 含义 |
|---|---|
sys.result |
图谱检索结果(实体 + 关系) |
💡 知识图谱节点和知识检索节点可以并行,两个的
sys.result都喂给同一个 LLM 节点,实现"向量 + 图谱"混合检索。
4.6 Agent 节点
在工作流中调用一个已经建好的智能体(连带它的知识库、提示词、检索配置等)。
配置项
| 配置 | 说明 |
|---|---|
| 查询内容 | 输入参数,引用用户问题 |
| 智能体 | 选择一个已创建的智能体(agentId) |
输出变量
| 变量 | 含义 |
|---|---|
sys.agentContent |
该智能体的回答内容 |
💡 Agent 节点 = 把一个完整的智能体当成"黑盒工具"嵌进工作流。适合复用已有智能体,而不是在工作流里重写一遍配置。
4.7 回复节点(Answer)
把内容作为最终回答返回给用户,是工作流的"终点"。每条流程分支最终都必须接到回复节点。
为什么回复节点必不可少
工作流的运行结果只有通过回复节点才会返回给用户。前面所有节点(LLM 生成的内容、Agent 的回答、检索结果)只是"中间产物",如果不接到回复节点,用户什么都看不到。
这一点在下面两类节点上尤其要注意:
| 节点 | 情况 | 处理方式 |
|---|---|---|
| 意图分类 / 条件分支 | 本身不产出内容,只负责分流 | 它们的每条分支末端必须接回复节点(或接 LLM/Agent 后再接回复) |
| 回复节点本身 | 是流程终点,输出 sys.answer 给用户,不再往下传 |
直接作为分支末端的收尾 |
正确:意图分类 ──► LLM ──► 回复 ──► 用户看到答案
错误:意图分类 ──► LLM ──(没有回复节点)──► 用户什么都收不到
⚠️ 调试时如果"流程跑完了但用户没收到回答",99% 是某条分支末端漏接了回复节点。
两种回复模式
| 模式 | 说明 |
|---|---|
| 引用变量(默认) | 直接把上游某个变量的值作为回答 |
| 自定义 | 填一段固定文本作为回答 |
引用变量的高级用法
引用变量模式下可引用多个上游变量(比如条件分支后的多个 LLM 输出):
- 单变量:直接取该变量值回复
- 多变量:用「回复模板」聚合,
{{1}}、{{2}}指代第 1、第 2 个变量- 例:
结论一:{{1}}\n结论二:{{2}} - 模板留空 = 按顺序拼接
- 例:
输出变量
| 变量 | 含义 |
|---|---|
sys.answer |
回复内容 |
4.8 条件分支节点(Switch)
按条件走不同分支(IF / ELSEIF / ELSE),是最灵活的流程控制节点。
分支结构
IF (条件1) → 走分支1
ELSEIF (条件2) → 走分支2
ELSE → 兜底分支(所有条件都不满足时)
每加一个 ELSEIF,节点右侧自动多一个输出端口;ELSE 是最后一个端口。
条件组成
每个分支可包含多个条件,用 AND / OR 连接:
| 元素 | 说明 |
|---|---|
| 变量 | 要判断的上游变量(从输入参数选) |
| 操作符 | 为空 / 不为空 / 包含 / 等于 / 大于等于 / 长度等于 …(共 12 种) |
| 值 | 操作符 > 2 时需填,如"包含 VIP"里的 VIP |
12 种操作符
| 编号 | 操作符 | 需要填值 |
|---|---|---|
| 1 | 为空 | ❌ |
| 2 | 不为空 | ❌ |
| 3 | 包含 | ✅ |
| 4 | 不包含 | ✅ |
| 5 | 等于 | ✅ |
| 6 | 大于等于 | ✅ |
| 7 | 小于 | ✅ |
| 8 | 长度等于 | ✅ |
| 9 | 长度大于等于 | ✅ |
| 10 | 长度大于 | ✅ |
| 11 | 长度小于等于 | ✅ |
| 12 | 长度小于 | ✅ |
💡 典型用法:先接一个意图分类节点(输出
sys.purposeName),再用条件分支判断sys.purposeName等于哪个值,走对应处理。
5. 变量传递机制
工作流的灵魂是变量在节点间流转。理解这一点,编排就通了:
[开始] ──sys.question──► [知识检索] ──sys.result──► [LLM] ──sys.content──► [回复]
│
sys.answer → 用户
| 规则 | 说明 |
|---|---|
| 每个节点有输入参数 | 引用上游节点的输出变量 |
| 每个节点有输出参数 | 产出新变量供下游使用(意图分类、条件分支除外,它们只分流) |
| 引用语法 | {{变量名}},如 {{sys.question}}、{{sys.result}} |
| 变量来源 | 配置抽屉里的「输入参数」会列出所有可选的上游变量 |
| 必须以回复节点收尾 | 只有回复节点会把内容返回给用户,其他节点的输出只是中间产物 |
⚠️ 注意:
sys.xxx是约定的系统变量命名空间。每个节点的输出字段名可能相同(如多个检索节点都输出sys.result),引用时按节点 + 字段区分。⚠️ 关键规则:每个流程分支的末端必须是回复节点。 意图分类、条件分支这类"只分流不产出"的节点,它们的每条分支后面都要继续接上处理节点(LLM/Agent/检索)并最终接一个回复节点,否则用户收不到任何回答。
6. 连线规则
| 规则 | 说明 |
|---|---|
| 输入端口 ↔ 输出端口 | 只能从输出连到输入,不能反向 |
| 不能自环 | 节点不能连到自己 |
| 一进一出节点 | LLM/检索/Agent/回复:一个输入、一个输出 |
| 多出节点 | 意图分类 / 条件分支:一个输入、多个输出(按分支) |
7. 典型编排示例
示例 1:标准 RAG 流程
开始 ──► 知识检索 ──► LLM ──► 回复
(sys.question) (sys.result) (sys.content)
最经典的"检索增强生成":查知识库 → 让模型基于检索结果回答。
示例 2:按意图分流
┌──► LLM(售后) ──► 回复
开始 ──► 意图分类 ┤
└──► Agent(售前) ──► 回复
意图分类把问题分成"售前/售后",各自走不同处理。
示例 3:向量 + 图谱混合检索
┌──► 知识检索 ──┐
开始 ──► LLM ◄───┤ ├── (sys.result 融合)──► 回复
└──► 知识图谱 ──┘
两个检索节点并行,结果都喂给同一个 LLM,在 LLM 节点统一重排,最后接回复节点返回给用户。
示例 4:条件处理
┌──► Agent(VIP客服) ──► 回复
开始 ──► 意图分类 ──► 条件分支 ┤
└──► 回复(自助引导)
先分意图,再按用户身份(VIP/普通)走不同服务通道。
8. 调试与保存
| 操作 | 入口 | 说明 |
|---|---|---|
| 保存 | 顶部菜单 | 保存当前编排(保存前会校验节点连线是否合法) |
| 调试 | 顶部菜单 | 先保存,再打开右侧"编排调试"对话框,可直接对话测试 |
| 执行详情 | 调试对话框 | 查看每次问答经过哪些节点、各节点输入输出,定位问题 |
💡 调试时重点看「执行详情」:能确认意图是否分对、检索是否召回、各分支是否走对。
9. 注意事项
- ⚠️ 开始节点不可删除,每个流程必须有且只有一个起点
- ⚠️ 每个分支末端必须接回复节点:只有回复节点会把内容返回给用户;意图分类/条件分支只分流不产出,它们后面要么直接接回复,要么接 LLM/Agent 后再接回复。漏接回复节点 = 用户收不到任何回答
- ⚠️ 节点必须连通:孤立的节点(没连进主流程)运行时会被跳过或报错
- ⚠️ 意图分类 / 条件分支的端口顺序很关键,接错分支会导致流程跑偏,调试时务必核对
- ⚠️ 引用变量前先确认上游有输出:比如 LLM 节点要在提示词里用
{{sys.result}},必须上游接了检索节点 - 💡 重排只在 LLM 节点配置,检索节点不需要也不应该单独重排
- 💡 复杂流程建议先调试单个分支,再串联整体
