このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
このページでは、Dify が外部ナレッジサービスからコンテンツを取得するために実装が必要な API 仕様を定義します。API の準備ができたら、外部ナレッジベースとの接続を参照して Dify に登録してください。
認証#
Dify は API キーを Bearer トークンとしてすべてのリクエストに含めます：
認証ロジックはサービス側で定義します。Dify はキーを送信するのみで検証しません。
リクエスト#
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 | 指定日より後 |
リクエスト例#
レスポンス#
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 の検索パイプラインでエラーを引き起こします。
レスポンス例#
エラーハンドリング#
Dify はレスポンスの HTTP ステータスコードを確認します。200 以外のステータスはユーザーに表示されるエラーを発生させます。
JSON で構造化されたエラー情報を返すこともできます：
| プロパティ | 型 | 説明 |
|---|---|---|
error_code | int | 独自に定義するアプリケーションレベルのエラーコードです。 |
error_msg | string | 人間が読めるエラーの説明です。 |
以下は推奨されるエラーコードです。これらは慣例であり、Dify による強制ではありません：
| コード | 推奨される用途 |
|---|---|
| 1001 | Authorization ヘッダーの形式が不正 |
| 1002 | 認証失敗 |
| 2001 | ナレッジベースが見つからない |