Dify开发中系统变量(system)和用户变量(user)的区别
理解 Dify 中系统变量(system)和用户变量(user)的区别,对于设计和调试工作流至关重要。简单来说:
系统变量是 Dify 自动生成的,提供了工作流运行时的上下文信息,你通常只能读取它。
用户变量则需要你自定义,用于接收和传递用户输入的原始数据。
为了让你能快速抓住它们的主要不同,我用一个表格来汇总:
特性维度 | 系统变量 (System Variables) | 用户变量 (User Variables) |
---|---|---|
定义与来源 | 由 Dify 平台自动生成 | 由用户输入或开发者定义,是工作流的起点 |
标识符前缀 | 通常以 sys. 开头 | 无固定前缀,由开发者自定义命名(仅限英文、数字、下划线) |
数据内容 | 系统运行时状态信息(如查询内容、对话轮次、会话ID、上传的文件列表等) | 用户输入的原始数据(如文本、数字、上传的文件等) |
作用域与生命周期 | 全局只读,可在大部分节点内全局引用 | 通常在单次请求中有效 |
可操作性 | 只读,无法修改 | 可读可写,可在工作流中传递和处理 |
主要用途 | 为节点提供上下文信息,实现条件判断、记录状态等 | 接收用户输入,作为工作流处理的原始材料 |
常见示例 | sys.query (用户当前查询)sys.dialogue_count (对话轮数)sys.conversation_id (会话ID)sys.files (用户上传的文件列表) | 自定义的变量名,如 user_name , uploaded_file , question_text 等 |
🧭 如何引用变量
无论在系统变量还是用户变量,在 Dify 工作流的节点配置中,都通过 {{变量名}}
的格式来引用。
💡 操作与调试提示
善用“预览”和“运行日志”:在 Dify 工作流编辑器中,充分利用 “预览” 和 “运行日志” 功能。这些功能可以帮你查看每个节点实际输入和输出的变量值,是排查上下文传递问题的重要手段。
变量命名清晰:为用户变量起一个易于理解的名字(如
user_query
,retrieved_knowledge
),这将大大提高工作流的可读性和可维护性。
⚠️ 需要注意的常见问题
变量未定义或拼写错误:确保在引用变量时,变量名的大小写和拼写与定义完全一致,特别是系统变量的
sys.
前缀。作用域理解不清:记住用户变量通常在单次请求中有效,而系统变量是全局的。在设计多轮对话(Chatflow)时,需要会话变量(Session Variables)来在对话期间保持状态。
误解系统变量的可写性:系统变量是只读的。不要尝试在工作流中赋值修改
sys.query
或sys.dialogue_count
等系统变量。
🎯 总结
系统变量和用户变量在 Dify 工作流中扮演着不同但同样重要的角色:
系统变量像是工作流的观察员,告诉你当前发生了什么,提供了运行时的环境和状态信息。
用户变量则是工作流的原材料,提供了需要被处理和加工的原始数据。
理解它们的差异,能帮助你更有效地构建和调试 Dify 工作流。
希望这些信息能帮助你更好地理解 Dify 中的变量系统。