设置

更新知识库设置

更改知识库的嵌入模型或检索设置。在内容索引前后如何设置模型，详见更换模型或检索设置。

具体行为取决于模型是否已经生效：

第一个文档完成索引前，设置会保存为待生效状态，调用返回 200。这些设置会在第一个文档索引时校验并生效。省略 embedding 或 retrieval 时，该组设置保持其待生效的值。
模型生效后，调用返回 202，更改以迁移的方式进行。更换嵌入模型或推理模型会重建受影响的内容，其他检索设置的更改则无需重建即可生效。用 migration.id 轮询获取设置迁移，直到迁移结束，再读取最终设置。无需迁移的更改（例如重新发送当前生效的嵌入模型）返回 200。

规则：

至少发送 embedding 或 retrieval 之一。模型生效后，每次调用只能发送其中一个。
没有已启用的重排序模型时无法保存 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 Key 认证：Authorization: Bearer {API_KEY}。应用接口使用应用 API Key，知识库接口使用知识库 API Key（快速开始）。

API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 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 等同于省略。

规范化后的请求不得超过 65,536 个 UTF-8 字节。参见请求大小限制。

嵌入设置
检索设置

embedding

object

required

用于索引内容的嵌入模型。模型生效后，更换模型会启动迁移，为所有文档重新生成嵌入。

通过获取可用模型查找可用值：嵌入模型对应 text-embedding，推理模型对应 llm，重排序模型对应 rerank。

pluginId 为插件的 organization/plugin_name，provider 为其供应商名称，model 为模型名称。

「获取可用模型」返回的 provider 是一个形如 organization/plugin_name/provider_name 的字符串，因此 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
  }
}