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

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

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

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

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

1.变量分类

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

1. 用户（输入）变量
2. 系统变量
3. 环境变量
4. 会话变量

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

2.用户变量

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

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

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

3.系统变量

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

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

Workflow

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

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

Chatflow

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

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

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、多模态、向量数据库、嵌入模型等内容。