mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
b65aabc65e
* draft * migrate from old docs repo * adjust content based on experiencing the feature * Improvements * changes upon feedback * refinements * zh draft * add plugin dev docs * update old links * add jp docs * change the position of variables related to multimodal embedding in the environment variable doc --------- Co-authored-by: Riskey <riskey47@dify.ai>
178 lines
6.9 KiB
Plaintext
178 lines
6.9 KiB
Plaintext
---
|
||
title: 外部知識API
|
||
---
|
||
|
||
<Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/knowledge/external-knowledge-api)を参照してください。</Note>
|
||
|
||
## エンドポイント
|
||
|
||
```
|
||
POST <your-endpoint>/retrieval
|
||
```
|
||
|
||
## ヘッダー
|
||
|
||
このAPIは、Difyとは独立して開発者が維持管理するナレッジベースに接続するために使用されます。詳細については、[外部ナレッジベースへの接続](/ja/use-dify/knowledge/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
|