外部知識API - Dify Docs

エンドポイント

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	TRUE	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 <api-key>` 形式が期待されます。

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

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

開発例

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

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

HTTPステータスコード

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

​エンドポイント

​ヘッダー

​リクエストボディ要素

​リクエスト構文

​レスポンス要素

​レスポンス構文

​エラー

​開発例

​HTTPステータスコード