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

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

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

• 最初のドキュメントがインデックスされる前は、設定は保留中として保存され、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

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
  }
}
'

200

success

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

すべてのリクエストは、Authorization: Bearer {API_KEY} ヘッダーに指定した API キーで認証します。アプリのエンドポイントにはアプリの 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 は省略と同じ扱いになります。

埋め込み設定

検索設定

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

200

application/json

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

migration · object | null

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

settings · object

Show child attributes