干貨分享：Dify中四種核心變量詳解！
在 Dify 工作流（Workflow 和 Chatflow）的實(shí)現(xiàn)中，“變量”做為最基礎(chǔ)、最核心的組件發(fā)揮著不可或缺的作用，因?yàn)樗休d了不同節(jié)點(diǎn)間數(shù)據(jù)傳遞的作用。
也就是說，我們?cè)趯?shí)現(xiàn) Workflow 和 Chatflow 時(shí)，需要一種動(dòng)態(tài)數(shù)據(jù)容器，能夠存儲(chǔ)和傳遞不固定的內(nèi)容，在不同的節(jié)點(diǎn)內(nèi)被相互引用，實(shí)現(xiàn)信息在節(jié)點(diǎn)間的靈活通信，這個(gè)就是“變量”了。
“
變量作用：用于不同節(jié)點(diǎn)的信息傳遞。
例如以下場(chǎng)景，我們需要將第一個(gè)節(jié)點(diǎn)用戶輸入的內(nèi)容，傳遞給第二個(gè)節(jié)點(diǎn)大模型，就需要使用變量進(jìn)行傳遞。
圖片
1.變量分類
Dify 中總共有以下 4 種變量類型：
- 用戶（輸入）變量
- 系統(tǒng)變量
- 環(huán)境變量
- 會(huì)話變量
分別來(lái)看這四種變量類型的詳細(xì)介紹。
2.用戶變量
用戶變量是用戶在與 Dify 應(yīng)用交互過程中直接輸入的信息，這些信息可以是文本、段落（多行文本）、下拉選項(xiàng)、數(shù)字、單文件、文件列表（多文件）等，如下圖所示：
圖片
例如，在對(duì)話框中，用戶輸入“我想查詢明天的天氣”，這個(gè)輸入內(nèi)容就會(huì)作為用戶變量，應(yīng)用可以根據(jù)這個(gè)變量調(diào)用天氣查詢接口等。
注意：變量名稱只能為英文、數(shù)字和下劃線。
3.系統(tǒng)變量
系統(tǒng)變量是由 Dify 預(yù)設(shè)的系統(tǒng)級(jí)參數(shù)，可以被其它節(jié)點(diǎn)全局讀取，用于記錄和管理應(yīng)用運(yùn)行過程中的關(guān)鍵信息，以 sys. 前綴開頭。
其中 WorkFlow 和 ChatFlow 的系統(tǒng)變量還有所不同。
Workflow
Workflow 類型應(yīng)用提供以下系統(tǒng)變量：
變量名稱 | 數(shù)據(jù)類型 | 說明 | 備注 |
sys.files[LEGACY] | Array[File] | 文件參數(shù)，存儲(chǔ)用戶初始使用應(yīng)用時(shí)上傳的圖片 | 圖片上傳功能需在應(yīng)用編排頁(yè)右上角的 “功能” 處開啟 |
sys.user_id | String | 用戶 ID，每個(gè)用戶在使用工作流應(yīng)用時(shí)，系統(tǒng)會(huì)自動(dòng)向用戶分配唯一標(biāo)識(shí)符，用以區(qū)分不同的對(duì)話用戶 | |
sys.app_id | String | 應(yīng)用 ID，系統(tǒng)會(huì)向每個(gè) Workflow 應(yīng)用分配一個(gè)唯一的標(biāo)識(shí)符，用以區(qū)分不同的應(yīng)用，并通過此參數(shù)記錄當(dāng)前應(yīng)用的基本信息 | 面向具備開發(fā)能力的用戶，通過此參數(shù)區(qū)分并定位不同的 Workflow 應(yīng)用 |
sys.workflow_id | String | Workflow ID，用于記錄當(dāng)前 Workflow 應(yīng)用內(nèi)所包含的所有節(jié)點(diǎn)信息 | 面向具備開發(fā)能力的用戶，可以通過此參數(shù)追蹤并記錄 Workflow 內(nèi)的包含節(jié)點(diǎn)信息 |
sys.workflow_run_id | String | Workflow 應(yīng)用運(yùn)行 ID，用于記錄 Workflow 應(yīng)用中的運(yùn)行情況 | 面向具備開發(fā)能力的用戶，可以通過此參數(shù)追蹤應(yīng)用的歷次運(yùn)行情況 |
圖片
Chatflow
Chatflow 類型應(yīng)用提供以下系統(tǒng)變量：
變量名稱 | 數(shù)據(jù)類型 | 說明 | 備注 |
sys.query | String | 用戶在對(duì)話框中初始輸入的內(nèi)容 | |
sys.files | Array[File] | 用戶在對(duì)話框內(nèi)上傳的圖片 | 圖片上傳功能需在應(yīng)用編排頁(yè)右上角的 “功能” 處開啟 |
sys.dialogue_count | Number | 用戶在與 Chatflow 類型應(yīng)用交互時(shí)的對(duì)話輪數(shù)。每輪對(duì)話后自動(dòng)計(jì)數(shù)增加 1，可以和 if-else 節(jié)點(diǎn)搭配出豐富的分支邏輯。例如到第 X 輪對(duì)話時(shí)，回顧歷史對(duì)話并給出分析 | |
sys.conversation_id | String | 對(duì)話框交互會(huì)話的唯一標(biāo)識(shí)符，將所有相關(guān)的消息分組到同一個(gè)對(duì)話中，確保 LLM 針對(duì)同一個(gè)主題和上下文持續(xù)對(duì)話 | |
sys.user_id | String | 分配給每個(gè)應(yīng)用用戶的唯一標(biāo)識(shí)符，用以區(qū)分不同的對(duì)話用戶 | |
sys.app_id | String | 應(yīng)用 ID，系統(tǒng)會(huì)向每個(gè) Workflow 應(yīng)用分配一個(gè)唯一的標(biāo)識(shí)符，用以區(qū)分不同的應(yīng)用，并通過此參數(shù)記錄當(dāng)前應(yīng)用的基本信息 | 面向具備開發(fā)能力的用戶，通過此參數(shù)區(qū)分并定位不同的 Workflow 應(yīng)用 |
sys.workflow_id | String | Workflow ID，用于記錄當(dāng)前 Workflow 應(yīng)用內(nèi)所包含的所有節(jié)點(diǎn)信息 | 面向具備開發(fā)能力的用戶，可以通過此參數(shù)追蹤并記錄 Workflow 內(nèi)的包含節(jié)點(diǎn)信息 |
sys.workflow_run_id | String | Workflow 應(yīng)用運(yùn)行 ID，用于記錄 Workflow 應(yīng)用中的運(yùn)行情況 | 面向具備開發(fā)能力的用戶，可以通過此參數(shù)追蹤應(yīng)用的歷次運(yùn)行情況 |
圖片
4.環(huán)境變量
環(huán)境變量用于保護(hù)工作流內(nèi)所涉及的敏感信息，例如運(yùn)行工作流時(shí)所涉及的 API 密鑰、數(shù)據(jù)庫(kù)密碼等。它們被存儲(chǔ)在工作流程中，而不是代碼中，以便在不同環(huán)境中共享。
環(huán)境變量支持以下三種數(shù)據(jù)類型：
圖片
- String 字符串
- Number 數(shù)字
- Secret 密鑰
其中，Secret 密鑰用于定義敏感信息或數(shù)據(jù)，導(dǎo)出 DSL 時(shí)設(shè)置了防泄露機(jī)制。
環(huán)境變量擁有以下特性：
- 環(huán)境變量可在大部分節(jié)點(diǎn)內(nèi)全局引用；
- 環(huán)境變量命名不可重復(fù)；
- 環(huán)境變量為只讀變量，不可寫入。
5.會(huì)話變量
會(huì)話變量只存在 ChatFlow 場(chǎng)景中，因?yàn)樗敲嫦蚨噍唽?duì)話場(chǎng)景，而 Workflow 類型應(yīng)用的交互是線性而獨(dú)立的，不存在多次對(duì)話交互的情況，因此會(huì)話變量?jī)H適用于 Chatflow 類型（聊天助手 → 工作流編排）應(yīng)用。
會(huì)話變量允許應(yīng)用開發(fā)者在同一個(gè) Chatflow 會(huì)話內(nèi)，指定需要被臨時(shí)存儲(chǔ)的特定信息，并確保在當(dāng)前工作流內(nèi)的多輪對(duì)話內(nèi)都能夠引用該信息，如上下文、上傳至對(duì)話框的文件（即將上線）、 用戶在對(duì)話過程中所輸入的偏好信息等。好比為 LLM 提供一個(gè)可以被隨時(shí)查看的”備忘錄”，避免因 LLM 記憶出錯(cuò)而導(dǎo)致的信息偏差。
例如，你可以將用戶在首輪對(duì)話時(shí)輸入的語(yǔ)言偏好存儲(chǔ)至?xí)捵兞恐校琇LM 在回答時(shí)將參考會(huì)話變量中的信息，并在后續(xù)的對(duì)話中使用指定的語(yǔ)言回復(fù)用戶。
圖片
會(huì)話變量支持以下六種數(shù)據(jù)類型：
- String 字符串
- Number 數(shù)值
- Object 對(duì)象
- Array[string] 字符串?dāng)?shù)組
- Array[number] 數(shù)值數(shù)組
- Array[object] 對(duì)象數(shù)組
會(huì)話變量具有以下特性：
- 會(huì)話變量可在大部分節(jié)點(diǎn)內(nèi)全局引用；
- 會(huì)話變量的寫入需要使用變量賦值節(jié)點(diǎn)；
- 會(huì)話變量為可讀寫變量。
使用“變量賦值”組件修改會(huì)話變量的值：
圖片
小結(jié)
在 Dify 工作流（Workflow 和 Chatflow）的實(shí)現(xiàn)中，“變量”做為最基礎(chǔ)、最核心的組件發(fā)揮著不可或缺的作用，因?yàn)樗休d了不同節(jié)點(diǎn)間數(shù)據(jù)傳遞的作用。變量總共分為 4 種類型：用戶變量、系統(tǒng)變量、環(huán)境變量和會(huì)話變量，我們需要根據(jù)不同的業(yè)務(wù)場(chǎng)景選擇合適的變量類型進(jìn)行使用。
