---
title: 外部知識API
---

## エンドポイント

```
POST <your-endpoint>/retrieval
```

## ヘッダー

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

```
Authorization: Bearer {API_KEY}
```

## リクエストボディ要素

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

| プロパティ | 必須 | 型 | 説明 | 例値 |
|------------|------|-----|------|------|
| knowledge_id | TRUE | string | ナレッジベースの一意ID | AAA-BBB-CCC |
| query | TRUE | string | ユーザーのクエリ | Difyとは何ですか？ |
| retrieval_setting | TRUE | object | 知識の検索パラメータ | 以下参照 |
| metadata_condition | TRUE | object | 元の配列のフィルタリング | 以下参照 |

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

| プロパティ | 必須 | 型 | 説明 | 例値 |
|------------|------|-----|------|------|
| top_k | TRUE | int | 検索結果の最大数 | 5 |
| score_threshold | TRUE | float | クエリに対する結果の関連性スコアの閾値、範囲：0〜1 | 0.5 |

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

| 属性 | 必須かどうか | 型 | 説明 | 例 |
|------|----------|------|------|--------|
| logical_operator | いいえ | 文字列 | 論理演算子、値は `and` または `or`、デフォルトは `and` | and |
| 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`：特定の日付より後

## リクエスト構文

```json
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形式で返します。

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

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

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

## レスポンス構文

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

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

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

## 開発例

以下の動画では、LlamaCloudを例として外部ナレッジベースプラグインの開発方法を学ぶことができます：

<iframe
  src="https://www.youtube.com/embed/FaOzKZRS-2E"
  width="100%"
  height="315"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

詳細については、プラグインの[GitHubリポジトリ](https://github.com/langgenius/dify-official-plugins/tree/main/extensions/llamacloud)を参照してください。

### HTTPステータスコード

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

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

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[このページを編集する](https://github.com/langgenius/dify-docs/edit/main/ja-jp/guides/knowledge-base/api-documentation/external-knowledge-api-documentation.mdx) | [問題を報告する](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

