DifyのRAG用ファイルを外部から操作する検証

Difyでは、RAG（検索拡張生成：Retrieval-Augmented Generation）を実装する機能が「ナレッジベース機能」として提供されています。
DifyでRAGとして扱えるデータは下記のようになっています。

RAG用のデータは、Difyの「ナレッジ」をクリック後の画面で、アップロードして反映させる事ができます。

RAGはLLMが問い合わせる際の情報源として利用されます。

ここでは、RAG用のファイル操作を外部から行う方法について、下記の簡易検証を行ってみました。

例えば、下図のようにナレッジに「火星保険会社」という箱（ナレッジベース）を作成して、
その中に含まれるファイルを外部から操作（一覧表示、削除、追加）する場合を想定してみます。

• 外部のプログラムからDifyのナレッジベース内のファイル操作ができるか
• 外部のWordPressにDifyのナレッジベース内のファイル管理機能を用意して更新できるか

ナレッジAPIの基本仕様

• APIキー認証が必要
  外部からナレッジAPIにアクセスするには、APIキー認証が必要になります。
  ナレッジAPIのAPI認証（英語版）
• 主なナレッジAPIのエンドポイント
  ナレッジAPIのエンドポイントは、主に下記のようなエンドポイントがあります。

  操作	エンドポイント	内容	公式サイト
  ナレッジベース一覧取得	GET /datasets	Difyに登録されているナレッジベースの一覧を表示します。	https://docs.dify.ai/api-reference/datasets/get-knowledge-base-list
  ドキュメント一覧取得	GET /datasets/{dataset_id}/documents	指定されたナレッジベース内のすべてのドキュメントのリストを取得します。	https://docs.dify.ai/api-reference/documents/get-the-document-list-of-a-knowledge-base
  ファイル追加	POST /datasets/{dataset_id}/document/create-by-file	ファイルをアップロードして、既存のナレッジ ベース内に新しいドキュメントを作成します。	https://docs.dify.ai/api-reference/documents/create-a-document-from-a-file
  ファイル更新	POST /datasets/{dataset_id}/document/{document_id}/update-by-file	新しいファイルをアップロードして既存のドキュメントの内容を置き換え・更新します。	https://docs.dify.ai/api-reference/documents/update-a-document-with-a-file
  ファイル削除	DELETE /datasets/{dataset_id}/document/{document_id}	ナレッジ ベースから特定のドキュメントを削除します。	https://docs.dify.ai/api-reference/documents/delete-a-document

• 必要なキーの構造
  ナレッジAPIのアクセスに必要な必要なキーの構造は、下記のようなイメージになっています。

  ナレッジベースAPIのシークレットキー　※ナレッジAPI自体のアクセスに必要。
  └─データセットID（dataset_id）　※今回の例では「火星保険会社」。
  └─ドキュメントID（document_id）　※上記に含まれるファイルのID。

１．ナレッジAPIのシークレットキー取得

• ナレッジベースAPIのシークレットキーを取得
  ナレッジの画面で左上の「API ACCESS」をクリックして、右上の「APIキー」をクリックします。
  「新しいシークレットキーを作成」をクリックすると、下図のように発行されます。
  このキー情報を手元に控えておきます。

  

２．外部のプログラムからファイル操作

• ナレッジベースAPIのシークレットキーを使用してナレッジベース一覧を取得
  ナレッジAPIのAPI認証（英語版）
  の仕様を元にして、下記のようなPythonのプログラムを実行してみます。

  import requests
  
  API_KEY = "シークレットキー"
  BASE_URL = "http://localhost/v1"url = f"{BASE_URL}/datasets"
  headers = {"Authorization": f"Bearer {API_KEY}"}BASE_URL = "http://localhost/v1"
  
  url = f"{BASE_URL}/datasets"
  headers = {"Authorization": f"Bearer {API_KEY}"}
  
  resp = requests.get(url, headers=headers)
  datasets = resp.json().get("data", [])
  
  # 見やすく整形して表示
  print(f"{'ID':36} | {'File Name'}")
  print("-" * 60)
  for ds in datasets:
  	dataset_id = ds.get("id")
  	file_name = ds.get("metadata", {}).get("file_name", ds.get("name"))
  	print(f"{dataset_id} | {file_name}")
  

  結果は下記のように出力されました。

  ID                                   | File Name
  ------------------------------------------------------------
  224785c5-6120-46b8-842f-f0caf3fdcc96 | 火星保険会社
  

