バージョン管理と更新手順

1. バージョン管理の仕組み

1.1 下書きと公開（Publish）

• 下書き（Draft）: 編集画面での変更内容は自動的に「下書き」として保存されます。この段階ではAPIやWebアプリのエンドユーザーには反映されません。

• 公開（Publish）: 右上の「公開（Publish）」ボタンを押すことで、変更内容が本番環境（API/Webアプリ）に反映され、バージョン履歴として確定します。

1.2 バージョン履歴の確認

DifyのバージョンによってUIが異なりますが、一般的に以下の手順で過去の履歴を確認可能です。

1. フローエディタを開く

2. 「公開する」ボタンの右にある「バージョン履歴」アイコンを選択

3. バージョン履歴が表示され、各バージョンの公開日時と変更者を確認可能

2. 更新前の準備（必須）

2.1 DSLファイルのエクスポート（バックアップ）

重要： バージョン履歴機能だけに頼らず、必ずDSLファイル（ファイル拡張子: .yml）を手元に保存してください。これにより、環境が破損した場合や別環境への移行時にも確実に復旧できます。

手順：

1. 対象のアプリケーションのフローエディタを開く

2. バージョン履歴を開き、エクスポートするバージョンの右上にポインタを移動、「…」メニューを選択

3. 「DSLをエクスポート」 をクリック

4. ダウンロードされたDSLファイルを、「App名_YYYYMMDD_vX.yml」等の規則的な名前で保存

2.2 更新チェックリスト

• 変更箇所の特定: プロンプト、モデルパラメータ、ツール設定、ナレッジ参照の変更点を整理

• 現状の記録: 複雑なプロンプトや設定はスクリーンショットやテキストで控える

• 影響範囲の確認: ナレッジベースの再インデックスが必要か確認

3. 安全な更新フロー

1. バックアップ取得: 現行バージョンのDSLファイルをエクスポート。

2. 下書きでの編集: 必要な変更を適用（この時点では公開しない）。

3. デバッグとプレビュー:

   • プレビューや「デバッグ機能を使用し、実際にメッセージを送信して動作確認を行う。

   • チェック観点: 応答精度、エラーの有無、ツール呼び出しの成功可否、応答速度。

4. 公開: テストで問題がないことを確認後、「公開」ボタンを押下。

5. 本番確認: 公開されたアプリ（Web URLまたはAPI経由）で最終動作確認。

4. ロールバック（復旧手順）

万が一、更新後に不具合が発生した場合の復旧手順です。

4.1 DSLファイルからの復旧（推奨・確実）

最も確実な方法は、更新前にバックアップしたDSLファイルを使って「以前の状態のアプリ」を再作成することです。

1. Difyのスタジオ（アプリ一覧）画面を開く

2. 「DSLファイルをインポート」を選択

3. 「DSLファイルから」タブを選択し、バックアップしたDSLファイルをアップロード

4. 動作確認後、APIのエンドポイント差し替えや、旧アプリのアーカイブを行う

4.2 履歴機能からの復元

UI上に「バージョン履歴」がある場合、過去のバージョンを選択して復元がおこなえます。復元後には必ず再度「公開」を行う必要があります。

5. ナレッジベースの更新運用

ナレッジベースの変更は、アプリの更新とは別に管理が必要です。

5.1 更新の注意点

• ドキュメントの「セグメント設定」や「インデックスモード」を変更すると、再インデックスに時間がかかり、その間検索精度が落ちる可能性があります。

• 推奨フロー:

  1. 本番用とは別の「検証用ナレッジベース」を作成し、ドキュメントをアップロード。

  2. アプリのコンテキスト設定で一時的に検証用ナレッジを参照させテスト。

  3. 問題なければ本番用ナレッジベースを更新（置換または追加）。

6. 運用ベストプラクティス

• メンテナンス時間の確保: ナレッジの大規模更新やモデル変更は、利用者が少ない時間帯（早朝・深夜）に実施する。

• 変更ログの管理: 「いつ・誰が・何を・なぜ」変更したか、バックアップしたファイルと共に記録を残す。

• バージョン番号の付与: ファイル名やアプリ名に v1.0, v1.1 といったバージョン番号を含め、管理を明確にする。