メインコンテンツへスキップ
⚠️ このドキュメントは 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いいえstringand または 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

プロパティ型説明
contentstring取得されたテキストチャンクです。Dify はこれを LLM に渡すコンテキストとして使用します。
scorefloat類似度スコア（0～1）です。スコアしきい値によるフィルタリングと結果のランキングに使用します。
titlestringソースドキュメントのタイトルです。
metadataobjectDify が保持する任意のキーバリューペアです。
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_codeint独自に定義するアプリケーションレベルのエラーコードです。
error_msgstring人間が読めるエラーの説明です。
以下は推奨されるエラーコードです。これらは慣例であり、Dify による強制ではありません：
コード推奨される用途
1001Authorization ヘッダーの形式が不正
1002認証失敗
2001ナレッジベースが見つからない

​
エラーレスポンス例

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