【Dify】変数スコープとは？入力・会話・システム変数の違いと使い分け
DifyでWorkflowやChatflowを作っていると、「入力した値が空になる」「前のノードの出力を選べない」「前の会話で保存した値が残っている」といった問題が起こることがあります。
こうした問題を切り分けるには、変数名だけでなく、その値が「どこで作られたのか」「いつまで残るのか」「どのノードから参照できるのか」を確認する必要があります。
Difyで扱う値には、User Inputで受け取る入力変数、各ノードが生成する出力変数、Chatflowで会話をまたいで保持する会話変数、Difyが自動的に用意するシステム変数などがあります。見た目は同じ「変数」でも、出どころや寿命、参照できる範囲が異なります。
この記事では、個々のシステム変数の一覧や入力フォームの作成手順ではなく、Difyの変数を「出どころ・寿命・参照範囲」の3つの軸で整理します。
WorkflowとChatflowの違いも踏まえながら、目的に合った変数を選ぶための考え方を確認していきましょう。
Difyの変数スコープとは
Difyの変数スコープとは、その変数を「いつ・どこから参照できるのか」という有効範囲を表す考え方です。
変数を「値を入れる箱」と考えるなら、スコープは「その箱を使える場所と期間」です。同じように見える変数でも、値が作られた場所や保持される期間によって、参照できる範囲が異なります。
Difyの変数を整理するときは、次の3つを確認します。
- 出どころ：その値は、ユーザー、Dify、各ノードのどこから来たのか
- 寿命：1回の実行で消えるのか、同じ会話の続きでも保持されるのか
- 参照範囲：どのノードから、その値を参照できるのか
たとえば、あるノードが実行結果として作った値は、その後に実行されるノードで利用します。まだ実行されていない後続ノードの出力を、前のノードから参照することはできません。
また、1回の実行で使い終わる値と、Chatflowの会話中に保持する値では、適した変数の種類が異なります。値が空になる場合や、前の値が意図せず残る場合は、この「出どころ・寿命・参照範囲」のどこかを取り違えていないか確認することが大切です。
次の章では、この3つの軸を使って、入力変数・ノード出力変数・会話変数・システム変数の違いを整理します。
変数は「出どころ・寿命・参照範囲」で選ぶ
Difyでは、ユーザーが入力した値だけでなく、各ノードの実行結果や会話中に保存した値、Difyが自動的に用意する情報も変数として扱います。
この章では、WorkflowやChatflowの実行中によく使う変数を、次の4種類に分けて整理します。
入力変数：実行開始時に受け取る値
入力変数は、User Inputノードを通して、ユーザーやAPIから受け取る値です。
値の出どころは実行時の入力で、基本的にはその1回の実行で使用します。User Inputノードで作成した入力フィールドは変数になり、後続のLLM、If/Else、Codeなどのノードから参照できます。
質問文、商品名、出力形式、選択肢、アップロードされたファイルなど、実行するたびに内容が変わる値に適しています。
入力欄の種類やUser Inputノードの具体的な設定方法については、次の記事で解説しています。
ノード出力変数：処理の途中で生成される値
ノード出力変数は、LLM、Code、Document Extractorなどのノードを実行した結果として生成される値です。
値の出どころは各ノードの処理結果で、基本的には1回の実行中だけ使用します。出力を生成したノードより後に実行されるノードから参照します。
たとえば、LLMノードが生成した文章、Codeノードが計算した値、Document Extractorが取り出したテキストなどが該当します。
入力変数が「実行開始時に受け取る値」であるのに対し、ノード出力変数は「実行途中で新しく作られる値」です。参照したい変数が選択画面に表示されない場合は、その値を作るノードが前に配置され、実際に実行される経路になっているか確認します。
この章ではノード出力の役割だけを扱い、各ノードの設定方法までは説明しません。
会話変数：同じ会話の中で保持する値
会話変数は、Chatflowの同じ会話セッション内で、複数の会話ターンをまたいで保持する値です。
通常の入力変数やノード出力変数は1回の実行が終わるとリセットされますが、会話変数は次のメッセージでフローが再実行されたときも利用できます。
ユーザーが選んだ言語、会話中に確定した条件、進行状況など、同じ会話の続きで再利用したい情報に適しています。
ただし、会話内容が自動的にすべて会話変数へ保存されるわけではありません。保持したい値を会話変数として用意し、Variable Assignerなどを使って更新します。
会話変数の作成方法やVariable Assignerの詳しい操作手順は、実践記事へ委ねます。
システム・プリセット変数：Difyが自動的に用意する値
システム変数は、ユーザーやアプリ、実行状況を識別するために、Difyが自動的に用意する値です。変数名が sys. から始まるものが該当します。
一方、ユーザーが送信した最新のメッセージやファイルは、現在のDifyではUser Inputのプリセット変数として扱われます。Chatflowの userinput.query や、アップロードされたファイルを表す userinput.files は、sys.*とは区別して考える必要があります。
この章では、システム変数とプリセット入力変数の位置づけだけを確認します。利用できる変数名、ChatflowとWorkflowの違い、具体的な参照方法については、次の記事で詳しく解説しています。
変数を選ぶときは、次のように判断します。
- 実行開始時に受け取る値：入力変数
- 実行途中の処理結果：ノード出力変数
- 同じ会話で保持したい値：会話変数
- Difyが自動的に用意する実行情報：システム変数
この4種類を区別すると、値がどこで作られ、いつまで残り、どのノードから参照できるのかを追いやすくなります。
WorkflowとChatflowで変数の寿命はどう変わる？
Difyの変数の寿命を理解するには、WorkflowとChatflowで「1回の実行」が何を意味するのかを分けて考える必要があります。
Workflowの変数は1回の実行で完結する
Workflowは、入力を受け取って処理を進め、結果を返すまでを1回の実行として扱います。
User Inputで受け取った入力変数や、LLM、Codeなどのノードが生成した出力変数は、その実行中に後続ノードから参照できます。処理が終了すると、これらの変数は次の実行へ引き継がれません。
同じ値を次回のWorkflowでも使いたい場合は、再度入力として渡すか、データベースなどの外部保存先から取得する設計が必要です。
Chatflowではメッセージごとにフローが実行される
Chatflowでは、ユーザーがメッセージを送信するたびに、フローが1回実行されます。
そのターンで受け取った入力変数や、各ノードが生成した出力変数は、基本的にそのターンの実行中だけ使用します。次のメッセージでは、入力変数やノード出力変数が新しく作られます。
一方、会話変数は同じ会話セッション内で複数のターンをまたいで保持できます。前のターンで確定した条件や進行状況を、次のターンでも使いたい場合は会話変数が適しています。
ただし、会話変数が保持されるのは同じ会話の中です。新しい会話を開始した場合まで、以前の値が自動的に引き継がれるわけではありません。
同じ値が表示されても、保持されたとは限らない
Difyが自動的に用意するシステム変数などは、複数回の実行で同じ値が表示されることがあります。
ただし、同じ値が表示されているからといって、前回の変数がそのまま残っているとは限りません。実行のたびにDifyが値を用意した結果、同じ値になっている場合があります。
変数の寿命を判断するときは、画面に表示された値だけでなく、次のどちらなのかを確認します。
- 実行のたびに新しく用意される値
- 同じ会話内で保存され、次のターンへ引き継がれる値
1回の処理で使い終わるなら入力変数やノード出力変数、同じ会話の続きで保持したいなら会話変数、という区別が基本です。
WorkflowとChatflowの用途や機能、どちらを選ぶべきかについては、次の記事で詳しく解説しています。
変数が空になる・前の値が残る原因
Difyで変数が空になったり、前回の値が残ったりした場合は、変数の「出どころ・寿命・参照範囲」を順番に確認します。
ただし、値が期待どおりにならない原因が、すべて変数スコープにあるとは限りません。入力漏れ、データ型の不一致、条件分岐なども考えられるため、まずはスコープに関係する原因から切り分けます。
変数が空になる場合
変数が空になる場合は、その値を作る処理が実行されていない可能性があります。
次の順番で確認します。
- その変数は、どの入力またはノードから作られるのか
- 値を作るノードが、参照するノードより前にあるか
- If/Elseなどの分岐によって、値を作るノードを通らない経路になっていないか
- User Inputで必要な値が実際に入力されているか
- 会話変数の場合は、値を更新する処理が実行されているか
特に、後続ノードが生成する出力を、それより前のノードから参照することはできません。
また、分岐後の一方でしか生成されない変数を、分岐の合流後に使用する場合は注意が必要です。選ばれなかった経路のノードは実行されないため、その経路で作られる変数には値が入りません。
前の値が残る場合
前の会話で使用した値が残る場合は、会話変数として保存されていないか確認します。
会話変数は、同じChatflowの会話セッション内で複数のターンをまたいで保持されます。そのため、一度保存した値を更新またはクリアしないまま使い続けると、前のターンの値が次の回答へ影響することがあります。
次の点を確認します。
- 今回だけ使用する値を会話変数へ保存していないか
- 新しい入力を受け取ったときに値を上書きしているか
- 不要になった値をクリアする処理があるか
- 同じ会話セッションを使ってテストし続けていないか
原因を切り分けるときは、新しい会話を開始して同じ操作を試します。新しい会話では問題が起こらない場合、同じ会話内に保持された会話変数が影響している可能性があります。
変数を選択できない場合
ノードの変数選択画面に使いたい変数が表示されない場合は、そのノードから参照できる範囲に変数が存在していない可能性があります。
まず、値を作るノードと値を使うノードの接続順を確認します。ノード出力変数は、基本的にその出力を生成したノードより後にあるノードから参照します。
変数名を直接入力して解決しようとせず、Difyの変数選択画面に表示される候補から選ぶことが大切です。候補に表示されない場合は、ノードの順番や実行経路を見直します。
Variable Inspectorで実際の値を確認する
画面上の設定だけで原因を判断できない場合は、Variable Inspectorで各ノードの入力値と出力値を確認します。
確認するポイントは次の3つです。
- 値を作るノードが実行されているか
- 想定した変数に値が入っているか
- 値のデータ型が想定と一致しているか
Variable Inspectorの具体的な操作手順はこの章では扱いません。ここでは、問題が起きたノードだけでなく、その値を作った上流ノードから順番に確認することを覚えておきましょう。
「出どころ・寿命・参照範囲」に問題がなければ、次に入力内容、データ型、条件分岐、各ノードの設定を確認します。
目的別の変数の選び方
どの変数を使うか迷ったときは、変数名から考えるのではなく、「その値をどこから受け取り、いつまで使いたいのか」から判断します。
次の4つの質問を順番に確認してください。
実行開始時に受け取る値か？
ユーザーやAPIから、実行のたびに受け取る値には入力変数を使います。
たとえば、質問文、商品名、文章のトーン、出力形式など、その都度内容が変わる値です。
その値を次の会話でも使いたい場合でも、最初に受け取る場所は入力変数です。必要に応じて、受け取った値を会話変数へ保存します。
処理の途中で作られる値か？
LLM、Code、Document Extractorなど、各ノードの処理によって作られる値にはノード出力変数を使います。
たとえば、LLMが生成した文章を次のCodeノードへ渡す場合や、文書から抽出したテキストをLLMノードで使用する場合です。
ノード出力変数は、値を生成したノードより後に実行されるノードから参照します。
同じ会話の続きでも使いたい値か？
Chatflowの次の会話ターンでも保持したい値には会話変数を使います。
たとえば、会話中に決まった回答言語、ユーザーが選んだ条件、複数ターンにわたる進行状況などです。
ただし、今回のターンだけで使い終わる値まで会話変数へ保存すると、前の値が次の回答へ影響する原因になります。次のターンでも本当に必要な値だけを保存します。
Difyが自動的に用意する情報か？
ユーザー、アプリ、会話、実行状況などについて、Difyが自動的に用意する情報を参照したい場合はシステム変数を確認します。
システム変数は、自分で同じ情報を入力変数として作り直すのではなく、ノードの変数選択画面に表示される候補から選びます。
ただし、ユーザーが入力した最新のメッセージやファイルは、sys.*ではなくUser Inputのプリセット変数として扱われる場合があります。具体的な変数名は、システム変数一覧記事で確認してください。
4つの判断をまとめる
変数の選び方は、次のように整理できます。
- 実行開始時に受け取る値：入力変数
- 実行途中で作られる値：ノード出力変数
- 同じ会話の続きでも保持する値：会話変数
- Difyが自動的に用意する情報：システム変数
なお、新しい会話を開始した後も保持したい情報や、複数のユーザー・アプリで共有したい情報は、会話変数だけでは管理できません。その場合は、データベースなどの外部保存先を含めた設計を検討します。
APIキーなどの秘密情報も、入力変数や会話変数へ保存するのではなく、環境変数など適切な保存方法を使用してください。
まとめ：変数は「出どころ・寿命・参照範囲」で選ぶ
Difyの変数スコープで迷ったときは、変数名を覚えるだけでなく、次の3つを確認することが大切です。
- 出どころ：その値はどこで作られたのか
- 寿命：1回の実行で消えるのか、同じ会話で保持されるのか
- 参照範囲：どのノードから利用できるのか
Difyでよく使用する変数は、次の4種類に整理できます。
- 入力変数：実行開始時にユーザーやAPIから受け取る
- ノード出力変数：各ノードの処理結果として生成される
- 会話変数：同じChatflowの会話中に保持される
- システム変数：Difyが実行時に自動的に用意する
Workflowでは、入力変数やノード出力変数を基本的に1回の実行内で使用します。Chatflowでもメッセージごとにフローが実行されますが、会話変数を使うことで、必要な値を同じ会話の次のターンへ引き継げます。
変数が空になる場合は、値を作るノードが実行されているか、参照するノードより前にあるかを確認します。前の値が残る場合は、同じ会話内に会話変数として保持されていないかを確認してください。
まずは現在作成しているアプリから変数を1つ選び、「どこで作られ、いつまで残り、どのノードで使われるのか」を確認してみましょう。この3点を説明できれば、その変数のスコープを正しく把握できています。