外部ナレッジベースAPI

外部ナレッジベースAPI

外部知識API

エンドポイント

POST <your-endpoint>/retrieval

ヘッダー

このAPIは、Difyとは独立して開発者が維持管理するナレッジベースに接続するために使用されます。詳細については、外部ナレッジベースへの接続を参照してください。Authorization HTTPヘッダーで API-Key を使用して権限を検証できます。認証ロジックは、以下のように検索APIで定義します：

Authorization: Bearer {API_KEY}

リクエストボディ要素

リクエストは以下のJSON形式のデータを受け入れます。

プロパティ	必須	型	説明	例値
knowledge_id	TRUE	string	ナレッジベースの一意ID	AAA-BBB-CCC
query	TRUE	string	ユーザーのクエリ	Difyとは何ですか？
retrieval_setting	TRUE	object	知識の検索パラメータ	以下参照
metadata_condition	FALSE	object	元の配列のフィルタリング	以下参照

retrieval_setting プロパティは以下のキーを含むオブジェクトです：

プロパティ	必須	型	説明	例値
top_k	TRUE	int	検索結果の最大数	5
score_threshold	TRUE	float	クエリに対する結果の関連性スコアの閾値、範囲：0〜1	0.5

metadata_condition プロパティは以下のキーを含むオブジェクトです：

属性	必須かどうか	型	説明	例
logical_operator	いいえ	文字列	論理演算子、値は and または or、デフォルトは and	and
conditions	はい	配列（オブジェクト）	条件リスト	以下参照

conditions 配列の各オブジェクトには以下のキーが含まれます：

属性	必須かどうか	型	説明	例
name	はい	配列（文字列）	フィルタリングするmetadataの名前	["category", "tag"]
comparison_operator	はい	文字列	比較演算子	contains
value	いいえ	文字列	比較値、演算子が empty、not empty、null、not null の場合は省略可能	"AI"

サポートされている comparison_operator 演算子：

• contains：特定の値を含む

• not contains：特定の値を含まない

• start with：特定の値で始まる

• end with：特定の値で終わる

• is：特定の値と等しい

• is not：特定の値と等しくない

• empty：空である

• not empty：空ではない

• =：等しい

• ≠：等しくない

• >：より大きい

• <：より小さい

• ≥：以上

• ≤：以下

• before：特定の日付より前

• after：特定の日付より後

リクエスト構文

POST <your-endpoint>/retrieval HTTP/1.1
-- ヘッダー
Content-Type: application/json
Authorization: Bearer your-api-key
-- データ
{
    "knowledge_id": "your-knowledge-id",
    "query": "your question",
    "retrieval_setting":{
        "top_k": 2,
        "score_threshold": 0.5
    }
}

レスポンス要素

アクションが成功した場合、サービスはHTTP 200レスポンスを返します。

サービスは以下のデータをJSON形式で返します。

プロパティ	必須	型	説明	例値
records	TRUE	List[Object]	ナレッジベースのクエリ結果のレコードリスト	以下参照

records プロパティは以下のキーを含むリストオブジェクトです：

プロパティ	必須	型	説明	例値
content	TRUE	string	ナレッジベースのデータソースからのテキストチャンクを含む	Dify：GenAIアプリケーションのイノベーションエンジン
score	TRUE	float	クエリに対する結果の関連性スコア、範囲：0〜1	0.5
title	TRUE	string	ドキュメントタイトル	Dify紹介
metadata	FALSE	json	データソース内のドキュメントのメタデータ属性とその値を含む	例参照

レスポンス構文

HTTP/1.1 200
Content-type: application/json
{
    "records": [{
                    "metadata": {
                            "path": "s3://dify/knowledge.txt",
                            "description": "dify知識ドキュメント"
                    },
                    "score": 0.98,
                    "title": "knowledge.txt",
                    "content": "これは外部知識のドキュメントです。"
            },
            {
                    "metadata": {
                            "path": "s3://dify/introduce.txt",
                            "description": "dify紹介"
                    },
                    "score": 0.66,
                    "title": "introduce.txt",
                    "content": "GenAIアプリケーションのイノベーションエンジン"
            }
    ]
}

エラー

アクションが失敗した場合、サービスは以下のエラー情報をJSON形式で返します：

プロパティ	必須	型	説明	例値
error_code	TRUE	int	エラーコード	1001
error_msg	TRUE	string	API例外の説明	無効な認証ヘッダー形式です。'Bearer '形式が期待されます。

error_code プロパティには以下の種類があります：

コード	説明
1001	無効な認証ヘッダー形式
1002	認証失敗
2001	知識が存在しません

HTTPステータスコード

AccessDeniedException アクセス権限がないため、リクエストが拒否されました。権限を確認して再試行してください。 HTTPステータスコード：403

InternalServerException 内部サーバーエラーが発生しました。リクエストを再試行してください。 HTTPステータスコード：500

開発例

以下の動画では、LlamaCloudを例として外部ナレッジベースプラグインの開発方法を学ぶことができます：

詳細については、プラグインのGitHubリポジトリを参照してください。