> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # ナレッジベース設定を更新 > ナレッジベースの埋め込みモデルまたは検索設定を変更します。コンテンツのインデックス前後でのモデル設定については、[モデルと検索設定の変更](/ja/api-reference/guides/knowledge-base#change-models-or-retrieval-settings) を参照してください。 動作は、モデルがすでにアクティブかどうかによって異なります： - 最初のドキュメントがインデックスされる前は、設定は保留中として保存され、`200` が返ります。設定は最初のドキュメントのインデックス時に検証され、有効になります。`embedding` または `retrieval` を省略すると、そのグループは保留中の値のまま残ります。 - モデルがアクティブになった後は `202` が返り、変更は移行として実行されます。埋め込みモデルまたは推論モデルを変更すると、影響を受けるコンテンツが再構築されます。それ以外の検索設定の変更は、再構築なしで反映されます。移行が終わるまで `migration.id` で [設定の移行を取得](/ja/api-reference/settings/get-settings-migration) をポーリングし、その後で最終的な設定を読み取ってください。アクティブな埋め込みモデルを再送信する場合など、移行が不要な変更では `200` が返ります。 ルール： - `embedding` と `retrieval` の少なくとも一方を送信します。モデルがアクティブになった後は、1 回の呼び出しでどちらか一方だけを送信します。 - `retrieval` は有効なリランクモデルがないと保存できないため、`rerank.enabled: true` と `rerank.model` を一緒に送信します。 - `retrieval` には埋め込みモデルが必要です。同じ呼び出しで送信するか、事前に保存しておきます。そうでない場合は `409` が返ります。 - `scoreThreshold.enabled: true` には `scoreThreshold.value` が必要です。 ## OpenAPI ````yaml /ja/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/settings openapi: 3.0.1 info: description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 title: Dify サービス API version: 1.0.0 servers: - description: Dify サービス API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - description: チャットメッセージとインタラクションに関連する操作です。 name: チャットメッセージ - description: ファイルのアップロードとプレビューの操作です。 name: ファイル操作 - description: エンドユーザー情報に関連する操作です。 name: エンドユーザー - description: ユーザーフィードバックの操作です。 name: メッセージフィードバック - description: 会話管理に関連する操作です。 name: 会話管理 - description: テキスト読み上げと音声認識の操作です。 name: 音声・テキスト変換 - description: アプリケーション設定と情報を取得する操作です。 name: アプリケーション設定 - description: ダイレクト返信用のアノテーション管理に関連する操作です。 name: アノテーション管理 - description: 人間の入力を要する一時停止中のワークフローの再開操作です。 name: 人間の入力 - description: ワークフローの実行と管理のための操作です。 name: ワークフロー実行 - description: テキスト生成に関連する操作です。 name: 完了メッセージ - description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 name: ナレッジベース - description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 name: ドキュメント - description: ドキュメントチャンクと子チャンクの管理のための操作です。 name: チャンク - description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 name: メタデータ - description: ナレッジベースタグとタグバインディングの管理のための操作です。 name: タグ管理 - description: 利用可能なモデルを取得するための操作です。 name: モデル - description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 name: ナレッジパイプライン - description: ナレッジベースに質問し、回答をストリーミングで受け取ります。 name: クエリ - description: クエリが何を検索したか、またその理由を確認します。 name: クエリ記録 - description: リサーチの質問をバックグラウンドで実行し、その結果を取得します。 name: リサーチタスク - description: ナレッジベースのドキュメントと、そのファイル、リビジョン、チャンクを読み取り、ドキュメントにメタデータのラベルを付けます。 name: ドキュメントとチャンク - description: インデックス処理の追跡、キャンセル、再試行と、ナレッジベースのバックグラウンドタスクの一覧表示を行います。 name: インデックスタスク - description: ドキュメントファイル、ファイルのバッチ、またはソースの削除を、完了するまで追跡します。 name: 削除ジョブ - description: ナレッジベースにデータを供給するソース、その同期スケジュール、接続を管理します。 name: ソース - description: ソースの即時同期、ウェブサイトのページまたはプロバイダーのアイテムのインポート、実行の追跡、キャンセル、再試行を行います。 name: ソースの同期とインポート - description: ナレッジベースのモデルと検索設定の読み取りと変更、および変更によって始まる移行の追跡を行います。 name: 設定 paths: /knowledge-fs/spaces/{knowledge_base_id}/settings: patch: tags: - Settings summary: ナレッジベース設定を更新 description: >- ナレッジベースの埋め込みモデルまたは検索設定を変更します。コンテンツのインデックス前後でのモデル設定については、[モデルと検索設定の変更](/ja/api-reference/guides/knowledge-base#change-models-or-retrieval-settings) を参照してください。 動作は、モデルがすでにアクティブかどうかによって異なります： - 最初のドキュメントがインデックスされる前は、設定は保留中として保存され、`200` が返ります。設定は最初のドキュメントのインデックス時に検証され、有効になります。`embedding` または `retrieval` を省略すると、そのグループは保留中の値のまま残ります。 - モデルがアクティブになった後は `202` が返り、変更は移行として実行されます。埋め込みモデルまたは推論モデルを変更すると、影響を受けるコンテンツが再構築されます。それ以外の検索設定の変更は、再構築なしで反映されます。移行が終わるまで `migration.id` で [設定の移行を取得](/ja/api-reference/settings/get-settings-migration) をポーリングし、その後で最終的な設定を読み取ってください。アクティブな埋め込みモデルを再送信する場合など、移行が不要な変更では `200` が返ります。 ルール： - `embedding` と `retrieval` の少なくとも一方を送信します。モデルがアクティブになった後は、1 回の呼び出しでどちらか一方だけを送信します。 - `retrieval` は有効なリランクモデルがないと保存できないため、`rerank.enabled: true` と `rerank.model` を一緒に送信します。 - `retrieval` には埋め込みモデルが必要です。同じ呼び出しで送信するか、事前に保存しておきます。そうでない場合は `409` が返ります。 - `scoreThreshold.enabled: true` には `scoreThreshold.value` が必要です。 operationId: updateKnowledgeBaseSettings parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: リクエスト例 - モデルがアクティブになる前 value: embedding: model: text-embedding-3-small pluginId: langgenius/openai provider: openai expectedRevision: 7 retrieval: defaultMode: fast reasoningModel: model: gpt-4.1-mini pluginId: langgenius/openai provider: openai rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere scoreThreshold: enabled: true stage: mode-final value: 0.4 topK: 10 request_embedding: summary: リクエスト例 - 埋め込みモデルを変更 value: embedding: model: text-embedding-3-large pluginId: langgenius/openai provider: openai expectedRevision: 7 schema: additionalProperties: false anyOf: - properties: embedding: nullable: false type: object required: - embedding title: 埋め込み設定 - properties: retrieval: nullable: false type: object required: - retrieval title: 検索設定 properties: embedding: additionalProperties: false description: >- コンテンツのインデックスに使用する埋め込みモデルです。モデルがアクティブになった後に変更すると、すべてのドキュメントを再埋め込みする移行が始まります。 値は [利用可能なモデルを取得](/ja/api-reference/models/get-available-models) で確認します。埋め込みモデルは `text-embedding`、推論モデルは `llm`、リランクモデルは `rerank` で取得します。 `pluginId` はプラグインの `organization/plugin_name`、`provider` はそのプロバイダー名、`model` はモデル名です。 「利用可能なモデルを取得」は、`organization/plugin_name/provider_name` 形式の `provider` 文字列を 1 つ返します。そのため、`langgenius/openai/openai` は `pluginId` の `langgenius/openai` と `provider` の `openai` に分かれます。`openai` だけの場合は `langgenius/openai/openai` を表します。 nullable: true properties: model: description: プロバイダープラグインが示すとおりのモデル名（例：`text-embedding-3-small`）です。 maxLength: 256 minLength: 1 type: string pluginId: description: >- モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します（例：`langgenius/openai`）。 maxLength: 256 minLength: 1 type: string provider: description: プラグイン内のプロバイダー名（例：`openai`）です。 maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object expectedRevision: description: >- [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) で得た現在の `revision` です。古い値を送ると `409` が返り、何も変更されません。 minimum: 1 type: integer retrieval: additionalProperties: false description: >- クエリで使用する検索設定です。推論モデル、リランクモデル、スコアしきい値、`topK`、およびフォールバックとして使う検索の深度を含みます。 nullable: true properties: defaultMode: description: >- クエリで `mode` が省略された場合に使用する検索の深度です。[検索の深度](/ja/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth) を参照してください。 enum: - fast - deep - research type: string reasoningModel: additionalProperties: false description: >- システム推論モデルです。インデックス処理中と、`research` のクエリで使用されます。値は [利用可能なモデルを取得](/ja/api-reference/models/get-available-models) で確認します。 properties: model: description: プロバイダープラグインが示すとおりのモデル名です。 maxLength: 256 minLength: 1 type: string pluginId: description: >- モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します。 maxLength: 256 minLength: 1 type: string provider: description: プラグイン内のプロバイダー名です。 maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object rerank: additionalProperties: false description: |- 検索されたチャンクに適用するリランクモデルです。 この操作では、`enabled: true` と null 以外のモデルが必要です。 properties: enabled: description: 検索されたチャンクをリランクするかどうかです。 enum: - true type: boolean model: additionalProperties: false description: >- 使用するリランクモデルです。値は [利用可能なモデルを取得](/ja/api-reference/models/get-available-models) で確認します。 nullable: false properties: model: description: プロバイダープラグインが示すとおりのモデル名です。 maxLength: 256 minLength: 1 type: string pluginId: description: >- モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します。 maxLength: 256 minLength: 1 type: string provider: description: プラグイン内のプロバイダー名です。 maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object required: - enabled - model type: object scoreThreshold: additionalProperties: false anyOf: - properties: enabled: enum: - false title: しきい値無効 - properties: enabled: enum: - true value: nullable: false type: number required: - value title: しきい値有効 description: スコアの低いチャンクを除外するスコアしきい値です。 properties: enabled: description: しきい値を適用するかどうかです。`true` の場合は `value` を送信します。 type: boolean stage: default: mode-final description: >- しきい値を適用する段階です。`mode-final` は、実行される検索の深度の最終スコアに適用します。`fast` と `deep` ではリランクスコア、`research` では PageIndex スコアです。`rerank` は同じ設定の旧名称です。 enum: - mode-final - rerank type: string value: description: >- しきい値となるスコアです。これを下回るチャンクは除外されます。しきい値を高くすると関連性の高い一致だけが残りますが、何も返らないおそれがあります。低くすると、より幅広い一致が通ります。 maximum: 1 minimum: 0 nullable: true type: number required: - enabled type: object topK: description: >- 1 回の検索で返すチャンクの最大数です。値を大きくするとモデルに渡るコンテキストが増えますが、ノイズも増えます。値を小さくすると焦点は絞られますが、関連するチャンクを取りこぼすことがあります。 maximum: 100 minimum: 1 type: integer required: - defaultMode - reasoningModel - rerank - scoreThreshold - topK type: object required: - expectedRevision type: object description: >- [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) のレスポンスは snake_case で、このリクエストボディは camelCase です。そのため、そのレスポンスをそのまま送り返すことはできません。 nullable と記されたオプションフィールドでは、`null` は省略と同じ扱いになります。 正規化後のリクエストは、UTF-8 で 65,536 バイト以内に収める必要があります。[リクエストサイズの制限](/ja/api-reference/guides/knowledge-base#request-size-limits) を参照してください。 required: true responses: '200': content: application/json: examples: success: summary: レスポンス例 value: migration: null settings: active_profile_available: false active_profile_revisions: embedding: null retrieval: null capabilities: deep: false index: false ingest: true query: false research: false source_sync: true configuration_state: active embedding: dimension: null model: text-embedding-3-small plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null issues: [] retrieval: default_mode: fast reasoning_model: dimension: null model: gpt-4.1-mini plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere revision: null score_threshold: enabled: true stage: mode-final value: 0.4 top_k: 10 revision: 8 schema: properties: migration: description: ここでは常に `null` です。移行は開始されていません。 nullable: true type: object settings: $ref: '#/components/schemas/KnowledgeBaseSettings' type: object description: >- 移行は開始されていません。設定が保留中として保存されたか、モデルがアクティブで変更に移行が不要でした。`settings` は [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) と同じ形式で、その `revision` を次回の更新で送信します。設定が保留中の間は、`active_profile_available` は `false`、`capabilities.query` も `false` のままです。 '202': content: application/json: examples: migration: summary: レスポンス例 - 移行を開始 value: migration: candidate_publication_fingerprint: null changed_kind: embedding checkpoint: queued completed_at: null created_at: '2026-09-08T03:10:00Z' error_code: null evaluation_summary: null id: a7c3e9f1-2b4d-4c6e-8f0a-1b3d5f7a9c2e knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d rebuild_scope: full-vector-space run_state: queued updated_at: '2026-09-08T03:10:00Z' settings: active_profile_available: true active_profile_revisions: embedding: 2 retrieval: 3 capabilities: deep: true index: true ingest: true query: true research: true source_sync: true configuration_state: active embedding: dimension: 1536 model: text-embedding-3-small plugin_id: langgenius/openai provider: openai revision: 2 vector_space_id: >- embedding-space-sha256:4f7c2d9a1b3e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4 issues: [] retrieval: default_mode: fast reasoning_model: dimension: null model: gpt-4.1-mini plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere revision: 3 score_threshold: enabled: false stage: mode-final value: null top_k: 10 revision: 7 schema: properties: migration: allOf: - $ref: '#/components/schemas/KnowledgeBaseSettingsMigration' description: >- この変更で開始された移行です。[設定の移行を取得](/ja/api-reference/settings/get-settings-migration) で追跡します。 settings: $ref: '#/components/schemas/KnowledgeBaseSettings' type: object description: >- 変更によって移行が開始されました。移行の内容は `migration` に示されます。`settings` は [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) と同じ形式です。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - expectedRevision type: missing knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (settings rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。原因は次のとおりです。 - 不明なキーがある、またはフィールドが制約を満たしていない - `embedding` も `retrieval` も送信されていない - 有効なリランクモデルなしで `retrieval` が送信された - `knowledge_fs_invalid_request`：設定が拒否されました。たとえば、`value` なしで `scoreThreshold.enabled: true` を送信した場合です。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized_1: summary: unauthorized (header missing) value: code: unauthorized message: >- Authorization header must be provided and start with 'Bearer' status: 401 unauthorized_2: summary: unauthorized (key unknown) value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：`Authorization` ヘッダーがないか、キーが不明であるか、ナレッジベースの API キーではありません。 - `knowledge_fs_invalid_credential`：キーは有効ですが、キーのワークスペースにこの ID のナレッジベースが存在しないか、キーがワークスペースに紐付いていません。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `knowledge_fs_access_denied`：リクエストの認可が拒否されました。 - `forbidden`：Dify Cloud で、ワークスペースがサブスクリプションで定められたナレッジベースのリクエストレート制限に達しました。読み取りを含め、すべての呼び出しがカウントされます。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: |- - `knowledge_fs_resource_not_found`：ナレッジベース ID が認識されません。 - `not_found`：このデプロイ環境では Agent ナレッジベース機能が無効になっています。 '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict (no embedding model) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 knowledge_space_settings_revision_conflict: summary: knowledge_fs_conflict (stale revision) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT message: >- Knowledge space settings have changed. Reload the latest settings and review your changes before saving again. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Knowledge space settings have changed. Reload the latest settings and review your changes before saving again. status: 409 description: |- - `knowledge_fs_conflict`：原因はレスポンスボディの `failure.code` に示されます： - `KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT`：`expectedRevision` が現在の `revision` と一致しません。別の更新が先に反映された場合などに起こります。[ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) で読み直し、返された `revision` で再試行してください。 - `KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS`：ドキュメントを処理中です。モデルを変更する前に、処理の完了を待つか、インデックスタスクをキャンセルしてください。 - `KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED`：変更には移行が必要ですが、モデルがアクティブになったか、コンテンツがまだ公開されていないため、この呼び出しでは開始できませんでした。もう一度試す前に、設定を読み直してください。 - `KNOWLEDGE_FS_CONFLICT`：モデルがアクティブになる前に、埋め込みモデルのないナレッジベースに `retrieval` が送信されました。`retrieval` を送信する前に、埋め込みモデルを設定してください。モデルがアクティブになった後は、同じコードは移行をリクエストまたは再試行できなかったことを示します。 '422': content: application/json: examples: knowledge_fs_request_rejected: summary: knowledge_fs_request_rejected (both groups) value: code: knowledge_fs_request_rejected message: Agent Knowledge Base request was rejected. status: 422 description: >- - `knowledge_fs_request_rejected`：モデルがアクティブな状態で、リクエストボディに `embedding` と `retrieval` の両方が含まれています。別々の呼び出しで送信してください。このレスポンスボディには `failure` も `violations` も含まれません。 - `knowledge_fs_request_rejected`：モデルがアクティブになった後で、選択したモデルが事前チェックに失敗しました。レスポンスボディの `failure` には `MODEL_*` または `EMBEDDING_DIMENSION_*` のコードが入ります。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 knowledge_fs_upstream_unavailable_upstream: summary: knowledge_fs_upstream_unavailable (internal error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：時間内に応答が返らなかったか、応答を読み取れませんでした。 設定が保存されている可能性があります。次の更新を送信する前に、[ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) で設定を読み取り、値と `revision` を比較してください。リビジョンが変わっただけでは、更新が成功したことも、モデルが検証に通ったことも確定しません。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：このワークスペースで Agent ナレッジベース機能が設定されていないか、このデプロイ環境ではこの操作を利用できません。または、リクエストの認可中に、このナレッジベースに対するキーのアクセス権が変更されました。再試行してください。 - `knowledge_fs_operation_unavailable`：現在このリクエストを処理できません。`failure.retryPolicy` に従ってください。 - `knowledge_fs_operation_unavailable`：埋め込みモデルがアクティブで検索設定がアクティブでない状態で `retrieval` が送信されたため、変更をルーティングできません。 - `knowledge_fs_operation_unavailable`：モデルの事前チェックまたは移行を、現在開始できません。 components: schemas: KnowledgeBaseSettings: properties: active_profile_available: description: >- 埋め込みモデルと検索設定の両方がアクティブな場合は `true` です。最初のドキュメントのインデックス処理が済むとアクティブになります。 type: boolean active_profile_revisions: description: >- アクティブなモデルのリビジョンです。最初のドキュメントのインデックス処理が済むまでは、いずれも `null` です。プロファイルがアクティブになった後は、[ナレッジベース設定を更新](/ja/api-reference/settings/update-knowledge-base-settings) による変更は設定の移行として実行されます。 properties: embedding: description: アクティブな埋め込みモデルのリビジョンです。 nullable: true type: integer retrieval: description: アクティブな検索設定のリビジョンです。 nullable: true type: integer type: object capabilities: description: >- 公開済みの設定で各機能を使える状態かどうかを示します。3 つのフラグは検索の深度に対応し、`query` は `fast` を表します。 特定の深度で使えるかどうかを確認するには、その深度を `mode` として明示的に送信し、対応するフラグを確認してください。`mode` を省略したクエリの深度を判断するために、保留中の `retrieval.default_mode` を使用しないでください。 properties: deep: description: '`deep` の深度でクエリを実行できます。' type: boolean index: description: ドキュメントのインデックス処理を実行できます。モデルがアクティブです。 type: boolean ingest: description: >- ドキュメントを追加できます。モデルがアクティブであるか、保留中の設定が揃っていて、最初のドキュメントでアクティブ化できる状態です。 type: boolean query: description: '`fast` の深度でクエリを実行できます。' type: boolean research: description: '`research` の深度でクエリを実行できます。' type: boolean source_sync: description: ソースを同期できます。条件は `ingest` と同じです。 type: boolean type: object configuration_state: description: >- 埋め込みモデルと完全な検索設定（有効なリランクモデルを含む）が保存されている場合は `active` です。いずれかが欠けている場合は `setup-required` です。最初のドキュメントのインデックス処理中に、保留中の設定が検証に失敗した場合は `validation-failed` です。失敗した設定は `issues` に示されます。 type: string embedding: description: >- 埋め込みモデルです。保留中の選択が保存されている場合はその選択、それ以外の場合はアクティブなモデルです。保留中の選択は、クエリが現在使用しているモデルと異なる場合があります。設定されていない場合は `null` です。 `dimension`、`revision`、`vector_space_id` は参考情報であり、これらを受け取る操作はありません。 nullable: true properties: dimension: description: ベクトルの次元数で、モデルの初回使用時に確認されます。モデルがアクティブになるまでは `null` です。 nullable: true type: integer model: description: モデル名です。 type: string plugin_id: description: モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します。 type: string provider: description: プラグイン内のプロバイダー名です。 type: string revision: description: アクティブな埋め込みモデルのリビジョンです。モデルがアクティブになるまでは `null` です。 nullable: true type: integer vector_space_id: description: モデルのベクトルの保存先を識別します。モデルがアクティブになるまでは `null` です。 nullable: true type: string type: object issues: description: ナレッジベースが使用可能になるのを妨げている問題です。問題がない場合は空です。 items: properties: code: description: >- 設定の問題点です： - `missing`：選択されていないか、リランクが無効です。 - `validation_failed`、`unavailable`、`incompatible`：保留中の設定が検証に失敗しました。`incompatible` の場合は、モデルが対応するタスク、埋め込みの次元数、選択したモデルをプロバイダーが返したかどうかを確認してください。 - `binding_missing`：公開済みのコンテンツが、設定されたモデルを使用できる状態になっていません。Dify でインデックス処理の進捗を確認してください。 - `publication` に対する `unavailable`：公開済みのコンテンツが、すべての深度に対応できる状態になっていません。 type: string field: description: >- 対象の設定で、`embedding`、`reasoning`、`rerank`、`publication`（公開済みのコンテンツ）のいずれかです。 type: string retryable: description: 設定を変更しなくても、時間をおいて再試行すれば問題が解消するかどうかです。 type: boolean type: object type: array retrieval: description: >- 検索設定です。保留中の選択が保存されている場合はその選択、それ以外の場合はアクティブな設定です。保留中の選択は、クエリが現在使用している設定と異なる場合があります。設定されていない場合は `null` です。 nullable: true properties: default_mode: description: >- 返された検索設定におけるデフォルトの深度で、`fast`、`deep`、`research` のいずれかです。`mode` を省略したクエリは、公開済みのデフォルトを使用します。保留中の設定が返されている場合、公開済みのデフォルトはこの値と異なることがあります。 type: string reasoning_model: description: >- システムの推論モデルです。`dimension`、`revision`、`vector_space_id` は常に `null` です。 properties: dimension: description: 常に `null` です。 nullable: true type: integer model: description: モデル名です。 type: string plugin_id: description: モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します。 type: string provider: description: プラグイン内のプロバイダー名です。 type: string revision: description: 常に `null` です。 nullable: true type: integer vector_space_id: description: 常に `null` です。 nullable: true type: string type: object rerank: description: >- リランクモデルです。このレスポンスのほかの部分とは異なり、`model` オブジェクトではキャメルケースのキー `pluginId` が使われます。 properties: enabled: description: 検索されたチャンクをリランクするかどうかです。 type: boolean model: description: 選択されたリランクモデルです。リランクモデルが設定されていない場合は `null` です。 nullable: true properties: model: description: モデル名です。 type: string pluginId: description: モデルを提供するプラグインです。`organization/plugin_name` の形式で指定します。 type: string provider: description: プラグイン内のプロバイダー名です。 type: string type: object type: object revision: description: アクティブな検索設定のリビジョンです。設定が保留中の間は `null` です。 nullable: true type: integer score_threshold: description: スコアの低いチャンクを除外するスコアしきい値です。 properties: enabled: description: しきい値を適用するかどうかです。 type: boolean stage: description: >- しきい値を適用する段階です。`mode-final` は、実行される検索の深度の最終スコアに適用します。`fast` と `deep` ではリランクスコア、`research` では PageIndex スコアです。`rerank` は同じ設定の旧名称です。 type: string value: description: しきい値となるスコアで、0 から 1 の値です。設定されていない場合は `null` です。 nullable: true type: number type: object top_k: description: 1 回の検索で返すチャンクの最大数です。 type: integer type: object revision: description: >- 設定のリビジョンです。[ナレッジベース設定を更新](/ja/api-reference/settings/update-knowledge-base-settings) で `expectedRevision` として送信します。このレスポンスにあるほかのリビジョンのフィールドは、この値とは別物です。 type: integer type: object KnowledgeBaseSettingsMigration: properties: candidate_publication_fingerprint: description: 内部用です。移行の追跡には不要です。 nullable: true type: string changed_kind: description: 変更の対象で、`embedding` または `retrieval` です。 type: string checkpoint: description: >- 到達した最後のステップで、`queued`、`candidate-built`、`evaluated`、`activated` のいずれかです。 type: string completed_at: description: >- 移行が `succeeded`、`failed`、`canceled` のいずれかで終了した日時（ISO 8601）です。実行中は `null` です。 nullable: true type: string created_at: description: 移行の開始日時（ISO 8601）です。 type: string error_code: description: >- 直近の失敗のコードです（例：`PROFILE_MIGRATION_ATTEMPTS_EXHAUSTED`、`VECTOR_SPACE_QUOTA_EXCEEDED`）。失敗がない場合は `null` です。 nullable: true type: string evaluation_summary: description: 再構築されたインデックスについて記録された評価結果の、フラットなマップです。記録されていない場合は `null` です。 nullable: true type: object id: description: >- 移行 ID です。[設定の移行を取得](/ja/api-reference/settings/get-settings-migration) に渡します。 type: string knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string rebuild_scope: description: >- 移行で再構築される範囲です： - `full-vector-space`：埋め込みモデルの変更により、すべてのドキュメントを埋め込み直します。 - `full-page-index-summary-outline`：推論モデルの変更により、ページインデックス、要約、アウトラインを再構築します。 - `clone-publication`：そのほかの検索設定の変更では、現在のインデックスを再利用します。 type: string run_state: description: >- 移行の進行状況です： - `queued`、`running`：処理中です。 - `succeeded`：新しい設定が適用されています。 - `failed`：停止しました。理由は `error_code` に示されます。変更を再度試す前に、[ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) でモデルを確認してください。 - `canceled`：完了前に、同じ種類の新しい変更によってこの移行が置き換えられました。新しい移行を追跡してください。 type: string updated_at: description: 移行が最後に変更された日時（ISO 8601）です。 type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.