• ナレッジAPI経由でファイルの追加
  上記で得られたデータセットIDを用いて、下記のようなPythonのプログラムを実行してみます。
  前提として、実行するPythonのプログラムと同じ階層に、追加するファイル「火星保険会社_add01.pdf」を設置しておきます。
  ※データセットIDの「224785c5-6120-46b8-842f-f0caf3fdcc96」はサンプルですので、実際の値に読み替えてください。

  import requests
  
  API_KEY = "シークレットキー"
  BASE_URL = "http://localhost/v1"
  DATASET_ID = "224785c5-6120-46b8-842f-f0caf3fdcc96"
  
  headers = {"Authorization": f"Bearer {API_KEY}"}
  
  url = f"{BASE_URL}/datasets/{DATASET_ID}/document/create_by_file"
  
  files = {
      "file": ("火星保険会社_add01.pdf", open("火星保険会社_add01.pdf", "rb"), "application/pdf")
  }
  
  data = {
      "indexing_technique": "high_quality"  # or "economy"
  }
  
  resp = requests.post(url, headers=headers, files=files, data=data)
  print(resp.status_code, resp.json())
  

  下図のようにDifyのナレッジベースに反映されました。

  

• ナレッジAPI経由でファイルの削除
  ドキュメントの詳細画面のURLから、ドキュメントIDを確認します。

  

  上記で得られたドキュメントIDを用いて、下記のようなPythonのプログラムを実行してみます。
  ※ドキュメントIDの「54c839fc-e8e4-4aad-bb4c-055f46dd09de」はサンプルですので、実際の値に読み替えてください。

  import requests
  
  API_KEY = "シークレットキー"
  BASE_URL = "http://localhost/v1"
  DATASET_ID = "224785c5-6120-46b8-842f-f0caf3fdcc96"
  DOCUMENT_ID = "54c839fc-e8e4-4aad-bb4c-055f46dd09de"  # 削除対象のドキュメントID
  
  headers = {"Authorization": f"Bearer " + API_KEY}
  
  url = f"{BASE_URL}/datasets/{DATASET_ID}/documents/{DOCUMENT_ID}"
  
  resp = requests.delete(url, headers=headers)
  
  print(resp.status_code)
  print(resp.text)
  

  実行の結果、Difyのナレッジベースから削除されました。
  チャットボットでナレッジベース参照時に削除分は参照されなくなりました。

２．WordPressからファイル操作

• ローカルのDifyのアドレスを一時的に外部公開
  この例ではDifyがローカル環境の
  http://localhost/
  で、WordPressは外部のアドレス
  https://xxxxx.com/
  のため、WordPressからDifyのアドレスを参照できるようにするためにngrokのサービスを活用してみます。
  ngrokにサインインすると、下図のようにOSに沿ったインストール手順が示されます。

  

  インストールが完了後、macOSの場合はターミナル（Windowsの場合はPowerShell）で下記のコマンドを実行します。

  ngrok http http://localhost

  成功すると、下図のように外部公開用のアドレスが発行されます。

  

• WordPressの管理機能を用意
  下記のような要件でWordPressの管理機能を用意します。

  設定:
  API_KEY / BASE_URL / DATASET_ID を保存
  ※BASE_URLはngrokによって発行された外部公開用のアドレスを設定
  ↓
  保存後に一覧表示一覧:
  GET /v1/datasets/{dataset_id}/documents
  結果をテーブル表示（Document ID / File Name / 削除ボタン）
  
  追加:
  POST /v1/datasets/{dataset_id}/document/create_by_file
  （WordPress HTTP API を経由せず、PHPの cURL で直接 multipart を送る）
  
  削除:
  DELETE /v1/datasets/{dataset_id}/documents/{document_id}
  成功コード 200/204 で削除完了
  

  

• WordPress管理機能の動作確認
  ファイルの追加・削除を実行し、Difyのナレッジベースへの反映を確認します。
  当方の環境では動作できました。