Contents
Dify の概要と主要機能
Dify はオープンソースの LLM アプリ開発プラットフォームで、ノーコード／ローコード環境だけで AI エージェント や RAG（Retrieval‑Augmented Generation）パイプライン を構築できます。本節では、本ツールが提供する 4 つのコア機能を整理し、以降の手順が何に役立つかを簡潔に示します。
- エージェント機能 – プロンプトとツールチェーンで条件分岐や外部 API 呼び出しを定義でき、対話型アプリを数クリックで作成可能です。
- RAG パイプライン – ドキュメントアップロード → ベクトルインデックス生成 → 検索と生成のフローが UI のみで完結します。
- モデル管理 – OpenAI、Anthropic、Claude、Gemini など複数プロバイダーを統合し、バージョン切替やトークン使用量の可視化が行えます。
- Observability（可観測性） – Opik、Langfuse、Arize Phoenix と連携してリクエストログ・トークン消費・レイテンシをリアルタイムに取得でき、運用時のボトルネック特定や品質改善が容易になります。
これらの機能が一体化しているため、開発者は 「アイデア → プロトタイプ → 本番」 のサイクルを高速で回せます。
ローカル環境の要件とセットアップ手順
このセクションでは、Dify をローカルマシン上で動作させるために最低限必要なソフトウェアとハードウェア構成、および Windows（WSL2＋Docker Desktop）・macOS／Linux 向けの推奨設定を紹介します。環境が整っていないとコンテナ起動やイメージ取得時にエラーになるため、必ず事前確認してください。
必要ソフトウェアとバージョン
| ソフトウェア | 推奨バージョン | 入手先 |
|---|---|---|
| Docker Engine / Desktop | 24.0 以上（2024‑10‑01 時点） | https://docs.docker.com/engine/install/ |
| Docker Compose (v2) | 2.25 以上 | 同上 |
| WSL2（Windows のみ） | Ubuntu 22.04 LTS 推奨 | wsl --install -d Ubuntu |
| Git | 2.40 以上 | https://git-scm.com/downloads |
ハードウェアの最小構成とスケーリング指針
| 項目 | 最低要件 | 推奨上限 | スケールアウトのヒント |
|---|---|---|---|
| CPU | 2 vCPU | 4‑8 vCPU 以上（負荷テスト時） | K8s の Horizontal Pod Autoscaler (HPA) を利用し、CPU 使用率が 70 % 超えたら自動でレプリカ数を増やす |
| メモリ | 8 GB（Docker に割り当て） | 16‑32 GB 推奨 | docker compose の mem_limit オプション、または K8s の resources.requests.memory/limits.memory を設定 |
| ストレージ | 20 GB (PostgreSQL + ベクトルストア) | 100 GB 以上（大量ドキュメント） | 永続ボリュームを PV として確保し、必要に応じて拡張できるストレージクラス (e.g., gp3) を選択 |
| ネットワーク | ポート 3000, 8000, 5432 が外部からアクセス不可でも可 | 本番では TLS 終端をリバースプロキシで実装 | Ingress コントローラに rate‑limit と IP allowlist を設定 |
ポイント：ローカル開発は「メモリ 8 GB、CPU 2 コア」でも起動できますが、RAG のベクトル化や複数エージェント同時実行を想定する場合は上記推奨スペック以上を確保すると快適です。
Windows (WSL2) 向けインストール手順
- Windows 機能の有効化
-
「設定」→「アプリと機能」→「プログラムと機能」→「Windows の機能の有効化または無効化」で 仮想マシンプラットフォーム と WSL にチェックを入れ、再起動。
-
WSL2 ディストリビューション取得
powershell
wsl --install -d Ubuntu -
Docker Desktop のインストール（公式サイト 2024‑10‑01 版）
-
インストーラ実行後、設定画面で 「Use the WSL 2 based engine」 を有効化。
-
リソース割り当て
- Docker Desktop → Settings → Resources で Memory: 8 GB 以上、CPU: 2 コア以上 に設定し、
Apply & Restartをクリック。
Docker が WSL2 と正しく連携していないと
docker compose up時に「Cannot connect to the Docker daemon」エラーが出ます（Docker Docs – WSL 2 backend 参照、取得日: 2024‑10‑01）。
macOS / Linux 向け推奨設定
| OS | 必要ソフトウェア | 推奨リソース |
|---|---|---|
| macOS (Ventura 13+) | Docker Desktop for Mac、Homebrew | メモリ 8 GB、CPU 2 コア |
| Ubuntu 22.04 LTS 以降 | docker.io、docker-compose、git | 同上 |
|
1 2 3 4 5 6 7 |
# Ubuntu の例（公式パッケージ 2024‑10‑01 時点） sudo apt update && sudo apt install -y docker.io docker-compose git # Docker グループへの追加と再ログイン sudo usermod -aG docker $USER newgrp docker # すぐに権限を反映させる場合 |
docker info コマンドで Total Memory が 8 GB 以上かどうか確認し、足りない場合は /etc/docker/daemon.json に "default-runtime": "runc" と共にリソース制限を上書きしてください。
Dify のインストール・初期設定
この章では、GitHub からのクローン、Docker イメージ取得（高速化オプション含む）、そして実際に動かすための .env 設定例を示します。設定ミスがあるとコンテナ起動直後にエラーになるため、必ず公式リポジトリの最新版（2024‑10‑01） を参照してください。
リポジトリ取得とイメージビルド
|
1 2 3 4 5 6 7 |
# 1. リポジトリをクローン（公式 README: https://github.com/langgenius/dify/blob/main/README.md, アクセス日: 2024‑10‑01） git clone https://github.com/langgenius/dify.git cd dify # 2. Docker Compose でバックエンド・フロントエンドを起動（キャッシュ利用で高速化） docker compose up -d |
イメージ取得の高速化（ミラー設定）
- 旧方式：
registry.docker-cn.com等の中国向けミラーは 2023 年末に非推奨となり、現在は公式 Docker Hub が最も安定しています。 - 新方式：国内からのアクセスが遅い場合は、Docker Desktop の Settings → Resources → Proxies に企業プロキシを設定するか、
~/.docker/config.jsonに以下のようにregistry-mirrorsを追加してください（2024‑10‑01 時点の公式推奨ミラーはhttps://mirror.gcr.io）。
|
1 2 3 4 |
{ "registry-mirrors": ["https://mirror.gcr.io"] } |
注意：ミラーレジストリは随時変更されるため、最新情報は Docker の公式ブログ（2024‑09‑15 記事）を確認してください。
.env の作成と主要パラメータの解説
|
1 2 |
cp .env.example .env |
以下に必須項目と推奨設定例を示します。機密情報は必ず 環境変数 として管理し、リポジトリにコミットしないでください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
# ------------------------------ # LLM プロバイダー（例: OpenAI） # ------------------------------ OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX # 取得日: 2024‑09‑30 # ------------------------------ # データベース設定（PostgreSQL 推奨） # ------------------------------ POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=dify_user POSTGRES_PASSWORD=StrongPass123! # パスワードはランダム生成を推奨 POSTGRES_DB=dify_db # ------------------------------ # アプリケーションシークレット # ------------------------------ SECRET_KEY=$(openssl rand -hex 16) # 32 桁のランダム文字列 # ------------------------------ # Observability（可観測性）連携設定 # ------------------------------ OPIK_ENDPOINT=https://api.opik.ai/v1/track OPIK_API_KEY=opik-xxxxxxxxxxxxxx # 発行日: 2024‑09‑20 LANGFUSE_PUBLIC_KEY=lf_xxxxxxxxxxxxxx LANGFUSE_SECRET_KEY=ls_xxxxxxxxxxxxxx LANGFUSE_HOST=https://cloud.langfuse.com ARIZE_ENDPOINT=https://api.arize.com/v1/metrics ARIZE_API_KEY=arize-xxxxxxxxxxxxxx |
| 項目 | 説明 |
|---|---|
OPENAI_API_KEY など |
各 LLM プロバイダーの認証トークン。取得方法は公式ドキュメント（2024‑10‑01）参照 |
SECRET_KEY |
Dify の JWT 署名に使用。32 バイト以上が安全です |
| Observability 系 | Opik・Langfuse・Arize Phoenix のエンドポイントと API キーを設定するだけで、管理画面左側の Observability タブに指標が集約されます |
.env を保存したら再度コンテナを起動します。
|
1 2 3 |
docker compose down # 既存コンテナ停止（必要なら） docker compose up -d # 環境変数反映で再起動 |
ブラウザで http://localhost:3000 にアクセスし、管理者アカウントを作成すればインストール完了です。
UI でエージェントとナレッジベースを作成する実践フロー
この章では、Dify の Web UI を使って Knowledge Base と Agent を構築する手順を具体的に示します。コードを書かずに「質問 → 検索 → レスポンス」のフルサイクルが完成します。
Knowledge Base（ナレッジベース）作成
- メニュー操作 – 左側ナビゲーションの Knowledge Bases をクリックし、右上の Create New ボタンを選択します。
- データソース選択 –
File Upload,Web URL,Git Repositoryのいずれかを選びます。ここではローカル PDF ファイルを例にしています。
大容量ドキュメント（> 10 MB）の場合は、
Chunk Sizeを 300‑500 tokens に設定し、インデックス作成時のメモリ使用量を抑えます（公式ガイド: https://github.com/langgenius/dify/blob/main/docs/knowledge_base.md, 取得日: 2024‑10‑01）。
- ベクトルエンジン選択 –
OpenAI Embedding（デフォルト）またはMistral Embeddingを指定し、Chunk Size: 500 tokens、Overlap: 50 tokensを設定します。 - インデックス作成 – 「Create Index」ボタンを押すとバックエンドでベクトル化が走り、完了するとステータスが Ready に変わります。
エージェント（Agent）設計
- Agents メニューへ遷移し、Create New をクリック。
- ベースプロンプト入力 – 以下のように業務シナリオを明示します。
あなたは社内ドキュメント検索アシスタントです。ユーザーからの質問に対して、Knowledge Base から根拠付きで回答してください。
-
ツールチェーン構成 – UI の「Tools」セクションで次を追加します。
-
Search Knowledge Base（パラメータ: Top K = 3, Score Threshold = 0.7） -
HTTP Request Tool（外部在庫システム呼び出し用） -
条件分岐設定 – 「If user asks about 在庫 → Call HTTP Request Tool」 のように
if‑elseロジックを UI 上で定義できます。 -
テスト実行 – 右上の Test ボタンで質問例（例: 「最新の製品カタログは？」）を投げ、検索結果と外部 API 呼び出しが期待通りか確認します。
ポイント：
Chunk SizeとTop Kの組み合わせは検索精度に大きく影響します。実運用前に数パターン試すことを推奨します（公式ベストプラクティス: 2024‑09‑28）。
デプロイと Observability 活用
ローカルで検証が完了したら、本番環境へデプロイしつつ可観測性ツールを有効化する方法を示します。ここでは Docker Compose と Kubernetes の両方のパターンを比較し、スケーラビリティと運用上の留意点を解説します。
デプロイ方式比較
| 方法 | 主な手順 | 推奨シナリオ |
|---|---|---|
| Docker Compose（本番） | docker compose -f docker-compose.prod.yml up -d → .env.production に機密情報を分離 |
小規模チーム、単一サーバーでの PoC |
| Kubernetes (EKS / GKE / AKS) | 1. Helm リポジトリ追加 helm repo add dify https://langgenius.github.io/dify-helm 2. カスタム values.yaml を作成 3. helm install dify dify/dify -f values.yaml |
大規模・マルチゾーン、オートスケーリングが必要な場合 |
重要な設定ポイント（K8s 共通）
- 永続化：PostgreSQL とベクトルストア（Weaviate または Milvus）は
PersistentVolumeClaimを作成し、バックアップポリシーを策定します。 - Secret 管理：API キー類は Kubernetes の
Secretリソースで暗号化し、Pod へ環境変数として注入します（例:envFrom:）。 - リソース制限：各コンテナに
resources.requests.cpu/memoryとlimits.cpu/memoryを設定し、過負荷時の OOM キルを防止します。
|
1 2 3 4 5 6 7 8 9 10 |
# values.yaml の抜粋例（CPU/Memory リクエスト） backend: resources: requests: cpu: "500m" memory: "1Gi" limits: cpu: "2" memory: "4Gi" |
Observability 機能の有効化
| ツール | 有効化設定例（Helm values.yaml） |
主な取得指標 |
|---|---|---|
| Opik | yaml opik: enabled: true endpoint: https://api.opik.ai/v1/track apiKey: ${OPIK_API_KEY} |
Prompt Tokens、Completion Tokens、Latency、Error Rate |
| Langfuse | yaml langfuse: enabled: true host: https://cloud.langfuse.com publicKey: ${LANGFUSE_PUBLIC_KEY} secretKey: ${LANGFUSE_SECRET_KEY} |
Prompt バージョン、評価スコア、ユーザーフィードバック |
| Arize Phoenix | yaml arize: enabled: true endpoint: https://api.arize.com/v1/metrics apiKey: ${ARIZE_API_KEY} |
Drift 検知、分布変化、モデル品質指標 |
有効化後は Dify の左サイドバーに Observability タブが表示され、エージェント単位でリアルタイムメトリクスを確認できます。ダッシュボードのカスタマイズ方法は各ツールの公式ドキュメント（2024‑10‑01 版）を参照してください。
カスタムツール統合の詳細手順とエラーハンドリング
本節では、独自 API を Dify のエージェントから呼び出すまでの具体的な実装例と、失敗時に取るべき対策を示します。以下の手順は 実務者向け に設計しており、コードスニペット・Dockerfile 例・CI/CD パイプラインへの組み込み方まで網羅しています。
1. カスタム API の作成と Docker 化
|
1 2 3 4 5 6 7 8 9 10 11 |
# Dockerfile (custom-tool) FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY ./src/ . # src ディレクトリに main.py がある前提 EXPOSE 8080 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"] |
requirements.txt の例
|
1 2 3 4 5 |
fastapi==0.110.* uvicorn[standard]==0.29.* httpx==0.27.* pydantic==2.7.* |
main.py（FastAPI）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
from fastapi import FastAPI, HTTPException import httpx app = FastAPI(title="Custom Inventory Service") @app.get("/stock/{item_id}") async def get_stock(item_id: str): # 本来は DB 参照だが、外部 API を呼び出す例 async with httpx.AsyncClient(timeout=5.0) as client: try: resp = await client.get(f"https://inventory.example.com/api/{item_id}") resp.raise_for_status() except httpx.HTTPError as exc: # エラーログを標準出力に残す print(f"外部在庫 API 呼び出し失敗: {exc}") raise HTTPException(status_code=502, detail="在庫情報取得エラー") return {"item_id": item_id, "stock": resp.json()["available"]} |
ビルドとプッシュ（GitHub Container Registry を使用）
|
1 2 3 |
docker build -t ghcr.io/yourorg/custom-tool:latest . docker push ghcr.io/yourorg/custom-tool:latest |
ベストプラクティス：イメージは
latestタグだけでなく、Git SHA もタグ付けし CI で自動テストを走らせる。
2. Docker Compose にカスタムツールサービスを追加
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
version: "3.8" services: dify-backend: image: langgenius/dify-backend:latest env_file: .env depends_on: - custom-tool custom-tool: image: ghcr.io/yourorg/custom-tool:sha-abcdef restart: unless-stopped ports: - "8081:8080" |
3. Dify UI に「Custom HTTP Tool」を登録
- Tools メニュー → Create New → HTTP Request を選択
- 以下の項目を入力
| フィールド | 設定例 |
|---|---|
| Name | Internal Inventory Lookup |
| Method | GET |
| URL | http://custom-tool:8080/stock/{item_id} |
| Headers | Authorization: Bearer {{ env.INVENTORY_API_TOKEN }} |
| Timeout | 5 (秒) |
| Retry | 3 回 |
環境変数参照：
{{ env.VAR_NAME }}で Docker Compose の.envに定義したシークレットを注入できます。
4. エラーハンドリングとリトライ戦略
- Dify 側は HTTP ステータスコードが
5xx系の場合、デフォルトで最大 3 回のリトライを行います（設定可能）。 - カスタム API側ではタイムアウト (
httpx.AsyncClient(timeout=5.0)) と例外捕捉により、失敗時は 502 Bad Gateway を返すようにしています。
失敗シナリオ別対処表
| シナリオ | 発生箇所 | 推奨対応 |
|---|---|---|
| 外部 API タイムアウト | httpx.ReadTimeout |
再試行回数を増やすか、バックエンド側でキャッシュ (redis) を導入 |
| 認証エラー 401 | ヘッダーに無効なトークン | 環境変数 INVENTORY_API_TOKEN が正しいか CI パイプラインで検証 |
| JSON パース失敗 | resp.json() エラー |
try/except ValueError を追加し、エラーメッセージを詳細化 |
5. CI/CD パイプラインへの組み込み例（GitHub Actions）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
name: Build & Deploy Custom Tool on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Log in to GitHub Container Registry uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v5 with: context: . file: Dockerfile push: true tags: | ghcr.io/yourorg/custom-tool:${{ github.sha }} ghcr.io/yourorg/custom-tool:latest - name: Run integration tests run: | pip install httpx pytest pytest tests/integration_test.py |
上記ジョブは ビルド → テスト → プッシュ のフローを自動化し、失敗した場合はデプロイが止まります。
トラブルシューティングと次のステップ
本節では、実装・デプロイ時に頻出するエラーとその診断手順、さらに今後拡張していく際のロードマップをまとめます。問題が起きたらまずログを確認し、表に示す対処法を順に試してください。
代表的なエラーパターンと解決策
| エラー | 発生箇所 | 主な原因 | 推奨診断コマンド・対処 |
|---|---|---|---|
manifest unknown（Docker pull 失敗） |
イメージ取得時 | レジストリ URL が古い、ミラーレジストリが非推奨 | docker pull langgenius/dify-backend:latest → エラー内容確認。公式 Docker Hub のタグ一覧 (https://hub.docker.com/r/langgenius/dify-backend/tags) を参照し最新タグを指定 |
401 Unauthorized（LLM API） |
.env に設定したキーが無効 |
キー期限切れ、プロバイダー側の権限変更 | 各プロバイダーの管理コンソールでキー有効性確認 → 環境変数を再設定 |
| ベクトルインデックス作成タイムアウト | Knowledge Base のインデックス生成 | Chunk Size が大きすぎ、CPU/メモリ不足 |
docker stats でリソース使用率を見る。Chunk Size を 300‑400 tokens に下げ、Docker の CPU 割り当てを増やす |
Pod が CrashLoopBackOff（K8s） |
起動時に DB 接続失敗 | Secret が未マウント、DB URL 誤記 |
kubectl logs <pod-name> でスタックトレース確認 → kubectl describe secret dify-secret でキーが正しいか検証 |
| Observability データが届かない | Opik / Langfuse / Arize のエンドポイント設定ミス | API キー未設定、ネットワーク制限 | 各ツールのダッシュボードで Recent Calls を確認し 4xx/5xx が出ていないか。curl -H "Authorization: Bearer $OPIK_API_KEY" $OPIK_ENDPOINT で手動テスト |
カスタムツール開発の次フェーズ
| フェーズ | 主な作業項目 |
|---|---|
| ① 基本統合 | 上記「Custom HTTP Tool」の実装とテスト。 |
| ② 高度なオーケストレーション | 複数エージェント間でデータをパイプライン化（例: 検索 → データ正規化 → レポート生成）。Dify の「Workflow」機能がリリースされた 2024‑09‑30 版で利用可能。 |
| ③ モニタリング自動化 | Prometheus Exporter を独自ツールに組み込み、Arize Phoenix の Alert 機能と連携させる。 |
| ④ CI/CD 本番展開 | Helm chart に postStart フックでスキーママイグレーションを走らせ、GitOps（ArgoCD）で自動デプロイ。 |
ベストプラクティス：本番環境では必ずステージングクラスターに同一構成をデプロイし、負荷テスト (
heyやk6) を実施した上でトラフィックを切り替えてください（公式ガイド: https://github.com/langgenius/dify/blob/main/docs/deployment/k8s.md, 取得日: 2024‑10‑01）。
まとめ
- Dify は LLM・RAG・Observability を一体化したオールインワンプラットフォームで、ノーコードでも高度な AI アプリが構築可能です。
- ローカル環境は Docker + WSL2/macOS/Linux が前提で、最低 8 GB メモリ・2 vCPU のリソースを確保しつつ、スケールアウト時は HPA と PV 設計を意識してください。
- インストール手順では公式リポジトリと Docker ミラー設定の最新情報（2024‑10‑01）に基づき、
.envに必要なシークレットだけを書き込むことが重要です。 - UI で Knowledge Base と Agent を作成する流れは 「データアップロード → インデックス生成 → プロンプト設計 → ツールチェーン構築」 の４ステップに整理できます。
- 本番デプロイは Docker Compose と Helm の二択があり、Observability は Opik・Langfuse・Arize Phoenix をシンプルな
values.yaml設定だけで有効化可能です。 - カスタムツール統合は FastAPI + Docker で実装し、環境変数ベースの認証・リトライロジックを組むことで堅牢性が向上します。CI/CD パイプラインにビルド・テスト・デプロイを自動化すれば、運用負荷を大幅に削減できます。
以上を踏まえて、ぜひ 「アイデア → プロトタイプ → 本番」 の高速サイクルを Dify で体感してください。