【Dify自动化实战】定义工作流输入变量与必填校验

定义工作流输入变量与必填校验课程归属Dify 自动化实战第 5 节定义工作流输入变量与必填校验“资料报告助手”已经明确了核心输入用户上传资料并填写本次报告主题。真正开始搭建后问题通常不是模型能不能总结而是入口能否拒绝明显不完整的请求没有上传文件、主题为空、文件数量超出限制或上传了当前流程处理不了的格式。本文将以 Dify Workflow 的 User Input 节点为中心固定files与report_topic两个变量配置类型、必填规则和文件限制并用一组边界用例验证输入表单。完成后后续节点将能沿用稳定的变量契约。一、先明确输入变量契约本项目统一使用 Dify 的 Workflow 类型。User Input节点定义工作流启动时需要从用户处收集的信息每个自定义字段都会成为后续节点可引用的变量。官方文档还特别建议在 Workflow 中接收上传文件时使用自定义的文件输入字段而不是继续依赖旧的预设变量userinput.files。Dify 官方 User Input 文档本篇只负责定义入口和必填约束不重新实现摘要逻辑。两个公共输入名固定如下变量名类型必填作用filesFile List多文件是用户本次上传的资料文件对象列表不是本地路径字符串数组report_topicShort TextString是描述本次报告要回答的问题或归纳方向变量名属于工作流契约不只是界面显示文字。标签可以写成易懂的中文但变量名要保持为files和report_topic以便后续 Doc Extractor、LLM、条件分支和发布后的 API 调用沿用同一含义。1.1 输入数据从哪里流向哪里图 1输入变量在工作流中的流向用户填写表单User Input 节点files多文件对象列表report_topic主题字符串文件筛选与文档提取LLM 摘要任务summary 报告摘要图中要注意上传文件与提取出的正文不是同一种数据。files只表示上传对象及其元信息Dify 不会因为用户上传了 PDF就自动把 PDF 正文变成字符串。文件需要在后续节点中通过 List Operator、Doc Extractor 等节点按格式处理。官方 User Input 文档明确将“收集文件”和“处理文件内容”区分开来。Dify User InputFile Input 与 File Processing二、在 User Input 中配置files进入Studio → 资料报告助手 → Workflow 画布选中画布入口处的User Input节点。在节点配置侧栏新增一个自定义字段。Dify 的界面文字可能随版本或语言包稍有不同应按字段含义匹配设置平台版本基线以官方 Releases 页面截至 2026 年 10 月 15 日列出的正式稳定版v1.17.1为准。Dify Releases2.1 文件列表字段设置配置项推荐值原因Field Type / 字段类型File List一次接收多份文件符合课程固定输入类型Variable Name / 变量名files后续节点统一引用此变量名Label Name / 显示标签上传资料文件面向用户展示含义清楚Required / 必填Yes阻止用户在不上传文件的情况下正常提交表单Support File Types / 支持类型Document本篇主线处理文档不把图片误当成已支持输入Upload File Types / 上传方式选择当前实例支持的上传方式教学测试建议本地上传以运行表单中实际可用的方式为准Max Number of Uploads / 最大上传数5为小规模教学任务设定明确上限避免一次提交过多文件设置最大上传数量为 5 是本项目的教学约定不代表 Dify 的系统固定上限。官方快速入门示例中的 File List 也能配置支持类型、上传方式、最大上传数量与 Required 属性应以你当前界面实际提供的字段为准。Dify Quick Start确认字段保存后检查变量选择器中是否出现User Input / files。不要改成file_path也不要在这个字段中输入dify_lab/data/input/作为路径。该目录是课程的本地资料管理约定而 User Input 要收集的是用户在表单里上传的文件。三、配置report_topic并设置必填再新增一个文本输入字段配置如下配置项推荐值原因Field Type / 字段类型Short Text本次主题通常是一句话此类型输出字符串Variable Name / 变量名report_topic与课程公共字段一致后续节点不得静默改名Label Name / 显示标签本次报告主题用户能理解自己要填写什么Required / 必填Yes阻止空值直接通过表单必填检查Max Length / 最大长度256把主题限制在简短说明范围内Placeholder / 占位提示例如总结新员工流程并突出安全注意事项提供具体的填写示例Default Value / 默认值留空不默认替用户决定报告主题Dify 官方文档将Short Text定义为适合单行短文本的输入类型最多 256 个字符Paragraph更适合较长的多行文本。如果本节的主题字段改用Paragraph它仍然可以表示字符串但用户更容易输入较长的说明。本文选择Short Text因为只要求填写摘要主题而不是一整段任务背景。Dify User Input 文档Text Input3.1 必填校验能保证什么Required Yes的目标是让表单把字段作为必需项处理。对于files没有上传文件时应当无法按正常流程提交对于report_topic主题空着不填时应当被表单提示。必填校验是第一道输入门槛但它不能替代所有业务规则例如用户输入三个空格是否会被视为有效字符串、文件内容是否真的可解析都需要用测试用例确认不能仅凭勾选了 Required 就推断系统已经验证了这些语义。图 2输入提交前的基础检查否是否是准备提交已上传 files提示上传资料report_topic 是否填写提示填写主题进入工作流处理图 2 描述的是本篇要求实现的基础行为。它不表示Required会自动检查主题有没有实质内容也不代表已检查文件正文是否为空。语义层检查例如去掉首尾空格后仍为空、文件提取后没有正文需要单独的流程判断或代码校验后续课程会专门展开。四、为什么要同时约束类型、必填和数量只设置“必填”还不够。文件列表如果同时接收文档和图片后续的文档提取器可能遇到不支持的输入如果不限制文件数量测试时难以判断结果遗漏究竟来自哪个文件。report_topic如果不限制长度也可能被当成大段背景材料导致输入责任不清楚。表 3三类输入约束各自解决的问题约束主要解决的问题不能代替什么类型约束避免把非预期类型交给后续节点不代表文件内容一定可读必填约束避免缺失主要输入仍直接提交不等于去空白、语义完整性验证数量/长度限制控制一次提交的规模与输入边界不保证摘要准确也不保证模型上下文一定够用配置完成后工作流后续节点应该按同一变量契约连接files供 List Operator 和 Doc Extractor 使用report_topic供 LLM 节点决定摘要重点。若后面节点还在引用旧变量名必须通过变量选择器重新绑定而不是新建一个意思相同但名字不同的变量来绕过问题。五、测试输入表单正常用例和边界用例在画布右上角打开 Test Run / 测试运行查看 User Input 表单。先执行正常用例再执行负向测试。测试目标是观察表单能否拦截明显缺失的输入并确认正确提交后变量是否按预期传入运行记录。此处只给出预期判据当前没有连接到你的 Dify 实例不能声称这些用例已经实测通过。用例操作预期判据失败后先检查正常输入上传 1 个支持的文档并填写主题可提交运行输入中能看到files与report_topic字段类型和变量名缺少文件不上传文件只填写主题表单要求补充文件或运行不能进入有效处理流程files的 Required 是否为 Yes缺少主题上传文件主题留空表单要求填写主题report_topic的 Required 是否为 Yes主题只有空格填入几个空格后提交记录实例的实际行为不能默认认为系统会自动 trim若通过后续加语义校验不把它当成合格主题超出文件数量尝试上传 6 个文件表单应根据设置阻止超过 5 个或提示达到上限Max Number of Uploads 是否生效不支持的文件尝试上传不在允许范围内的类型上传控件拒绝该类型或后续必须明确报错支持类型配置与文件处理节点边界5.1 主题只包含空白字符时怎么办这是一个值得专门检查的边界条件。普通必填校验与“文本去首尾空白后仍有意义”不是同一件事。假如运行表单允许三个空格通过说明需要进一步增加语义校验而不是把字段设置错误地归咎于 LLM。按照课程目录第 9 节会使用 Code 节点检查缺失与异常字段本节先记录这个边界不提前引入该节的代码实现。同样地文件上传成功只证明平台接收了文件对象。它不证明文件可提取文本、更不证明扫描 PDF 已经经过 OCR。后续 Doc Extractor 若返回空文本应把问题归到文件内容处理阶段而不是认为files的必填校验失效。六、把字段正确传给后续节点输入字段配置完成后进入摘要流程逐项核对变量引用。具体画布节点可能因本地版本略有不同但字段含义必须一致List Operator 的输入变量选User Input / files筛选出本流程能处理的文档。Doc Extractor 接收筛选后的文档列表输出可供模型使用的正文文本。LLM 节点同时引用User Input / report_topic和 Doc Extractor 的实际文本输出。Output 节点把 LLM 的文本输出返回为summary。图 3从校验后的输入到摘要输出report_topicUser Inputfiles 与 report_topicList Operator过滤文件Doc Extractor提取正文LLM按主题摘要Outputsummary图 3 把输入校验与后续处理接起来。report_topic决定总结的关注方向文档提取结果提供内容依据如果某个节点引用了错误变量即便表单本身配置正确最终摘要仍可能为空或偏题。请通过变量选择器绑定已存在的节点输出避免手动拼写路径。七、排错顺序和验收记录如果必填表单没有按照预期工作按由外到内的顺序排查先看 User Input 节点中两个字段的 Required 属性再检查字段类型和最大值设置然后在 Test Run 里重现失败输入最后检查后续节点是否引用了正确变量。不要先去修改模型提示词因为输入在进入 LLM 之前就可能已经不符合要求。现象可能原因修复动作没有文件仍能提交files不是必填或上传控件配置与预期不符确认 File List 和 Required 设置再做一次 Test Run空主题仍能提交Required 未启用或输入只有空白但被表单接受检查必填设置空白语义校验留待 Code 节点章节实现下游看不到files使用了旧预设变量或引用了错误字段使用自定义 File List 字段并重新选择User Input/files文档提取为空上传文件无法提取文本或类型不支持确认实际文件类型检查 Doc Extractor 运行日志LLM 没有按主题处理提示词引用错变量或没引用report_topic从变量选择器重新绑定主题变量本节验收完成的标志是两个变量的名称和类型固定、必要字段配置为必填、文件数量及类型有清楚的约束并且正常输入与缺失输入测试都留下实际观察结果。发布前还要检查一次表单预览。如果以后通过 API 调用工作流不能只依赖浏览器表单的交互验证调用端同样应按files和report_topic的输入契约构造请求并在第 29 节的发布/API 实战中完成独立验证。参考资料Dify 官方文档User Input 节点Dify 官方文档30-Minute Quick StartDify 官方 ReleasesDify 官方文档Key Concepts