弊社は生成AIを強みとするベトナムオフショア開発・ラボ型開発や、生成AIコンサルティングなどのサービスを提供しており、最近はありがたいことに生成AIと連携したシステム開発のご依頼を数多く頂いています。
Difyの外部知識ベースAPIは、Difyプラットフォーム外部に存在する知識ベースをDifyのAIアプリケーションと統合するための強力な機能です。このAPIを利用することで、開発者は独自の検索アルゴリズムや外部の知識ベースサービスを活用し、AIアプリケーションの機能を拡張できます。
本記事では、Difyの外部知識ベースAPIの仕様、用途、実装方法、設定方法、そして注意点について詳細に解説します。
Difyとは
Difyとは、プログラムを書かずに簡単にAIアプリを作成できる超便利ツールです。Difyについては以下の記事をご覧ください！
- Difyってなに？という方：DifyでSEO記事作成を試してみる
- Difyでワークフローの作り方：Difyのワークフローを使って今度こそSEO記事を作成する【2024年6月更新】
外部知識ベースAPIの概要
なぜ外部知識ベースAPIを使ってみようと思ったのか
はじまりはDify公式からのこのツイートでした。
外部知識とAPI経由で連携できるだと・・・？システムのDBとAPIで連携して、そのシステム内にあるデータを知識ベースとしたBotとか作れるんじゃ！？とめっちゃテンション上がりました。
結論としては、頑張ればそういうものも作れそうですが、そのような用途には向いていないと思われます。
上記の用途であれば、カスタムツールを作成したほうが合理的と思われます。
そもそも外部知識ベースAPIってなに？
まずこれを理解するのが難しかった。。。Difyっ子の皆さんはどうしてるんですかね？参考になりそうなドキュメントは現時点で以下の２つだけです。
- Connect to an External Knowledge Base | Difydocs.dify.ai
- External Knowledge API | DifyEditor: Allen. Dify Technical Writerdocs.dify.ai
簡単にまとめると、外部知識をDifyのアプリケーションから参照できる知識ベースとして使用できるAPIの口を用意した、ということです。図示すると以下のようになります。
非常に重要な点として、以下を強調しておきたいと思います。
- 外部知識ベースAPIは自前で実装する必要がある。
- 外部知識ベースAPIは構造化されたデータ向けではなく、むしろ非構造化データ向けの仕組みである。
- 通常のDify上の知識ベースは登録するとインデックス化までしてくれますが、外部知識ベースAPIで取得された知識ベースはインデックス化されず、外部知識ベースAPIのレスポンスデータがそのままDifyアプリケーションに返却されます。
なぜ外部知識ベースAPIが必要なのか？
Difyプラットフォームには標準で知識ベース機能が搭載されていますが、高度なコンテンツ検索要件を持つ開発者にとっては、特にリコール結果のカスタマイズという点で限界がある場合があります。
テキスト検索とリコールの精度向上、そして内部資料の管理ニーズの高まりから、一部の開発チームは独自のRAGアルゴリズムやテキスト検索システムを開発・維持するか、クラウドベンダーの知識ベースサービス（例：AWS Bedrock）にコンテンツを一元的にホストすることを選択しています。
Difyは、中立的なLLMアプリケーション開発プラットフォームとして、開発者に幅広い選択肢を提供するため、外部知識ベースに接続する機能により、Difyプラットフォームと外部知識ベースの統合が可能になります。APIサービスを通じて、AIアプリケーションはより広範な情報ソースにアクセスできます。この機能には、主に2つの利点があります。
- Difyプラットフォームは、クラウドサービスプロバイダーの知識ベースにホストされているテキストコンテンツを直接取得できるため、開発者はコンテンツをDifyの知識ベースに繰り返し移動する必要がなくなります。
- Difyプラットフォームは、独自に構築した知識ベースのアルゴリズムによって処理されたテキストコンテンツを直接取得できます。開発者は、独自に構築した知識ベースの情報検索メカニズムに集中し、情報検索の精度を継続的に最適化および向上させることができます。
外部知識ベースAPIの動作原理
外部知識ベースAPIは、Difyプラットフォームと外部知識ベースシステムの間の橋渡し役【のみ】を果たします。
Difyアプリケーション（例：チャットボット）がユーザーの質問を受け取ると、Difyは外部知識ベースAPIを呼び出します。外部知識ベースAPIは、指定された外部知識ベースから関連する情報を検索し、その結果をDifyに返します。
ここで重要なのは、繰り返しになりますが、Dify側は検索処理を行わないという点です。ユーザーのメッセージに応じた検索は、上のシーケンス図で言うと、「外部知識ベースAPI」か「外部の知識ベースシステム」の方でやる必要があり、検索結果をDifyに返却しなくてはいけません。
外部知識ベースAPIの仕様
Dify側で用意されているAPIの使用はこちらです。
この仕様に沿った外部知識ベースAPIを自前で実装するということです。
リクエスト方法
- リクエスト先：your-endpoint/retrieval
- メソッド：POST
- ヘッダー
- Authorization: Bearer {API_KEY} (APIキー認証)
- Content-Type: application/json
リクエストボディフォーマット
{
"knowledge_id": "your-knowledge-id",
"query": "your question",
"retrival_setting": {
"top_k": 2,
"score_threshold": 0.5
}
}- knowledge_id (string, 必須): 検索対象の知識ベースを識別するID。外部知識ベースAPI側で定義されます。
- query (string, 必須): ユーザーの質問や検索キーワード。
- retrival_setting (object, 必須): 検索設定。
- top_k (integer, 必須): 返す検索結果の上位何件か。デフォルトは3。
- score_threshold (float, 必須): 類似度スコアの閾値。この値以上のスコアを持つ結果のみが返されます。デフォルトは0.5。
レスポンスフォーマット
{
"records": [
{
"content": "text",
"score": 0,
"title": "text",
"metadata": "text"
}
]
}- records (array, 必須): 検索結果の配列。
- content (string, 必須): 検索結果のテキストコンテンツ。
- score (float, 必須): 類似度スコア。
- title (string, オプション): 検索結果のタイトル。
- metadata (object, オプション): 検索結果のメタデータ。
ここまで、外部知識ベースAPIの使用方法を説明してきましたが、実際にやるとなるとDifyの使用に関する理解やAPIの実装などが必要になり、専門的な知識や経験がないと大変な部分が多いです。
もし、このあたりをまるっと任せてしまいたいというご要望がございましたら、ぜひ豊富な経験のある弊社へお気軽にご連絡ください！
外部知識ベースAPIの実装と設定
外部知識ベースAPIの実装例 (Python & Flask)
私はエンジニアではなくただの会社経営者ですので、外部知識ベースAPIの実装や環境構築に時間をかけたくはなく、とにかく簡単に、すぐにDifyと外部知識ベースAPIを連携する動作を確認できる方法を考えてみました。
その結果、Google Colabを使用することにしました。
FlaskでサクッとAPIを実装し、Ngrokで一時的な公開URLを作成しています。
以下のソースコードをそのままGoogle Colabに貼り付け、環境変数を設定し、外部知識ベース代わりの「external-knowledge-api.txt」になにか適当なことを書いてアップロードして実行すれば動作すると思います。
※動作の保証はいたしません。もしこちらのソースコードをご利用になる場合は、自己責任でお願いいたします。
# 必要なパッケージをインストール
!pip install flask flask-ngrok pyngrok requests
!pip install scikit-learn
# 必要なライブラリのインポート
from flask import Flask, request, jsonify
from flask_ngrok import run_with_ngrok
import threading
from google.colab import userdata
# 環境変数の設定（実際の値に置き換えてください）
API_KEY = userdata.get('YOUR_API_KEY') # 環境変数にあなたのAPIキーを設定してください
# ngrokのauthtokenを設定 ※事前に以下の手続きが必要
# ngrokの公式サイト（ https://dashboard.ngrok.com/signup ）にアクセスし、無料のアカウントを作成
# アカウント作成後、ダッシュボードの「Your Authtoken」ページ（ https://dashboard.ngrok.com/get-started/your-authtoken ）でauthtokenをコピー
NGROK_AUTHTOKEN = userdata.get('YOUR_NGROK_AUTHTOKEN') # YOUR_NGROK_AUTHTOKENを実際のトークンに置き換えてください
!ngrok authtoken {NGROK_AUTHTOKEN}
# Flaskアプリケーションの初期化
app = Flask(__name__)
run_with_ngrok(app) # アプリケーション実行時にngrokを起動
# /retrieval エンドポイントの実装
@app.route('/retrieval', methods=['POST'])
def retrieval():
try:
# リクエストのヘッダーとボディをログに出力（デバッグ用）
print('Headers:', request.headers)
print('Body:', request.get_data(as_text=True))
# テキストファイル 'external-knowledge-api.txt' を読み込む
try:
with open('external-knowledge-api.txt', 'r', encoding='utf-8') as file:
content = file.read()
except FileNotFoundError:
return jsonify({'error': "'external-knowledge-api.txt' が見つかりませんでした"}), 500
# レスポンスを作成
result = {
'content': content,
'score': 1.0,
'title': '',
'metadata': {}
}
return jsonify({'records': [result]}), 200
except Exception as e:
# エラーをログに出力
import traceback
traceback.print_exc()
return jsonify({'error': '予期せぬエラーが発生しました', 'details': str(e)}), 500
# アプリケーションを別スレッドで実行
def run_app():
app.run()
thread = threading.Thread(target=run_app)
thread.start()
# ngrokを使用して外部からアクセス可能にする
from pyngrok import ngrok
# 既存のトンネルを終了
ngrok.kill()
# 新しいngrokトンネルを開く
public_url = ngrok.connect(5000).public_url
print(f"Public URL: {public_url}")これをすべて実行すれば、例えば以下のような出力が、Google Colabのコンソールに出力されますので、そのURLを外部知識ベースAPIのエンドポイントとして使用できます。
Public URL: https://10d3-35-231-91-200.ngrok-free.appDifyでの設定方法
１．外部知識ベースAPIの追加:
- Difyの管理画面で、「ナレッジ」>「外部知識ベースAPI」>「外部知識ベースAPIを追加」に進みます。
- 「名前」に任意の名前を入力します。
- 「APIエンドポイント」にデプロイしたAPIのURLを入力します。
- 「APIキー」に外部知識ベースAPIで使用するAPIキーを入力します。
- 「保存」ボタンをクリックします。
２．外部知識ベースの接続:
- Difyの管理画面で、「ナレッジ」>「ナレッジベースを追加」>「外部知識ベースに接続」に進みます。
- 「ナレッジベース名」に任意の名前を入力します。
- 「外部知識ベースAPI」で先ほど追加したAPIを選択します。
- 「外部ナレッジID」に、外部知識ベースAPIで想定されているknowledge_idを入力します。複数の知識ベースを区別する必要がある場合に利用します。
- 「取得設定」でtop_kとscore_thresholdを設定します。
- 「保存」ボタンをクリックします。
３．アプリケーションでの利用:
作成したチャットボットのエージェント設定画面で、コンテキストとして登録した外部知識ベースを選択します。
外部知識ベースのテスト
Difyの管理画面で、外部知識ベースの設定が完了したら、「Retrieval Testing」セクションでテストを実行できます。想定される質問キーワードを入力し、「Test」ボタンをクリックすることで、外部知識ベースAPIから返されるテキストチャンクをプレビューできます。
取得結果が期待通りでない場合は、外部知識ベースの設定（top_k、score_thresholdなど）を調整するか、外部知識ベースAPI側の検索戦略を見直してください。
アプリケーションへの統合
チャットボット/エージェント型アプリケーションでは、オーケストレーションページで外部知識ベースを関連付けます。チャットフロー/ワークフロー型アプリケーションでは、「Knowledge Retrieval」ノードを追加し、使用する外部知識ベースを選択します。
外部知識ベースAPIの用途
向いている用途
- 独自のRAGアルゴリズムとの連携: 独自に開発したRAGアルゴリズムや検索システムとDifyを連携させることで、より高度な情報検索を実現できます。
- クラウドベンダーの知識ベースサービスとの連携: AWS Bedrockなどのクラウドサービスに保存されている知識ベースをDifyから直接利用できます。
- 機密情報の保護: 社内システムやデータベースに保存されている機密情報を、Difyにアップロードすることなく利用できます。
- リアルタイムデータの利用: 常に更新される情報（例：在庫状況、ニュース記事など）をDifyアプリケーションで利用できます。
向かない用途
- 構造化データの検索: 顧客DBのような構造化データの検索には、工夫が必要となります。データをテキスト化するか、外部知識ベースAPI内部でDBにアクセスする処理を実装する必要があります。
- Dify標準の知識ベースで十分な場合: 単純なキーワード検索やFAQシステムなど、Dify標準の知識ベースで実現できる場合は、外部知識ベースAPIを利用するメリットは少ないです。
