> ## 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. # 更新文档元数据 > 将键合并到文档的 `user_metadata` 中，并返回更新后的文档。与此路径上的其他操作不同，它接收的是文档 ID，而不是文档文件 ID。 将文档的 `row_version` 作为 `expectedRowVersion` 发送。更新前先读取文档；收到 `409` 时，重新读取后再次发送。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} 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}/documents/{document_file_id}: patch: tags: - Documents and Chunks summary: 更新文档元数据 description: >- 将键合并到文档的 `user_metadata` 中，并返回更新后的文档。与此路径上的其他操作不同，它接收的是文档 ID，而不是文档文件 ID。 将文档的 `row_version` 作为 `expectedRowVersion` 发送。更新前先读取文档；收到 `409` 时，重新读取后再次发送。 operationId: updateDocumentMetadata parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- 文档 ID：[获取文档列表](/zh/api-reference/documents-and-chunks/list-documents) 或 [获取文档](/zh/api-reference/documents-and-chunks/get-document) 返回的 `id`，或 [按文件获取文档](/zh/api-reference/documents-and-chunks/get-document-by-file) 返回的 `document_id`。不是文档文件 ID，尽管同一路径上的 [获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file) 和 [删除文档文件](/zh/api-reference/documents-and-chunks/delete-document-file) 接收的是文档文件 ID。传入文档文件 ID 会返回 `404`。 in: path name: document_file_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: 请求示例 value: expectedRowVersion: 4 patch: owner: billing-team review_date: '2027-03-01T00:00:00Z' schema: additionalProperties: false properties: expectedRowVersion: description: >- 文档当前的 `row_version`，从 [获取文档](/zh/api-reference/documents-and-chunks/get-document) 或 [获取文档列表](/zh/api-reference/documents-and-chunks/list-documents) 获取，也可以是此操作上次返回的 `row_version`。新的修订版本生效，或在 Dify 中启用、禁用该文档，也会改变该值，因此应在更新前立即读取。值已过时则返回 `409`，不做任何更改。 minimum: 0 type: integer patch: additionalProperties: true description: >- 要合并到 `user_metadata` 中的键： - 键带有值时，设置该键。 - 键的值为 `null` 时，删除该键。 - 未传入的键保持不变。 每个键对应一个元数据字段名，使用小写蛇形命名（snake case）。该字段必须已存在：先在 Dify 中创建。值必须与字段类型匹配：`string` 类型为字符串，`number` 类型为有限数值，`time` 类型为 UTC 时间戳，例如 `2026-12-01T00:00:00Z`。 使用保留键会返回 `400`：`activeRevision`、`contentHash`、`documentAssetId`、`documentAssetVersion`、`mimeType`、`provenance`、`providerItemId`、`sourceId`、`system`、`systemMetadata`、`tenantId`、`__knowledgeFs`，以及以 `system.`、`provenance.` 或 `__knowledgeFs.` 开头的键。 type: object required: - expectedRowVersion - patch type: object description: >- 规范化后的请求不得超过 131,072 个 UTF-8 字节。参见 [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。 required: true responses: '200': content: application/json: examples: success: summary: 响应示例 value: active: activated_at: '2026-10-20T08:16:05Z' content_hash: >- 4f7c2d9a1b3e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4 created_at: '2026-10-20T08:15:42Z' document_asset_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b document_asset_version: 1 document_id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mime_type: application/pdf revision: 2 size_bytes: 482113 state: active active_revision: 2 created_at: '2026-09-03T10:02:11Z' disabled_at: null disabled_by_subject_id: null enabled: true id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b latest_task: null provider_item_id: null row_version: 5 source_id: null status: ready title: handbook.pdf updated_at: '2026-10-21T02:40:13Z' user_metadata: owner: billing-team product_line: billing review_date: '2027-03-01T00:00:00Z' schema: $ref: '#/components/schemas/KnowledgeBaseDocument' description: 更新后的文档。下次更新时发送其中的 `row_version`；此响应中的 `latest_task` 始终为 `null`。 '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - patch type: missing knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (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: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：请求未通过校验。`violations` 列出每个出错的字段。缺少 `patch` 或 `expectedRowVersion`，或请求体中含有其他任何键，都会返回 `400`。 - `knowledge_fs_invalid_request`：`patch` 使用了保留键，指定了知识库中不存在的元数据字段，或为字段提供了类型错误的值。响应体的 `failure` 中带有错误详情，但不会指出被拒绝的是哪个键。 - `knowledge_fs_invalid_request`：`document_file_id` 不是 UUID。 - `knowledge_fs_invalid_request`：`document_file_id` 格式不正确。 '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: summary: unauthorized 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_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. 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: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 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: logical_document_cas_conflict: summary: knowledge_fs_conflict (stale row version) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: LOGICAL_DOCUMENT_CAS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. parameters: currentRowVersion: 5 expectedRowVersion: 4 retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：`expectedRowVersion` 不是文档当前的 `row_version`，例如有新的修订版本已生效，或另一个更新先写入。`failure.code` 为 `LOGICAL_DOCUMENT_CAS_CONFLICT`，`failure.parameters.currentRowVersion` 中带有当前值。重新读取文档，确认你的更改仍然适用，再使用当前的 `row_version` 重新发送。 '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`：Dify 补上默认值后，请求超过 131,072 个 UTF-8 字节。参见 [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service 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: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。 更新可能已经写入。重新发送前，先通过 [获取文档](/zh/api-reference/documents-and-chunks/get-document) 读取文档并比对 `user_metadata`。如果第一次调用已写入，用旧的 `expectedRowVersion` 重新发送会返回 `409`。 '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` 处理。 components: schemas: KnowledgeBaseDocument: properties: active: allOf: - $ref: '#/components/schemas/KnowledgeBaseDocumentRevision' description: >- 当前生效的修订版本，即知识库当前提供的内容。将其 `revision` 传给 [获取分段列表](/zh/api-reference/documents-and-chunks/list-chunks)，将其 `document_asset_id` 传给 [获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file)。没有生效的修订版本时为 `null`。 nullable: true active_revision: description: 生效修订版本的编号。没有生效的修订版本时为 `null`。 nullable: true type: integer created_at: description: 文档创建时间，ISO 8601 格式。 type: string disabled_at: description: 在 Dify 中禁用该文档的时间，ISO 8601 格式。 nullable: true type: string disabled_by_subject_id: description: 禁用该文档的操作者的内部 ID。调用此 API 时无需使用。 nullable: true type: string enabled: description: >- 在 Dify 中禁用文档后为 `false`。[重新索引文档](/zh/api-reference/documents-and-chunks/re-index-documents) 会跳过已禁用的文档。 type: boolean id: description: 文档 ID。文档内容更新后保持不变。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string latest_task: allOf: - $ref: '#/components/schemas/KnowledgeBaseBackgroundTask' description: >- 为该文档生成修订版本的最新索引任务（`task_kind: document`）。可用其 `id` 调用 [获取文档的索引任务](/zh/api-reference/indexing-tasks/get-document-indexing-task) 跟踪该任务。没有索引任务时为 `null`，在 [更新文档元数据](/zh/api-reference/documents-and-chunks/update-document-metadata) 的响应中始终为 `null`。 nullable: true provider_item_id: description: >- 从数据源导入的文档在该数据源中的条目标识，即发送给 [导入数据源条目](/zh/api-reference/source-syncs-and-imports/import-source-items) 的 `providerItemId`，或网站页面的 `page_id`。 nullable: true type: string row_version: description: >- 变更计数器。调用 [更新文档元数据](/zh/api-reference/documents-and-chunks/update-document-metadata) 时将其作为 `expectedRowVersion` 传入。更新元数据、新修订版本生效、在 Dify 中启用或禁用文档时，该值都会递增。 type: integer source_id: description: 文档的来源数据源。上传的文件为 `null`。 nullable: true type: string status: description: >- `pending`（尚无生效的修订版本）、`ready`（已有修订版本生效）、`failed`（首个修订版本索引失败，且没有生效的修订版本）或 `deleting`。`ready` 的文档在后续修订版本失败时仍保持 `ready`。 type: string title: description: 文档标题。 type: string updated_at: description: 文档最后变更时间，ISO 8601 格式。 type: string user_metadata: additionalProperties: true description: >- 自定义元数据，以元数据字段名为键。可通过 [更新文档元数据](/zh/api-reference/documents-and-chunks/update-document-metadata) 或在 Dify 中修改。 type: object type: object KnowledgeBaseDocumentRevision: properties: activated_at: description: 修订版本生效的时间，ISO 8601 格式。从未生效的修订版本为 `null`。 nullable: true type: string content_hash: description: 内容的 SHA-256 哈希值，十六进制编码。 type: string created_at: description: 修订版本创建时间，ISO 8601 格式。 type: string document_asset_id: description: >- 此修订版本对应的文档文件 ID，可用于 [获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file)。 type: string document_asset_version: description: 创建此修订版本时文档文件的 `version`。 type: integer document_id: description: >- 文档 ID，即 [获取文档](/zh/api-reference/documents-and-chunks/get-document) 中的 `id`。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string mime_type: description: 文档文件的 MIME 类型。 type: string revision: description: >- 修订版本号，从 `1` 开始。用作 [获取分段列表](/zh/api-reference/documents-and-chunks/list-chunks) 的路径参数 `revision`。 type: integer size_bytes: description: 文档文件大小，单位为字节。 type: integer state: description: >- 修订版本正在索引时为 `candidate`，知识库当前提供的修订版本为 `active`，有更新的修订版本生效后为 `superseded`，索引失败时为 `failed`。 type: string type: object KnowledgeBaseBackgroundTask: properties: can_cancel: description: >- 当前能否取消该任务。`task_kind: document` 的任务可用 `id` 调用 [取消索引任务](/zh/api-reference/indexing-tasks/cancel-indexing-task) 取消。即使 `can_cancel` 为 `true`，此 API 也没有取消批量任务的操作。 type: boolean can_retry: description: >- 当前能否重试该任务。`task_kind: document` 的任务可用 `id` 调用 [重试索引任务](/zh/api-reference/indexing-tasks/retry-indexing-task) 重试。该操作只接受 `failed` 或 `canceled` 的任务，但语义增强失败的 `completed` 索引任务，其 `can_retry` 也为 `true`。 type: boolean completed_at: description: 任务结束时间，ISO 8601 格式。运行期间为 `null`。 nullable: true type: string created_at: description: 任务创建时间，ISO 8601 格式。 type: string document_id: description: 索引任务的文档 ID。批量任务只有一个文档时才设置此字段。 nullable: true type: string document_revision: description: 索引任务构建的修订版本。 nullable: true type: integer document_title: description: 文档标题，仅当批量任务只有一个文档时设置。 nullable: true type: string error_code: description: '`state` 为 `failed` 时的错误码。' nullable: true type: string error_message: description: '`error_code` 对应的错误消息，可能与 `failure.message` 不同。' nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: '`state` 为 `failed` 时的错误详情，否则为 `null`。' nullable: true failures: description: 批量任务中每个失败的文档对应一项。其他类型的任务为 `null`。 items: properties: document_id: description: 文档 ID。 type: string document_title: description: 文档标题。 nullable: true type: string error_code: description: 失败的错误码。 type: string error_message: description: '`error_code` 对应的错误消息。' type: string failure: $ref: '#/components/schemas/KnowledgeBaseErrorDetails' job_id: description: 该文档对应任务的 ID（如有）。 nullable: true type: string type: object nullable: true type: array id: description: >- 任务 ID：`task_kind: document` 时为索引任务 ID，`document_bulk` 时为批量任务 ID，`source` 时为数据源运行 ID。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string operation: description: >- 任务执行的操作： - `document_processing`：索引任务。 - `document_reindex`、`document_upload`、`document_delete`：批量任务。批量上传和批量删除来自 Dify，通过此 API 发起的删除则会创建删除作业。 - `source_sync`、`source_crawl_preview`、`source_crawl_import`、`source_online_document_import`、`source_online_drive_import`：数据源运行。 type: string progress_completed: description: 已完成的项数。索引任务按其文档计，批量任务按其中的各个文档计，数据源运行按其条目计。 type: integer progress_failed: description: 失败的项数，计数方式同 `progress_completed`。 type: integer progress_percent: description: 进度，取值 0～100。索引任务的进度取决于任务所处的阶段。 type: integer progress_total: description: 任务中的总项数，计数方式同 `progress_completed`。索引任务为 `1`。 type: integer semantic_enrichment: allOf: - $ref: '#/components/schemas/KnowledgeBaseSemanticEnrichment' description: 索引任务内容的知识图谱构建状态。深度检索和研究检索会沿知识图谱进行。其他类型的任务为 `null`。 nullable: true source_id: description: 数据源运行所属的数据源。 nullable: true type: string source_title: description: 数据源运行所属数据源的名称。仅在未传 `task_ids` 列出任务时设置。 nullable: true type: string state: description: >- `queued`、`running`、`completed`、`failed` 或 `canceled`，由任务自身的状态映射而来： - 索引任务一经发布即为 `completed`，即使其语义增强仍在运行。 - 等待选择页面的抓取预览为 `completed`。 要查看确切状态，用 [获取索引任务](/zh/api-reference/indexing-tasks/get-indexing-task) 读取索引任务，用 [获取数据源运行](/zh/api-reference/source-syncs-and-imports/get-source-run) 读取数据源运行。 type: string task_kind: description: '`document`（索引任务）、`document_bulk`（批量任务）或 `source`（数据源运行）。' type: string updated_at: description: 任务最后变更时间，ISO 8601 格式。 type: string type: object KnowledgeBaseErrorDetails: properties: action: description: >- 建议的下一步操作（如有）：`configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload` 或 `retry`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string category: description: >- 失败类别：`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout` 或 `validation`。 type: string code: description: >- 稳定的错误码，采用大写蛇形命名，例如 `KNOWLEDGE_FS_CONFLICT` 或 `SOURCE_CREDENTIAL_TEST_FAILED`。 type: string message: description: 错误码或失败类别对应的公开消息。不会暴露提供商的错误详情。 type: string parameters: additionalProperties: true description: >- 描述失败细节的值，最多 8 个，键取自 `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds` 和 `status`。没有时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: object retryPolicy: description: >- 重试是否有用：`automatic`（服务会自动重试）、`manual`（需自行重试）、`after_configuration`（先在 Dify 中修正知识库配置）或 `never`（需修改请求）。 type: string stage: description: >- 失败所在的阶段，例如 `query_generation` 或 `credential-test`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string traceId: description: 联系管理员时需提供的参考编号。在包含失败详情的成功响应中可能为 `null`，在 HTTP 错误响应体中可能不出现。 nullable: true type: string type: object KnowledgeBaseSemanticEnrichment: properties: error_code: description: '`state` 为 `failed` 时的错误码。' nullable: true type: string error_message: description: '`error_code` 对应的错误消息，可能与 `failure.message` 不同。' nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: '`state` 为 `failed` 时的错误详情，否则为 `null`。' nullable: true nodes_completed: description: 已构建的知识图谱节点数：`state` 变为 `ready` 之前为 `0`，之后与 `nodes_total` 相同。 type: integer nodes_total: description: 需构建的知识图谱节点数。确定之前为 `null`。 nullable: true type: integer provider_calls: description: 目前已发起的模型调用次数。 nullable: true type: integer provider_calls_maximum: description: 构建知识图谱最多可发起的模型调用次数。 nullable: true type: integer state: description: >- `not_scheduled`、`pending`、`running`、`ready`、`failed` 或 `disabled`。索引任务发布修订版本后，知识图谱构建仍可能处于 `pending` 或 `running`。 type: string updated_at: description: 语义增强最后变更时间，ISO 8601 格式。 nullable: true 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.