> ## 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. # 更新知识库设置 > 更改知识库的嵌入模型或检索设置。在内容索引前后如何设置模型，详见 [更换模型或检索设置](/zh/api-reference/guides/knowledge-base#change-models-or-retrieval-settings)。 具体行为取决于模型是否已经生效： - 第一个文档完成索引前，设置会保存为待生效状态，调用返回 `200`。这些设置会在第一个文档索引时校验并生效。省略 `embedding` 或 `retrieval` 时，该组设置保持其待生效的值。 - 模型生效后，调用返回 `202`，更改以迁移的方式进行。更换嵌入模型或推理模型会重建受影响的内容，其他检索设置的更改则无需重建即可生效。用 `migration.id` 轮询 [获取设置迁移](/zh/api-reference/settings/get-settings-migration)，直到迁移结束，再读取最终设置。无需迁移的更改（例如重新发送当前生效的嵌入模型）返回 `200`。 规则： - 至少发送 `embedding` 或 `retrieval` 之一。模型生效后，每次调用只能发送其中一个。 - 没有已启用的重排序模型时无法保存 `retrieval`，因此需同时发送 `rerank.enabled: true` 和 `rerank.model`。 - `retrieval` 需要嵌入模型，可在同一次调用中发送，也可以是之前已保存的。否则调用返回 `409`。 - `scoreThreshold.enabled: true` 时必须提供 `scoreThreshold.value`。 ## OpenAPI ````yaml /zh/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: >- 更改知识库的嵌入模型或检索设置。在内容索引前后如何设置模型，详见 [更换模型或检索设置](/zh/api-reference/guides/knowledge-base#change-models-or-retrieval-settings)。 具体行为取决于模型是否已经生效： - 第一个文档完成索引前，设置会保存为待生效状态，调用返回 `200`。这些设置会在第一个文档索引时校验并生效。省略 `embedding` 或 `retrieval` 时，该组设置保持其待生效的值。 - 模型生效后，调用返回 `202`，更改以迁移的方式进行。更换嵌入模型或推理模型会重建受影响的内容，其他检索设置的更改则无需重建即可生效。用 `migration.id` 轮询 [获取设置迁移](/zh/api-reference/settings/get-settings-migration)，直到迁移结束，再读取最终设置。无需迁移的更改（例如重新发送当前生效的嵌入模型）返回 `200`。 规则： - 至少发送 `embedding` 或 `retrieval` 之一。模型生效后，每次调用只能发送其中一个。 - 没有已启用的重排序模型时无法保存 `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: >- 用于索引内容的嵌入模型。模型生效后，更换模型会启动迁移，为所有文档重新生成嵌入。 通过 [获取可用模型](/zh/api-reference/models/get-available-models) 查找可用值：嵌入模型对应 `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`。 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: >- [获取知识库设置](/zh/api-reference/settings/get-knowledge-base-settings) 返回的当前 `revision`。值已过时则返回 `409`，不做任何更改。 minimum: 1 type: integer retrieval: additionalProperties: false description: 查询使用的检索设置：推理模型、重排序模型、分数阈值、`topK`，以及未指定时使用的检索深度。 nullable: true properties: defaultMode: description: >- 查询省略 `mode` 时使用的检索深度。参见 [检索深度](/zh/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth)。 enum: - fast - deep - research type: string reasoningModel: additionalProperties: false description: >- 系统推理模型：用于索引，以及 `research` 查询。通过 [获取可用模型](/zh/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: >- 所选的重排序模型。通过 [获取可用模型](/zh/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: 每次检索最多返回的分段数。值越大，模型获得的上下文越多，干扰也越多；值越小，结果越集中，但可能漏掉相关分段。 maximum: 100 minimum: 1 type: integer required: - defaultMode - reasoningModel - rerank - scoreThreshold - topK type: object required: - expectedRevision type: object description: >- [获取知识库设置](/zh/api-reference/settings/get-knowledge-base-settings) 的响应使用 snake_case，而此请求体使用 camelCase，因此不能将其响应原样发回。 标记为 nullable 的可选字段，传 `null` 等同于省略。 规范化后的请求不得超过 65,536 个 UTF-8 字节。参见 [请求大小限制](/zh/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` 的结构与 [获取知识库设置](/zh/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: >- 此更改启动的迁移。通过 [获取设置迁移](/zh/api-reference/settings/get-settings-migration) 跟踪。 settings: $ref: '#/components/schemas/KnowledgeBaseSettings' type: object description: >- 此更改启动了迁移，详见 `migration`。`settings` 的结构与 [获取知识库设置](/zh/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`：设置被拒绝，例如 `scoreThreshold.enabled: true` 但未提供 `value`。 '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`，例如另一个更新先写入。重新调用 [获取知识库设置](/zh/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`：未能及时收到响应，或无法读取响应。 设置可能已经保存。发送下一次更新前，先调用 [获取知识库设置](/zh/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`。配置生效后，通过 [更新知识库设置](/zh/api-reference/settings/update-knowledge-base-settings) 进行的更改会作为设置迁移执行。 properties: embedding: description: 已生效嵌入模型的修订版本。 nullable: true type: integer retrieval: description: 已生效检索设置的修订版本。 nullable: true type: integer type: object capabilities: description: >- 已发布设置的就绪情况。其中三个标志对应检索深度，`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` 对象使用 camelCase 键 `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: 每次检索最多返回的分段数。 type: integer type: object revision: description: >- 设置的修订版本。调用 [更新知识库设置](/zh/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，可传给 [获取设置迁移](/zh/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`。再次尝试更改前，先通过 [获取知识库设置](/zh/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 Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.