外部ナレッジベース 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."
}

​認証

​リクエスト

​ボディ

​retrieval_setting

​metadata_condition

​リクエスト例

​レスポンス

​records

​レスポンス例

​エラーハンドリング

​エラーレスポンス例

認証

リクエスト

ボディ

`retrieval_setting`

`metadata_condition`

リクエスト例

レスポンス

`records`

レスポンス例

エラーハンドリング

エラーレスポンス例