​
エンドポイント

POST <your-endpoint>/retrieval

​
ヘッダー

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

Authorization: Bearer {API_KEY}

​
リクエストボディ要素

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

プロパティ必須型説明例値
knowledge_idTRUEstringナレッジベースの一意IDAAA-BBB-CCC
queryTRUEstringユーザーのクエリDifyとは何ですか？
retrieval_settingTRUEobject知識の検索パラメータ以下参照
metadata_conditionTRUEobject元の配列のフィルタリング以下参照

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

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

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

属性必須かどうか型説明例
logical_operatorいいえ文字列論理演算子、値は and または or、デフォルトは andand
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形式で返します。

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

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

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

​
レスポンス構文

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_codeTRUEintエラーコード1001
error_msgTRUEstringAPI例外の説明無効な認証ヘッダー形式です。Bearer <api-key> 形式が期待されます。

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

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

​
HTTPステータスコード

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

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

このページは役に立ちましたか？