-- Views
November 22, 26
スライド概要
はじめまして、yukikoと申します。 IT教育支援や、DX推進が可能です。 ◆ スキル LPIC レベル2 AI / Python Splunk BI(データ可視化・分析) ◆ その他 新卒・未経験の学生向けに、エンジニア転職を応援する資料を趣味で作成しています。 もしよろしければご活用ください。
1. 実務のための前提(ゼロから始める前に) 収録元:実務の前提_ゼロから始める前に.pptx(11枚)
実務のための前提:ゼロから始める前に揃えること 環境・アカウント・権限・知識・データ・費用・承認。始めてから困らないための確認 凡例:【確認済】公式の内容を確認 / 【要確認】版・契約・組織で必ず確認
前提の全体像:7つの柱 ① 環境(PC・Windows) ② アカウント(Dify・ OpenAI) ③ 権限と承認(組織) ⑤ データ(扱える範囲) ⑥ 費用(従量課金) ⑦ 時間と進め方 どれか一つでも欠けると、途中で止まる。本編の前に、7つすべてを確認する。 問いかけ:あなたの現場で、7つのうち最初に欠けやすいのはどれですか? 実務の前提 | 2/11 ④ 知識(最低限の操作)
① 環境:PC と Windows の前提 項目 必要な状態 確認方法 出典 Windows の版 サポート中の Windows 10 / 11(版は組織で確認 ) 設定 → システム → バージョン情報 【要確認】Microsoft 仮想化 BIOS / UEFI で有効(WSL 2 の前提) タスクマネージャー → パフォーマンス 【要確認】WSL 公式 空き容量 作業に十分な空き(目安は組織の基準) エクスプローラーでドライブ確認 【要確認】 メモリ・CPU Dify の最小要件を満たす(CPU 2コア以上・メモ リ4GiB以上) タスクマネージャー → パフォーマンス 【確認済】Dify 公式(最小 要件) Docker 環境 Docker Desktop(WSL 2 バックエンド) docker version 【要確認】Docker 問いかけ:会社の PC で仮想化が有効かどうか、誰に確認すれば確実ですか? 実務の前提 | 3/11
② アカウント:Dify・OpenAI・Git(受講前に作る) アカウント 用途 準備の要点 出典 Dify(セルフホストまたはクラウド) アプリ作成・ナレッジ・API 管理者が起動した環境にログインできること 【確認済】Dify 公式(セ ルフホスト手順) OpenAI(API) モデルの呼び出し API キーを発行できること。請求設定が必要 【要確認】OpenAI 公式 GitHub(任意) ソースの取得、版の確認 公開リポジトリの取得に必要な場合がある 【要確認】GitHub 問いかけ:APIキーを発行したら、どこに保管し、誰に共有してよいですか? 実務の前提 | 4/11
③ 権限と承認:着手前に決めること 利用の承認 データの範囲を決定 請求の上限を決定 キーの管理者を決定 決めること 誰が決めるか(RACI の A) 記録 利用の可否(ガイドラインとの適合) 管理責任者 承認番号 外部送信してよいデータの範囲 情報セキュリティ部門 範囲の一覧 請求の上限額と通知 管理責任者 上限額と設定日 PC へのインストール権限 情報システム 申請番号 問いかけ:管理者権限がない PC では、どの手順が止まりますか? 実務の前提 | 5/11 着手
④ 知識:最低限の前提(操作・用語) 分野 最低限できること できない場合の学び直し ファイル操作 フォルダの作成、ファイルの移動、拡張子の理解 Windows の基本操作の教材 ブラウザ操作 ログイン、設定画面の開閉、開発者ツールの表示 ブラウザの基本操作 ターミナル PowerShell を開き、一行のコマンドを実行 PowerShell の入門(本資料の 7〜9 枚) 用語 API・キー・モデル・プロンプトの意味を言える Why・What・How の用語表 問いかけ:「API とは何か」を、お客様に一文で説明できますか? 実務の前提 | 6/11
⑤ データ:扱ってよい情報の範囲 データの種類 扱い(原則) 学習での扱い 公開情報(Web に出ている資料) 利用可(著作権は確認) テストに使ってよい 社内規程(非公開) 外部送信の可否を情報システムが判断 架空のデータで練習する 個人情報(氏名・連絡先など) 原則として外部へ入力しない 架空の人物で練習する 顧客の機密情報 契約と社内規程に従う 研修では使わない APIキー・パスワード 共有・画面表示・チャット貼付は禁止 台帳で管理し、受講者に渡さない 問いかけ:社内規程のテキストをそのまま貼り付けてよいか、誰に確認しますか? 実務の前提 | 7/11
⑥ 費用:従量課金と上限の考え方 利用量が増える 料金が増える 上限に達する 通知を受ける • API は利用量に応じて課金されるのが一般的(料金は【要確認】:OpenAI の最新の料金表で確認) • 請求の上限と通知を、利用開始前に設定する • 受講中の試行回数を、最初に決めておく(例:テストは質問セット一回分) • Dify 本体の費用(サーバーや Docker Desktop の利用条件)は、組織の契約で確認する 問いかけ:研修の試行回数の上限を、いくつに決めますか? 根拠は何ですか? 実務の前提 | 8/11 停止・見直し
⑦ 時間と進め方:本編に入る前の学習計画 段階 目安時間(案) 完了の目印 事前学習(前提の確認) 30〜60分 7つの柱の確認表が埋まっている 環境の準備(導入・起動) 60〜90分 Dify にログインできる。docker version が表示さ れる 本編(構築・検証) 約90〜180分 質問セットの結果を記録できる 振り返り・記録 30分 変更記録と受講記録を残した 問いかけ:環境の準備で詰まった時、何分で情報システムに相談しますか?(目安を決める) 実務の前提 | 9/11
前提チェックシート(受講前に本人が記入) No. 確認項目 OK NG時の相談先 1 Windows の版と仮想化が確認できた □ 情報システム 2 管理者権限またはインストール申請の手段がある □ 情報システム 3 Dify にログインできる(または環境の案内を受けた) □ Dify 管理者 4 OpenAI の利用と請求設定の承認を得た □ 管理責任者 5 扱うデータは架空または公開情報に限定した □ 情報セキュリティ部門 6 PowerShell で一行のコマンドを実行できた □ 講師・先行学習の教材 7 試行回数と費用の上限を決めた □ 管理責任者 実務の前提 | 10/11
参考と確認状況(前提の根拠) 項目 出典 状況 Dify の最小要件・Compose の版 docs.dify.ai(セルフホストの手順) 【確認済】検索で確認 Dify のモデル設定(プラグイン・APIキー) Dify Marketplace・モデル設定の説明 【確認済】検索で確認 WSL 2 の要件(仮想化・導入) learn.microsoft.com/windows/wsl/ 【要確認】今回は未アクセ ス API の料金・上限 OpenAI 公式 【要確認】最新の料金表で 確認 Docker Desktop の利用条件 Docker 公式 【要確認】組織の契約で確 認 実務の前提 | 11/11
2. 初期設定:Docker・Git・GitHub 収録元:初期設定_Docker_Git_GitHub.pptx(11枚)
初期設定:Docker・Git・GitHub 開発を始める前に、最初の一回だけ行う設定(Why・What・How つき) 凡例:【確認済】公式の内容を確認 / 【要確認】版・組織の方針で必ず確認
全体像:何がどこに関係するか PC(Windows・WSL) Git(履歴を記録) Docker(実行環境) Git は「変更の記録」、GitHub は「記録の共有」、Docker は「動かす環境」 問いかけ:Git と GitHub は同じものですか? 違いを一文で説明できますか? 初期設定:Docker・Git・GitHub | 2/11 GitHub(共有の場所)
Docker Desktop:初期設定と確認 インストール WSL 2 を有効化 WSL 統合を有効化 起動を確認 テスト実行 コマンド 意味 確認の目安 docker --version Docker の版を表示 版番号が出る docker version Client と Server の版を表示 Server が表示される docker run hello-world テスト用イメージを取得して実行 「Hello from Docker」が出る docker info 設定と状態の詳細を表示 エラーがないこと 問いかけ:Docker Desktop が起動していない時、docker version で何が見えますか? 初期設定:Docker・Git・GitHub | 3/11
Git:インストールと確認 Git を導入 ターミナルを開き直す git --version PATH を確認 次の設定へ コマンド 意味 注意 git --version Git の版を表示 表示されなければ PATH を確認 where git(Windows) Git の場所を表示 複数あると混乱するので一つに統一 git help 使えるコマンドの概要 詳細は git help コマンド名 問いかけ:git --version が見つからない時、最初に何を開き直しますか? 初期設定:Docker・Git・GitHub | 4/11
Git:初期設定(最初の一回だけ) コマンド 意味 Why(なぜ) git config --global user.name "名前" 記録に残る作成者名 誰の変更かを追えるようにする git config --global user.email "メール" 記録に残るメール GitHub のアカウントと一致させる git config --global init.defaultBranch main 新しいリポジトリの既定ブランチ名 チームの名称を揃える git config --global core.autocrlf input 改行コードの変換を設定 Windows の CRLF 差分を防ぐ git config --list --show-origin 設定の値と場所を表示 設定の確認 問いかけ:user.email を社用とプライベートで使い分ける理由は何ですか? 初期設定:Docker・Git・GitHub | 5/11
GitHub:アカウントと認証(Why・What・How) 項目 Why(なぜ) What(何か) How(どうする) アカウント 作業の共有と記録の場所のため GitHub の利用者登録 組織の方針でメールを選ぶ 二要素認証 アカウントの乗っ取り防止 ログインの追加確認 設定画面で有効化(要確認) Personal Access Token(PAT) パスワードの代わりに認証するため 期限と権限を持つ認証文字列 必要最小の権限・期限を設定 SSH 鍵 パスワードを使わず安全に接続するた め 公開鍵と秘密鍵の組 ssh-keygen で作り、公開鍵を 登録 問いかけ:PAT を、メモ帳やチャットに貼ってよいのはどんな場合ですか? 初期設定:Docker・Git・GitHub | 6/11
SSH 鍵の作成と接続確認(任意の認証方式) 鍵を作る 公開鍵を確認 GitHub に登録 接続を確認 秘密鍵は共有しない コマンド 意味 注意 ssh-keygen -t ed25519 -C "メール" ed25519 方式の鍵ペアを作る パスフレーズを設定することを推奨 cat ~/.ssh/id_ed25519.pub 公開鍵の内容を表示(登録用) 公開鍵のみ。秘密鍵は表示しない ssh -T [email protected] GitHub への接続を確認 初回は確認メッセージが出る(内容を確認 ) 問いかけ:秘密鍵のファイル(id_ed25519)を、誰にも渡さないために何をしますか? 初期設定:Docker・Git・GitHub | 7/11
最初のリポジトリ:clone・commit・push(意味の確認) clone(取得) 編集 add(記録の準備) commit(記録) push(共有) コマンド 意味 確認の目安 git clone URL リポジトリを複製する フォルダが作られる git status 変更の有無を表示 変更ファイルが並ぶ git add ファイル名 記録の対象に加える status に緑(準備済)で出る git commit -m "説明" 変更を記録する(理由を書く) git log --oneline で確認 git push GitHub へ送る GitHub の画面に反映される 問いかけ:commit メッセージに、何を書くと後で役立ちますか? 初期設定:Docker・Git・GitHub | 8/11
リスクと対応(初期設定でよくある事故) リスク 起きること 予防 対応 認証情報の漏えい(PAT・秘密鍵) 第三者による不正な操作 共有しない、期限と権限を最小化 直ちに失効・再発行。履歴の確認 .env など秘密ファイルのコミット 履歴に残り、消すのが難しい .gitignore を先に作る 情報システムに報告し、鍵を再発 行 誤った user.email 作業者が特定できない GitHub のアカウントと一致させる 設定を直し、以後の記録で確認 改行コードの差分大量発生 レビューが困難になる core.autocrlf と .gitattributes を統一 設定を見直し、取り直す Docker の未起動・権限不足 docker が使えず作業が止まる Desktop の起動と WSL 統合を確認 情報システムに権限を相談 初期設定:Docker・Git・GitHub | 9/11
初期設定チェックシート(本人が記入) No. 確認項目 OK 1 docker run hello-world が成功した □ 2 git --version が表示される □ 3 user.name と user.email を設定し、git config --list で確認した □ 4 GitHub にログインでき、二要素認証の状態を確認した □ 5 認証方式(PAT または SSH)を選び、保管場所を決めた □ 6 .gitignore で .env などの秘密ファイルを除外した □ 初期設定:Docker・Git・GitHub | 10/11
参考と確認状況 項目 出典 状況 Docker Compose の版(2.24.0 以上) docs.dify.ai(セルフホスト手順) 【確認済】検索で確認 Docker Desktop の設定・WSL 統合 docs.docker.com 【要確認】今回は未アクセス Git の設定(user・autocrlf) git-scm.com(Documentation) 【要確認】今回は未アクセス GitHub の認証(PAT・SSH) docs.github.com(Authentication) 【要確認】今回は未アクセス 二要素認証・組織のポリシー GitHub と組織の規程 【要確認】組織で確認 初期設定:Docker・Git・GitHub | 11/11
3. Dify 全教材(受講生用まとめ) 収録元:Dify_全教材_受講生用まとめ.pptx(180枚)
1. Dify入門(セクション1〜3) 収録元:Dify入門_受講生用スライド_セクション1-3.pptx(10枚)
Dify入門:ノーコードで作る生成AIアプリ 受講生用スライド | セクション1〜3 1 / 10
セクション1 導入 レクチャー1-1 この講座で作れるようになること • 学習目標:Difyのアプリ種類を選べる • RAGの流れを説明できる • 社内文書を使うChatflowを作れる • 失敗の原因を切り分けられる 2 / 10
セクション1 導入 レクチャー1-2 Difyとは何か • Difyは、LLMを使うアプリを画面操作で組み立てる開発基盤 • ノーコード:プロンプトや処理の流れを組み立てる • ローコード:必要な部分だけコードで拡張 • LLMは複数のモデルから選んで差し替え可能 3 / 10
セクション1 導入 レクチャー1-3 受講前の確認と進め方 • 講座の流れ:原理 → 仕組み → ハンズオン → 評価 • ハンズオンでは1回に1か所だけ変えて確認する • 環境:Difyの利用アカウントを事前に用意 • 修了テストの合格基準は後日確定 4 / 10
セクション2 LLMの基礎 レクチャー2-1 LLMは「次にくる言葉」を確率で選ぶ • LLMは、続く言葉を確率にもとづいて一つずつ選んで文章を作る • 正しい答えを調べて返しているわけではない • もっともらしい誤り(幻覚・ハルシネーション)が混じることがある 5 / 10
セクション2 LLMの基礎 レクチャー2-2 プロンプトは「指示書」 • プロンプトはモデルへの指示書 • 役割・回答の範囲・回答形式を明記すると出力が安定する • プロンプトだけでは社内の特定情報は分からない 6 / 10
セクション2 LLMの基礎 レクチャー2-3 根拠を渡すという発想 • 社内情報は、答えの前に文書を渡すことで補える • 根拠を示せると、誤りを確認しやすくなる • 根拠があっても誤読は起きる(セクション6で扱う) 7 / 10
セクション3 アプリ種類 レクチャー3-1 5つのアプリ種類 • Chatflow、Workflow、チャットボット、エージェント、テキストジェネレー ター • 公式が推奨するのはChatflowとWorkflow 8 / 10
セクション3 アプリ種類 レクチャー3-2 WorkflowとChatflowの違い • Workflow:一回の入力に対して処理を実行し、結果を返す • Chatflow:会話を続け、会話履歴を踏まえて答える • 会話履歴は、モデルが自然に覚えるのではなくDifyが渡している 9 / 10
セクション3 アプリ種類 レクチャー3-3 用途からアプリ種類を選ぶ • 判断の順番:1. 会話が続くか 2. 一回で終わるか 3. ツールで作業させるか • 社内FAQは会話が続くため、Chatflowを使う • エージェントは概要の紹介にとどめる 10 / 10
2. Dify中堅向け(業務組み込み) 収録元:Dify中堅向け_受講生用スライド.pptx(9枚)
Dify中堅向け:業務システムへの組み込みと検索 品質 DXエンジニア・中堅エンジニア向け | 約60分 | 受講生用スライド 1 /9
第1部 設計の観点 レクチャーM-1 中堅が設計で見る3つの観点 • 要件:何を、誰が、どの精度で使うか • データ:どこにあり、誰が更新し、どの権限で見せるか • 運用:変更、監視、ロールバックを誰が担うか 2 /9
第2部 業務システムとの連携 レクチャーM-2 呼ぶ Service APIでアプリを業務システムから • Difyのアプリを、外部システムからAPIとして呼び出せる • アプリごとにAPIキーを発行し、用途ごとに分ける • レスポンスの受け取り方(一括・ストリーミング)を選ぶ 3 /9
第3部 検索品質と外部データ レクチャーM-3 める 検索品質:Top K・スコア閾値を測って決 • Top K:検索で取り出す件数。多すぎると関係のない情報が混ざる • Score threshold:類似度の下限。Rerank 有効時に効くとの公式注記あり( 版で要確認) • 感覚で決めず、同じ質問で結果を比べて決める 4 /9
第3部 検索品質と外部データ レクチャーM-4 APIの契約 外部ナレッジ連携:External Knowledge • Difyは endpoint に /retrieval を付けて POST する • リクエスト:knowledge_id、query、top_k、score_threshold • レスポンス:records の content・score・title・metadata • metadata は null ではなく空のオブジェクトにする 5 /9
第4部 ワークフローと評価 レクチャーM-5 ワークフロー設計:分岐とエラー処理 • 外部APIが失敗した場合の分岐を必ず用意する • HTTPリクエストノードの結果を条件で振り分ける • 失敗時に利用者へ返す文言を決めておく 6 /9
第4部 ワークフローと評価 レクチャーM-6 る 評価の仕組み:質問セットで回帰テストす • 本番前に、質問と期待する根拠の組を20問程度用意する • 設定を変えるたびに全問を再実行する • 変更前後の結果を表で比べ、悪化した問いを確認する 7 /9
第5部 運用と確認 レクチャーM-7 APIキー 運用:環境分離・アップグレード・ログと • 開発・検証・本番を分け、本番に直接試作しない • アップグレードは検証環境で先に行い、リリースノートを確認する • APIキーは定期的に見直し、不要になったものを無効化する 8 /9
第5部 運用と確認 レクチャーM-8 まとめと確認課題 • 要件・データ・運用の3観点で設計を見る • Service APIとExternal Knowledge APIの契約を理解する • 検索設定と分岐は、質問セットで比べて決める • 確認課題:自社の業務で1つ、外部連携の設計案を書く 9 /9
3. 8段階スロープ(受講生用) 収録元:Dify開発環境_8段階スロープ_受講生用.pptx(11枚)
Dify開発環境構築 8段階スロープで、たのしい・むずかしいを行き来しながら進む 対象:Windows(WSL 2)で Dify を動かしたい方 | 受講生用スライド 1 / 11
8段階の波:たのしい → むずかしい → 達成 の繰り返し 最難関 むずかしい むずかしい やや難 やさしい 達成 達成 たのしい 1 緑:たのしい・達成 Dify開発環境 | 2/11 2 橙:やや難 3 4 赤:むずかしい・最難関 5 6 7 8
1 全体像を知る 難易度:たのしい 問いかけ ブラウザ Dify開発環境 | 3/11 Q1. 入口(web)とAPIは、どちらが ブラウザから直接つながる? 入口 (web/nginx) api DB・キャッシュ worker Q2. データベースは、画面とAPIのど ちらから使われる?
2 Docker Desktopを起動する 難易度:やさしい 問いかけ Q1. Docker Desktopを閉じると、動 いているDifyはどうなる? Windows Docker Desktop Docker Desktopが停止するとコンテナも止まります Dify開発環境 | 4/11 停止? Q2. WindowsとWSLのどちらで docker コマンドを打つ?
3 WSL 2とファイルの置き場所 難易度:むずかしい 問いかけ Windows側 C:\ /mnt/c(遅い) Q1. ソースは C:\ と ~/ のどちらに置 く? その理由は? Q2. 同じ作業が遅い原因を、2つの場 所の違いで説明できる? WSL内 ~/dify(推奨) Dify公式:ソースとデータはLinux側に置く Dify開発環境 | 5/11
4 ソースコードを取得する 難易度:達成 問いかけ GitHub (Dify) Q1. git clone の結果、どのフォルダ ができる? git clone ~/dify(ローカル) ~/dify/docker へ移動 Dify開発環境 | 6/11 Q2. docker フォルダに移動してから 作業するのはなぜ?
5 .envを作って設定する 難易度:むずかしい 問いかけ cp .env.example .env(優先) Q1. .env と envs/*.env に同じ値があ ったら、どちらが優先される? Q2. .env.example をそのまま使うと 、何が足りない可能性がある? envs/*.env(上書き用テンプレート) .env の値が envs/ より優先される Dify開発環境 | 7/11
6 コンテナを起動して確認する 難易度:やや難 問いかけ docker compose up -d web api Q1. 全部 running なのに画面が開かな い。最初に何を確認する? Q2. ps と logs は、それぞれ何を教え てくれる? worker docker compose ps で全部 running か確認 Dify開発環境 | 8/11 db
7 初期設定をしてログインする 難易度:達成 問いかけ localhost/install 管理者を作成 Q1. /install で作った管理者アカウン トは、どのアドレスでログインする ログイン ? Q2. 初期設定を一度完了したあとも、 /install を開けるのはなぜ困る? 開かないときは、ps → logs の順で見る Dify開発環境 | 9/11
8 開発者向け:ソースから起動する 難易度:最難関 問いかけ Q1. APIを止めると、Webの画面はど うなる? ミドルウェア (Docker) API (手元) 順番:ミドルウェア → API → Web Dify開発環境 | 10/11 Web (手元) Q2. ミドルウェアを先に起動する理由 は?
まとめ:難しい段の後には、必ず達成がある 問い:次に詰まりそうなのは、どの段ですか? 問い:その段で、最初に確認する項目は何ですか? 問い:環境が動いたら、最初に何を試しますか? 11 / 11
4. Docker・WSL 開発 Udemy講座(受講生 用) 収録元:Dify_Docker_WSL開発_Udemy講座_受講生用.pptx(83枚)
Dify × Docker × WSL 2 で学ぶ開発環境 原理原則から仕様・運用まで(DXエンジニア向け・法人研修レベル) 受講生用 | 約90分 | 公式ドキュメント準拠
対象と前提 • 対象:Windows(Windows 10/11)を使うDXエンジニア・新人〜中堅エンジニ ア • 前提:Dify・Docker・WSLの経験は不要。ファイルとフォルダの基本操作ができ れば十分 • 到達点:自分のPCでDifyを起動し、設定と基本の確認ができる • 範囲外:クラウド版Difyの操作、Difyのアプリ開発の詳細、本番運用の設計 Dify Docker WSL開発 | 2/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
目次(クリックで移動) A. 原理原則 A1 / A2 p.6 B. WSL 2 と Docker 環境 B1 / B2 p.8 C. 起動と設定 C1 / C2 p.10 D. 開発環境 D1 / D2 p.12 E. 仕様と連携 E1 / E2 p.14 F. 運用と修了 F1 / F2 p.16 コマンド早見表(CMD・PowerShell・WSL・Docker・VSCode) 実習で参照 p.18 コマンドの意味 各コマンドの読み方 p.24 よくあるエラー 症状・原因・対処 p.25 間違いやすいポイント 誤りの予防 p.27 保守担当向け 点検・障害対応・引き継ぎ p.28 ネットワーク関連 通信経路・トラブル・確認コマンド p.30 各仕様・保守方法・部品ごとの更新 部品の役割と更新の手順 p.33 学ぶ・もっと学びたいとき 学習の順番と次に読む資料 p.36 業務で役立つネットワークの原理原則 IP・ポート・DNS・HTTP・プロキシ p.38 Dify 構成全体(nginx を含む) 構成図・要素一覧・nginx・分離・確認 p.41 周辺知識(Why・What・How) 環境変数・Git・Docker・LLM用語 p.46 Dify 中級・上級(ワークフロー・検索・API・権限・性能) 10ページ p.51 上級者になるために・責任者 役割・思考・承認・インシデント・育成 p.61 確認テストと得点 Dify Docker WSL開発 | 3/8310問・得点の判定(案) 目次 | 基礎 p.70 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
図解:Dify を動かす全体の関係 Windows(PC) WSL 2(Ubuntu) ~/dify(ソース・.env) Docker Desktop (コンテナの実行先) ブラウザ http://localhost VSCode(WSL 接続) Dify コンテナ群 (web・api・worker・DB) ※ 編集は VSCode、実行は WSL の Ubuntu、表示はブラウザ Dify Docker WSL開発 | 4/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
関係性の補足:何がどこに関わるか 要素 役割 ほかとの関係 Windows PC本体のOS。WSL と VSCode を導入する WSL・Docker・VSCode の土台 WSL 2(Ubuntu) Windows の中で動く Linux。Dify のソースを置く docker コマンドを実行し、~/dify で作 業する Docker Desktop コンテナを動かす仕組み。WSL 2 と連携する Dify のコンテナ群の実行先 Docker Compose 複数のコンテナを一度に起動・停止する docker/ の設定を読んで Dify を構成 Dify(コンテナ群) web・api・worker・DB などの集まり ブラウザから localhost で利用 .env と envs/ 設定値。.env の値が envs/ より優先される Dify の動作を決める VSCode ファイルを編集するエディタ。WSL 拡張で Ubuntu に接続 ~/dify の設定や手順を編集する Dify Docker WSL開発 | 5/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
A1 Dockerの基本:イメージ・コンテナ・ボリューム A. 原理原則 | 約6分 • イメージ:アプリの設計図(読み取り専用) 問いかけ • コンテナ:イメージから起動した実行中の箱 • ボリューム:コンテナを消してもデータを残す仕組み Q1. コンテナを削除したら、ボリューム のデータはどうなる? • Difyはこれらを docker compose でまとめて起動する イメージ Dify Docker WSL開発 | 6/83 コンテナ Q2. イメージとコンテナは、どちらが「 実行中」のもの? 停止・削除 ボリューム(データ) 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
A2 Difyの構成要素と役割 A. 原理原則 | 約7分 • 入口(nginx など)が画面と受付を担う 問いかけ • api:アプリの処理とAPIを担当 • worker:非同期の処理(文書の取り込みなど) Q1. 文書を取り込む重い処理は、どのサ ービスが担当しそう? • データベース・キャッシュ・ベクトルDBが情報を保持 ブラウザ Dify Docker WSL開発 | 7/83 入口 web / api Q2. ブラウザが直接つなぐのは、どのサ ービス? worker DB・キャッシュ 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
B1 WSL 2 と Docker Desktop の役割分担 B. WSL 2 と Docker 環境 | 約6分 • WSL 2:Windows の中で Linux を動かす仕組み 問いかけ • Docker Desktop:WSL 2 上でコンテナを動かす土台 • docker コマンドは WSL の Ubuntu から実行する Q1. docker コマンドは、Windows と WSL のどちらで打つ? • 動作要件:Docker Compose 2.24.0 以上(公式) Windows Dify Docker WSL開発 | 8/83 WSL 2 (Ubuntu) Q2. Docker Desktop を閉じると何が起き る? Docker Desktop コンテナ 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
B2 ファイルの置き場所とパフォーマンス B. WSL 2 と Docker 環境 | 約6分 • ソースとデータは WSL 内の ~/ に置く(公式の推奨) 問いかけ • /mnt/c は Windows 側のファイルで、動作が遅くなる ことがある Q1. ソースは C:\ と ~/ のどちらに置く? 理由は? • 確認:pwd で現在の場所を確認する Q2. 作業が遅いとき、最初に確認するの は? C:\(遅い) Dify Docker WSL開発 | 9/83 /mnt/c ~/dify(推奨) 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
C1 ソース取得と設定ファイル(.env と envs/) C. 起動と設定 | 約7分 • git clone で ~/dify を取得し、docker フォルダへ移動 問いかけ • cp .env.example .env で設定ファイルを作る • envs/ のテンプレートで上書きできる Q1. .env と envs/*.env に同じ値があった ら、どちらが優先? • .env の値が envs/ より優先される .env.example Dify Docker WSL開発 | 10/83 cp Q2. .env.example をそのまま使うと何が 危ない? .env(優先) envs/*.env 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
C2 起動・確認・初期設定 C. 起動と設定 | 約7分 • docker compose up -d で起動する 問いかけ • docker compose ps で全サービスの状態を確認する • http://localhost/install で管理者を作成する Q1. 全部 running なのに画面が開かない 。最初の確認は? • 設定変更後は down → up -d で反映する up -d Dify Docker WSL開発 | 11/83 ps(状態) Q2. 設定を変えたあと、何をすると反映 される? logs(原因) /install 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
D1 ミドルウェアとアプリ本体を分けて起動する D. 開発環境 | 約7分 • ミドルウェア(DBなど)は Docker で起動する 問いかけ • API と Web は手元で動かし、変更をすぐ確認できる • 起動順:ミドルウェア → API → Web Q1. API を止めると Web の画面はどうな る? • 公式の手順で指定されたプロファイルを使う ミドルウェア(Docker) Dify Docker WSL開発 | 12/83 API(手元) Q2. ミドルウェアを最初に起動する理由 は? Web(手元) 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
D2 API・Webの開発環境(版の確認を前提に) D. 開発環境 | 約8分 • api/.env を作り、SECRET_KEY を必ず設定する 問いかけ • 依存関係の管理方法(Poetry 等)は版ごとに公式で確 認 Q1. SECRET_KEY が空のまま起動すると 、何を見直す? • Web は .env.local を作り、開発用の値を設定する • Python・Node.js のバージョンは公式ページの指定に 従う Q2. 依存関係の手順が違うとき、どこを 確認する? api/.env Dify Docker WSL開発 | 13/83 SECRET_KEY 依存関係 起動・確認 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
E1 Service API:アプリを業務システムから呼ぶ E. 仕様と連携 | 約7分 • アプリごとに API キーを発行する 問いかけ • キーは用途ごとに分け、不要になったら無効にする • 応答の受け取り方(一括・ストリーミング)を選ぶ Q1. 同じキーを複数の業務システムで共 有すると、何が困る? • パラメータ名と上限は版ごとに公式で確認 業務システム Dify Docker WSL開発 | 14/83 Service API Q2. ストリーミングと一括の違いは、利 用者のどこに効く? アプリ 回答 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
E2 ナレッジ検索と External Knowledge API の仕様 E. 仕様と連携 | 約8分 • • 問いかけ Top K:取り出す件数(Rerank有効時に効く。版で要 確認) Score threshold:類似度の下限(同じくRerank有効時 。版で要確認) • External Knowledge API:endpoint に /retrieval を付 けて POST • リクエスト:knowledge_id・query・retrieval_setting • レスポンス:records の content・score・title・ metadata Dify Dify Docker WSL開発 | 15/83 POST /retrieval Q1. Top K を大きくすると、何が起きや すい? Q2. metadata に null を入れると、何がま ずい? records 回答に利用 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
F1 環境の分離とバージョンアップ F. 運用と修了 | 約7分 • 開発・検証・本番を分け、本番で直接試さない 問いかけ • アップグレードは検証で先に行い、リリースノートを 確認する Q1. アップグレードで最初に確認すべき 資料は? • .env.example の差分を確認し、必要な値だけ反映する • ロールバック用に旧タグ・.env・DBダンプを控える( マイグレーション後は旧タグだけでは戻せない) Q2. 失敗したとき、戻すために必要なも のは? 開発 Dify Docker WSL開発 | 16/83 検証 本番 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
F2 トラブル切り分けの型と修了課題 F. 運用と修了 | 約8分 • 型:状態(ps)→ 原因(logs)→ 設定(.env)→ 再起 動 問いかけ • 一度に1か所だけ変えて結果を確認する Q1. 原因が分からないとき、最初に変え てはいけないものは? • 修了課題:自社の業務で、環境構築の手順書を1枚にま とめる Q2. 修了課題の手順書に必ず入れる項目 は? ps Dify Docker WSL開発 | 17/83 logs .env 再起動 確認 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
CMD(コマンドプロンプト)の基本 目的 コマンド 注意(躓きやすい点) 現在の場所を見る cd 引数なしで現在のフォルダを表示 別のドライブへ移動 cd /d D:\work /d を付けないとドライブは変わらない フォルダの中身を見る dir 一覧を表示 コマンドの場所を調べる where docker 見つからない場合はPATH未設定を疑う 環境変数を見る echo %UserProfile% 値が展開されて表示される ホームへ戻る cd /d %UserProfile% CMDでは ~ は使えない Dify Docker WSL開発 | 18/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
PowerShell の基本 目的 コマンド 注意(躓きやすい点) 現在の場所を見る Get-Location(pwd) 表示される場所を毎回確認する フォルダを移動する Set-Location C:\work(cd) パスに空白があれば "..." で囲む 環境変数を見る $env:UserProfile $env: の後に変数名を付ける Webの内容を取得する curl.exe -s <URL> curl だけでは別のコマンドになる ファイルを開く notepad "$env:UserProfile\.wslconfig" ファイルがなければ新規作成される スクリプトが拒否される Get-ExecutionPolicy 原因の確認に使う(変更は組織の方針に 従う) Dify Docker WSL開発 | 19/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
WSL の基本(PowerShell・CMDから実行) 目的 コマンド 注意(躓きやすい点) WSL を導入する(管理者) wsl --install 再起動が必要な場合がある 一覧とバージョンを見る wsl -l -v Ubuntu が VERSION 2 か確認 VERSION 1 を 2 に変える wsl --set-version Ubuntu 2 完了まで時間がかかることがある Ubuntu に入る wsl -d Ubuntu プロンプトが変われば成功 WSL を停止する wsl --shutdown .wslconfig を変えた後に実行する Ubuntu から Windows を見る cd /mnt/c/Users Windows側は遅い。作業はWSL内で行 う Dify Docker WSL開発 | 20/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Docker コマンド(WSLのUbuntuで実行) 目的 コマンド 注意(躓きやすい点) バージョンを確認する docker compose version 2.24.0 以上であること 起動する docker compose up -d ~/dify/docker で実行する 状態を確認する docker compose ps 全サービスが running か確認 ログを見る docker compose logs --tail=100 api サービス名は ps で確認する 停止する docker compose down データは残る(ボリュームは消えない) イメージを取得する docker compose pull 途中で止まったら再実行する Dify Docker WSL開発 | 21/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
VSCode の基本 目的 コマンド 注意(躓きやすい点) WSLのフォルダを開く code . Ubuntu の中で実行する バージョンを確認する code --version 未導入ならPATH設定を確認 コマンドパレットを開く Ctrl + Shift + P 操作名を入力して実行する PATH に code を登録する Shell Command: Install 'code' command in PATH パレットから実行し、ターミナルを開き 直す ターミナルを開く Ctrl + ` WSL接続中は Ubuntu のシェルが開く WSL に接続されているか確認 左下に「WSL: Ubuntu」と表示 WSL拡張機能が必要 Dify Docker WSL開発 | 22/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
危険なコマンド(実行前に必ず確認) 目的 コマンド 注意(躓きやすい点) ボリュームも削除する docker compose down -v DBとアップロードデータが消える データフォルダを削除する rm -rf volumes バックアップを取ってからのみ実行 未使用のイメージを広く削除 docker system prune -a 再取得に時間がかかる。対象を確認する 未コミットの変更を捨てる git reset --hard 作業中の変更が失われる Ubuntu環境を丸ごと削除 wsl --unregister Ubuntu 環境全体が消える。復元できない Dify Docker WSL開発 | 23/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
コマンドの意味:分解して読む コマンド 部品の意味 何をするか docker compose up -d docker | compose(Composeの機能)| up(起動)| d(バックグラウンドで実行) 設定ファイルに書いたサービス をまとめて起動 docker compose ps ps(process status:状態を表示) 各サービスが running か確認 docker compose logs --tail=100 api logs(ログ)| --tail=100(末尾の100行)| api(サービ ス名) 問題の原因を探す docker compose down down(停止して後片付け) 停止する。ボリュームは既定で は残る docker compose down -v -v(volumes:ボリュームも削除) データも消える。注意して実行 wsl -l -v wsl | -l(一覧)| -v(詳細表示) Ubuntu の VERSION を確認 wsl --set-version Ubuntu 2 --set-version(WSLの世代を指定)| Ubuntu(ディスト リビューション名) VERSION 1 を 2 に変える cp .env.example .env cp(コピー)| 元のファイル | 新しいファイル名 設定ファイルを作る code . code(VSCodeを起動)| .(今いるフォルダ) フォルダを VSCode で開く Dify Docker WSL開発 | 24/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
よくあるエラー(1/2):接続・起動まわり 症状・間違い 原因 対処・正しい方法 docker が接続できない Docker Desktop が起動していない、また はWSL統合が無効 Docker Desktop を起動し、Ubuntu を WSL Integration で有効にする docker compose が使えない 旧版の docker-compose、または Compose 2.24.0 未満 docker compose version で確認し、2.24.0 以上へ更新 ポートが使用中で起動しない 同じポートを使うソフトやコンテナがある (port is already allocated) docker ps と競合ソフトを確認。.env の公 開ポートを変える /install が開かない 起動直後で待機中、または一部サービスが 未起動 ps で全 running を確認し、数分待ってから 再読込。logs で原因を見る 改行コードの警告が出る Windows の自動変換(LF → CRLF) git config --global core.autocrlf input を設 定し、ファイルを取り直す code が認識されない VSCode の PATH が未登録 コマンドパレットで PATH 登録し、ターミ ナルを開き直す Dify Docker WSL開発 | 25/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
よくあるエラー(2/2):設定・実行場所・画面まわり 症状・間違い 原因 対処・正しい方法 .env を変えても反映されない 再起動していない docker compose down → docker compose up -d 特定のサービスが再起動を繰り返 す 必須の値の不足や誤り docker compose logs <サービス名>。.env と .env.example を比べる ファイルが見つからないと表示さ れる docker フォルダの外で実行している pwd で場所を確認し、cd ~/dify/docker へ 移動する Windows から WSL のファイルが 編集できない 置き場所や参照方法の誤り エクスプローラーで \\wsl$\Ubuntu を開 いて参照する イメージの取得(pull)が失敗す る ディスク容量不足、またはネットワーク docker system df で容量を確認。ネットワ ークを確認して再実行 画面は開くが回答が返らない モデルの設定やAPIキーが未設定、または誤 り 設定画面でモデルとAPIキーを確認する Dify Docker WSL開発 | 26/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
間違いやすいポイント 症状・間違い 原因 対処・正しい方法 docker compose を ~/dify で実 行する compose の設定ファイルは docker/ にある cd ~/dify/docker に移動してから実行する .env.example を直接編集する テンプレートが変わると、次の更新で困る .env をコピーして、その .env を編集する C:\ の下で作業する ファイル操作が遅くなることがある ~/dify(WSL内)で作業する down -v を「停止」の意味で使う ボリューム(DB・アップロード)が消える 停止は docker compose down だけにする 設定を変えて再起動しない 変更が反映されない down → up -d で反映させる エラーのログを見ずに再インスト ールする 原因が残ったまま、同じ問題が再発する ps → logs の順で原因を特定する APIキーをコードに直接書く 共有時に漏えいしやすい 環境変数や設定ファイルで管理し、リポジ トリに含めない Dify Docker WSL開発 | 27/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
保守担当向け:点検チェックリスト 症状・間違い 原因 対処・正しい方法 毎日 全サービスが running か docker compose ps 毎日 直近のエラーがないか docker compose logs --tail=100 api 週次 ディスクの使用量 docker system df(OS側の空き容量も確認 ) 週次 ナレッジの処理に失敗していないか Dify の管理画面で文書の状態を確認 月次 不要になったAPIキーの無効化 アプリのAPIキー画面で棚卸し 月次 バックアップの取得と復元の確認 volumes/ と docker/.env を退避し、復元手 順を試す 随時 新しいリリースの確認 GitHub のリリース一覧で確認。検証で先に 試す Dify Docker WSL開発 | 28/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
保守担当向け:障害時の切り分けとバックアップ 症状を記録 ps で状態 logs で原因 .env・直前の変更を 確認 再起動 確認・記録 • 退避する対象:DBのダンプ(pg_dump)、volumes/(アップロード等)、docker/.env と envs/ • DBダンプは停止前に取り、その後 docker compose down で停止する(起動中の volumes 退避は 避ける) • APIキーは、台帳に用途と発行日を記録し、共有は安全な方法で行う • 変更の履歴(いつ・誰が・何を変えたか)を残す • 引き継ぎ資料には、この講座の確認チェックリストを添付する Dify Docker WSL開発 | 29/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
ネットワーク:通信経路の全体像 ブラウザ(Windows) localhost Docker の公開ポート 入口(web) api・worker・DB(内部 ネットワーク) • localhost は、自分の PC(この端末)を指す特別な名前です • Docker は、.env で決めた公開ポートを Windows 側へ転送します • WSL 2 は独自の仮想ネットワークを持ちます。通常は localhost で届きますが、環境によって異なること があります • Dify の内部の通信は、Docker の内部ネットワークでサービス名を使って行われます • 既定の設定では、自分の PC からのみ開く想定です。社内へ公開する設定は、管理者が設計します Dify Docker WSL開発 | 30/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
ネットワーク関連のトラブル対応 症状・間違い 原因 対処・正しい方法 localhost に接続できない サービスが未起動、または公開ポートの設 定違い docker compose ps で状態確認。.env の公 開ポートを確認 ポートが使用中 別のソフトが同じポートを使っている netstat -ano | findstr :80 で PID を確認し 、競合を止める イメージ取得が社内で失敗 企業のプロキシ設定が未対応 Docker Desktop の Proxies 設定。情報シ ステム部門に確認 ファイアウォールで遮断 Windows の防火壁ルールで通信がブロック 許可の追加は管理者の承認を得て行う WSL からインターネットに出られ ない DNS や VPN の影響、WSL の不調 wsl --shutdown のあと再起動。VPN 接続 の影響を確認 外部のモデルAPIに接続できない 社内の許可リスト未登録、APIキーの誤り 通信先の許可を情報システムに依頼し、キ ーを確認 別のPCから開けない 既定では自分の PC からのみ開く設計 社内公開は、管理者が公開方法と認証を設 計する Dify Docker WSL開発 | 31/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
ネットワーク確認コマンド 症状・間違い 原因 対処・正しい方法 ポートの使用状況(CMD) netstat -ano | findstr :80 最後の数字(PID)で、使っているプロセ スを調べる 接続確認(PowerShell) Test-NetConnection -ComputerName localhost -Port 80 TcpTestSucceeded が True なら接続でき る HTTP の応答確認(PowerShell) curl.exe -I http://localhost/install curl.exe と書く(curl だけでは別のコマン ド) WSL の IP アドレス(Ubuntu) hostname -I 表示された値は通常、WSL 内部のアドレス 名前の解決(PowerShell) nslookup github.com 失敗すると DNS の問題を疑う Docker のネットワーク一覧 docker network ls Dify 用のネットワークが作られているか確 認 Dify Docker WSL開発 | 32/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
各仕様:部品ごとの役割と設定場所 部品 役割 設定場所 確認コマンド web(入口) 画面の配信と受付。公開ポートを持つ docker/.env(公開ポート) docker compose ps api アプリの処理とAPIを担当 docker/.env、api/.env(開発 時) docker compose logs --tail=100 api worker 文書の取り込みなど非同期の処理 docker/.env docker compose logs --tail=100 worker DB(PostgreSQL 等) アプリのデータを保存する docker/.env、volumes/ docker compose ps キャッシュ(Redis 等) 一時的なデータを高速に扱う docker/.env docker compose ps ベクトルDB(Weaviate 等 ) ナレッジの検索用データを保存する docker/.env、envs/ docker compose ps Docker Compose サービスの起動定義をまとめる docker-compose の設定ファ イル docker compose version Dify Docker WSL開発 | 33/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
保守方法:変更を安全に進める手順 変更内容を決める 影響範囲を確認 検証環境で試す 本番へ反映 • 一度に変えるのは一つだけにする。原因の切り分けがしやすくなる • 変更の前に、旧タグ・.env・volumes/ の退避を済ませる • 確認は「画面」「回答」「ログ」の3点で行う • 変更記録(日付・変更内容・担当・結果)を、毎回同じ書式で残す • 不具合が出たら、直前の変更から戻して原因を調べる Dify Docker WSL開発 | 34/83 動作を確認 記録を残す 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
各部品だけ更新する 対象の部品を確認 • • • 影響範囲を確認 検証で単独更新 ログと画面を確認 記録を残す 目的 コマンド 注意 部品の状態を見る docker compose ps 更新前後で running を比べる 部品のイメージを取得 docker compose pull api 取得先のタグを事前に確認する 部品だけ作り直して起動 docker compose up -d api 依存サービスも起動することがある 部品を一時停止 docker compose stop api データは消えない 停止した部品を再開 docker compose start api 停止中の影響範囲を確認してから行う 部品のログを見る docker compose logs --tail=100 worker 更新後の異常を早く見つける api と web などの版は、そろえるのが原則(公式の案内と照らして確認する) .env や設定ファイルを変える更新は、部品だけでなく全体で扱う docker compose down -v は使わない(データが消える) Dify Docker WSL開発 | 35/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
学ぶ:学習の順番 公式の Quick start ローカルで起動 アプリを作る ナレッジと検索 • 最初は、公式の手順どおりに一度動かすことを優先する • アプリの種類(Workflow・Chatflow など)を一つずつ試す • 検索の設定は、同じ質問で比べながら決める • 保守は、変更記録と検証の習慣から始める Dify Docker WSL開発 | 36/83 API連携 保守と更新 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
もっと学びたいとき(次に読む資料) Dify 公式:基本概念(アプリの種類) https://docs.dify.ai/ja/learn/key-concepts Dify 公式:セルフホスト・インストール Dify 公式:External Knowledge API Dify:リリースノート(GitHub) https://docs.dify.ai/en/self-host/use-dify/knowledge/external-knowledge-api.md https://github.com/langgenius/dify/releases Docker:Compose のドキュメント Microsoft:WSL のドキュメント https://docs.dify.ai/en/getting-started/install-self-hosted https://docs.docker.com/compose/ https://learn.microsoft.com/windows/wsl/install • 学んだことを、自社の小さな業務で一度試すと定着しやすい • • 公式のリリースノートを、月に一度は読む習慣をつける エラーに出会ったら、症状・原因・対処を自分の言葉で記録する Dify Docker WSL開発 | 37/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
原理原則(1/3):名前から届くまで 名前(例:localhost) DNS(名前→IP) IPアドレス(相手の場 所) ポート(どのサービス か) アプリ(HTTP等) • IPアドレスは、ネットワーク上の機器の住所にあたる • ポートは、同じ機器の中で「どのサービスへ届けるか」を示す番号(例:80・443・5432) • DNSは、名前(例:github.com)を IP アドレスに変換する仕組み • Dify の入口は既定でポート80(HTTP)。HTTPS は 443 が一般的 • 「届かない」問題は、名前→IP→ポート→アプリの順に切り分ける Dify Docker WSL開発 | 38/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
業務で役立つ:HTTP のステータスコード 番号の範囲 意味 業務での例 2xx(成功) 要求が正しく処理された 200:画面が正常に表示される 3xx(転送) 別の場所へ案内された 301:アドレスが恒久的に変わった 4xx(利用者側の問題) 要求の内容や権限に問題がある 401:認証が必要。404:アドレスが違う 5xx(サーバ側の問題) サーバが処理できなかった 502:nginx は応答したが後段が応答しない 504(ゲートウェイの時間 切れ) 後段の応答が時間内に来なかった 処理が重い、または後段が停止している 確認のしかた ブラウザの開発者ツール、curl.exe -I 番号と症状を組にして記録する Dify Docker WSL開発 | 39/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
原理原則(3/3):プロキシとNAT 社内から外へ: 利用者のPC 正方向プロキシ(社内の 出口) インターネット リバースプロキシ(nginx ) web・api(社内) 外から内へ: 外部の利用者 • 正方向プロキシは、社内から外へ出る通信を中継して管理する • • リバースプロキシは、外から来た通信を受けて、内側のサービスへ渡す(Dify の nginx の役割) ファイアウォールは、許可したポートと通信だけを通す • NAT は、家庭や社内の複数の機器が、一つの IP アドレスで外と通信する仕組み • DHCP は、機器に IP アドレスを自動で割り当てる仕組み(IP が変わる理由の一つ) Dify Docker WSL開発 | 40/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Dify 構成全体図(代表的な構成) web(画面) 利用者(ブラウザ) nginx(入口) api(処理・API) worker(非同期) plugin_daemon 内部ネットワーク(Docker) db(PostgreSQL) redis weaviate(ベクトルDB) sandbox(コード実行) ssrf_proxy(外部中継) 外部(モデル提供元など) Dify Docker WSL開発 | 41/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Dify 構成要素の一覧 要素 役割 主な通信先・ポート nginx 入口。リバースプロキシとして通信を振り分ける 80(HTTP)・443(HTTPS) web 画面(フロントエンド)を配信する nginx 経由で利用 api アプリの処理とAPIを担当する db・redis・weaviate・sandbox worker 時間のかかる処理を非同期で実行する redis(キュー)・db db(PostgreSQL 等) アプリのデータを保存する 5432 redis キャッシュと、非同期処理のキューに使う 6379 weaviate(ベクトルDB) ナレッジの検索用データを保存する 8080 sandbox コードの実行環境を分けて提供する 8194 Dify Docker WSL開発 | 42/83 ssrf_proxy 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考 外部への通信を中継して制御する(Squid) 3128
nginx の役割と設定 利用者 nginx(80 / 443) web(画面) api(処理) • nginx は Dify の入口。外からの要求を受け、web と api へ振り分ける(リバースプロキシ) • 公開ポートは .env の NGINX_PORT(既定 80)と NGINX_SSL_PORT(既定 443)で決まる • HTTPS を使う場合は、NGINX_HTTPS_ENABLED と証明書の設定が必要(管理者が行う) • アップロードの上限や待ち時間は、NGINX_ で始まる設定に関係する • 502 は nginx が後段から応答を受けられなかったとき、504 は時間切れのときに見られる Dify Docker WSL開発 | 43/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
ネットワークの分離:Docker の内部と外部 ネットワーク 何のためか 例(版により異なる) default(既定) サービス同士が名前で通信する内部の通路 api → db、api → redis ssrf_proxy_network 外部通信を、必ず ssrf_proxy を経由させる api・sandbox → ssrf_proxy 公開ポート(nginx) 外部の利用者が入ってくる唯一の入口にする 80・443 のみ公開 内部だけのサービス 外から直接届かないようにする db・redis・weaviate は公開しな い Dify Docker WSL開発 | 44/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Dify 構成の確認コマンド 目的 コマンド 読み方 サービスの名前を一覧する docker compose config --services この版でのサービス名を確認する 状態と公開ポートを見る docker compose ps PORTS 列で公開されているポート を確認 nginx のログを見る docker compose logs --tail=100 nginx 502・504 の原因を探す ネットワークを見る docker network ls Dify 用のネットワークがあるか確 認 設定の展開結果を見る docker compose config .env が反映された最終的な設定を 確認(秘密情報を含むため共有し ない) Dify Docker WSL開発 | 45/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
周辺知識の読み方:Why・What・How 観点 問い 例(.env の場合) Why(なぜ) なぜ必要か。目的や背景は何か 設定をコードの外に分けるのは、変更と秘密情報を 守るため What(何か) 用語や部品は何か。どう定義されるか .env は、環境ごとの設定値を書くファイル How(どう使うか) 具体的な手順とコマンドは何か cp .env.example .env で作り、値を編集して起動す る 確認(Check) うまくいったかをどう確かめるか docker compose config で反映された値を確認する Dify Docker WSL開発 | 46/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Why・What・How:環境変数と秘密情報 項目 Why(なぜ) What(何か) How(どう使う) 環境変数 設定をコードから分ける 外から渡す設定値 .env に書き、コンテナへ渡す .env 環境ごとに値を変えるため 設定値を並べたファイル cp .env.example .env で作る 秘密情報 漏えいの被害を防ぐため パスワード・APIキー等 Git に含めず、共有は安全な経 路で .gitignore 誤って記録しないため Git が無視する対象の一覧 .env が除外されているか確認 権限の最小化 被害の範囲を小さくするため 必要な操作だけ許可する APIキーは用途ごとに分ける Dify Docker WSL開発 | 47/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Why・What・How:Git の基本 項目 Why(なぜ) What(何か) How(どう使う) バージョン管理 変更を追い、戻せるようにする ため 変更の履歴を記録する仕組み git log で履歴を確認する コミット 変更のまとまりを残すため 記録の一単位 git commit -m "説明" で記録 差分(diff) 何が変わったか確かめるため 変更内容の比較 git diff で確認してから記録 ブランチ 作業を分けて安全に試すため 作業の分岐 git checkout -b 名前 で作成 退避(stash) 作業中の変更を一時的に退ける ため 変更を一時保存する git stash、戻すのは git stash pop Dify Docker WSL開発 | 48/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Why・What・How:Docker のイメージ 項目 Why(なぜ) What(何か) How(どう使う) イメージ 同じ環境を何度でも作るため 読み取り専用の設計図 docker images で一覧を見る レイヤー 共通部分を再利用して効率よく するため 変更の積み重ね 取得は不足しているレイヤーだ け行われる タグ 版を区別するため 版の名札 版を固定し、latest に頼らない コンテナ 実行環境を分けて動かすため イメージを起動した実体 docker ps で実行中を確認 ボリューム コンテナを消してもデータを残 すため コンテナの外の保存領域 docker volume ls で確認 Dify Docker WSL開発 | 49/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Why・What・How:LLM と RAG の用語 項目 Why(なぜ) What(何か) How(どう使う) トークン 文章を処理する単位のため 言葉を分けた断片 長さは上限や料金に関わる コンテキスト 一度に扱える量の上限のため 入力と出力の合計の長さ 長い文書は分割して扱う 温度(temperature ) 回答のばらつきを調整するため 出力の選び方の幅 事実確認には低めを検討する 埋め込み( embedding) 意味で検索するため 文章を数値の並びに変換 検索の結果を同じ質問で比べる チャンク 検索しやすい単位に分けるため 文書を分けた断片 Dify のナレッジで分割方法を設 定 Dify Docker WSL開発 | 50/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
中級・上級への地図:到達の目安 段階 できること 次に身につけること 初級 公式の手順で起動し、アプリを一つ作れる ワークフローの分岐と変数の扱い 中級 ナレッジの検索を比べて設定を決められる 検索設定の評価、メタデータの活用 中級(応用) 外部のシステムからAPIで呼べる 失敗時の設計、タイムアウト、ログの読み方 上級 設定を環境ごとに管理し、保守の計画を立てられ る 権限・セキュリティ・性能の設計 Dify Docker WSL開発 | 51/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級:ワークフローの設計の型 開始(入力) 変数 処理(LLM・ツー ル) 条件分岐 エラー時の分岐 終了(出力) 項目 目的 方法 注意 変数 処理の間で値を受け渡す 入力値や途中結果を名前で保持 同じ変数名で前後の処理を つなぐ 条件分岐 結果によって処理を変える IF の条件で経路を分ける 想定外の結果も分岐に入れ る エラー処理 失敗を利用者に分かりやすく返す 失敗時の経路と文言を用意 外部APIの失敗を必ず分岐さ せる 繰り返し 一覧の要素を順に処理する 件数が多いと時間がかかる 上限を決めて、途中経過を 確認する Dify Docker WSL開発 | 52/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
ナレッジ検索の方式を比べる 方式 仕組み 向いている場面 注意 ベクトル検索 意味の近さで文章を探す 言い換えや曖昧な質問 固有名詞の一致は弱いこと がある 全文検索 キーワードの一致で探す 製品名・型番・規程番号 言い換えには弱い ハイブリッド検索 両方を同時に行い、結果を並べ直す 業務文書の両方の要素がある場合 重みと Rerank の設定を比 べる Rerank(再順位付け ) 候補を別のモデルで並べ直す 上位の精度を上げたいとき 追加のモデルとAPIキーが 必要 Dify Docker WSL開発 | 53/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
中級:メタデータで検索を絞り込む ナレッジ(複数) メタデータ(属性) フィルタ条件 絞り込んだ検索 • メタデータは、文書に付ける属性(部署・年度・版など)のこと • フィルタは、Knowledge Retrieval ノードで手動または自動の条件として設定する • 複数のナレッジを選ぶと、共通のメタデータ項目だけが候補に出る • 絞り込みすぎると、答えが出なくなるため、条件は少しずつ増やす Dify Docker WSL開発 | 54/83 回答 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
中級:検索設定の注意点(公式の注記) • Top K と Score は、Rerank を有効にしたときに効く、と公式ドキュメントに注記がある( 版により異なるため要確認) • インデックス方式(高品質・経済的)によって選べる検索方法が変わる • 同じ質問セットで、方式と設定を変えて結果を比べる Dify Docker WSL開発 | 55/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
検索品質の評価:回帰テストの手順 手順 目的 確認の観点 記録 質問セットを作る 同じ条件で比べるため 業務で実際に聞かれる質問を20問程 度 質問・期待する根拠 基準を取る 変更前の結果を残すため 根拠が正しく引用されているか 正誤と根拠の一致 設定を一つ変える 原因を切り分けるため Top K・方式・Rerank のどれか一つ 変更内容 全問を再実行する 悪化した問いを見つけるため 以前正しかった問いが壊れていない か 前後の差 判断する 採用か戻すかを決めるため 正答率と悪化の数の両方 判断と理由 Dify Docker WSL開発 | 56/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級:API連携の設計 論点 考え方 具体策 注意 呼び出しの方式 一括と段階的な受け取りを使い分 ける 画面の体験に合わせて選ぶ 版ごとの仕様を公式で確認 失敗の扱い 失敗を前提に設計する 再試行の上限と、利用者への文言を 決める 同じ処理を何度も送らない タイムアウト 応答が来ない時間を決める 外部APIごとに時間を決める 長すぎると画面が固まる 外部ナレッジ連携 社内の文書を外に置いたまま使う External Knowledge API の仕様どお りに応答する metadata は空のオブジェ クトにする Dify Docker WSL開発 | 57/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級:権限・秘密情報・外部通信 領域 リスク 対策 確認方法 APIキー 漏えいによる不正利用 用途ごとに分け、不要なら無効化する 台帳で棚卸しする アクセス権 必要以上の人が編集できる 役割ごとに権限を分ける 定期的に権限を見直す 外部への通信 意図しない先へ送信される ssrf_proxy などの中継を経由させる ネットワークの設定を 確認 設定の変更 誰が何を変えたか分からない 変更の記録を残す 変更記録と照合する Dify Docker WSL開発 | 58/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級:性能と運用の見方 利用者の要求 nginx api worker(非同期) • 時間のかかる処理は worker に任せ、画面の応答を速く保つ • 外部APIの遅さは、タイムアウトと再試行の上限で守る • 同時に多くの要求が来ると、どこが先に詰まるかを logs で確認する • モデルの利用量は、コストに直結するため、定期的に確認する Dify Docker WSL開発 | 59/83 外部API・DB 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
次の一歩:中級から上級へ 期間の目安 やること 完成の目印 1か月目 ナレッジの検索方式を比べる 同じ質問で正答率を記録できる 2か月目 ワークフローに分岐と失敗処理を入れる 想定外の入力でも案内が出る 3か月目 API連携と権限の設計をする 運用手順書を第三者が読める 継続 公式のリリースノートを読み、検証で試す 変更記録が途切れない Dify Docker WSL開発 | 60/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級者の仕事:作ることから判断することへ 作る人(構築) 判断する人(設計) 育てる人(教育・改善) 責任を持つ人(管理) • 上級者の仕事は、動かすことから、判断の理由を説明することへ移る • 「なぜこの設定か」を、記録と言葉で残せるかが分かれ目 • 影響範囲を先に考え、変更の可否を決められることが求められる • 個人の知識を、手順書とチェックリストに変えて組織に残す Dify Docker WSL開発 | 61/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級者の思考:Why・What・How 観点 問い 判断の材料 記録 仮説 何が原因だと考えるか ログ・画面・直前の変更 仮説と根拠 影響範囲 変えると、どこまで影響するか 依存するサービス・利用部門 影響の一覧 トレードオフ 速さ・安全・コストのどれを選ぶか 業務上の優先順位 選んだ理由 撤退条件 どうなったら戻すか 事前に決めた判定基準 戻す条件 再発防止 同じことを起こさないためにどうする か 原因の根本 手順書への反映 Dify Docker WSL開発 | 62/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級者のチェックリスト:変更の前・中・後 段階 確認項目 確認方法 記録 変更前 目的と変更内容を一文で言えるか 変更の申請書 申請番号 変更前 影響範囲と戻し方を書いたか 影響表・旧タグと .env の退避 退避先 変更中 一度に一か所だけ変えているか 変更の順番を記録 変更の履歴 変更後 ps・logs・画面・回答を確認したか 確認表(3点セット) 確認結果 変更後 利用部門に完了を伝えたか 報告文の送信 報告の日時 Dify Docker WSL開発 | 63/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
責任者の役割:RACI で役割を明確にする 業務 管理責任者 運用担当 開発者 情報システム 利用部門 利用範囲・目的の決定 A I C C R 変更の承認 A C C C I 設定・ワークフローの変更 I C R C I 日次の点検 A R I I I ネットワーク・セキュリティの設 定 A I C R I 障害の一次対応 A R C C I 利用者への周知 A C I I R Dify Docker WSL開発 | 64/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
RACI の読み方と、責任者の位置づけ • R(Responsible):実行する人。A(Accountable):最終的に責任を負う人(一つの業務に一人 ) • C(Consulted):相談を受ける人。I(Informed):結果を知らされる人 責任者(Accountable)は、一つの業務に一人だけ置きます。複数の人を置くと、判断が遅れる 原因になります。 Dify Docker WSL開発 | 65/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
責任者が決めること・任せること 項目 責任者が決める 任せる範囲 報告先 利用してよい業務の範囲 ○(承認) 対象の業務の選び方 経営層・利用部門 本番への変更 ○(承認) 検証を通した変更の実施 変更記録 権限と APIキーの発行 ○(方針) 日々の発行と無効化 台帳 外部のモデル・サービスの利 用 ○(承認) 候補の調査 情報システム 障害時の対外説明 ○(最終判断) 事実の整理と一次報告 利用部門・経営層 Dify Docker WSL開発 | 66/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
インシデント対応の流れと担当 検知 報告 一次対応 復旧 振り返り 再発防止 段階 担当 やること 記録 検知 運用担当 症状を記録し、ps と logs で状態を確認 発生時刻と症状 報告 運用担当→管理責任者 影響範囲と見込みを短く報告 報告の内容 一次対応 運用担当 直前の変更から戻すかを判断する 実施した操作 復旧 開発者・運用担当 原因を特定し、検証を経て直す 変更の履歴 振り返り 全員 責めずに、原因と手順の不足を話し合う 振り返りの記録 Dify Docker WSL開発 | 67/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
変更の承認フロー 申請 影響評価 検証環境で試す 承認(管理責任者) • 申請には、目的・変更内容・影響範囲・戻し方を必ず書く • 承認は、検証の結果を見てから行う(口頭だけで承認しない) • 緊急の変更でも、事後に申請と記録を残す • 承認の記録は、後から誰でも追えるように保管する Dify Docker WSL開発 | 68/83 本番へ反映 記録と報告 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
上級者への育成計画 段階 経験の目安 評価の観点 次の目標 中級 ナレッジ検索の比較を一度でも行 った 同じ質問で結果を比べられるか ワークフローの失敗設計 上級の入口 障害対応を一度主導した 原因と影響を整理して報告できるか 変更の承認に参加する 上級 変更の承認と手順書の整備を行っ た 他の人が手順書だけで作業できるか 後進の教育を担当する 責任者 運用の方針と役割を決めた 判断の理由を組織に説明できるか 利用範囲の方針を見直す Dify Docker WSL開発 | 69/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
確認テスト(1/2):No.1〜5 No. 問い 選択肢 1 コンテナを削除しても、ボリュームのデータは 残る。○か×か ○/× 2 docker compose の設定ファイルがあるフォル ダは? a) ~/dify C:\ b) ~/dify/docker 3 .env と envs/*.env に同じ値があると、どちら が優先される? a) envs/ b) .env 4 動いているDifyを止めて、データを残したいと きのコマンドは? a) docker compose down -v docker compose down 5 WSL でソースを置く推奨の場所は? a) C:\ Dify Docker WSL開発 | 70/83 得点 /10 b) ~/(WSL内) c) /10 /10 b) /10 /10 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
確認テスト(2/2):No.6〜10 No. 問い 選択肢 6 Dify の Docker Compose 環境で必要な Compose の最低版は? a) 2.24.0 以上 b) 1.0 以上 7 HTTP 502 の意味として適切なのは? a) 認証が必要 ない b) 後段が応答でき 8 External Knowledge API で、検索の要求を送る 方式は? a) GET 9 部品だけを更新するときに、最も注意すること は? a) 版の組み合わせ b) 何もしない 10 RACI で「A(最終的な責任)」を置く数は? a) 業務ごとに一人 い b) 何人でも良 Dify Docker WSL開発 | 71/83 得点 b) POST(/retrieval へ) /10 /10 /10 /10 /10 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
得点の仕組みと判定(案) 項目 記入 項目 受講者名 日付 得点(10問 × 10点) 判定 記入 判定 得点の目安 次の行動 修了 90点以上 上級のページへ進み、責任者の役割を学ぶ 合格 80〜89点 不正解だった章を復習して次へ進む 再受験 70〜79点 該当する章を読み直し、再受験する 復習 69点以下 講座を最初から見直し、手を動かして確認する Dify Docker WSL開発 | 72/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
後半(1/4)Docker の版:確認と基準 確認対象 コマンド 基準・見るところ 出典 Docker(クライアント・サ ーバ) docker version Client と Server の両方が表示されるこ と 【要確認】 Docker Compose docker compose version 2.24.0 以上(Dify の公式手順の要件) 【確認済】Dify 手順 Docker Desktop Desktop の About 画面 WSL 2 バックエンドが有効か(画面名は 版で異なる) 【要確認】 Docker Desktop 利用可能な容量 docker system df イメージ・ボリュームの使用量を把握す る 【要確認】 Docker Dify Docker WSL開発 | 73/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
後半(2/4)WSL の版:確認と基準 確認対象 コマンド 基準・見るところ リスク・注意 WSL 本体の版 wsl --version WSL のバージョンを表示(新しい WSL で使える) 古い版では機能が異 なる ディストリビューションの世 代 wsl -l -v Ubuntu の VERSION が 2 である こと VERSION 1 では想 定と違う動作があり うる Ubuntu の版 cat /etc/os-release VERSION_ID と VERSION_CODENAME を記録 サポート期間を確認 する 設定の反映 wsl --shutdown .wslconfig の変更後に実行 実行中の作業が止ま る Dify Docker WSL開発 | 74/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
後半(3/4)版の組み合わせと確認の流れ Dify の版(タグ) Compose の版 Docker の版 WSL・Ubuntu の版 記録して判断 • Dify の版の確認:git describe --tags(ソースの版)/ docker compose images(起動中のイメージ) • 組み合わせの確認:Dify のリリースノートで、必要な Docker・Compose の版を読む • 判断:版が合わない場合は、検証環境で先に揃えてから本番を更新する • 注意:Docker と WSL の更新は、Dify とは別の作業として記録する(原因の切り分けのため) Dify Docker WSL開発 | 75/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
後半(4/4)版の記録テンプレート 項目 記入例 確認コマンド 記録日 Dify(タグ) (例)版番号を記入 git describe --tags ( ) Docker Engine / Client (例)版番号を記入 docker version ( ) Compose (例)2.24.0 以上 docker compose version ( ) WSL (例)版番号を記入 wsl --version ( ) Ubuntu (例)版番号を記入 cat /etc/os-release ( ) 作業者・理由 (例)定期点検 (記録のみ) ( ) Dify Docker WSL開発 | 76/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
Ubuntu の基本:場所と役割 場所 役割 Windows側の対応 コマンド ~(/home/ユーザー名) 自分の作業場所(ホーム) C:\Users\ユーザー名 cd ~ で移動 /mnt/c Windows の C ドライブ C:\ 遅いので作業は ~ で行 う /etc システムの設定ファイル (Windows のレジストリに近い役 割) cat /etc/os-release /var/log ログの保存先 イベントログ(役割は近似) ls /var/log /usr プログラムの本体 Program Files(役割は近似) which docker Dify Docker WSL開発 | 77/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
パスと権限:絶対・相対・rwx の読み方 • 絶対パス:/ から始まる(例:/home/user/dify)。どこからでも同じ場所を指す • 相対パス:今いる場所からの相対(例:docker/.env)。pwd で場所を確かめてから使う • 権限表示 -rw-r--r--:先頭のd はフォルダ、続く3文字ずつが「持ち主・グループ・その他」の r(読む)w (書く)x(実行) • chmod:権限を変える。広く開けすぎない(例:秘密情報のファイルは持ち主だけ読めるようにする) • 注意:sudo は管理者として実行する。内容を理解せずに付けない Dify Docker WSL開発 | 78/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
パッケージとサービス:apt と sudo の関係 sudo(管理者) apt update(一覧更新) apt install(導入) 動作確認(コマンド) • apt update は、導入できるパッケージの一覧を更新する(導入はしない) • apt install で導入する。導入するものの出どこを確認してから行う • リスク:信頼できない手順を sudo で実行すると、システム全体に影響する • 対応:手順は公式の案内に従い、コマンドの意味を一行ずつ確かめる Dify Docker WSL開発 | 79/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
開発の基本ループ:編集・実行・確認・記録 編集(VSCode) 保存 実行(WSL のターミナ ル) 確認(ブラウザ・logs ) 記録(Git) 段階 どこで行うか 見るもの 失敗したときの次の一手 編集 VSCode(WSL 接続) 変更した行と意図 差分(git diff)を見直す 実行 WSL の Ubuntu docker compose の出力 ps → logs の順に見る 確認 ブラウザ・API の応答 画面・回答・ステータス 症状を記録し、一か所だけ戻す 記録 Git(コミット) 変更の理由と結果 理由を書けない変更は戻す Dify Docker WSL開発 | 80/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
関係性を追う練習:「回答が出ない」を一本の線で 順 層 確認する場所 コマンド・方法 1 ブラウザ 開発者ツールの Network ステータスを確認(502・504 など) 2 Windows の公開ポート PowerShell Test-NetConnection -ComputerName localhost -Port 80 3 WSL 2(Ubuntu) Ubuntu のターミナル ~/dify/docker に居るか(pwd) 4 Docker の公開 Ubuntu docker compose port nginx 80 5 nginx(入口) Ubuntu docker compose logs --tail=100 nginx 6 api・worker・DB Ubuntu docker compose ps → logs api Dify Docker WSL開発 | 81/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
参考(公式ドキュメント・クリックで開く) Dify:Docker Compose によるデプロイ https://docs.dify.ai/en/self-host/quick-start/docker-compose Dify:セルフホスト・インストール https://docs.dify.ai/en/getting-started/install-self-hosted Dify:基本概念(アプリの種類) https://docs.dify.ai/ja/learn/key-concepts Dify:External Knowledge API https://docs.dify.ai/en/self-host/use-dify/knowledge/external-knowledge-api.md Microsoft:WSL のインストール https://learn.microsoft.com/windows/wsl/install VSCode:WSL での開発 https://code.visualstudio.com/docs/remote/wsl Docker:Compose のドキュメント https://docs.docker.com/compose/ Dify Docker WSL開発 | 82/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
まとめ:原理を知ると、初めての画面でも判断できる 問い:今の環境で、どの段の確認から始めますか? 問い:修了課題の手順書で、最初に書く項目は? 問い:次に業務で試すDifyのアプリ種類は? Dify Docker WSL開発 | 83/83 目次 | 基礎 | コマンド | エラー | 保守 | ネットワーク | 仕様 | 学ぶ | 原理 | 構成 | 周辺 | 中上級 | 上級 | 得点 | 版 | 土台 | 参考
5. 上級:ネットワーク編(受講生用) 収録元:Dify_上級_ネットワーク編_受講生用.pptx(15枚)
Dify 上級:ネットワーク構成と仕組み DXエンジニア(保守・開発)向け | Docker・WSL 2・nginx の周辺知識を含む 受講生用 | 約120分 | 公式ドキュメントの確認を前提とする
全体構成図(代表的な構成・版で異なる) 利用者のPC Windows (公開ポート) WSL 2(NAT) Docker 内部網 nginx(80/443) web(画面) api(処理) weaviate sandbox ssrf_proxy(中継) インターネット 内部ネットワーク(サービス名で通信) worker Dify 上級ネットワーク編 | 2/15 db redis
通信を層で考える 層 例 見る場所 障害の例 アプリ(HTTP等) 画面の表示、API の応答 ブラウザの開発者ツール、logs ステータスコード 502・ 504 転送(TCP・ポート) 80・443・5432 などの番号 netstat、docker compose port port is already allocated ネットワーク(IP) IPアドレス、経路、NAT ipconfig、ip addr、hostname -I 接続先が見つからない 名前解決(DNS) 名前→IP への変換 nslookup、サービス名の解決 名前が解決できない リンク(仮想NIC) 仮想ネットワークの接続 docker network inspect コンテナ同士が届かない Dify 上級ネットワーク編 | 3/15
WSL 2 の経路:Windows から Ubuntu へ ブラウザ(Windows) localhost WSL 2 の仮想ネットワーク • WSL 2 は仮想マシンで Linux を動かし、独自の仮想ネットワークを持つ • 既定では、Windows 側の localhost から公開ポートへ転送される • .wslconfig の networkingMode(例:mirrored)で挙動が変わる版がある • 版と設定の確認は、公式の WSL ドキュメントと照らして行う Dify 上級ネットワーク編 | 4/15 Ubuntu 内の公開ポート
Docker のネットワーク:種類と役割 種類 特徴 注意 bridge(既定) 同じ網の中でサービス名により通信できる 公開しない限り外から届かない ユーザー定義の網 名前解決が効き、通信の範囲を分けられる compose の定義で作られる網を確認 ポート公開(-p・ports) ホストの番号をコンテナの番号へ転送する ホストの番号が競合しやすい 内部のみ(internal) 外部へ出られない網を作る 外部API利用が必要なら使えない Dify 上級ネットワーク編 | 5/15
nginx の役割:入口で振り分ける 利用者 nginx(80/443) location で振り分け web または api • server ブロックが待ち受けるポートと名前を決める • location が、パスごとの転送先を決める(proxy_pass) • proxy_set_header で、元の Host や送信元の情報を後段へ渡す • タイムアウトと上限サイズで、遅い要求や大きすぎる要求を制御する • ストリーミング応答では、バッファリングの設定が影響しうる Dify 上級ネットワーク編 | 6/15 応答を返す
nginx 設定の読み方(例)
例(説明用の架空の設定。実際の Dify の設定は版により異なる)
行の例
意味
確認のポイント
listen 80;
80番で待ち受ける
docker compose port で公開を確認
server_name ...;
どの名前の要求を受けるか
Host の値と一致するか
location / { proxy_pass http://web:<port>; }
すべての要求を web へ渡す
サービス名(web)が解決できるか
location /api { proxy_pass
http://api:<port>; }
/api で始まる要求を api へ渡す
パスの一致順序に注意
proxy_set_header Host $host;
元の Host を後段へ渡す
アプリが Host を使う場合に必要
client_max_body_size ...;
送れる本文サイズの上限
大きい文書の登録失敗を疑う
Dify 上級ネットワーク編 | 7/15
名前解決と内部通信 api が "db" を呼ぶ Docker の DNS サービス名→内部IP • 同じ網の中では、サービス名がそのまま名前として使える • 名前が解決できない時は、網の所属と compose の定義を確認する • コンテナの中のlocalhost は、そのコンテナ自身を指す(ホストではない) • 接続の確認には、サービス名とポートを指定して確かめる Dify 上級ネットワーク編 | 8/15 db へ接続
外部通信と ssrf_proxy の役割 api・sandbox ssrf_proxy(中継) 許可した先のみ • 外部への通信を一か所に集め、宛先や経路を管理しやすくする • 中継を経由させる設定は、環境変数などで指定される(版により異なる) • 社内の許可リストと照らして、通信先を決める • ログを残し、通信の監査に使える Dify 上級ネットワーク編 | 9/15 インターネット
主なポートと公開の考え方 要素 ポート(代表) 公開の考え方 nginx 80(HTTP)・443(HTTPS) 利用者が使う唯一の入口として公開 db(PostgreSQL) 5432 内部だけで使い、外へ公開しない redis 6379 内部だけで使い、外へ公開しない weaviate(ベクトルDB) 8080 内部だけで使い、外へ公開しない sandbox 8194 内部だけで使い、外へ公開しない ssrf_proxy(Squid) 3128 内部の通信だけが使う plugin_daemon 5002 版により有無が異なる。内部で使う Dify 上級ネットワーク編 | 10/15
通信トラブルの切り分け(上級の型) 名前解決 到達性 ポート nginx ログ 後段(api)ログ 段階 確認コマンド(例) 見るもの 名前解決 docker compose exec api getent hosts db サービス名がIPに変わるか(イメージ に依存) 到達性(Windows) Test-NetConnection -ComputerName localhost -Port 80 TcpTestSucceeded が True か ポート docker compose port nginx 80 公開ポートの対応 nginx docker compose logs --tail=100 nginx 502・504 の記録 後段 docker compose logs --tail=100 api アプリ側の例外・時間切れ Dify 上級ネットワーク編 | 11/15
セキュリティの境界(ネットワーク視点) 境界 守るもの 具体策 確認方法 外と nginx の間 入口の安全 HTTPS、公開ポートの最小化 ポートの公開状況 nginx と後段の間 内部サービスの隔離 内部の網だけで通信させる 網の一覧と所属 後段と外部の間 外への不正な通信 ssrf_proxy で中継し、許可した先だけ通 す 中継の設定と許可リス ト 管理者の操作 設定の改ざん・漏えい 秘密情報を分離し、変更を記録する 変更記録と権限の見直 し Dify 上級ネットワーク編 | 12/15
開発から実装へ:ネットワーク変更の手順 変更の目的 影響範囲(網・ポ ート) 検証環境で試す • 変更前:ポート・網・名前の一覧を控える • 変更中:一度に一か所だけ変える • 変更後:到達性・ログ・画面の3点を確認する • 失敗時:旧設定に戻す手順を事前に用意する Dify 上級ネットワーク編 | 13/15 本番へ反映 確認(3点) 記録
保守チェック(ネットワーク) 頻度 点検項目 確認方法 毎日 入口(nginx)が応答するか docker compose ps、curl.exe -I http://localhost/ 毎日 502・504 の発生件数 docker compose logs --tail=100 nginx 週次 公開ポートの変更がないか docker compose port nginx 80 週次 外部への通信先(許可リスト) ssrf_proxy の設定と台帳の照合 月次 証明書の期限(HTTPS の場合) 証明書の有効期限を台帳で管理 随時 版の更新に伴う変更の影響 リリースノートと検証環境で確認 Dify 上級ネットワーク編 | 14/15
参考(公式ドキュメント) • Dify:Docker Compose によるデプロイ(docs.dify.ai/en/self-host/quick-start/docker-compose) • Dify:セルフホスト・インストール(docs.dify.ai/en/getting-started/install-self-hosted) • Docker:Compose のドキュメント(docs.docker.com/compose/) • Microsoft:WSL のドキュメント(learn.microsoft.com/windows/wsl/) • nginx:公式ドキュメント(nginx.org) Dify 上級ネットワーク編 | 15/15
6. 実務リファレンス(Why・What・How) 収録元:Dify_実務リファレンス_Why_What_How_出典つき.pptx(14枚)
Dify 実務リファレンス Why・What・How・リスク・関係性を、出典つきで整理 出典の凡例:【確認済】今回、公式ページの内容を検索結果で確認 / 【要確認】一般的な仕様にもとづく。公開前に 公式で確認
図解:関係性マップ(何が何を支えるか) Windows(PC) PowerShell / CMD VSCode WSL 2(Ubuntu) ~/dify(ソース・.env) Docker Desktop Docker Compose Dify(nginx・api 他) ブラウザ(localhost) 矢印は「操作・依存の向き」。赤は利用者が結果を見る経路。 Dify 実務リファレンス | 2/14
VSCode:操作・コマンド・意味・出典 操作 方法 意味 出典 WSL のフォルダを開く Ubuntu で code . code=VSCode を起動、.=今のフォルダ 【要確認】VSCode WSL コマンドパレット Ctrl+Shift+P 全操作を名前で呼び出す入口 【要確認】VSCode code をPATHに登録 パレット→Shell Command: Install ... ターミナルから code を使えるようにする 【要確認】VSCode ターミナルを開く Ctrl+` プロジェクトの場所で実行できる 【要確認】VSCode WSL接続の確認 左下に「WSL: Ubuntu」 編集・実行が WSL 側で行われる 【要確認】VSCode WSL Dify 実務リファレンス | 3/14
PowerShell:操作・コマンド・意味・出典 操作 コマンド 意味 出典 場所を見る Get-Location(pwd) 今いるフォルダを表示 【要確認】 PowerShell 移動する Set-Location C:\work(cd) フォルダを変える 【要確認】 PowerShell 環境変数を見る $env:UserProfile 環境変数の値を表示 【要確認】 PowerShell WSLに入る wsl -d Ubuntu 指定したLinuxディストリビューションを起動 【要確認】WSL ポートを確かめる Test-NetConnection -ComputerName localhost -Port 80 TCP接続が成功するか確認 【要確認】 PowerShell Webの応答を見る curl.exe -I http://localhost/ HTTPヘッダーを取得(curl だけでは別物) 【要確認】 PowerShell スクリプトの制限を見る Get-ExecutionPolicy スクリプト実行の方針を確認 【要確認】 PowerShell Dify 実務リファレンス | 4/14
WSL:操作・コマンド・意味・出典 操作 コマンド 意味 リスク・注意 導入(管理者) wsl --install WSL と既定のLinuxを導入 再起動が必要な場合あり 一覧と版を見る wsl -l -v ディストリビューションと VERSION を表示 VERSION 2 を確認 版を2に変える wsl --set-version Ubuntu 2 WSL の世代を指定 完了まで時間がかかること がある 停止する wsl --shutdown WSL を停止(設定変更の反映に使う) 実行中の作業が止まる Windowsを見る cd /mnt/c(Ubuntu内) Windows側のファイルへ移動 遅い。作業は ~ で行う 削除(危険) wsl --unregister Ubuntu ディストリビューションを削除 環境が消え、復元できない Dify 実務リファレンス | 5/14
Docker・Compose:操作・コマンド・意味・出典 操作 コマンド 意味 出典 版の確認 docker compose version Compose が 2.24.0 以上か確認 【確認済】Dify Docker Compose 手順 起動 docker compose up -d 設定のサービスを、バックグラウンドで起動 【確認済】Dify Docker Compose 手順 状態 docker compose ps 各サービスの状態と公開ポートを表示 【確認済】Dify 手順( ps を使用) 停止 docker compose down 停止して後片付け(ボリュームは既定で残る) 【要確認】Docker Compose 危険:データも削除 docker compose down -v ボリュームも削除(DB・アップロードが消える ) 【要確認】Docker Compose ログ docker compose logs --tail=100 api 最新100行のログを表示 【要確認】Docker Compose 設定の確認 docker compose config 反映された最終設定を表示(秘密情報を含む) 【要確認】Docker Compose Dify 実務リファレンス | 6/14
リスクと対応(業務で起きやすいもの) リスク 起きる場面 影響 対応 データの消失 down -v、volumes/ の削除 DB・アップロードが失われる 停止は down のみ。退避後に操作 秘密情報の漏えい .env を Git に含める、config を共有 APIキーの不正利用 .gitignore を確認。共有しない ポートの競合 別のソフトが同じポートを使う 起動できない netstat で確認し、ポートを変える 版の不一致 部品だけの更新、古い手順の使用 動作の不具合 版をそろえ、公式の手順を確認 意図しない外部通信 外部API設定の誤り データの外部送信 ssrf_proxy の経路と許可先を確認 作業場所の誤り C:\ での作業、実行場所の違い 遅い、ファイル不一致 WSL 内(~/)で作業し pwd で確認 手順の陳腐化 版の更新で画面や手順が変わる 作業の失敗 リリースノートを読み、検証で試す Dify 実務リファレンス | 7/14
Why・What・How:主要項目と出典 項目 Why(なぜ) What(何か) How(どう使う) 出典 .env 設定と秘密情報を分けるため 環境ごとの設定値のファイル cp .env.example .env 【確認済】Dify 手順 ssrf_proxy 外部通信を一か所で管理するた め 外部への通信を中継するサービス API設定で中継経路を使う 【確認済】Dify 構成 ベクトル検索 意味で探すため 文章を数値で比べる検索 方式を質問セットで比べる 【確認済】Dify ナレッジ Rerank 上位の順番を整えるため 候補を並べ直す仕組み 有効にして Top K の効果を見る 【確認済】Dify ナレッジ注記 volumes/ データを残すため DB・アップロードの保存先 停止前に退避する 【要確認】Dify 構成 Dify 実務リファレンス | 8/14
関係性のまとめ:何が何に依存するか 依存する側 依存される側 関係 壊れたときの症状 Dify(api) PostgreSQL(db) データの保存と読み出し ログイン・保存ができない Dify(api) Redis・worker 非同期処理の受け渡し 文書の取り込みが進まない nginx web・api 要求の振り分け 502・504 が出る Compose docker/.env サービスの定義と設定値 設定が反映されない WSL 2 Docker Desktop コンテナの実行環境 docker が接続できない VSCode WSL 2(~/dify) 編集と実行の場所 ファイルが見えない・遅い Dify 実務リファレンス | 9/14
後半(1/4)Docker の版:確認と基準 確認対象 コマンド 基準・見るところ 出典 Docker(クライアント・サーバ) docker version Client と Server の両方が表示されること 【要確認】Docker Compose docker compose version 2.24.0 以上(Dify の公式手順の要件) 【確認済】Dify Docker Compose 手 順 Docker Desktop Desktop の About 画面 WSL 2 バックエンドが有効か(画面名は版で異な る) 【要確認】Docker Desktop 利用可能な容量 docker system df イメージ・ボリュームの使用量を把握する 【要確認】Docker Dify 実務リファレンス | 10/14
後半(2/4)WSL の版:確認と基準 確認対象 コマンド 基準・見るところ リスク・注意 WSL 本体の版 wsl --version WSL のバージョンを表示(対応する Windows の版が必要) 古い版では機能が異なる ディストリビューションの世代 wsl -l -v Ubuntu の VERSION が 2 であること VERSION 1 では想定と 異なる動作がありうる Ubuntu の版 cat /etc/os-release(Ubuntu内) VERSION_ID と VERSION_CODENAME を記録 サポート期間を確認する 設定の反映 wsl --shutdown .wslconfig の変更後に実行する 実行中の作業が止まる Dify 実務リファレンス | 11/14
後半(3/4)版の組み合わせと確認の流れ Dify の版(タグ) Compose の版 Docker の版 WSL・Ubuntu の版 記録して判断 • Dify の版の確認:git describe --tags(ソースの版)/ docker compose images(起動中のイメージ) • 組み合わせの確認:Dify のリリースノートで、必要な Docker・Compose の版を読む • 判断:版が合わない場合は、検証環境で先に揃えてから本番を更新する • 注意:Docker と WSL の更新は、Dify とは別の作業として記録する(原因の切り分けのため) Dify 実務リファレンス | 12/14
後半(4/4)版の記録テンプレート 項目 記入例 確認コマンド 記録日 Dify(タグ) (例)版番号を記入 git describe --tags () Docker Engine / Client (例)版番号を記入 docker version () Compose (例)2.24.0 以上 docker compose version () WSL (例)版番号を記入 wsl --version () Ubuntu (例)版番号を記入 cat /etc/os-release () 作業者・理由 (例)定期点検 (記録のみ) () Dify 実務リファレンス | 13/14
出典一覧と確認状況 記号 出典(公式) 確認状況 D1 docs.dify.ai/en/self-host/quick-start/docker-compose 【確認済】検索で内容を確認 D2 docs.dify.ai/en/getting-started/install-self-hosted 【確認済】検索で内容を確認 D3 docs.dify.ai/ja/learn/key-concepts(アプリの種類) 【確認済】検索で内容を確認 D4 enterprise-docs.dify.ai(ナレッジの索引方式の注記) 【確認済】版3.7.x の注記。最新版で要確認 W1 learn.microsoft.com/windows/wsl/ 【要確認】今回は未アクセス V1 code.visualstudio.com/docs/remote/wsl 【要確認】今回は未アクセス C1 docs.docker.com/compose/ 【要確認】今回は未アクセス Dify 実務リファレンス | 14/14
7. 上級:ニッチな仕様と差分 収録元:Dify_上級_ニッチ仕様と差分.pptx(13枚)
Dify 上級:ニッチな仕様と差分 版の差分、設定の優先順位、知っておくと事故を防げる細かい仕様 凡例:【確認済】今回、公式または公式PRの内容を確認 / 【要確認】一般的な仕様・コミュニティ情報。版で必ず 確認
版の差分を自分で読む方法 版(タグ)を調べる 旧版と新版を指定 変更ファイルを絞る リリースノートと照合 影響を判断 目的 コマンド(例) 見るところ タグの一覧(新しい順) git tag --sort=-v:refname 新旧の版番号を決める 設定の差分 git diff 旧タグ 新タグ -- docker/ .env.example・compose の変更 変更ファイルの一覧 git diff --stat 旧タグ 新タグ -- docker/ 影響範囲の大きさ 特定ファイルの履歴 git log --oneline 旧タグ..新タグ -docker/.env.example いつ何が変わったか Dify 上級:ニッチな仕様と差分 | 2/13
設定の優先順位(何が勝つか) envs/*.env(テンプレート から作成) .env(docker フォルダ) Compose の service 環境 変数 (最終的に採用される値) • 【確認済】.env の値は、envs/*.env の値より優先される(公式の Premium 手順に記載) • 【確認済】Compose の service レベルの environment は、env ファイルの値より優先される(同じ記載) • 【要確認】docker-compose.override.yaml で上書きする運用が公式に言及されている。版ごとに確認する • 注意:同じ変数が三か所にあると、どこを直しても効かないことが起きる。変数の置き場所を一か所に決める Dify 上級:ニッチな仕様と差分 | 3/13
設定ファイルの構成の差分(旧と新) 項目 従来の構成(例) 新しい構成(例) 影響・確認 .env.example 全設定を一つに集約 軽量化し、詳細を envs/ に分割(3.10 以降の Enterprise 版で確認) 【確認済】差分の見方が変わ る 既定値の置き場所 .env.example を直接使用 .env.default が追加された例がある(公式PR で確認) 【確認済】PR の差分で確認 プロファイル 手動で指定 COMPOSE_PROFILES で既定を決める例があ る 【確認済】PR の差分で確認 設定の同期 手作業で差分を確認 dify-env-sync.sh で差分を反映する(3.10 以 降の Enterprise 版) 【確認済】Enterprise 版の手 順 Dify 上級:ニッチな仕様と差分 | 4/13
Compose プロファイル:部品を有効にする仕組み 指定方法 例 注意 コマンドで指定 docker compose --profile weaviate up -d ミドルウェア起動の例で使用(開発手順) 環境変数で既定化 COMPOSE_PROFILES=weaviate,postgresql 【確認済】.env.default の例で使用されている サービスに付与 services の profiles 項目 プロファイルを指定しないと起動しない 確認 docker compose config --profiles(版で確認) 起動対象の見落としを防ぐ Dify 上級:ニッチな仕様と差分 | 5/13
上書きの安全な方法:override ファイル 公式の compose を変 えない override ファイルを作 る 必要な項目だけ書く config で結果を確認 • 公式の docker-compose.yaml を直接編集すると、版の更新で差分が衝突しやすい • override に書いた値は、元の定義の上に重ねて適用される(公式の注記) • docker compose config で、合成後の最終設定を必ず確認する • 注意:config の出力には秘密情報が含まれるため、共有しない Dify 上級:ニッチな仕様と差分 | 6/13 起動
ナレッジの索引方式と Rerank(版注意) 項目 内容 注意 確認 高品質(High-Quality) ベクトル・全文・ハイブリッドから選ぶ 埋め込みモデルの設定が必要 【確認済】3.x の索引 方式の注記 経済的(Economical) キーワード中心で、コストを抑える 意味での検索は弱くなる 【確認済】3.x の索引 方式の注記 Top K・Score Rerank を有効にした時に効く(注記) Rerank なしでは期待通り効かないことが ある 【確認済】注記(版 要確認) Rerank モデル 候補を並べ直す。別のモデルとキーが必要 費用と遅延が増える 【確認済】注記 Dify 上級:ニッチな仕様と差分 | 7/13
External Knowledge API の落とし穴 • 【確認済】endpoint に /retrieval を付けて POST する(公式ドキュメント) • 【確認済】レスポンスの records に content と score が必要 • 【確認済】metadata は null ではなく、空のオブジェクトにする(null は検索処理で問題になりうる) • 【確認済】エラーコード 1001・1002・2001 は、公式で推奨される値(強制ではない) • 注意:認証に Bearer トークンを使う。トークンの漏えいと期限切れに注意 Dify 上級:ニッチな仕様と差分 | 8/13
アップグレードの落とし穴(上級) DBの移行(マイグレーショ ン) 前方のみ(戻れない) ダンプで戻す 版をそろえる 落とし穴 起きること 対策 確認 マイグレーションは戻せない 旧版が新しいDBで動かない DB ダンプを必ず取る 【要確認】コミュニ ティ情報 複数の版を飛ばす 想定しない移行の順番 リリースノートの推奨経路を確認 【要確認】 部品の版がずれる api と web などの不整合 同じ版で更新する 【要確認】 .env.example の注記 移行の自動実行 起動時に移行が走る版がある logs で移行の完了を確認 【要確認】 Dify 上級:ニッチな仕様と差分 | 9/13
WSL の細かい仕様(上級) 項目 内容 注意 確認 .wslconfig Windows 側の全体設定(%UserProfile%) 変更後は wsl --shutdown で反映 【要確認】WSL 公式 wsl.conf ディストリビューション内の設定(/etc/wsl.conf ) Ubuntu ごとに効く 【要確認】WSL 公式 networkingMode ネットワークの動作方式(例:mirrored) 版により利用可否と挙動が異なる 【要確認】WSL 公式 IP アドレス 再起動で変わることがある 固定の IP に依存しない 【要確認】 版の確認 wsl --version 古い版では機能が異なる 【要確認】 Dify 上級:ニッチな仕様と差分 | 10/13
Docker とネットワークの細部(公開範囲) • 【要確認】-p 80:80 のようなポート公開は、既定ではホストのすべてのネットワークで受け付けることがある • 対策:127.0.0.1:80:80 のように、受け付ける範囲を限定する(業務の要件で判断) • 【要確認】公開範囲を変えると、別のPCや社内から届かなくなる(意図した動作かを確認) • 確認コマンド:docker compose port nginx 80(公開先の確認)、netstat -ano(待ち受け状況) Dify 上級:ニッチな仕様と差分 | 11/13
Windows と Git の細かい落とし穴 項目 起きること 対策 確認 改行コード(CRLF / LF) シェルスクリプトが動かない・差分が大量 に出る core.autocrlf と .gitattributes で統一 【確認済】改行の警 告は一般的な現象 \\wsl$ の参照 Windows から WSL のファイルを扱える 編集は WSL 内で行い、参照のみにする 【要確認】WSL 公式 秘密情報の混入 .env をコミットして漏えい .gitignore と履歴の確認(git log -p の検索 ) 【確認済】一般的な 運用 実行ポリシー PowerShell のスクリプトが止まる Get-ExecutionPolicy で確認し、方針に従 う 【要確認】 Dify 上級:ニッチな仕様と差分 | 12/13
出典と確認状況(この資料) 項目 出典 状況 Premium/Enterprise の手順(優先順位・override・アッ プグレード) docs.dify.ai(Dify Premium 手順) 【確認済】検索で内容を確認 Enterprise 3.10 以降の設定の構成 enterprise-docs.dify.ai(3.11.x) 【確認済】検索で内容を確認 索引方式・Rerank の注記 enterprise-docs.dify.ai(3.7.x・3.12.x) 【確認済】版差に注意 .env.default・COMPOSE_PROFILES GitHub PR(langgenius/dify #35708) 【確認済】PR の差分で確認 アップグレードの実例・移行 GitHub Discussions(非公式) 【要確認】参考情報のみ WSL・Docker・VSCode の細部 各公式ドキュメント 【要確認】今回は未アクセス Dify 上級:ニッチな仕様と差分 | 13/13
8. 開発環境:Windows対応・MTG・コマン ド全集 収録元:Dify_開発環境_Windows対応_お客様説明_MTG_コマンド全集.pptx(17枚)
Dify 開発環境:Windows対応・お客様説明・MTG・ コマンド全集 お客様への説明、同僚とのMTG、コマンドの意味を一つにまとめた資料 凡例:【確認済】公式の内容を確認 / 【要確認】一般的な仕様。実機と版で確認してから使う
Windows 対応の確認:これまでの講座で足りていたか 項目 これまで 不足・補うべき点 状態 Windows の版(10 / 11) 版の要件を記載していない 対応する版を明記し、確認方法を追加 要追加 エディション(Home / Pro) 触れていない Docker・WSL の導入条件を要確認と明記 要追加 仮想化(BIOS / UEFI) 触れていない WSL 2 が動かない主因。確認と有効化の案内が必要 要追加(重大 ) 管理者権限・企業ポリシー 一部(wsl --install は管理者) 社内で導入が禁止されている場合の代替と相談先 要追加 ポートの競合(80・443) ネットワーク編で記載 Windows 側のサービスとの競合の確認方法 概ね対応 日本語のユーザー名・パス 触れていない ツールによっては問題になりうる。【要確認】 要追加 容量・メモリ メモリの設定を記載 容量の目安と確認コマンドを明記 概ね対応 Dify 開発環境:Windows対応・MTG・コマンド | 2/17
事前確認チェック(Windows) 確認項目 確認方法 NGの場合の対応 出典 Windows の版 設定 → システム → バージョン情報 版を更新する(組織の方針に従う) 【要確認】 仮想化の有効化 タスクマネージャー → パフォーマンス → 仮想化 BIOS / UEFI で有効化(情シスに相談) 【要確認】WSL 公式 WSL の導入 wsl -l -v wsl --install を管理者で実行 【要確認】WSL 公式 Docker Desktop の導入 Docker Desktop を起動し、docker version 導入条件と利用規約を確認 【要確認】 Docker Compose の版 docker compose version 2.24.0 以上へ更新 【確認済】Dify 手順 空き容量 エクスプローラーでドライブの空き 作業に必要な容量を確保する 【要確認】 ポートの空き netstat -ano | findstr :80 競合するソフトを止める、または別ポート 【要確認】 Dify 開発環境:Windows対応・MTG・コマンド | 3/17
お客様向け説明(平易な言葉で) • できること:社内の文書をもとに、質問に答えるAIアプリを自社のPCで動かせるようになります • 必要なもの:Windows の PC、WSL 2(Linux の仮想環境)、Docker Desktop、VSCode • データの置き場所:作業データは PC の中(WSL 内)に保存されます。外部への送信は設定により決まります • 安全のための決まり:秘密情報(パスワード・APIキー)はファイルに分け、共有しない • 費用とライセンス:Docker Desktop などの利用条件は、組織の規模で異なる。【要確認】導入前に確認が必要 • 保守:更新は検証環境で先に試し、記録を残してから本番に反映します • 相談先:導入の判断は、情報システム部門と一緒に進めます Dify 開発環境:Windows対応・MTG・コマンド | 4/17
同僚とのMTG:要点3つと役割分担 • 要点1:Dify は Windows に直接入れるのではなく、WSL 2 の中の Docker で動く • 要点2:変更は一つずつ行い、検証環境を通してから本番へ(記録を残す) • 要点3:困ったら、ps → logs → 直前の変更 の順で確認する • 役割:開発(設定・ワークフロー)/運用(点検・障害対応)/管理責任者(承認)/情報システム(ネ ットワーク・セキュリティ) • 次のアクション:事前確認表の配布、版の記録の開始、障害時の連絡先の確定 Dify 開発環境:Windows対応・MTG・コマンド | 5/17
MTG でよく出る質問 質問 答えの要点 Windows に直接入れられないのか? Dify は Linux 環境の Docker で動かす想定。WSL 2 を介して動かす(公式の手順に従 う) なぜ C:\ ではなく WSL 内に置くのか? 公式が Linux 側での配置を推奨。Windows 側は遅くなることがある データは外に出るのか? 設定と外部サービスの利用により決まる。送信先は設定で管理する アップグレードは止められるか? 検証を通してから行う。DB の退避とダンプを必ず取る 誰が承認するのか? 変更の承認は管理責任者。実行は運用・開発が行う 障害が起きたら? 症状を記録 → ps → logs → 直前の変更 → 再起動の順 Dify 開発環境:Windows対応・MTG・コマンド | 6/17
コマンド全集 1/5:Windows(PowerShell・CMD)(1/2) コマンド 意味 使う場面 注意 wsl --install WSL と既定の Linux を導入する 初回導入(管理者) 再起動が必要な場合がある wsl -l -v 導入済みの一覧と VERSION を表示 版の確認 VERSION 2 を確認 wsl --set-version Ubuntu 2 Ubuntu の WSL 世代を 2 にする VERSION 1 の修正 時間がかかる wsl --version WSL 本体の版を表示 版の記録 【要確認】新しい WSL で使用 wsl -d Ubuntu Ubuntu に入る(起動する) 作業の開始 -d は対象の指定 wsl --shutdown WSL を停止する .wslconfig の反映 作業中の内容が止まる Dify 開発環境:Windows対応・MTG・コマンド | 7/17
コマンド全集 1/5:Windows(PowerShell・CMD)(2/2) コマンド 意味 使う場面 注意 wsl --unregister Ubuntu Ubuntu 環境を削除する (通常は使わない) 復元できない。実行しない notepad "$env:UserProfile\.wslconfig" 設定ファイルを開く(なければ作成) メモリ等の設定 パスは引用符で囲む Get-Location(pwd) 今いるフォルダを表示 場所の確認 作業前に毎回確認 Set-Location(cd) フォルダを移動する 移動 空白があれば引用符 $env:UserProfile 環境変数の値を表示 ユーザーフォルダの確認 $env: の後に変数名 Get-ExecutionPolicy スクリプト実行の方針を表示 スクリプトが止まる時 変更は方針に従う Dify 開発環境:Windows対応・MTG・コマンド | 8/17
コマンド全集 2/5:Windows の確認(ネットワーク・CMD)(1/2) コマンド 意味 使う場面 注意 Test-NetConnection -ComputerName localhost Port 80 指定ポートに接続できるか確認 到達性の確認 TcpTestSucceeded が True か curl.exe -I http://localhost/ HTTP のヘッダーを取得 画面の応答確認 PowerShell の curl とは別 curl.exe -s URL 応答の内容を取得(簡潔) API の確認 URL は引用符で囲む netstat -ano | findstr :80 80番を使うプロセスを表示 ポート競合の確認 最後の数字が PID cd /d D:\work(CMD) 別のドライブへ移動 ドライブをまたぐ移動 /d が必要 dir(CMD) フォルダの中身を一覧 確認 PowerShell では GetChildItem Dify 開発環境:Windows対応・MTG・コマンド | 9/17
コマンド全集 2/5:Windows の確認(ネットワーク・CMD)(2/2) コマンド 意味 使う場面 注意 where docker(CMD) コマンドの場所を探す PATH の確認 見つからない場合は PATH を 疑う echo %UserProfile%(CMD) 環境変数を表示(CMD の書き方) ユーザーフォルダの確認 % で囲む cd /d %UserProfile%(CMD) ユーザーフォルダへ戻る 場所を戻す CMD では ~ は使えない ipconfig IP アドレスや接続情報を表示 ネットワークの確認 VPN 接続中は表示が変わる nslookup github.com 名前から IP を調べる 名前解決の確認 失敗時は DNS を疑う Get-NetTCPConnection(PowerShell) TCP 接続の状態を表示 ポートの詳細確認 【要確認】版により表示が異 なる Dify 開発環境:Windows対応・MTG・コマンド | 10/17
コマンド全集 3/5:WSL 内(Ubuntu の基本)(1/2) コマンド 意味 使う場面 注意 pwd 今いる場所を表示する 作業前の確認 必ず確認する習慣 cd ~ ホームフォルダへ移動 作業の開始 ~ は自分のホーム cd ~/dify/docker Dify の docker フォルダへ移動 compose の実行 ここで docker compose を実行 cd /mnt/c Windows の C ドライブへ移動 ファイルの確認のみ 作業は避ける(遅い) ls -la 隠しファイルを含めて一覧 .env の確認 . で始まるのは隠しファイル cat /etc/os-release Ubuntu の版を表示 版の記録 【確認済】一般的な方法 Dify 開発環境:Windows対応・MTG・コマンド | 11/17
コマンド全集 3/5:WSL 内(Ubuntu の基本)(2/2) コマンド 意味 使う場面 注意 hostname -I WSL の IP アドレスを表示 ネットワーク確認 再起動で変わることがある ls -l 権限と所有者を表示 権限の確認 rwx の読み方を確認 chmod ファイルの権限を変える 秘密情報の保護 広く開けすぎない sudo 管理者として実行する パッケージ導入など 内容を理解してから使う sudo apt update 導入できる一覧を更新 導入の前 導入はしない sudo apt install パッケージ名 パッケージを導入する 必要な道具の導入 導入元の確認 Dify 開発環境:Windows対応・MTG・コマンド | 12/17
コマンド全集 4/5:Git・VSCode・Dify 周辺(1/2) コマンド 意味 使う場面 注意 git clone URL リポジトリを複製する ソースの取得 URL の出どころを確認 git status 変更の有無を表示 作業前の確認 未コミットの変更を見る git diff 変更内容を比べる 記録の前の確認 出力を読めるように git log --oneline 履歴を一行ずつ表示 版の確認 古い順ではなく新しい順 git describe --tags 最も近いタグ(版)を表示 Dify の版の確認 タグがない場合は別の確認 git fetch --tags タグ(版)の一覧を取得 最新版の確認 ネットワークが必要 Dify 開発環境:Windows対応・MTG・コマンド | 13/17
コマンド全集 4/5:Git・VSCode・Dify 周辺(2/2) コマンド 意味 使う場面 注意 git checkout タグ 指定の版に切り替える 版の変更 未コミットの変更があると失 敗 git stash / git stash pop 変更を一時的に退避 / 戻す 切り替えの前 pop を忘れない git config --global core.autocrlf input 改行コードの変換を設定 Windows の改行対策 設定後にファイルを取り直す git reset --hard 作業中の変更を捨てる (通常は使わない) 変更が失われる。実行前に確 認 code . 今のフォルダを VSCode で開く 編集の開始 WSL 内で実行する code --version VSCode の版を表示 導入の確認 表示されない場合は PATH Dify 開発環境:Windows対応・MTG・コマンド | 14/17
コマンド全集 5/5:Docker・Compose(Dify の起動と保守)(1/2) コマンド 意味 使う場面 注意 docker version Docker の Client と Server の版 導入の確認 Server が表示されない時は Desktop を確認 docker compose version Compose の版を表示 要件(2.24.0 以上)の確認 古い版は要更新 docker compose up -d 設定のサービスを起動(-d はバックグラウンド ) 起動 docker フォルダで実行 docker compose ps サービスの状態と公開ポートを表示 状態確認 最初に見る docker compose logs --tail=100 api api の最新 100 行のログ 原因の調査 サービス名は ps で確認 docker compose down 停止して後片付け(データは残る) 停止 down -v は使わない Dify 開発環境:Windows対応・MTG・コマンド | 15/17
コマンド全集 5/5:Docker・Compose(Dify の起動と保守)(2/2) コマンド 意味 使う場面 注意 docker compose down -v 停止し、ボリュームも削除 (通常は使わない) データが消える。実行しな い docker compose pull イメージを取得する 更新の準備 途中で止まったら再実行 docker compose config 合成された最終設定を表示 設定の確認 秘密情報を含む。共有しな い docker compose port nginx 80 公開ポートの対応を表示 公開先の確認 nginx はサービス名 docker images / docker ps イメージ・実行中コンテナの一覧 状態の確認 停止中は ps -a docker system df ディスク使用量を表示 容量の確認 定期的に確認 Dify 開発環境:Windows対応・MTG・コマンド | 16/17
出典と確認状況 項目 出典 状況 Compose 2.24.0 以上・停止と更新の手順 docs.dify.ai(Dify の Docker Compose・Premium 手 順) 【確認済】 設定の優先順位・override docs.dify.ai(Premium 手順) 【確認済】 WSL・PowerShell・VSCode・Docker の各コマンド 各公式ドキュメント 【要確認】実機で確認が 必要 Docker Desktop の利用条件(組織規模による) Docker 公式 【要確認】最新の条件を 確認 Windows 版・仮想化の要件 Microsoft 公式 【要確認】 Dify 開発環境:Windows対応・MTG・コマンド | 17/17
4. Windows で VSCode・PowerShell・ WSL をコマンドで使う(法人研修) 収録元:Windows_VSCode_PowerShell_WSL_法人研修.pptx(17枚)
Windows で VSCode・PowerShell・WSL をコマン ドで使う 法人研修:DXエンジニア向け(実務・お客様提案に使える版) よくあるエラー | もっと学びたいとき(出典つき)| Why・What・How | 図解 | 問いかけ
対象者と到達目標 区分 内容 対象者 DXエンジニア(Windows で開発する方)。お客様の環境を提案する担当者 前提 Windows の基本操作、ターミナル(PowerShell)を開けること 到達目標1 VSCode を PowerShell とWSLのコマンドから開ける 到達目標2 WSL の版と状態を確認し、必要な変更を安全に行える 到達目標3 よくあるエラーを、原因の順に切り分けられる 到達目標4 お客様に、環境の提案を根拠つきで説明できる 問いかけ:あなたの現場で、いちばん多い「動かない」は、どの段階で起きていますか? Windows で VSCode・PowerShell・WSL | 2/17
図解:Windows・PowerShell・WSL・VSCode の関係 PowerShell(Windows) VSCode(Windows) ブラウザ(結果) WSL 2(Ubuntu) ~/dify(ファイル) Docker(コンテナ) PowerShell は「入り口」、WSL は「実行場所」、VSCode は「編集場所」 問いかけ:どの作業を、どの層で行うべきか。逆に、Windows 側で行うと困る作業は何ですか? Windows で VSCode・PowerShell・WSL | 3/17
Why・What・How:VSCode 項目 Why(なぜ) What(何か) How(コマンド・操作) 出典 VSCode 編集と実行を一つにまとめる 軽量なエディタ code . で開く 【要確認】VSCode 公 式 code コマンド PowerShell から開くため VSCode の起動コマンド code --version で確認 【要確認】VSCode 公 式 WSL 拡張 Linux 側のファイルを編集する ため WSL に接続する拡張 左下に WSL: Ubuntu と表示 【要確認】VSCode 公 式 コマンドパレット 操作を名前で呼ぶため 全機能への入口 Ctrl+Shift+P 【要確認】VSCode 公 式 問いかけ:code . の「.」は何を指しますか? 別のフォルダを開きたい時はどうしますか? Windows で VSCode・PowerShell・WSL | 4/17
Why・What・How:PowerShell 項目 Why(なぜ) What(何か) How(コマンド) 出典 PowerShell Windows の操作を自動化するた め Windows の標準的なシェル 起動してコマンドを入力 【要確認】 Microsoft 公式 cd / Set-Location フォルダを移動するため 作業場所の変更 Set-Location C:\work 【要確認】 Microsoft 公式 Get-Location(pwd) 今の場所を確かめるため 現在のフォルダ pwd と入力 【要確認】 Microsoft 公式 実行ポリシー 不正なスクリプトを防ぐため スクリプトの実行制限 Get-ExecutionPolicy 【要確認】 Microsoft 公式 問いかけ:PowerShell で curl と打つと、期待どおりの結果になりますか? なぜですか? Windows で VSCode・PowerShell・WSL | 5/17
Why・What・How:WSL(Windows Subsystem for Linux) 項目 Why(なぜ) What(何か) How(コマンド) 出典 WSL 2 Linux の環境を Windows の中 で使うため 仮想化された Linux wsl --install(管理者) 【要確認】 Microsoft WSL 公式 ディストリビューション 用途に合った Linux を選ぶため Ubuntu など wsl -l -v で一覧 【要確認】 Microsoft WSL 公式 VERSION 2 Docker などが正しく動くため WSL の世代 wsl --set-version Ubuntu 2 【要確認】Dify 手順と合わせて確 認 Linux 側の場所(~) ファイルの速さと権限のため Ubuntu のホーム cd ~(/mnt/c は避ける) 【要確認】Dify 公式の推奨 問いかけ:Windows のフォルダで作業すると、なぜ遅くなることがあるのでしょうか? Windows で VSCode・PowerShell・WSL | 6/17
VSCode をコマンドで開く(PowerShell からの手順) PowerShell を開く wsl -d Ubuntu cd ~/dify コマンド 意味 確認の目安 wsl -d Ubuntu Ubuntu を起動して入る(-d は対象の指定) プロンプトが Ubuntu に変わる cd ~/dify ホーム配下の dify に移動する pwd で場所を確認 code . 今のフォルダを VSCode で開く(. は今の場所) 左下に WSL: Ubuntu が出る 問いかけ:PowerShell のまま code . を打つと、何が開くでしょうか? Windows で VSCode・PowerShell・WSL | 7/17 code . WSL 接続を確認
WSL の確認と操作(コマンドと意味) コマンド 意味 注意 wsl -l -v 導入済みの一覧と VERSION を表示 VERSION 2 を確認 wsl --set-version Ubuntu 2 Ubuntu を WSL 2 に変換 時間がかかる。作業中は避ける wsl --version WSL 本体の版を表示 【要確認】新しい WSL で使える wsl --shutdown WSL を停止する(設定の反映) 作業中の内容が止まる wsl --unregister Ubuntu Ubuntu 環境を削除する 復元できない。研修では実行しない 問いかけ:.wslconfig を変えたのに効かない時、最初に実行するコマンドは何ですか? Windows で VSCode・PowerShell・WSL | 8/17
PowerShell の注意点(実行ポリシーと引用符) スクリプトが拒否される Get-ExecutionPolicy で確 認 組織の方針を確認 必要なら承認を得て変更 • 実行ポリシーは組織の方針に従う。個人の判断で緩めない(【要確認】設定の名称は版で異なる) • パスに空白がある時は "..." で囲む(例:notepad "$env:UserProfile\.wslconfig") • $env:UserProfile は環境変数の値を表示する($env: の後に名前を付ける) 問いかけ:実行ポリシーを緩めることの、組織としてのリスクは何でしょうか? Windows で VSCode・PowerShell・WSL | 9/17
よくあるエラー 1/2:導入と WSL 症状 原因(よくあるもの) 一次対応 出典 WSL 2 が使えない・VERSION 1 仮想化が無効/WSL 版が古い BIOS/UEFI の仮想化を有効化。wsl --set-version Ubuntu 2 【要確認】 Microsoft wsl コマンドが見つからない WSL が未導入、または古い版 管理者で wsl --install。再起動する 【要確認】 Microsoft .wslconfig が効かない WSL を再起動していない wsl --shutdown のあと Ubuntu を開き直す 【要確認】 Microsoft Ubuntu のファイルが遅い Windows 側の場所で作業 ~ の下で作業する(/mnt/c を避ける) 【確認済】 Dify 公式の推 奨 問いかけ:仮想化が無効のとき、画面のどこで気づけますか?(タスクマネージャーを使って考えてください) Windows で VSCode・PowerShell・WSL | 10/17
よくあるエラー 2/2:VSCode・PowerShell・Docker・ポート 症状 原因(よくあるもの) 一次対応 出典 code が認識されない VSCode の PATH 未登録 コマンドパレットで PATH 登録。ターミナルを開き 直す 【要確認】 VSCode 公式 スクリプトが実行できない 実行ポリシーの制限 Get-ExecutionPolicy で確認し、組織の方針に従う 【要確認】 Microsoft docker が接続できない Docker Desktop が未起動・WSL 統合が 無効 Docker Desktop を起動。WSL 統合で Ubuntu を有 効化 【確認済】 Dify 手順と一 般的動作 ポートが使用中 同じポートの別のソフト netstat -ano | findstr :80 で PID を確認 【要確認】一 般的な方法 改行の警告・ファイルの差分が大量 Windows の改行コード(CRLF/LF) git config --global core.autocrlf input 【要確認】Git 公式 問いかけ:「ポートが使用中」のとき、どのソフトが使っているかを、何で確かめますか? Windows で VSCode・PowerShell・WSL | 11/17
図解:エラーの切り分けの順番 症状を記録 PowerShell で状態を確認 WSL の版と状態 VSCode と権限 ログを見る 一か所だけ直す 問いかけ:「一か所だけ直す」を守らないと、どんな問題が起きますか? Windows で VSCode・PowerShell・WSL | 12/17 Docker と Compose
お客様への提案:提案の型(4段階) 課題をヒアリング 環境を診断 導入案を提示 効果・リスクを説明 段階 伝えること 根拠(出典) 課題 どこで止まっているかを、お客様の言葉で確認 ヒアリングシート 診断 PC の版、仮想化、権限、ネットワークの確認 事前確認チェック 提案 WSL 2 と Docker の導入手順、役割分担、承認の流れ 公式の導入手順【確認済】 リスク キー・データ・課金・版の変更の扱い リスク表 問いかけ:お客様が「費用はいくら?」と聞いたら、どう答えますか?(根拠の出どころを添えて) Windows で VSCode・PowerShell・WSL | 13/17
お客様へのヒアリング:問いかけ例 • 現在の PC の Windows の版と、導入の権限はどこにありますか? • 仮想化(WSL 2 の前提)を、情報システムで確認できますか? • データを外部に送ってよい範囲は、どこまでですか? • 誰が APIキーや請求を管理しますか? • 障害時の連絡先と、対応時間の目安はありますか? • 過去に導入で止まった経験はありますか? Windows で VSCode・PowerShell・WSL | 14/17
もっと学びたいとき:学習の順番 基本操作( PowerShell) WSL の仕組み VSCode の操作 Docker・ Compose • 最初は、コマンドを一行ずつ実行し、表示の意味を言葉にする • 次に、同じ作業を別の環境(検証)で再現する • 最後に、障害の記録を残し、次の人の手順書にする 問いかけ:今の学習の段階は、どこですか? 次に進む前に、何を確かめますか? Windows で VSCode・PowerShell・WSL | 15/17 Dify の構成 運用と記録
もっと学びたいとき:出典一覧(一次情報) 分野 出典(公式) 状況 Dify の導入と Compose の版 docs.dify.ai(Docker Compose によるデプロイ) 【確認済】検索で確認 Dify の基本概念(アプリの種類) docs.dify.ai/ja/learn/key-concepts 【確認済】検索で確認 WSL の導入・設定 learn.microsoft.com/windows/wsl/ 【要確認】今回は未アクセス VSCode のコマンドラインと WSL code.visualstudio.com/docs(command-line・remote/wsl) 【要確認】今回は未アクセス PowerShell の基本 learn.microsoft.com/powershell/ 【要確認】今回は未アクセス Docker Compose docs.docker.com/compose/ 【要確認】今回は未アクセス 問いかけ:この表の中で、お客様提案の根拠として使うには、どの出典の確認が先に必要ですか? Windows で VSCode・PowerShell・WSL | 16/17
まとめ:判断の理由(Why)を言えれば、コマンドは怖くない 問い:今日学んだコマンドを、一つ、理由つきで説明できますか? 問い:お客様の環境で、最初に確かめるのは何ですか? 問い:次に、どの出典を一次で確認しますか? Windows で VSCode・PowerShell・WSL | 17/17
5. 生成AI API チャットボット(法人研修・ DXエンジニア向け) 収録元:Dify_生成AI_法人研修_DXエンジニア向け.pptx(16枚)
生成AI APIを使った社内チャットボットの構築 法人研修 | DXエンジニア(初めて作る方)向け | 約3時間(演習含む) ツール:Dify(Chatflow)+ OpenAI プラグイン | 公式ドキュメントに基づき、組織の承認と運用を前提に設計
学習目標(修了時にできること) No. 学習目標 評価の方法 1 生成AI API の仕組み(従量課金・キー・モデル)を説明できる 確認テスト(用語) 2 Dify に生成AI のプラグインを導入し、APIキーを安全に登録できる 設定の画面確認 3 社内規程を題材に、Chatflow で回答するボットを作れる 演習の成果物 4 機密情報・誤答・課金のリスクを挙げ、対応を決められる リスク表の作成 5 変更記録と運用手順を残し、引き継げる 手順書・記録の提出 生成AI APIチャットボット(法人研修) | 2/16
対象・前提・範囲 区分 内容 対象 DXエンジニア。生成AI・Dify は初めて扱う方を含む 前提 Windows の操作、ブラウザ操作、Dify にログインできること 範囲 Chatflow の作成、OpenAI プラグインの導入、プロンプト、テスト、運用の基本 範囲外 モデルの学習、大規模な性能設計、本番のセキュリティ監査(別途) 必要な承認 利用ガイドライン、情報セキュリティ部門の確認、APIキーの管理者 生成AI APIチャットボット(法人研修) | 3/16
全体像:利用者から OpenAI API までの流れ 利用者(社員) Dify(Chatflow) LLM ノード OpenAI プラグイン 層 責任者(RACI の A) 確認する人 Dify の画面・プロンプト 開発(R) プレビュー結果 APIキー・請求 管理責任者(A) 利用量・上限の確認 社内ルール・データの扱い 情報セキュリティ部門 承認の記録 生成AI APIチャットボット(法人研修) | 4/16 OpenAI API
Why・What・How:基本用語(出典つき) 用語 Why(なぜ) What(何か) How(どう使う) 出典 Chatflow 会話の流れを組むため 会話型アプリの種類 Studio で作成 【確認済】Dify 基本概 念 プラグイン モデルの接続を部品化するため 提供元との接続部品 Marketplace から導入 【確認済】Dify Marketplace APIキー 呼び出しを認証するため 秘密の文字列 Model Provider で登録 【確認済】プラグイン 説明 従量課金 使った分の支払いのため 利用量に応じた料金 上限と通知を先に設定 【要確認】OpenAI 公 式 生成AI APIチャットボット(法人研修) | 5/16
準備1:承認と環境(着手前に必ず確認) 利用の承認 アカウント作成 支払い・上限の設定 キーの保管先決定 Dify の起動確認 項目 確認者 完了の記録 利用ガイドラインに適合している 情報セキュリティ部門 承認番号 外部送信してよいデータの範囲 情報セキュリティ部門・利用部門 範囲の一覧 請求の上限額 管理責任者 上限額と設定日 APIキーの保管場所 管理責任者 保管場所(台帳) 生成AI APIチャットボット(法人研修) | 6/16
準備2:プラグインの導入と APIキーの登録 Marketplace で検索 langgenius/openai を 確認 Install Model Provider で Setup • 【確認済】公式の OpenAI プラグイン(langgenius/openai)が Marketplace にある • 【確認済】APIキーは Model Provider の設定で登録する • 注意:発行元が公式か、必ず確認する。キーを画面共有・チャットに貼らない • 【要確認】画面の位置は版と契約で異なる 生成AI APIチャットボット(法人研修) | 7/16 API Key を保存
設計:プロンプトの構成要素 要素 目的 記述の例(社内規程FAQ) 役割 回答の立場を固定する 社内規程の案内役として答える 範囲 答えてよい領域を限定する 社内規程に関する質問のみ 根拠 推測を減らす 規程の該当箇所を引用して答える 不明時 誤答を防ぐ わからない場合は担当部門へ案内する 形式 読みやすさを揃える 結論→根拠→問い合わせ先の順 生成AI APIチャットボット(法人研修) | 8/16
構築:Chatflow の組み立て Start(入力) LLM(生成) Answer(回答) ノード 設定する項目 確認の方法 Start 入力変数(必要な場合のみ) プレビューで入力が届く LLM モデル・システムプロンプト・ユーザー入力 出力の内容を確認 Answer LLM の出力を参照する 画面に回答が表示される 生成AI APIチャットボット(法人研修) | 9/16
検証:質問セットで回帰テストする 質問セットを作る(10 問) プレビューで実行 期待と比べる 一か所だけ変える 区分 問いの例 合格の目安(案) 通常質問(6問) 規程の要点を聞く質問 期待する要点を含む 範囲外(2問) 社外のニュースなど 範囲外と伝えて案内する あいまい(2問) 主語のない質問など 確認の質問を返す 生成AI APIチャットボット(法人研修) | 10/16 再実行し記録
リスクと対応(法人の視点) リスク 影響 予防 発見・対応 APIキーの漏えい 第三者の利用・高額請求 保管台帳、画面共有禁止 即時の再発行と利用履歴の確認 想定外の課金 予算超過 上限・通知の設定 請求の確認と上限の見直し 機密情報の外部送信 情報漏えい テストは架空データのみ インシデントとして報告 誤答による判断ミス 業務上の損害 出典確認、担当者への案内 誤答の記録と質問セットへの追加 版変更による挙動の変化 回答の質の変化 変更前後で質問セットを比較 変更記録と差し戻し 生成AI APIチャットボット(法人研修) | 11/16
トラブル対応(一次対応の手順) 症状 考えられる原因 一次対応 認証エラー(401 など) キーの誤り・無効 キーを確認し、台帳と照合して再登録 利用上限(429 など) レート制限・利用枠の超過 時間をあけて再試行。請求設定を確認 モデルが見つからない モデル名の誤り 公式の一覧で名前を確認 応答が返らない 通信・タイムアウト logs を確認し、一か所だけ直す プラグインが見つからない 未導入・発行元の誤り Marketplace で発行元を確認 生成AI APIチャットボット(法人研修) | 12/16
評価ルーブリック(演習の採点基準) 観点 4(十分) 2(一部) 0(不足) 配点 機能 5問以上で期待どおり回答 3〜4問 2問以下 20 安全 キー・データの扱いが適切 一部に不備 不備が重大 25 範囲外の対応 範囲外で答えを作らない 一部で推測 推測で答える 20 記録 変更と結果を1行ずつ記録 一部のみ 記録なし 15 説明 根拠と次の一手を説明できる 一部説明 説明できない 20 生成AI APIチャットボット(法人研修) | 13/16
修了課題・提出物・受講記録 • 課題:自社の「よく聞かれる質問」10問を用意し、Chatflow で回答させる • 提出物1:Chatflow の画面(個人情報・キーは隠す) • 提出物2:質問セットと結果の表(判定を含む) • 提出物3:変更記録(日付・変更内容・理由・結果) • 受講記録:氏名・受講日・評価・承認者を台帳に残す(個人情報は社内規程に従う) 生成AI APIチャットボット(法人研修) | 14/16
運用:公開後に必要なこと(保守の型) 利用者の声を集める 誤答を記録 質問セットに追加 一か所ずつ改善 版と記録を更新 頻度 作業 担当 毎日 エラーと利用量の確認 運用担当(R) 週次 誤答の記録と質問セットの更新 開発(R) 月次 APIキーの棚卸しと請求の確認 管理責任者(A) 随時 モデルや版の変更の検証 開発(R)・承認は管理責任者(A) 生成AI APIチャットボット(法人研修) | 15/16
参考と確認状況 項目 出典 状況 OpenAI プラグインの導入とAPIキーの登録 Dify Marketplace(langgenius/openai)・Dify のモデル 設定の説明 【確認済】検索で確認 Dify の基本概念(アプリの種類) Dify 公式(docs.dify.ai) 【確認済】検索で確認 画面の名称・メニュー位置 Dify の版により異なる 【要確認】実機で確認 料金・利用上限・エラー仕様 OpenAI 公式 【要確認】受講前に最新を 確認 社内の利用ルール 組織の規程 【要確認】承認の記録を確 認 生成AI APIチャットボット(法人研修) | 16/16
6. Dify × ChatGPT API:チャットボット実 践講座 収録元:Dify_ChatGPT_API_チャットボット実践講座.pptx(14枚)
Dify × ChatGPT API:チャットボット実践講座 OpenAI のプラグインを使い、社内FAQボットを自分で作る(約90分) 前提:Dify が起動していること、OpenAI の APIキーを持つこと。API は従量課金です(費用は利用量で変わります)
全体像:利用者 → Dify → OpenAI API 利用者(質問) Dify(Chatflow) LLM ノード OpenAI プラグイン OpenAI API 要素 役割 設定の場所 Chatflow 会話の流れを組み立てる(Start → LLM → Answer) Studio で作成 LLM ノード モデルへの指示(プロンプト)と呼び出し ノードの設定 OpenAI プラグイン Dify から OpenAI のモデルを使えるようにする部品 Marketplace から導入 APIキー OpenAI への認証。第三者に渡すと課金される Model Provider 設定 Dify × ChatGPT API | 2/14
Why・What・How:この講座の基本用語 用語 Why(なぜ) What(何か) How(どう使う) プラグイン モデルの接続を部品化するため モデル提供元との接続部品 Marketplace で Install Model Provider APIキーを一か所で管理するため 提供元ごとの設定画面 Settings → Model Provider APIキー OpenAI に呼び出しを認めるため 秘密の文字列 Setup で入力して保存 従量課金 使った分だけ支払うため 利用量に応じた料金 利用上限と請求を先に設定 Dify × ChatGPT API | 3/14
準備:始める前の確認 確認項目 確認方法 NGの場合 Dify が起動している http://localhost にログインできる Dify入門の起動手順に戻る OpenAI のアカウント OpenAI の管理画面にログインできる アカウントを作成する 支払いと利用上限 請求設定で、上限額を設定する 上限を決めるまでキーを入れない APIキーの保管場所 パスワード管理ツールなどに保管 メモ帳やチャットに貼らない 社内データの扱い 情報システムで外部送信の可否を確認 機密情報はテストに使わない Dify × ChatGPT API | 4/14
Step 1:OpenAI プラグインを導入する Marketplace を開く openai で検索 langgenius/openai Install • 【確認済】公式の OpenAI プラグインは Dify Marketplace で公開されている • 【要確認】画面の名前(Marketplace の場所)は版と契約で異なる場合がある • 注意:提供元が不明なプラグインは入れない(公式の名前と発行元を確認) Dify × ChatGPT API | 5/14 導入の確認
Step 2:APIキーを登録する Model Provider を開く OpenAI を選ぶ Setup API Key を入力 Save 項目 内容 注意 API Key OpenAI で作ったキー 画面に表示して共有しない Organization ID(任意) 組織を指定する場合のみ 通常は空でよい API Base URL(任意) 既定の接続先を変える場合のみ 社内プロキシ等の指示があるときだけ Dify × ChatGPT API | 6/14
Step 3:Chatflow を作る(ノードの意味) Start(入力) LLM(生成) Answer(回答) ノード 意味 設定する主な項目 Start 利用者の入力を受け取る 入力変数(任意) LLM OpenAI のモデルに指示して文章を作る モデル・システムプロンプト・ユーザー入力 Answer 利用者に返す文章を決める LLM の出力を参照する Dify × ChatGPT API | 7/14
Step 4:プロンプトを設計する(Why・What・How) 観点 内容(例) 役割(Why) 回答の立場を決め、答えの質を安定させる 範囲(What) 社内規程に関する質問だけに答える、など 形式(How) 箇条書き、最後に出典を書く、など 禁止(Why) 推測で断定しない、わからない時は担当者へ案内 Dify × ChatGPT API | 8/14
Step 5:テストと改善(5問で確認する) 質問を5つ用意 プレビューで実行 期待と比べる 一か所だけ変える 記録する No. 質問 期待する回答の要点 判定 1 有給休暇は何日ありますか? (自社規程に基づく要点) ○/× 2 出張の申請方法を教えてください (手順の要点) ○/× 3 社外への情報持ち出しは可能ですか? (禁止事項の要点) ○/× 4 (範囲外の質問)明日の天気は? 範囲外と伝えて案内する ○/× 5 (あいまいな質問)手続きを教えて 確認の質問を返す ○/× Dify × ChatGPT API | 9/14
リスクと対応(実務で起きやすいもの) リスク 起きる場面 影響 対応 APIキーの漏えい 画面共有・チャットへの貼り付け 第三者に使われ、高額請求 キーを再発行し、履歴を確認 想定外の課金 上限を決めず大量に実行 費用が増える 利用上限と通知を設定 機密情報の入力 テスト時に実データを入れる 外部へ送信される テストは架空のデータで行う 誤った回答 根拠のない断定 誤った業務判断 出典の確認と、担当者への案内 モデル変更による挙動の変化 モデルの名前や版を変える 回答の質が変わる 変更前後で質問セットを比べる Dify × ChatGPT API | 10/14
トラブル対応(よくあるエラー) 症状 考えられる原因 確認・対応 認証エラー(401 など) APIキーの誤り・無効 キーを確認し、再登録する 利用上限(429 など) レート制限・利用枠の超過 時間をあけて再試行。請求設定を確認 モデルが見つからない モデル名の誤り・未対応 モデル名を公式の一覧で確認 応答が返らない・遅い ネットワーク・タイムアウト logs で確認し、一度に一か所だけ直す プラグインが見つからない 未導入・発行元の誤り Marketplace で langgenius/openai を確認 Dify × ChatGPT API | 11/14
関係性の確認:どこで何が起きるか 利用者の質問 Chatflow LLM ノード プラグイン OpenAI API 層 見る場所 確認の例 Dify の画面 プレビュー 質問への回答が出るか LLM ノード ノードの実行結果 入力と出力の内容 プラグインの設定 Model Provider キーが登録されているか OpenAI 側 OpenAI の利用状況画面 利用量・エラーの記録 Dify × ChatGPT API | 12/14 回答
修了課題と評価 • 課題:自社の「よく聞かれる質問」を5つ用意し、Chatflow で回答させる • 合格の目安(案):5問中4問で期待する要点を含む。範囲外の質問で答えを作らない • 提出物:Chatflow の画面(個人情報を隠す)、テスト結果の表、変更の記録(1行) • 注意:実データを含む提出物は、社内規程に従って扱う Dify × ChatGPT API | 13/14
参考と確認状況 項目 出典 状況 OpenAI プラグインの導入と APIキーの登録 Dify Marketplace(langgenius/openai)・Dify の Model Provider の説明 【確認済】検索で確認 Dify のモデル設定の考え方 Dify 公式(モデル設定のチュートリアル) 【確認済】検索で確認 画面の名称・メニューの位置 Dify の版により異なる 【要確認】実機で確認 OpenAI の料金・上限・エラー仕様 OpenAI 公式 【要確認】最新の条件を 確認 Dify × ChatGPT API | 14/14