干货分享：Dify中4种核心变量详解！

在 Dify 工作流（Workflow 和 Chatflow）的实现中，“变量”做为最基础、最核心的组件发挥着不可或缺的作用，因为它承载了不同节点间数据传递的作用。

也就是说，我们在实现 Workflow 和 Chatflow 时，需要一种动态数据容器，能够存储和传递不固定的内容，在不同的节点内被相互引用，实现信息在节点间的灵活通信，这个就是“变量”了。

变量作用：用于不同节点的信息传递。

例如以下场景，我们需要将第一个节点用户输入的内容，传递给第二个节点大模型，就需要使用变量进行传递。

1.变量分类

Dify 中总共有以下 4 种变量类型：

用户（输入）变量
系统变量
环境变量
会话变量

分别来看这四种变量类型的详细介绍。

2.用户变量

用户变量是用户在与 Dify 应用交互过程中直接输入的信息，这些信息可以是文本、段落（多行文本）、下拉选项、数字、单文件、文件列表（多文件）等，如下图所示：

例如，在对话框中，用户输入“我想查询明天的天气”，这个输入内容就会作为用户变量，应用可以根据这个变量调用天气查询接口等。

注意：变量名称只能为英文、数字和下划线。

3.系统变量

系统变量是由 Dify 预设的系统级参数，可以被其它节点全局读取，用于记录和管理应用运行过程中的关键信息，以 sys. 前缀开头。

其中 WorkFlow 和 ChatFlow 的系统变量还有所不同。

Workflow

Workflow 类型应用提供以下系统变量：

变量名称	数据类型	说明	备注
sys.files[LEGACY]	Array[File]	文件参数，存储用户初始使用应用时上传的图片	图片上传功能需在应用编排页右上角的 “功能” 处开启
sys.user_id	String	用户 ID，每个用户在使用工作流应用时，系统会自动向用户分配唯一标识符，用以区分不同的对话用户
sys.app_id	String	应用 ID，系统会向每个 Workflow 应用分配一个唯一的标识符，用以区分不同的应用，并通过此参数记录当前应用的基本信息	面向具备开发能力的用户，通过此参数区分并定位不同的 Workflow 应用
sys.workflow_id	String	Workflow ID，用于记录当前 Workflow 应用内所包含的所有节点信息	面向具备开发能力的用户，可以通过此参数追踪并记录 Workflow 内的包含节点信息
sys.workflow_run_id	String	Workflow 应用运行 ID，用于记录 Workflow 应用中的运行情况	面向具备开发能力的用户，可以通过此参数追踪应用的历次运行情况

Chatflow

Chatflow 类型应用提供以下系统变量：

变量名称	数据类型	说明	备注
sys.query	String	用户在对话框中初始输入的内容
sys.files	Array[File]	用户在对话框内上传的图片	图片上传功能需在应用编排页右上角的 “功能” 处开启
sys.dialogue_count	Number	用户在与 Chatflow 类型应用交互时的对话轮数。每轮对话后自动计数增加 1，可以和 if-else 节点搭配出丰富的分支逻辑。例如到第 X 轮对话时，回顾历史对话并给出分析
sys.conversation_id	String	对话框交互会话的唯一标识符，将所有相关的消息分组到同一个对话中，确保 LLM 针对同一个主题和上下文持续对话
sys.user_id	String	分配给每个应用用户的唯一标识符，用以区分不同的对话用户
sys.app_id	String	应用 ID，系统会向每个 Workflow 应用分配一个唯一的标识符，用以区分不同的应用，并通过此参数记录当前应用的基本信息	面向具备开发能力的用户，通过此参数区分并定位不同的 Workflow 应用
sys.workflow_id	String	Workflow ID，用于记录当前 Workflow 应用内所包含的所有节点信息	面向具备开发能力的用户，可以通过此参数追踪并记录 Workflow 内的包含节点信息
sys.workflow_run_id	String	Workflow 应用运行 ID，用于记录 Workflow 应用中的运行情况	面向具备开发能力的用户，可以通过此参数追踪应用的历次运行情况

4.环境变量

环境变量用于保护工作流内所涉及的敏感信息，例如运行工作流时所涉及的 API 密钥、数据库密码等。它们被存储在工作流程中，而不是代码中，以便在不同环境中共享。

环境变量支持以下三种数据类型：

String 字符串
Number 数字
Secret 密钥

其中，Secret 密钥用于定义敏感信息或数据，导出 DSL 时设置了防泄露机制。

环境变量拥有以下特性：

环境变量可在大部分节点内全局引用；
环境变量命名不可重复；
环境变量为只读变量，不可写入。

5.会话变量

会话变量只存在 ChatFlow 场景中，因为它是面向多轮对话场景，而 Workflow 类型应用的交互是线性而独立的，不存在多次对话交互的情况，因此会话变量仅适用于 Chatflow 类型（聊天助手 → 工作流编排）应用。

会话变量允许应用开发者在同一个 Chatflow 会话内，指定需要被临时存储的特定信息，并确保在当前工作流内的多轮对话内都能够引用该信息，如上下文、上传至对话框的文件（即将上线）、用户在对话过程中所输入的偏好信息等。好比为 LLM 提供一个可以被随时查看的”备忘录”，避免因 LLM 记忆出错而导致的信息偏差。

例如，你可以将用户在首轮对话时输入的语言偏好存储至会话变量中，LLM 在回答时将参考会话变量中的信息，并在后续的对话中使用指定的语言回复用户。

会话变量支持以下六种数据类型：

String 字符串
Number 数值
Object 对象
Array[string] 字符串数组
Array[number] 数值数组
Array[object] 对象数组

会话变量具有以下特性：

会话变量可在大部分节点内全局引用；
会话变量的写入需要使用变量赋值节点；
会话变量为可读写变量。

使用“变量赋值”组件修改会话变量的值：

小结

在 Dify 工作流（Workflow 和 Chatflow）的实现中，“变量”做为最基础、最核心的组件发挥着不可或缺的作用，因为它承载了不同节点间数据传递的作用。变量总共分为 4 种类型：用户变量、系统变量、环境变量和会话变量，我们需要根据不同的业务场景选择合适的变量类型进行使用。

本文已收录到我的技术小站 www.javacn.site，其中包含的内容有：Spring AI、LangChain4j、Dify、AI Agent、MCP、Function Call、RAG、向量数据库、Prompt、多模态、向量数据库、嵌入模型等内容。