Dify 三昧：【リリース情報】 Dify v1.19.0：ワークフローを「階層ごと」にトレースできるようになりました

はじめに

Dify をご利用・ご検討中の皆さん、11月に入って朝晩の冷え込みも増してきましたが、いかがお過ごしでしょうか？
ディーネットのよろず請負人、深見です。

Dify の最新バージョン、v1.19.0 がリリースされました！今回のアップデートでは、Workflow Tool の中身まで外部の可観測性ツールで階層ごとに追えるようになったほか、Workflow Tool を含むアプリのパッケージでの持ち運び、difyctl によるワークスペースの Skill 管理（一覧・エクスポート・インポート・公開）などが導入されています。

ただし、アップグレードには Docker Compose v2.35.0 以上が必須です。あわせて、今回のマイグレーションには元に戻せないもの（トレース設定の重複行の削除）が含まれますので、必ずバックアップを取ってから作業してください。また、アプリのエクスポートは新しい「パッケージ形式 v2」に統一されるため、古い Dify へインポートする場合は、インポート先を先に 1.19.0 へ上げておく必要があります。

Dify v1.19.0 リリース情報

New Features (新機能)

1. ネストされたワークフローのトレース

1.18.0 で、Console の履歴から Workflow Tool の呼び出しを掘り下げられるようになりました。1.19.0 では、それが外部トレースにも拡張されています。Workflow Tool が実行した内部ステップが、呼び出し元の Tool スパンの子として出力され、ネストした呼び出しや繰り返し呼び出しでも階層が保たれます (#44673)。

階層を辿れる: Workflow Tool を展開すると、内部の実行ステップが Tool スパンの下に並びます。
呼び出しごとに把握できる: 繰り返し呼び出しや失敗も、トレース上の位置を保ったまま残ります。
LLM のコンテキストも残る: 整形済みのプロンプトとレスポンス、トークン使用量、プロジェクト・トレース・オブザベーションへのリンクを確認できます。

リリースノートには、Langfuse 上でネストした Workflow Tool の LLM 呼び出しまで辿れるスクリーンショットが掲載されています。

注意点が3つあります。

保存済みのプロバイダー設定は、そのまま使えます。
新しい階層構造が適用されるのは新しい実行分だけです。過去のトレースは遡って作り直されません。
独立してネストされたワークフロー実行は、別々のトレースのまま残り、親の識別子でリンクされます。

関連して、トレース配信が各プロバイダー共通のインターフェースに統合されました。対象は Langfuse、LangSmith、Opik、Weave、Arize、Phoenix、Aliyun、MLflow、Databricks、Tencent です。リトライ可能なエクスポートは、決定論的な ID で同じトレース単位を再送します。

また、トレースの認証情報は書き込み専用になりました。空欄や省略は保存済みの値を維持します。送信先のホストやエンドポイントを変えるときは、シークレットの再入力が必要です。

2. Workflow Tool をアプリごと持ち運べる (App パッケージ)

アプリをエクスポートすると、その Workflow Tool の裏にあるワークフローも一緒に持ち出せます (#44592)。.ifpkg パッケージには、バインドされているバージョンのワークフローが、推移的な依存も含めて入ります。

インポート時の動きは次のとおりです。

移行先に同じツールがあれば再利用します。
無ければ作成・公開・登録し、参照を張り替えます。
パッケージに含められる Workflow Tool のワークフローは、既定で最大 20 個です (APP_PACKAGE_MAX_WORKFLOW_TOOLS)。
不足ツールの作成には、ツール管理の権限と十分なアプリクォータが必要です。

もうひとつ重要なのが、すべての Dify アプリのエクスポートが「パッケージ形式 v2」になったことです (#45353)。Workflow Tool を含まないアプリも対象です。v1 のインポートと、明示的な YAML エクスポートは引き続き使えますが、YAML には Workflow Tool の依存は含まれません。

注意: 古い Dify へインポートすると拒否される場合があります。新しいパッケージを古い環境に入れる前に、移行先を先に上げてください。

3. Agent のファイル: まとめてアップロード、その場でプレビュー

アップロード (#44947)

複数ファイルの選択やドロップに対応し、並列でアップロードします。
成功したファイルは1回のアトミックなバッチでバインドされます。
Composer の同時保存でも最新のファイルが保たれます。
Prompt へのアップロードでは、複数参照を挿入してもカーソル位置が維持されます。

プレビュー (#45032、#45045)

PDF をインラインで読めます。
ソースファイルはシンタックスハイライト付きで見られます。
テキストが途中で切り詰められている場合は、その旨が表示されます。
対象は、設定済みファイル、Skill のメンバー、作業ディレクトリ内のファイルです。
PDF を読み込めない場合は、ダウンロード操作が表示されます。

4. Developer spotlight: Skill を OpenAPI と difyctl で管理

ワークスペースの Skill を、コマンドラインから検索・確認・エクスポート・インポート・公開できます (#44941)。

コマンド	できること
`difyctl get skill`	Skill 一覧 (キーワードとタグで絞り込み可)
`difyctl describe skill`	詳細、ドラフトのハッシュ、最新の公開バージョン
`difyctl get skill version`	公開済みバージョンの一覧
`difyctl export skill`	ドラフトまたは指定バージョンを ZIP で出力
`difyctl import skill --files <dir>`	ローカルのファイルから Skill を作成、または既存 Skill のドラフトを置換
`difyctl publish skill`	ドラフトを新バージョンとして公開

利用には、アカウントでの呼び出し、対応するワークスペース権限、Skills が有効になっていることが必要です。

Import は公開まではしません。 公開するには publish を別途実行します。
既存 Skill への Import は破壊的操作に分類されます。Skill ID を指定したインポートは、その Skill のドラフトを置き換えます。このとき、インポートする SKILL.md の name が対象の Skill と一致している必要があります。
操作カタログと CLI ヘルプでは、読み取り・書き込み・破壊的操作が区別して表示されます。
任意の draft_hash チェックで、古い内容による置換を弾けます。ただし秒単位のタイムスタンプを使うため、同じ秒の中での編集は検出できません。

Improvements / Bug Fixes (改善・バグ修正)

改善

ダイアログの安全性: 削除・名前変更・メタデータ・アノテーション・メンバーのロール・プラグイン設定のダイアログで、入力途中のセッションとドラフトが保たれます。処理中は閉じず、完了後はフォーカスが戻ります。削除の二重送信もブロックされます。
アクセシビリティ: 右から左へ書く言語 (RTL) のレイアウト対応が広がり、日時ピッカーのキーボード操作が改善しました。
Cloud のクォータ表示: 「無制限」と「容量ゼロ」を区別して表示し、リセット日を Unix 秒として解釈するよう修正しました。
クエリ負荷の軽減: セグメントページで、子チャンクと添付ファイルをまとめて読み込みます。アプリのストレージクリーンアップ用に、参照インデックスも追加されました。
Gunicorn の keep-alive: 設定項目 (GUNICORN_KEEP_ALIVE) が新設され、既定値は 10 秒 です。サーバー側の短いアイドル時間のあとで接続を再利用して失敗する問題を減らします。
Docker 設定: サービスやプロバイダーの上書きが、関係するコンテナ、DB コマンド、ヘルスチェック、WebSocket 設定まで届くようになりました。ジェネレーターが作るのは、無い場合のルート .env だけです。

セキュリティ強化

プロバイダーモデルの有効化・無効化は、オーナーまたは管理者のみになりました。
メールアドレスの利用可否チェックには、アカウントの受け入れ (admission) が必要になりました。
SSRF 対策クライアントで、レスポンスの Cookie が現在のリクエストとそのリダイレクトの中だけに保持されるようになりました。別リクエストに Cookie が引き継がれません。
Dataset のリソースアクセストークンは、明示的にバインドされたアクティブな Dataset だけを一覧できます。include_all=true でも範囲は広がりません。
DSL を既存アプリにインポートしても、Web App のアクセスモードは保たれます。
依存関係の更新: Authlib 1.9.1、LiteLLM 1.100.4 以降、Pydantic AI 2.53.0、Pillow 13.0.0、pypdf 6.21.4 など。

主なバグ修正

ワークフロー
- ネイティブ非対応モデルでの構造化出力フォールバックを復旧し、JSON の真偽値が文字列にならないようにしました。
- ストリーミングリクエストが同時実行数の上限に二重カウントされなくなりました。上限1でも、単独のリクエストが通ります。
- Start ノードの sys.timestamp を UTC にしました。
Agent / ツール
- リフレッシュした OAuth 認証情報を保存し、同時リフレッシュを直列化するようにしました。ローテーションするトークンが保護されます。
- Agent の LLM ゲートウェイで、応答チャンクごとにプロンプト履歴全体をシリアライズしていた問題を解消しました。
ナレッジ
- Notion のページ一覧とファイルインポートを復旧しました。
- EPUB、EML、DOCX、CSV、Markdown の抽出まわりを修正しました。
- 否定のメタデータフィルターで、キーを持たないドキュメントも含めるようにしました。
- top_k=0 を尊重するようにしました。
SDK
- Node.js SDK: SSE の改行形式 (CR/LF/CRLF) と BOM に対応しました。
- PHP SDK: ストリーミング応答のバッファリングを回避し、会話ページネーションで last_id を送るようにしました。

アップグレードガイド

Dify v1.19.0 へアップグレードする際は、必ずバックアップを最初に行ってください。ここでは、Docker Compose で運用している 1.18.0 の環境を 1.19.0 へ上げる流れで説明します。

事前準備と互換性に関する注意点

バックアップの実施: データベース、ベクターストアのデータ、アップロード済みファイル、Agent のスナップショットとワークスペースのストレージ、デプロイのシークレットと環境変数ファイルを取得してください。シングルスタックの場合は、メンテナンスウィンドウを設けるのが安全です。
Docker Compose v2.35.0 以上が必須: ルートの .env による上書きが優先されるための最低バージョンです。docker compose version で確認し、未満なら先に Compose を更新してください。
イメージのバージョンを揃える: API、worker、web、Agent Backend、Local sandbox の各イメージは、すべて 1.19.0 に揃えます。plugin daemon は 0.6.14-local です。既存の Local sandbox の認証トークンと、設定済みの PASSWORD_PEPPER は変更しないでください。
元に戻せないマイグレーションがある: トレース設定の重複行は、マイグレーションで削除されます。インデックスをダウングレードしても、削除された行は戻りません。
1.18.0 より前のバージョンから上げる場合: 先に 1.18.0 のアップグレードガイドも実施してください。1.17.1 以前で、同梱 Weaviate がまだ 1.27 の場合は、1.17.1 の段階的な Weaviate アップグレードを先に済ませてください (1.18.0 のガイドに書かれている注意点です)。

環境変数ファイルの方針

設定ファイルの扱いが整理されています。テンプレートで置き換えず、既存の .env をその場で編集してください。

docker/envs/**/*.defaults は自動で読み込まれます。サービスごとのカスタマイズは、対応するローカルの .env に書きます。
ルートの docker/.env には、デプロイの入力値と明示的な上書きを置きます。
既存の shared.env は引き続き使えます。API・worker・Beat の共通設定は、新しくは docker/envs/core-services/api-worker.env に書きます。
読み込み順は shared.env、api-worker.env、ルート .env で、後のものが優先されます。shared.env と api-worker.env で値が競合したら api-worker.env が勝ち、ルートの .env はそのどちらにも勝ちます。
api-worker.defaults を変更せずにコピーしてあれば、既存の shared.env のカスタマイズは保たれます。
誤って空にした代入や、古いテンプレートのコピーで固定されている値がないか、アップグレード前に見直してください。
PLUGIN_DAEMON_KEY と PLUGIN_DIFY_INNER_API_KEY は、ルートの docker/.env に設定します。daemon とそのクライアントに、同じ値が渡るようにするためです。ポート、ボリュームパス、プロファイル、ヘルスチェックのスケジュールも、引き続きルートの設定です。

設定の見直し方や各設定の置き場所については、公式の Docker configuration guide も参照してください。

デプロイ手順 (Docker Compose)

1.19.0 のタグとイメージが公開されていることを確認してから、実行します。

cd dify/docker
docker compose stop -t -1
git fetch --tags
git checkout 1.19.0
# 必要な設定変更を既存の env ファイルへマージする
docker compose pull
docker compose up -d

git checkout が失敗するときは、ローカルで変更したファイルが原因のことがあります。.env を消さないように注意して、先に差分を整理してください。

マイグレーションの確認

API の起動時マイグレーションは有効のままにします (MIGRATION_ENABLED=true)。マネージドなマイグレーション手順を使う場合は、新しい worker を起動する前に全チェーンを適用してください。
1.18.0 からは 6つのマイグレーションリビジョンが適用され、最後は 53c10126d551 です。
次の2点は、運用に影響します。
- ストレージクリーンアップ用のインデックス (d7e9a1c3f502): message_files.upload_file_id、workflow_node_execution_offload.file_id、workflow_draft_variable_files.upload_file_id に追加されます。PostgreSQL では CONCURRENTLY で作られますが、データスキャンと I/O は発生します。途中で中断して無効なインデックスが残った場合は、原因を調べてから再実行してください。健全なインデックスを復旧の手段として削除するのは避けます。
- トレース設定の一意性 (53c10126d551): アプリとプロバイダーの組ごとに1件へ絞り、ユニークインデックスを追加します。重複があれば、最後に更新された行が残り、同時刻なら ID で決まります。

動作確認

起動後は、少なくとも次を確認してください。

docker compose ps
docker compose logs -f api

コンテナがすべて起動していて、API のログにマイグレーションエラーが出ていないこと
Web UI にログインできること
外部トレース (Langfuse など) を使っている場合は、新しく実行したワークフローで Workflow Tool の内部ステップが出ること (過去分には出ません)

環境変数・データベースマイグレーションの変更点

設定	変更内容
`OPS_TRACE_QUEUE`	新規。既定は `ops_trace_v2`。API・ワーカー・Beat で値を揃える必要があります
`OPS_TRACE_EXPORT_MAX_ATTEMPTS`	新規。既定は `6` (リトライ可能なトレースエクスポートの総試行回数)
`ENABLE_TRACE_PAYLOAD_SWEEP_TASK`	新規。既定は `true`。新パイプラインの孤立したトレースペイロードを毎日クリーンアップします
`APP_PACKAGE_MAX_WORKFLOW_TOOLS`	新規。既定は `20`
`GUNICORN_KEEP_ALIVE`	新規。既定は `10` 秒

次の旧設定は削除されました: OPS_TRACE_UNIFIED_ENABLED、OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES、OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS、OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS。

状況別の補足

ローリングデプロイの場合: トレースキューを分ける

単一スタックを止めて上げるなら、この項は不要です。新旧のコンポーネントを同時に動かすローリングデプロイのときだけ、次に従ってください。

新しいタスクは、既定で OPS_TRACE_QUEUE=ops_trace_v2 を使います。API、worker、Beat で値を揃えます。
CELERY_QUEUES、CELERY_WORKER_QUEUES、--queues を独自に指定している場合は、新しいキューを含めてください。
古いトレース worker は、古い producer と、そのキュー済み・実行中・予約済み・スケジュール済み・リトライ中の処理がすべて終わるまで、ops_trace を処理させ続けます。
古いキューをパージしないでください。新しい側の廃止済みハンドラーに、旧メッセージをエクスポートさせることもできません。

詳細は tracing rollout guide を参照してください。

App パッケージを使う場合

新しいパッケージは必ず v2 です。インポート先の Dify を先に 1.19.0 へ上げてから、新しいパッケージを入れてください。古いインポーターは拒否することがあります。v1 のインポートは 1.19.0 でも使えます。

ソースから動かしている場合

必要な実行環境は次のとおりです。

Python 3.13
Node.js 24.22.1 以上 (24.x 系)
pnpm 12.16.1

pnpm は Node.js を自動で用意しなくなったため、Node.js は別途インストールが必要です。リポジトリのルートで、次を実行します。

uv sync --project api --frozen
uv run --directory api flask db upgrade
pnpm install --frozen-lockfile

そのうえで、Web アプリを再ビルドし、API、worker、scheduler、Agent の各サービスを同じリリースから再起動してください。Agent Backend を別途デプロイしている場合は、ロックされた server 依存関係も更新します。

difyctl を使っている場合

1.19.0 に対応するクライアントを入れて、現在のコマンド体系を確認します。

difyctl help
difyctl install skills <dir>

インストール済みのエージェント向け Skill は、difyctl install skills <dir> で更新します。Workflow / Chatflow を自動化しているスクリプトは、新しい stop.run に合わせてください。メッセージ系アプリは stop.task のままです。

アップグレード後のデータ対応

ドキュメントの再取り込み: EPUB、EML、DOCX、CSV、Markdown、Notion の抽出修正は、新しく処理されるコンテンツにだけ効きます。影響を受けていた既存ドキュメントは、再インポートまたは再インデックスしてください。
PDF プレビューの重複: 同じ PDF のプレビューで重複アセットが増える問題は、今後の分が防がれるだけです。すでに保存された重複は消えません。
トレース履歴: 既存の Agent トレース台帳のデータは読めますが、すでにエクスポート済みのトレースに、新しいネストスパンが付くことはありません。

Full Change List (重要な変更点のピックアップ)

今回は、Full Change List のうち、運用や利用に影響が大きいものを私の判断でピックアップしています。UI の細かな修正や、内部のテスト整備などは省いています。特に、API を直接利用している方は次の変更にご注意ください。

Console のプロフィール更新 POST (/account/name、/avatar、/interface-language、/interface-theme、/timezone) は非推奨になりました。PATCH /console/api/account/profile を使ってください。
GET /console/api/apps/{app_id}/trace-config は、保存済みのシークレット値を返さなくなりました。独自クライアントは configured_secrets を参照してください。
Workflow / Chatflow の OpenAPI は、停止に POST /openapi/v1/apps/{app_id}/runs/{run_id}:stop (stop.run)、イベント取得に GET .../runs/{run_id}/events (get.run.event) を使います。Chat、Agent Chat、Completion は従来のタスク ID 方式 (stop.task) のままです。

詳細については、公式の変更ログをご確認ください。

Full Changelog: 1.18.0...1.19.0

終わりに

以上、Dify v1.19.0 のリリース情報をお届けしました。

今回は、Workflow Tool の内部まで外部トレースで階層的に追えるようになり、Langfuse などの可観測性ツールでの調査がぐっと楽になるリリースです。App パッケージや difyctl による Skill 管理など、環境間の移行や運用の自動化に役立つ機能も加わりました。

一方で、Docker Compose のバージョン要件や環境変数ファイルの扱い、トレース設定のマイグレーションなど、アップグレード時に気をつけたい点も多いリリースです。実際に作業される際は、次の点を改めてご確認ください。

作業前にバックアップを取得する（トレース設定の重複行を削除するマイグレーションは、元に戻せません）
Docker Compose が v2.35.0 以上であること、各イメージを 1.19.0 に揃えていること
既存の .env をテンプレートで置き換えず、その場で編集していること
ローリングデプロイの場合は、トレースキュー (OPS_TRACE_QUEUE) を API・worker・Beat で揃えていること
新しい App パッケージ（形式 v2）を別の環境へ持ち込む場合は、インポート先を先に 1.19.0 へ上げていること
API や difyctl で自動化している場合は、stop.run、PATCH /console/api/account/profile、configured_secrets への対応が済んでいること

なお、本記事は公式リリースノートの要点をまとめたものですので、実際のアップグレード前には、必ず公式のリリースノートもあわせてご確認ください。

次回も Dify の最新情報をお届けしていきますので、引き続き「Dify 三昧」をよろしくお願いいたします。

参考リンク

本記事は Dify v1.19.0 のリリースノートを基に作成されています。最新情報は公式サイトおよび GitHub リポジトリをご確認ください。

深見和正