外部ナレッジベース API

Dify と統合するために外部ナレッジサービスが実装する必要がある API 仕様

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。

このページでは、Dify が外部ナレッジサービスからコンテンツを取得するために実装が必要な API 仕様を定義します。API の準備ができたら、外部ナレッジベースとの接続を参照して Dify に登録してください。

​

認証

Dify は API キーを Bearer トークンとしてすべてのリクエストに含めます：

Authorization: Bearer {API_KEY}

認証ロジックはサービス側で定義します。Dify はキーを送信するのみで検証しません。

​

リクエスト

POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}

Dify は設定されたエンドポイント URL に /retrieval を付加します。https://your-service.com を登録した場合、https://your-service.com/retrieval にリクエストを送信します。

​

ボディ

プロパティ	必須	型	説明
knowledge_id	はい	string	外部システム内のナレッジソースの識別子で、接続時に 外部ナレッジベース ID フィールドに入力した値です。クエリを正しいナレッジソースにルーティングするために使用します。
query	はい	string	ユーザーの検索クエリです。
retrieval_setting	はい	object	検索パラメータです。下記を参照してください。
metadata_condition	いいえ	object	メタデータのフィルタリング条件です。下記を参照してください。

​

retrieval_setting

プロパティ	必須	型	説明
top_k	はい	int	返す結果の最大数です。
score_threshold	はい	float	最小類似度スコア（0～1）です。Dify でスコアしきい値が無効の場合、この値は 0.0 になります。

​

metadata_condition

Dify はメタデータ条件を API に渡しますが、現在ユーザーが設定するための UI は提供していません。このパラメータはプログラムからの利用のみ可能です。

プロパティ	必須	型	説明
logical_operator	いいえ	string	and または or です。デフォルト：and。
conditions	はい	array[object]	フィルタ条件のリストです。

conditions 内の各オブジェクト：

プロパティ	必須	型	説明
name	はい	string	フィルタ対象のメタデータフィールド名です。
comparison_operator	はい	string	比較演算子です。サポートされる値は下記を参照してください。
value	いいえ	string、number、または array[string]	比較値です。empty または not empty を使用する場合は省略します。

サポートされる比較演算子

演算子	説明
contains	値を含む
not contains	値を含まない
start with	値で始まる
end with	値で終わる
is	値と等しい
is not	値と等しくない
in	リスト内のいずれかの値に一致
not in	リスト内のいずれの値にも一致しない
empty	空である
not empty	空ではない
=	等しい（数値）
≠	等しくない（数値）
>	より大きい
<	より小さい
≥	以上
≤	以下
before	指定日より前
after	指定日より後

​

リクエスト例

{
    "knowledge_id": "your-knowledge-id",
    "query": "Dify とは何ですか？",
    "retrieval_setting": {
        "top_k": 3,
        "score_threshold": 0.5
    }
}

​

レスポンス

HTTP 200 と records 配列を含む JSON ボディを返します。一致する結果がない場合は、空の配列を返してください：{"records": []}。

​

records

プロパティ	型	説明
content	string	取得されたテキストチャンクです。Dify はこれを LLM に渡すコンテキストとして使用します。
score	float	類似度スコア（0～1）です。スコアしきい値によるフィルタリングと結果のランキングに使用します。
title	string	ソースドキュメントのタイトルです。
metadata	object	Dify が保持する任意のキーバリューペアです。

Dify はフィールドが欠落したレコードを拒否しませんが、content や score を省略すると不完全またはランキングされない結果になります。

レコードに metadata を含める場合、オブジェクト（{}）である必要があります。null は Dify の検索パイプラインでエラーを引き起こします。

​

レスポンス例

{
    "records": [
        {
            "content": "これは外部ナレッジベースのドキュメントです。",
            "score": 0.98,
            "title": "knowledge.txt",
            "metadata": {
                "path": "s3://dify/knowledge.txt",
                "description": "dify ナレッジドキュメント"
            }
        },
        {
            "content": "GenAI アプリケーションのイノベーションエンジン",
            "score": 0.66,
            "title": "introduce.txt",
            "metadata": {}
        }
    ]
}

​

エラーハンドリング

Dify はレスポンスの HTTP ステータスコードを確認します。200 以外のステータスはユーザーに表示されるエラーを発生させます。

JSON で構造化されたエラー情報を返すこともできます：

プロパティ	型	説明
error_code	int	独自に定義するアプリケーションレベルのエラーコードです。
error_msg	string	人間が読めるエラーの説明です。

以下は推奨されるエラーコードです。これらは慣例であり、Dify による強制ではありません：

コード	推奨される用途
1001	Authorization ヘッダーの形式が不正
1002	認証失敗
2001	ナレッジベースが見つからない

​

エラーレスポンス例

{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}