設定

ナレッジベース設定を更新

ナレッジベースの埋め込みモデルまたは検索設定を変更します。コンテンツのインデックス前後でのモデル設定については、モデルと検索設定の変更を参照してください。

動作は、モデルがすでにアクティブかどうかによって異なります：

最初のドキュメントがインデックスされる前は、設定は保留中として保存され、200 が返ります。設定は最初のドキュメントのインデックス時に検証され、有効になります。embedding または retrieval を省略すると、そのグループは保留中の値のまま残ります。
モデルがアクティブになった後は 202 が返り、変更は移行として実行されます。埋め込みモデルまたは推論モデルを変更すると、影響を受けるコンテンツが再構築されます。それ以外の検索設定の変更は、再構築なしで反映されます。移行が終わるまで migration.id で設定の移行を取得をポーリングし、その後で最終的な設定を読み取ってください。アクティブな埋め込みモデルを再送信する場合など、移行が不要な変更では 200 が返ります。

ルール：

embedding と retrieval の少なくとも一方を送信します。モデルがアクティブになった後は、1 回の呼び出しでどちらか一方だけを送信します。
retrieval は有効なリランクモデルがないと保存できないため、rerank.enabled: true と rerank.model を一緒に送信します。
retrieval には埋め込みモデルが必要です。同じ呼び出しで送信するか、事前に保存しておきます。そうでない場合は 409 が返ります。
scoreThreshold.enabled: true には scoreThreshold.value が必要です。

PATCH

knowledge-fs

spaces

{knowledge_base_id}

settings

curl --request PATCH \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
  }
}
'

{
  "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
  }
}

Authorizations

Authorization

string

header

required

すべてのリクエストは API キーで認証します：Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。

キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401（unauthorized）で失敗します。

Path Parameters

knowledge_base_id

string<uuid>

required

ナレッジベース ID です。ナレッジベースの API アクセスダイアログに表示されるサービス API エンドポイントの最後のセグメント（…/knowledge-fs/spaces/<knowledge base ID>）です。アドレスバーでは /datasets/new/ の後のセグメントです。

Body

application/json

ナレッジベース設定を取得のレスポンスは snake_case で、このリクエストボディは camelCase です。そのため、そのレスポンスをそのまま送り返すことはできません。

nullable と記されたオプションフィールドでは、null は省略と同じ扱いになります。

正規化後のリクエストは、UTF-8 で 65,536 バイト以内に収める必要があります。リクエストサイズの制限を参照してください。

埋め込み設定
検索設定

embedding

object

required

コンテンツのインデックスに使用する埋め込みモデルです。モデルがアクティブになった後に変更すると、すべてのドキュメントを再埋め込みする移行が始まります。

値は利用可能なモデルを取得で確認します。埋め込みモデルは 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 を表します。

Show child attributes

expectedRevision

integer

required

ナレッジベース設定を取得で得た現在の revision です。古い値を送ると 409 が返り、何も変更されません。

Required range: x >= 1

retrieval

object | null

クエリで使用する検索設定です。推論モデル、リランクモデル、スコアしきい値、topK、およびフォールバックとして使う検索の深度を含みます。

Show child attributes

Response

移行は開始されていません。設定が保留中として保存されたか、モデルがアクティブで変更に移行が不要でした。settings はナレッジベース設定を取得と同じ形式で、その revision を次回の更新で送信します。設定が保留中の間は、active_profile_available は false、capabilities.query も false のままです。

migration

object | null

ここでは常に null です。移行は開始されていません。

settings

object

Show child attributes

curl --request PATCH \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
  }
}
'

{
  "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
  }
}

ガイド

アプリ API

ナレッジ API

ナレッジベース設定を更新

Authorizations

Path Parameters

Body

Response