このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。Dify コンソールを介さず、自分のコードから ナレッジベース を構築・管理できます。ナレッジベースを作成し、ドキュメントとチャンクを取り込み、メタデータとタグで整理し、検索や RAG のために直接クエリできます。
API エンドポイントとキーの取得
ナレッジ 画面右上の サービスAPI をクリックすると、API 設定パネルが開きます。ここから以下を行えます。- サービスAPI エンドポイントをコピーします。すべてのナレッジ API リクエストのベース URL です。
- APIキー をクリックしてキーを作成・管理します。
API キーのスコープを限定する
連携先で一部のナレッジベースだけを扱う場合は、キーの作成時にそのナレッジベースを選びます。ナレッジベースの一覧取得や作成が必要な場合は、すべてのナレッジベースを選んでください。 スコープを限定したキーで呼び出せるのは、パスにスコープ内のdataset_id を含むエンドポイントだけです。別の ID を指定した場合や、パスに dataset_id がない場合は、403 forbidden が返ります。
スコープを限定したキーで使う ID は、Dify で対象のナレッジベースを開いて取得します。ページ URL の /datasets/ の後にある ID をコピーし、リクエストパスの dataset_id に指定してください。
スコープを変更するには、新しいキーを作成します。連携先を新しいキーに切り替えてから、古いキーを削除してください。
ナレッジベースを削除すると、そのナレッジベースだけに限定されたキーも削除されます。他のナレッジベースも対象に含むキーは、それらに対して引き続き使えます。
ナレッジベースの API アクセス管理
既定では、すべてのナレッジベースで API アクセスが有効です。特定のナレッジベースへの API アクセスをすべてのキーで無効にするには、対象のナレッジベースを開き、左下の API アクセス をオフにします。ナレッジベースの作成と管理
- 空のナレッジベースを作成：ドキュメントを含まないナレッジベースを作成します。
- ナレッジベースリストを取得：キーワードやタグで絞り込めるページネーション付きリストを返します。
- ナレッジベース詳細を取得：埋め込みモデル、検索設定、ドキュメント統計を返します。
- ナレッジベースを更新：名前、権限、埋め込みモデル、検索設定を変更します。リクエストで指定したフィールドのみを更新します。
- ナレッジベースを削除：ナレッジベースとその中のすべてのドキュメント、そしてそのナレッジベースだけに限定された API キーを完全に削除します。
- ナレッジベースからチャンクを取得 / テスト検索：ナレッジベースを検索し、最も関連性の高いチャンクを返します。本番検索と検索テストの両方に同じエンドポイントを使います。
ドキュメントの追加と更新
ドキュメントの作成は非同期です。作成後、インデックスが完了するまでポーリングします。1
ナレッジベースの作成
空のナレッジベースを作成 を呼び出します。既存のナレッジベースをそのまま使うこともできます。
2
ドキュメントの追加
テキストからドキュメントを作成 または ファイルからドキュメントを作成 を呼び出します。どちらも
batch ID を返します。ナレッジベース作成時に indexing_technique（検索用に内容をインデックスする方法）を設定しなかった場合は、この最初のドキュメントで設定します。以降のドキュメントには自動的に引き継がれます。3
インデックス状況のポーリング
batch ID を使って ドキュメント埋め込みステータス（進捗）を取得 をポーリングします。indexing_status が completed または error になるまで待ちます。処理は waiting、parsing、cleaning、splitting、indexing の順に進みます。- ナレッジベースのドキュメントリストを取得：キーワードやインデックスステータスで絞り込めるページネーション付きリストを返します。
- ドキュメント詳細を取得：インデックスステータス、メタデータ、処理統計を返します。
metadataクエリパラメータで、メタデータフィールドを含める・省略する・のみ返すのいずれかを指定できます。 - ドキュメントをダウンロード：ドキュメントの元ファイルに対する署名付きダウンロード URL を返します。
- ドキュメントを一括ダウンロード（ZIP）：ファイルからアップロードしたドキュメントを最大 100 件、1 つのアーカイブにまとめます。
- ドキュメントを更新：新しいファイルをアップロードして内容を置き換え、インデックスを再実行します。これがファイルベースのドキュメントを更新する標準的な方法です。
- テキストでドキュメントを更新：ドキュメントのテキスト内容、名前、処理設定をインラインで更新します。内容が変わるとインデックスを再実行します。
- ファイルでドキュメントを更新：置き換え用のファイルをアップロードするための非推奨のエイリアスです。代わりに「ドキュメントを更新」を使用してください。
- ドキュメントステータスを一括更新：複数のドキュメントを一度に有効化・無効化・アーカイブ・アーカイブ解除します。
- ドキュメントを削除：ドキュメントとその中のすべてのチャンクを完全に削除します。
チャンクと子チャンクの管理
- ドキュメントにチャンクを追加：チャンクを手動でドキュメントに追加します（アップロードされた内容は、インデックス処理が自動でチャンク化します）。各チャンクには
contentが必須で、Q&A モードのドキュメントではanswerも必須です。 - チャンク一覧を取得：キーワードやステータスで絞り込めるページネーション付きリストを返します。
- ドキュメント内のチャンク詳細を取得：チャンクの内容、キーワード、インデックスステータスを返します。
- ドキュメント内のチャンクを更新：チャンクの内容、キーワード、回答を変更し、そのチャンクのインデックスを再実行します。
- ドキュメント内のチャンクを削除：チャンクを完全に削除します。
hierarchical_model）のドキュメントでは、子チャンクは親チャンクの配下に置かれます。API から作成・更新した子チャンクは常に customized になり、インデックス処理が自動生成する automatic とは区別されます。
- 子チャンクを作成：親チャンクの下に子チャンクを追加します。
- 子チャンク一覧を取得：親チャンク配下の子チャンクをページネーション付きで返します。
- 子チャンクを更新：子チャンクの内容を変更します。
- 子チャンクを削除：子チャンクを完全に削除します。
メタデータフィールドの管理
メタデータフィールドはドキュメントに構造化情報を付与し、検索時のフィルタリングに使えます。- メタデータフィールドを作成：
string、number、timeのいずれかの型でカスタムフィールドを追加します。 - メタデータフィールドリストを取得：カスタムフィールドと組み込みフィールドの両方を、使用ドキュメント数とともに返します。
- メタデータフィールドを更新：カスタムフィールドの名前を変更します。
- メタデータフィールドを削除：カスタムフィールドを削除します。対象ドキュメントはその値を失います。
- 組み込みメタデータフィールドを取得：
document_name、uploader、upload_dateなど、システム提供のフィールドを返します。 - 組み込みメタデータフィールドを更新：ナレッジベースごとに組み込みフィールドの有効・無効を切り替えます。
- ドキュメントメタデータを一括更新：1 回の呼び出しで複数のドキュメントにメタデータのキーと値を設定します。
タグによるナレッジベースの整理
タグはワークスペース単位で管理され、個々のナレッジベースには依存しません。- ナレッジベースタグを作成：ナレッジベースを整理するためのタグを作成します。
- ナレッジベースタグリストを取得：ワークスペース内のすべてのタグを返します。
- ナレッジベースタグを変更：タグの名前を変更します。
- ナレッジベースタグを削除：紐づいていたすべてのナレッジベースからタグを外します。ナレッジベース自体は削除されません。
- タグをナレッジベースにバインド：1 つ以上のタグをナレッジベースにバインドします。1 つのナレッジベースに複数のタグを付けられます。
- タグとナレッジベースのバインドを解除：ナレッジベースからタグを外します。
- ナレッジベースにバインドされたタグを取得：ナレッジベースに現在バインドされているタグを返します。
利用可能なモデルの取得
- 利用可能なモデルを取得：指定した
model_typeで利用できるモデルを返します。ナレッジベースの設定では、text-embeddingで埋め込みモデルを、rerankでリランクモデルを照会します。
ナレッジパイプラインの実行
ナレッジパイプラインは、データソースからデータを取り込みドキュメントに変換するワークフローです。- パイプラインファイルをアップロード：パイプラインが処理するファイルをアップロードします。
- データソースプラグインリストを取得：パイプラインに設定されたデータソースノードを返します。既定では公開版を、
is_published=falseを指定すると下書き版を返します。 - データソースノードを実行：単一のデータソースノードを実行し、結果をストリーミングで返します。1 つのステップを個別にテストする際に便利です。
- パイプラインを実行：
streamingまたはblockingモードでパイプライン全体を実行します。is_publishedで公開版と下書きのどちらを実行するかを指定します。