Difyの外部ナレッジベース連携を使用する

はじめに
外部ナレッジベース API の仕様
Flask 実装
Dify との接続設定
Dify への登録
まとめ

はじめに

Dify には独自の RAG 機能（ナレッジベース）が備わっていますが、外部ナレッジベース API を使うことで、自前のベクトル DB や検索システムをナレッジソースとして接続することができます。

本記事では外部ナレッジベース API の仕様を満たす最小構成のサーバーを Flask で作成し、Dify と連携させる手順を紹介します。

今回は動作確認のため固定のレスポンスを返す構成としています。実際の RAG 構築についてはこちらの記事をご参照ください。

外部ナレッジベース API の仕様

Dify の外部ナレッジベースは以下の仕様が求められます。

エンドポイント
POST /retrieval

リクエストボディ

{
  "knowledge_id": "ナレッジID",
  "query": "検索クエリ",
  "retrieval_setting": {
    "top_k": 2,
    "score_threshold": 0.5
  }
}

レスポンスボディ

{
  "records": [
    {
      "content": "ドキュメントの内容",
      "score": 0.95,
      "title": "ドキュメントのタイトル",
      "metadata": {
        "path": "doc/path",
        "description": "説明"
      }
    }
  ]
}

Flask 実装

プロジェクト構成

external-knowledge/
├── app.py
├── requirements.txt
├── docker-compose.yml
└── Dockerfile

requirements.txt

flask==3.1.0

app.py

import os
from flask import Flask, request, jsonify

app = Flask(__name__)

API_KEY = os.environ.get("API_KEY", "your-api-key")

@app.route("/retrieval", methods=["POST"])
def retrieval():
    auth = request.headers.get("Authorization", "")
    if auth != f"Bearer {API_KEY}":
        return jsonify({"error": "Unauthorized"}), 403

    data = request.get_json()
    query = data.get("query", "")
    top_k = data.get("retrieval_setting", {}).get("top_k", 3)

    # ここに実際の検索処理を実装する（今回はダミーレスポンス）
    records = [
        {
            "content": f"'{query}' に関するサンプルドキュメントの内容です。",
            "score": 0.95,
            "title": "サンプルドキュメント",
            "metadata": {
                "path": "sample/doc.md",
                "description": "サンプル用のダミーレスポンスです"
            }
        }
    ]

    return jsonify({"records": records[:top_k]})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

EXPOSE 5000

CMD ["python", "app.py"]

Dify との接続設定

Dify のネットワークへの接続方法は DifyとMCPを組み合わせてAIを構築するの記事を参考に、外部ナレッジ用コンテナを Dify の Docker ネットワークに接続します。

docker-compose.yml にサービスを追加する場合は以下のようになります。

services:
  external-knowledge:
    build: ./external-knowledge
    environment:
      - API_KEY=your-api-key
    networks:
      - docker_ssrf_proxy_network  # Dify のネットワーク名に合わせて変更

networks:
  docker_ssrf_proxy_network:
    external: true

コンテナを起動します。

docker compose up -d

Dify への登録

1. 外部ナレッジベースを作成する

Dify の「ナレッジ」メニュー右上から「外部ナレッジベース連携 API」を選択します。

続いて「外部ナレッジベース連携 API を追加」をクリックします。

2. API 設定を入力する

以下の情報を入力します。

項目	値
外部ナレッジ API の名前	任意の名前
API エンドポイント	`http://external-knowledge:5000`
API キー	`app.py` の `API_KEY` に設定した値

3. ナレッジとして登録する

外部ナレッジベースを作成した後、「ナレッジ」メニューの左側の「外部ナレッジベースと連携」を選択します。

4. 外部ナレッジベースの設定を入力する

以下の情報を入力します。

項目	値
外部ナレッジベース名	任意の名前
外部ナレッジベース連携 API	2で作成した外部ナレッジベース連携 API
外部ナレッジベース ID	任意のID

作成後に一覧に戻りますが、筆者の環境ではリロードしないと作成したナレッジが表示されませんでした。必要に応じてブラウザをリロードしてください。

5. 検索テストを行う

作成したナレッジを開き、「検索テスト」タブを選択します。クエリを入力して「テスト」ボタンをクリックすると、app.py で定義したダミーレスポンスが表示されるはずです。

まとめ

Dify の外部ナレッジベース API を満たす最小構成の Flask サーバーを作成し、Dify と連携する手順を紹介しました。今回はダミーレスポンスを返す構成ですが、retrieval 関数内に実際の検索処理（ベクトル検索など）を実装することで、自前の RAG システムを Dify から利用できるようになります。