{
  "openapi": "3.0.1",
  "info": {
    "title": "知识库 API",
    "description": "用于管理知识库、文档、分段、元数据和标签的 API，包括创建、检索和配置操作。**注意：**单个知识库 API 密钥有权操作同一账户下所有可见的知识库。请注意数据安全。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{apiBaseUrl}",
      "description": "Knowledge API 的基础 URL。",
      "variables": {
        "apiBaseUrl": {
          "default": "https://api.dify.ai/v1",
          "description": "API 的实际基础 URL"
        }
      }
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "知识库",
      "description": "用于管理知识库的操作，包括创建、配置和检索。"
    },
    {
      "name": "文档",
      "description": "用于在知识库中创建、更新和管理文档的操作。"
    },
    {
      "name": "分段",
      "description": "用于管理分段和子分段的操作。"
    },
    {
      "name": "元数据",
      "description": "用于管理知识库元数据字段和文档元数据值的操作。"
    },
    {
      "name": "标签",
      "description": "用于管理知识库标签和标签绑定的操作。"
    },
    {
      "name": "模型",
      "description": "用于获取可用模型的操作。"
    },
    {
      "name": "知识流水线",
      "description": "用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。"
    }
  ],
  "paths": {
    "/datasets": {
      "post": {
        "tags": [
          "知识库"
        ],
        "summary": "创建空知识库",
        "description": "创建新的空知识库。创建后，使用 [从文本创建文档](/api-reference/文档/从文本创建文档) 或 [从文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。",
        "operationId": "createDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40,
                    "description": "知识库名称。"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 400,
                    "default": "",
                    "description": "知识库描述。"
                  },
                  "indexing_technique": {
                    "type": "string",
                    "enum": [
                      "high_quality",
                      "economy"
                    ],
                    "nullable": true,
                    "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
                  },
                  "permission": {
                    "type": "string",
                    "enum": [
                      "only_me",
                      "all_team_members",
                      "partial_members"
                    ],
                    "default": "only_me",
                    "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。"
                  },
                  "provider": {
                    "type": "string",
                    "enum": [
                      "vendor",
                      "external"
                    ],
                    "default": "vendor",
                    "description": "`vendor` 为内部知识库，`external` 为外部知识库。"
                  },
                  "embedding_model": {
                    "type": "string",
                    "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
                  },
                  "embedding_model_provider": {
                    "type": "string",
                    "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
                  },
                  "retrieval_model": {
                    "$ref": "#/components/schemas/RetrievalModel",
                    "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
                  },
                  "external_knowledge_api_id": {
                    "type": "string",
                    "description": "外部知识库 API 连接的 ID。"
                  },
                  "external_knowledge_id": {
                    "type": "string",
                    "description": "外部知识库的 ID。"
                  },
                  "summary_index_setting": {
                    "type": "object",
                    "nullable": true,
                    "description": "摘要索引配置。",
                    "properties": {
                      "enable": {
                        "type": "boolean",
                        "description": "是否启用摘要索引。"
                      },
                      "model_name": {
                        "type": "string",
                        "description": "用于生成摘要的模型名称。"
                      },
                      "model_provider_name": {
                        "type": "string",
                        "description": "摘要生成模型的提供商。"
                      },
                      "summary_prompt": {
                        "type": "string",
                        "description": "用于摘要生成的自定义提示词模板。"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "知识库创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
                      "name": "Product Documentation",
                      "description": "产品 API 技术文档",
                      "provider": "vendor",
                      "permission": "only_me",
                      "data_source_type": null,
                      "indexing_technique": "high_quality",
                      "app_count": 0,
                      "document_count": 0,
                      "word_count": 0,
                      "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "author_name": "admin",
                      "created_at": 1741267200,
                      "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "updated_at": 1741267200,
                      "embedding_model": "text-embedding-3-small",
                      "embedding_model_provider": "openai",
                      "embedding_available": true,
                      "retrieval_model_dict": {
                        "search_method": "semantic_search",
                        "reranking_enable": false,
                        "reranking_mode": null,
                        "reranking_model": {
                          "reranking_provider_name": "",
                          "reranking_model_name": ""
                        },
                        "weights": null,
                        "top_k": 3,
                        "score_threshold_enabled": false,
                        "score_threshold": null
                      },
                      "tags": [],
                      "doc_form": "text_model",
                      "external_knowledge_info": null,
                      "external_retrieval_model": null,
                      "doc_metadata": [],
                      "built_in_field_enabled": true,
                      "pipeline_id": null,
                      "runtime_mode": null,
                      "chunk_structure": null,
                      "icon_info": null,
                      "summary_index_setting": null,
                      "is_published": false,
                      "total_documents": 0,
                      "total_available_documents": 0,
                      "enable_api": true,
                      "is_multimodal": false
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`dataset_name_duplicate` : 知识库名称已存在，请修改名称。",
            "content": {
              "application/json": {
                "examples": {
                  "dataset_name_duplicate": {
                    "summary": "dataset_name_duplicate",
                    "value": {
                      "status": 409,
                      "code": "dataset_name_duplicate",
                      "message": "The dataset name already exists. Please modify your dataset name."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "知识库"
        ],
        "summary": "获取知识库列表",
        "description": "返回知识库的分页列表。支持按关键词和标签筛选。",
        "operationId": "listDatasets",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "要获取的页码。"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "每页条目数。"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "按名称筛选的搜索关键词。"
          },
          {
            "name": "include_all",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "是否包含所有知识库，无论权限如何。"
          },
          {
            "name": "tag_ids",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true,
            "description": "用于筛选的标签 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "知识库列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "知识库对象数组。",
                      "items": {
                        "$ref": "#/components/schemas/Dataset"
                      }
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "下一页是否还有更多项目。"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "每页条目数。"
                    },
                    "total": {
                      "type": "integer",
                      "description": "匹配条目的总数。"
                    },
                    "page": {
                      "type": "integer",
                      "description": "当前页码。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
                          "name": "Product Documentation",
                          "description": "产品 API 技术文档",
                          "provider": "vendor",
                          "permission": "only_me",
                          "data_source_type": null,
                          "indexing_technique": "high_quality",
                          "app_count": 0,
                          "document_count": 0,
                          "word_count": 0,
                          "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "author_name": "admin",
                          "created_at": 1741267200,
                          "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "updated_at": 1741267200,
                          "embedding_model": "text-embedding-3-small",
                          "embedding_model_provider": "openai",
                          "embedding_available": true,
                          "retrieval_model_dict": {
                            "search_method": "semantic_search",
                            "reranking_enable": false,
                            "reranking_mode": null,
                            "reranking_model": {
                              "reranking_provider_name": "",
                              "reranking_model_name": ""
                            },
                            "weights": null,
                            "top_k": 3,
                            "score_threshold_enabled": false,
                            "score_threshold": null
                          },
                          "tags": [],
                          "doc_form": "text_model",
                          "external_knowledge_info": null,
                          "external_retrieval_model": null,
                          "doc_metadata": [],
                          "built_in_field_enabled": true,
                          "pipeline_id": null,
                          "runtime_mode": null,
                          "chunk_structure": null,
                          "icon_info": null,
                          "summary_index_setting": null,
                          "is_published": false,
                          "total_documents": 0,
                          "total_available_documents": 0,
                          "enable_api": true,
                          "is_multimodal": false
                        }
                      ],
                      "has_more": false,
                      "limit": 20,
                      "total": 1,
                      "page": 1
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}": {
      "get": {
        "tags": [
          "知识库"
        ],
        "summary": "获取知识库详情",
        "description": "获取指定知识库的详细信息，包括嵌入模型、检索配置和文档统计信息。",
        "operationId": "getDatasetDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "知识库详情。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
                      "name": "Product Documentation",
                      "description": "产品 API 技术文档",
                      "provider": "vendor",
                      "permission": "only_me",
                      "data_source_type": null,
                      "indexing_technique": "high_quality",
                      "app_count": 0,
                      "document_count": 0,
                      "word_count": 0,
                      "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "author_name": "admin",
                      "created_at": 1741267200,
                      "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "updated_at": 1741267200,
                      "embedding_model": "text-embedding-3-small",
                      "embedding_model_provider": "openai",
                      "embedding_available": true,
                      "retrieval_model_dict": {
                        "search_method": "semantic_search",
                        "reranking_enable": false,
                        "reranking_mode": null,
                        "reranking_model": {
                          "reranking_provider_name": "",
                          "reranking_model_name": ""
                        },
                        "weights": null,
                        "top_k": 3,
                        "score_threshold_enabled": false,
                        "score_threshold": null
                      },
                      "tags": [],
                      "doc_form": "text_model",
                      "external_knowledge_info": null,
                      "external_retrieval_model": null,
                      "doc_metadata": [],
                      "built_in_field_enabled": true,
                      "pipeline_id": null,
                      "runtime_mode": null,
                      "chunk_structure": null,
                      "icon_info": null,
                      "summary_index_setting": null,
                      "is_published": false,
                      "total_documents": 0,
                      "total_available_documents": 0,
                      "enable_api": true,
                      "is_multimodal": false
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 访问此知识库的权限不足。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Insufficient permissions to access this knowledge base."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "知识库"
        ],
        "summary": "更新知识库",
        "description": "更新现有知识库的名称、描述、权限或检索设置。仅更新请求体中提供的字段。",
        "operationId": "updateDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40,
                    "description": "知识库名称。"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 400,
                    "description": "知识库描述。"
                  },
                  "indexing_technique": {
                    "type": "string",
                    "enum": [
                      "high_quality",
                      "economy"
                    ],
                    "nullable": true,
                    "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
                  },
                  "permission": {
                    "type": "string",
                    "enum": [
                      "only_me",
                      "all_team_members",
                      "partial_members"
                    ],
                    "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。"
                  },
                  "embedding_model": {
                    "type": "string",
                    "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
                  },
                  "embedding_model_provider": {
                    "type": "string",
                    "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
                  },
                  "retrieval_model": {
                    "$ref": "#/components/schemas/RetrievalModel",
                    "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
                  },
                  "partial_member_list": {
                    "type": "array",
                    "description": "当 `permission` 为 `partial_members` 时有访问权限的团队成员列表。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "user_id": {
                          "type": "string",
                          "description": "要授予访问权限的团队成员 ID。"
                        }
                      }
                    }
                  },
                  "external_retrieval_model": {
                    "type": "object",
                    "description": "外部知识库的检索设置。",
                    "properties": {
                      "top_k": {
                        "type": "integer",
                        "description": "返回的最大结果数。"
                      },
                      "score_threshold": {
                        "type": "number",
                        "description": "用于过滤结果的最低相关性分数阈值。"
                      },
                      "score_threshold_enabled": {
                        "type": "boolean",
                        "description": "是否启用分数阈值过滤。"
                      }
                    }
                  },
                  "external_knowledge_id": {
                    "type": "string",
                    "description": "外部知识库的 ID。"
                  },
                  "external_knowledge_api_id": {
                    "type": "string",
                    "description": "外部知识库 API 连接的 ID。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "知识库更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
                      "name": "Product Documentation",
                      "description": "产品 API 技术文档",
                      "provider": "vendor",
                      "permission": "only_me",
                      "data_source_type": null,
                      "indexing_technique": "high_quality",
                      "app_count": 0,
                      "document_count": 0,
                      "word_count": 0,
                      "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "author_name": "admin",
                      "created_at": 1741267200,
                      "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "updated_at": 1741267200,
                      "embedding_model": "text-embedding-3-small",
                      "embedding_model_provider": "openai",
                      "embedding_available": true,
                      "retrieval_model_dict": {
                        "search_method": "semantic_search",
                        "reranking_enable": false,
                        "reranking_mode": null,
                        "reranking_model": {
                          "reranking_provider_name": "",
                          "reranking_model_name": ""
                        },
                        "weights": null,
                        "top_k": 3,
                        "score_threshold_enabled": false,
                        "score_threshold": null
                      },
                      "tags": [],
                      "doc_form": "text_model",
                      "external_knowledge_info": null,
                      "external_retrieval_model": null,
                      "doc_metadata": [],
                      "built_in_field_enabled": true,
                      "pipeline_id": null,
                      "runtime_mode": null,
                      "chunk_structure": null,
                      "icon_info": null,
                      "summary_index_setting": null,
                      "is_published": false,
                      "total_documents": 0,
                      "total_available_documents": 0,
                      "enable_api": true,
                      "is_multimodal": false
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 访问此知识库的权限不足。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Insufficient permissions to access this knowledge base."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "知识库"
        ],
        "summary": "删除知识库",
        "description": "永久删除知识库及其所有文档。该知识库不能被任何应用正在使用。",
        "operationId": "deleteDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "responses": {
          "204": {
            "description": "Success."
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`dataset_in_use` : 该知识库正在被一些应用使用。请先从应用中移除后再删除。",
            "content": {
              "application/json": {
                "examples": {
                  "dataset_in_use": {
                    "summary": "dataset_in_use",
                    "value": {
                      "status": 409,
                      "code": "dataset_in_use",
                      "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/document/create-by-text": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "从文本创建文档",
        "description": "通过纯文本内容创建文档。文档将异步处理——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
        "operationId": "createDocumentFromText",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "text"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "文档名称。"
                  },
                  "text": {
                    "type": "string",
                    "description": "文档文本内容。"
                  },
                  "indexing_technique": {
                    "type": "string",
                    "enum": [
                      "high_quality",
                      "economy"
                    ],
                    "description": "向知识库添加首个文档时必填。后续文档如果省略此字段，将继承知识库的索引方式。`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
                  },
                  "doc_form": {
                    "type": "string",
                    "enum": [
                      "text_model",
                      "hierarchical_model",
                      "qa_model"
                    ],
                    "default": "text_model",
                    "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。"
                  },
                  "doc_language": {
                    "type": "string",
                    "default": "English",
                    "description": "用于处理优化的文档语言。"
                  },
                  "process_rule": {
                    "type": "object",
                    "description": "分块处理规则。",
                    "required": [
                      "mode"
                    ],
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "automatic",
                          "custom",
                          "hierarchical"
                        ],
                        "description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。"
                      },
                      "rules": {
                        "type": "object",
                        "properties": {
                          "pre_processing_rules": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "enum": [
                                    "remove_stopwords",
                                    "remove_extra_spaces",
                                    "remove_urls_emails"
                                  ],
                                  "description": "规则标识符。"
                                },
                                "enabled": {
                                  "type": "boolean",
                                  "description": "该预处理规则是否启用。"
                                }
                              }
                            }
                          },
                          "segmentation": {
                            "type": "object",
                            "properties": {
                              "separator": {
                                "type": "string",
                                "default": "\n",
                                "description": "用于拆分文本的自定义分隔符。"
                              },
                              "max_tokens": {
                                "type": "integer",
                                "description": "每个分段的最大令牌数。"
                              },
                              "chunk_overlap": {
                                "type": "integer",
                                "default": 0,
                                "description": "分段之间的令牌重叠数。"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "retrieval_model": {
                    "$ref": "#/components/schemas/RetrievalModel",
                    "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
                  },
                  "embedding_model": {
                    "type": "string",
                    "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
                  },
                  "embedding_model_provider": {
                    "type": "string",
                    "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
                  },
                  "original_document_id": {
                    "type": "string",
                    "description": "用于版本控制的原始文档 ID。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/Document"
                    },
                    "batch": {
                      "type": "string",
                      "description": "用于跟踪索引进度的批次 ID。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "document": {
                        "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "position": 1,
                        "data_source_type": "upload_file",
                        "data_source_info": {
                          "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        },
                        "data_source_detail_dict": {
                          "upload_file": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "name": "guide.txt",
                            "size": 2048,
                            "extension": "txt",
                            "mime_type": "text/plain",
                            "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                            "created_at": 1741267200
                          }
                        },
                        "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                        "name": "guide.txt",
                        "created_from": "api",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "tokens": 0,
                        "indexing_status": "indexing",
                        "error": null,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "archived": false,
                        "display_status": "indexing",
                        "word_count": 0,
                        "hit_count": 0,
                        "doc_form": "text_model",
                        "doc_metadata": [],
                        "summary_index_status": null,
                        "need_summary": false
                      },
                      "batch": "20250306150245647595"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在。/ indexing_technique 为必填项。",
            "content": {
              "application/json": {
                "examples": {
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "invalid_param_dataset": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Dataset does not exist."
                    }
                  },
                  "invalid_param_indexing": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "indexing_technique is required."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/document/create-by-file": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "从文件创建文档",
        "description": "通过上传文件创建文档。支持常见文档格式（PDF、TXT、DOCX 等）。处理过程为异步——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
        "operationId": "createDocumentFromFile",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "要上传的文件。"
                  },
                  "data": {
                    "type": "string",
                    "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。",
                    "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/Document"
                    },
                    "batch": {
                      "type": "string",
                      "description": "用于跟踪索引进度的批次 ID。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "document": {
                        "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "position": 1,
                        "data_source_type": "upload_file",
                        "data_source_info": {
                          "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        },
                        "data_source_detail_dict": {
                          "upload_file": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "name": "guide.txt",
                            "size": 2048,
                            "extension": "txt",
                            "mime_type": "text/plain",
                            "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                            "created_at": 1741267200
                          }
                        },
                        "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                        "name": "guide.txt",
                        "created_from": "api",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "tokens": 0,
                        "indexing_status": "indexing",
                        "error": null,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "archived": false,
                        "display_status": "indexing",
                        "word_count": 0,
                        "hit_count": 0,
                        "doc_form": "text_model",
                        "doc_metadata": [],
                        "summary_index_status": null,
                        "need_summary": false
                      },
                      "batch": "20250306150245647595"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `no_file_uploaded` : 请上传文件。\n- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在、不支持外部数据集、文件过大、不支持的文件类型或缺少必填字段。",
            "content": {
              "application/json": {
                "examples": {
                  "no_file_uploaded": {
                    "summary": "no_file_uploaded",
                    "value": {
                      "status": 400,
                      "code": "no_file_uploaded",
                      "message": "Please upload your file."
                    }
                  },
                  "too_many_files": {
                    "summary": "too_many_files",
                    "value": {
                      "status": 400,
                      "code": "too_many_files",
                      "message": "Only one file is allowed."
                    }
                  },
                  "filename_not_exists_error": {
                    "summary": "filename_not_exists_error",
                    "value": {
                      "status": 400,
                      "code": "filename_not_exists_error",
                      "message": "The specified filename does not exist."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "invalid_param_dataset": {
                    "summary": "invalid_param (dataset)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Dataset does not exist."
                    }
                  },
                  "invalid_param_external": {
                    "summary": "invalid_param (external)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "External datasets are not supported."
                    }
                  },
                  "invalid_param_file_too_large": {
                    "summary": "invalid_param (file_too_large)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "File size exceeded."
                    }
                  },
                  "invalid_param_unsupported_file_type": {
                    "summary": "invalid_param (unsupported_file_type)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "File type not allowed."
                    }
                  },
                  "invalid_param_indexing": {
                    "summary": "invalid_param (indexing_technique)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "indexing_technique is required."
                    }
                  },
                  "invalid_param_process_rule": {
                    "summary": "invalid_param (process_rule)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "process_rule is required."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取知识库的文档列表",
        "description": "返回知识库中的文档分页列表。支持按关键词和索引状态进行筛选。",
        "operationId": "listDocuments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "要获取的页码。"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "每页的项目数量。服务器上限为 `100`。"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "按文档名称筛选的搜索关键词。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "queuing",
                "indexing",
                "paused",
                "error",
                "available",
                "disabled",
                "archived"
              ]
            },
            "description": "按显示状态筛选。"
          }
        ],
        "responses": {
          "200": {
            "description": "文档列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "知识库对象数组。",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "下一页是否还有更多项目。"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "每页条目数。"
                    },
                    "total": {
                      "type": "integer",
                      "description": "匹配条目的总数。"
                    },
                    "page": {
                      "type": "integer",
                      "description": "当前页码。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                          "position": 1,
                          "data_source_type": "upload_file",
                          "data_source_info": {
                            "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                          },
                          "data_source_detail_dict": {
                            "upload_file": {
                              "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                              "name": "guide.txt",
                              "size": 2048,
                              "extension": "txt",
                              "mime_type": "text/plain",
                              "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                              "created_at": 1741267200
                            }
                          },
                          "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                          "name": "guide.txt",
                          "created_from": "api",
                          "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "created_at": 1741267200,
                          "tokens": 512,
                          "indexing_status": "completed",
                          "error": null,
                          "enabled": true,
                          "disabled_at": null,
                          "disabled_by": null,
                          "archived": false,
                          "display_status": "available",
                          "word_count": 350,
                          "hit_count": 0,
                          "doc_form": "text_model",
                          "doc_metadata": [],
                          "summary_index_status": null,
                          "need_summary": false
                        }
                      ],
                      "has_more": false,
                      "limit": 20,
                      "total": 1,
                      "page": 1
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 知识库未找到。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取文档详情",
        "description": "获取指定文档的详细信息，包括索引状态、元数据和处理统计信息。",
        "operationId": "getDocumentDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "metadata",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "only",
                "without"
              ],
              "default": "all"
            },
            "description": "`all` 返回所有字段（包括元数据）。`only` 仅返回 `id`、`doc_type` 和 `doc_metadata`。`without` 返回除 `doc_metadata` 外的所有字段。"
          }
        ],
        "responses": {
          "200": {
            "description": "文档详情。响应结构根据 `metadata` 查询参数的不同而变化。当 `metadata` 为 `only` 时，仅返回 `id`、`doc_type` 和 `doc_metadata`。当 `metadata` 为 `without` 时，省略 `doc_type` 和 `doc_metadata`。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "文档标识符。"
                    },
                    "position": {
                      "type": "integer",
                      "description": "在知识库中的位置索引。"
                    },
                    "data_source_type": {
                      "type": "string",
                      "description": "文档的上传方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。"
                    },
                    "data_source_info": {
                      "type": "object",
                      "description": "原始数据源信息。"
                    },
                    "dataset_process_rule_id": {
                      "type": "string",
                      "description": "应用于该文档的处理规则 ID。"
                    },
                    "dataset_process_rule": {
                      "type": "object",
                      "description": "知识库级别的处理规则配置。"
                    },
                    "document_process_rule": {
                      "type": "object",
                      "description": "文档级别的处理规则配置。"
                    },
                    "name": {
                      "type": "string",
                      "description": "文档名称。"
                    },
                    "created_from": {
                      "type": "string",
                      "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。"
                    },
                    "created_by": {
                      "type": "string",
                      "description": "创建该文档的用户 ID。"
                    },
                    "created_at": {
                      "type": "number",
                      "description": "文档创建的 Unix 时间戳。"
                    },
                    "tokens": {
                      "type": "integer",
                      "description": "文档中的令牌数。"
                    },
                    "indexing_status": {
                      "type": "string",
                      "description": "当前索引状态，例如 `waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。"
                    },
                    "error": {
                      "type": "string",
                      "nullable": true,
                      "description": "索引失败时的错误消息，否则为 `null`。"
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "该文档是否启用检索。"
                    },
                    "disabled_at": {
                      "type": "number",
                      "nullable": true,
                      "description": "文档被禁用的 Unix 时间戳，启用时为 `null`。"
                    },
                    "disabled_by": {
                      "type": "string",
                      "nullable": true,
                      "description": "禁用该文档的用户 ID，启用时为 `null`。"
                    },
                    "archived": {
                      "type": "boolean",
                      "description": "文档是否已归档。"
                    },
                    "display_status": {
                      "type": "string",
                      "description": "适合 UI 显示的索引状态。"
                    },
                    "word_count": {
                      "type": "integer",
                      "description": "文档的总字数。"
                    },
                    "hit_count": {
                      "type": "integer",
                      "description": "该文档被检索的次数。"
                    },
                    "doc_form": {
                      "type": "string",
                      "description": "文档分块模式。`text_model` 表示标准文本，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对。"
                    },
                    "doc_language": {
                      "type": "string",
                      "description": "文档内容的语言。"
                    },
                    "doc_type": {
                      "type": "string",
                      "nullable": true,
                      "description": "文档类型分类，未设置时为 `null`。"
                    },
                    "doc_metadata": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "元数据字段标识符。"
                          },
                          "name": {
                            "type": "string",
                            "description": "元数据字段名称。"
                          },
                          "type": {
                            "type": "string",
                            "description": "元数据字段类型。"
                          },
                          "value": {
                            "type": "string",
                            "description": "此文档的元数据字段值。"
                          }
                        }
                      },
                      "description": "此文档的自定义元数据键值对。"
                    },
                    "completed_at": {
                      "type": "number",
                      "nullable": true,
                      "description": "处理完成的 Unix 时间戳，尚未完成时为 `null`。"
                    },
                    "updated_at": {
                      "type": "number",
                      "nullable": true,
                      "description": "最后更新的 Unix 时间戳，从未更新时为 `null`。"
                    },
                    "indexing_latency": {
                      "type": "number",
                      "nullable": true,
                      "description": "索引耗时（秒），未完成时为 `null`。"
                    },
                    "segment_count": {
                      "type": "integer",
                      "description": "文档中的分段数。"
                    },
                    "average_segment_length": {
                      "type": "number",
                      "description": "分段的平均字符长度。"
                    },
                    "summary_index_status": {
                      "type": "string",
                      "nullable": true,
                      "description": "摘要索引的状态，未启用摘要索引时为 `null`。"
                    },
                    "need_summary": {
                      "type": "boolean",
                      "description": "该文档是否需要生成摘要。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                      "position": 1,
                      "data_source_type": "upload_file",
                      "data_source_info": {
                        "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      },
                      "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                      "dataset_process_rule": {
                        "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                        "mode": "custom"
                      },
                      "document_process_rule": {
                        "mode": "custom",
                        "rules": {
                          "pre_processing_rules": [],
                          "segmentation": {
                            "separator": "###",
                            "max_tokens": 500,
                            "chunk_overlap": 50
                          }
                        }
                      },
                      "name": "guide.txt",
                      "created_from": "api",
                      "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "created_at": 1741267200,
                      "tokens": 512,
                      "indexing_status": "completed",
                      "error": null,
                      "enabled": true,
                      "disabled_at": null,
                      "disabled_by": null,
                      "archived": false,
                      "display_status": "available",
                      "word_count": 350,
                      "hit_count": 0,
                      "doc_form": "text_model",
                      "doc_language": "English",
                      "doc_type": null,
                      "doc_metadata": [],
                      "completed_at": 1741267260,
                      "updated_at": 1741267260,
                      "indexing_latency": 60.0,
                      "segment_count": 5,
                      "average_segment_length": 70.0,
                      "summary_index_status": null,
                      "need_summary": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`invalid_metadata` : 指定键的元数据值无效。",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_metadata": {
                    "summary": "invalid_metadata",
                    "value": {
                      "status": 400,
                      "code": "invalid_metadata",
                      "message": "Invalid metadata value: {metadata_key}"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 没有权限。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "No permission."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到文档。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document not found."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "文档"
        ],
        "summary": "删除文档",
        "description": "从知识库中永久删除文档及其所有分段。",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          }
        ],
        "responses": {
          "204": {
            "description": "Success."
          },
          "400": {
            "description": "`document_indexing` : 索引期间无法删除文档。",
            "content": {
              "application/json": {
                "examples": {
                  "document_indexing": {
                    "summary": "document_indexing",
                    "value": {
                      "status": 400,
                      "code": "document_indexing",
                      "message": "Cannot delete document during indexing."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`archived_document_immutable` : 已归档的文档不可编辑。",
            "content": {
              "application/json": {
                "examples": {
                  "archived_document_immutable": {
                    "summary": "archived_document_immutable",
                    "value": {
                      "status": 403,
                      "code": "archived_document_immutable",
                      "message": "The archived document is not editable."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 文档不存在。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document Not Exists."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/download": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "下载文档",
        "description": "获取文档原始上传文件的签名下载 URL。",
        "operationId": "downloadDocumentZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          }
        ],
        "responses": {
          "200": {
            "description": "下载 URL 生成成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "用于下载原始上传文件的签名 URL。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 没有权限访问此文档。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "No permission."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到文档。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{batch}/indexing-status": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取文档嵌入状态（进度）",
        "description": "检查批量文档的索引进度。返回每个文档的当前处理阶段和分段完成计数。请轮询此接口直到 `indexing_status` 变为 `completed` 或 `error`。状态按以下顺序推进：`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。",
        "operationId": "getDocumentIndexingStatus",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "batch",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "创建文档时返回的批次 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "批次中文档的索引状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "文档标识符。"
                          },
                          "indexing_status": {
                            "type": "string",
                            "description": "当前索引状态：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed` 或 `error`。"
                          },
                          "processing_started_at": {
                            "type": "number",
                            "description": "处理开始的 Unix 时间戳。"
                          },
                          "parsing_completed_at": {
                            "type": "number",
                            "description": "解析完成的 Unix 时间戳。"
                          },
                          "cleaning_completed_at": {
                            "type": "number",
                            "description": "清洗完成的 Unix 时间戳。"
                          },
                          "splitting_completed_at": {
                            "type": "number",
                            "description": "拆分完成的 Unix 时间戳。"
                          },
                          "completed_at": {
                            "type": "number",
                            "description": "索引完成的 Unix 时间戳。"
                          },
                          "paused_at": {
                            "type": "number",
                            "nullable": true,
                            "description": "索引暂停的时间戳。未暂停时为 `null`。"
                          },
                          "error": {
                            "type": "string",
                            "nullable": true,
                            "description": "索引失败时的错误信息。无错误时为 `null`。"
                          },
                          "stopped_at": {
                            "type": "number",
                            "nullable": true,
                            "description": "索引停止的时间戳。未停止时为 `null`。"
                          },
                          "completed_segments": {
                            "type": "integer",
                            "description": "已索引的分段数。"
                          },
                          "total_segments": {
                            "type": "integer",
                            "description": "待索引的分段总数。"
                          }
                        }
                      },
                      "description": "索引状态条目列表。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                          "indexing_status": "completed",
                          "processing_started_at": 1741267200,
                          "parsing_completed_at": 1741267200,
                          "cleaning_completed_at": 1741267200,
                          "splitting_completed_at": 1741267200,
                          "completed_at": 1741267200,
                          "paused_at": null,
                          "error": null,
                          "stopped_at": null,
                          "completed_segments": 5,
                          "total_segments": 5
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 知识库未找到。/ 文档未找到。",
            "content": {
              "application/json": {
                "examples": {
                  "dataset_not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  },
                  "documents_not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Documents not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/update-by-text": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "用文本更新文档",
        "description": "更新现有文档的文本内容、名称或处理配置。内容变更时将重新触发索引——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
        "operationId": "updateDocumentByText",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "文档名称。当提供 `text` 时必填。"
                  },
                  "text": {
                    "type": "string",
                    "description": "文档文本内容。"
                  },
                  "process_rule": {
                    "type": "object",
                    "description": "分块处理规则。",
                    "required": [
                      "mode"
                    ],
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "automatic",
                          "custom",
                          "hierarchical"
                        ],
                        "description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。"
                      },
                      "rules": {
                        "type": "object",
                        "properties": {
                          "pre_processing_rules": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "enum": [
                                    "remove_stopwords",
                                    "remove_extra_spaces",
                                    "remove_urls_emails"
                                  ],
                                  "description": "规则标识符。"
                                },
                                "enabled": {
                                  "type": "boolean",
                                  "description": "该预处理规则是否启用。"
                                }
                              }
                            }
                          },
                          "segmentation": {
                            "type": "object",
                            "properties": {
                              "separator": {
                                "type": "string",
                                "default": "\n",
                                "description": "用于拆分文本的自定义分隔符。"
                              },
                              "max_tokens": {
                                "type": "integer",
                                "description": "每个分段的最大令牌数。"
                              },
                              "chunk_overlap": {
                                "type": "integer",
                                "default": 0,
                                "description": "分段之间的令牌重叠数。"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "doc_form": {
                    "type": "string",
                    "enum": [
                      "text_model",
                      "hierarchical_model",
                      "qa_model"
                    ],
                    "default": "text_model",
                    "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。"
                  },
                  "doc_language": {
                    "type": "string",
                    "default": "English",
                    "description": "用于处理优化的文档语言。"
                  },
                  "retrieval_model": {
                    "$ref": "#/components/schemas/RetrievalModel",
                    "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/Document"
                    },
                    "batch": {
                      "type": "string",
                      "description": "用于跟踪索引进度的批次 ID。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "document": {
                        "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "position": 1,
                        "data_source_type": "upload_file",
                        "data_source_info": {
                          "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        },
                        "data_source_detail_dict": {
                          "upload_file": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "name": "guide.txt",
                            "size": 2048,
                            "extension": "txt",
                            "mime_type": "text/plain",
                            "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                            "created_at": 1741267200
                          }
                        },
                        "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                        "name": "guide.txt",
                        "created_from": "api",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "tokens": 512,
                        "indexing_status": "completed",
                        "error": null,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "archived": false,
                        "display_status": "available",
                        "word_count": 350,
                        "hit_count": 0,
                        "doc_form": "text_model",
                        "doc_metadata": [],
                        "summary_index_status": null,
                        "need_summary": false
                      },
                      "batch": "20250306150245647595"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在，或提供文本时 name 为必填项。",
            "content": {
              "application/json": {
                "examples": {
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "invalid_param_dataset": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Dataset does not exist."
                    }
                  },
                  "invalid_param_name_required": {
                    "summary": "invalid_param (name required)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "name is required when text is provided."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/update-by-file": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "用文件更新文档",
        "description": "通过上传新文件更新现有文档。将重新触发索引——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
        "operationId": "updateDocumentByFile",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "要上传的文件。"
                  },
                  "data": {
                    "type": "string",
                    "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。",
                    "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/Document"
                    },
                    "batch": {
                      "type": "string",
                      "description": "用于跟踪索引进度的批次 ID。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "document": {
                        "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "position": 1,
                        "data_source_type": "upload_file",
                        "data_source_info": {
                          "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        },
                        "data_source_detail_dict": {
                          "upload_file": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "name": "guide.txt",
                            "size": 2048,
                            "extension": "txt",
                            "mime_type": "text/plain",
                            "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                            "created_at": 1741267200
                          }
                        },
                        "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
                        "name": "guide.txt",
                        "created_from": "api",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "tokens": 512,
                        "indexing_status": "completed",
                        "error": null,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "archived": false,
                        "display_status": "available",
                        "word_count": 350,
                        "hit_count": 0,
                        "doc_form": "text_model",
                        "doc_metadata": [],
                        "summary_index_status": null,
                        "need_summary": false
                      },
                      "batch": "20250306150245647595"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在、不支持外部数据集、文件过大或不支持的文件类型。",
            "content": {
              "application/json": {
                "examples": {
                  "too_many_files": {
                    "summary": "too_many_files",
                    "value": {
                      "status": 400,
                      "code": "too_many_files",
                      "message": "Only one file is allowed."
                    }
                  },
                  "filename_not_exists_error": {
                    "summary": "filename_not_exists_error",
                    "value": {
                      "status": 400,
                      "code": "filename_not_exists_error",
                      "message": "The specified filename does not exist."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "invalid_param_dataset": {
                    "summary": "invalid_param (dataset)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Dataset does not exist."
                    }
                  },
                  "invalid_param_external": {
                    "summary": "invalid_param (external)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "External datasets are not supported."
                    }
                  },
                  "invalid_param_file_too_large": {
                    "summary": "invalid_param (file_too_large)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "File size exceeded."
                    }
                  },
                  "invalid_param_unsupported_file_type": {
                    "summary": "invalid_param (unsupported_file_type)",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "File type not allowed."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/download-zip": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "批量下载文档（ZIP）",
        "description": "将多个上传文件文档下载为单个 ZIP 压缩包。最多接受 `100` 个文档 ID。",
        "operationId": "downloadDocumentsZipZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_ids"
                ],
                "properties": {
                  "document_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "description": "要包含在 ZIP 压缩包中的文档 ID 数组。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "包含所请求文档的 ZIP 压缩包。",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "ZIP 压缩包二进制流。"
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 权限不足。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Insufficient permissions."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 文档或知识库未找到。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/status/{action}": {
      "patch": {
        "tags": [
          "文档"
        ],
        "summary": "批量更新文档状态",
        "description": "批量启用、禁用、归档或取消归档多个文档。",
        "operationId": "batchUpdateDocumentStatus",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "enable",
                "disable",
                "archive",
                "un_archive"
              ]
            },
            "description": "`enable` 启用，`disable` 停用，`archive` 归档，`un_archive` 从归档中恢复。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_ids"
                ],
                "properties": {
                  "document_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "要更新的文档 ID 列表。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string",
                      "description": "操作结果。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "result": "success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`invalid_action` : 无效的操作。",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_action": {
                    "summary": "invalid_action",
                    "value": {
                      "status": 400,
                      "code": "invalid_action",
                      "message": "Invalid action."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 权限不足。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Insufficient permissions."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 知识库未找到。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments": {
      "post": {
        "tags": [
          "分段"
        ],
        "summary": "向文档添加分段",
        "description": "在文档中创建一个或多个分段。每个分段可以包含可选的关键词和答案字段（适用于 QA 模式文档）。",
        "operationId": "createSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "segments"
                ],
                "properties": {
                  "segments": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "content": {
                          "type": "string",
                          "description": "分段文本内容。"
                        },
                        "answer": {
                          "type": "string",
                          "description": "QA 模式的回答内容。"
                        },
                        "keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "分段的关键词。"
                        },
                        "attachment_ids": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "附件文件 ID。"
                        }
                      }
                    },
                    "description": "要创建的分段对象数组。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分段创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Segment"
                      },
                      "description": "已创建的分段列表。"
                    },
                    "doc_form": {
                      "type": "string",
                      "description": "该文档使用的分块模式。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                          "position": 1,
                          "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                          "content": "Dify is an open-source LLM app development platform.",
                          "sign_content": "",
                          "answer": "",
                          "word_count": 9,
                          "tokens": 12,
                          "keywords": [
                            "dify",
                            "platform",
                            "llm"
                          ],
                          "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
                          "index_node_hash": "abc123def456",
                          "hit_count": 0,
                          "enabled": true,
                          "disabled_at": null,
                          "disabled_by": null,
                          "status": "completed",
                          "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "created_at": 1741267200,
                          "updated_at": 1741267200,
                          "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "indexing_at": 1741267200,
                          "completed_at": 1741267200,
                          "error": null,
                          "stopped_at": null,
                          "child_chunks": [],
                          "attachments": [],
                          "summary": null
                        }
                      ],
                      "doc_form": "text_model"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 文档未完成或已禁用。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found_not_completed": {
                    "summary": "not_found (not completed)",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document is not completed."
                    }
                  },
                  "not_found_disabled": {
                    "summary": "not_found (disabled)",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Document is disabled."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "分段"
        ],
        "summary": "从文档获取分段",
        "description": "返回文档内分段的分页列表。支持按关键词和状态筛选。",
        "operationId": "listSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "要获取的页码。"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "每页的项目数量。服务器上限为 `100`。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true,
            "description": "按索引状态筛选分段，例如 `completed`、`indexing`、`error`。"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "搜索关键词。"
          }
        ],
        "responses": {
          "200": {
            "description": "分段列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Segment"
                      },
                      "description": "分段列表。"
                    },
                    "doc_form": {
                      "type": "string",
                      "description": "该文档使用的分块模式。"
                    },
                    "total": {
                      "type": "integer",
                      "description": "匹配的分段总数。"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "下一页是否还有更多项目。"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "每页条目数。"
                    },
                    "page": {
                      "type": "integer",
                      "description": "当前页码。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                          "position": 1,
                          "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                          "content": "Dify is an open-source LLM app development platform.",
                          "sign_content": "",
                          "answer": "",
                          "word_count": 9,
                          "tokens": 12,
                          "keywords": [
                            "dify",
                            "platform",
                            "llm"
                          ],
                          "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
                          "index_node_hash": "abc123def456",
                          "hit_count": 0,
                          "enabled": true,
                          "disabled_at": null,
                          "disabled_by": null,
                          "status": "completed",
                          "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "created_at": 1741267200,
                          "updated_at": 1741267200,
                          "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                          "indexing_at": 1741267200,
                          "completed_at": 1741267200,
                          "error": null,
                          "stopped_at": null,
                          "child_chunks": [],
                          "attachments": [],
                          "summary": null
                        }
                      ],
                      "doc_form": "text_model",
                      "total": 1,
                      "has_more": false,
                      "limit": 20,
                      "page": 1
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": {
      "get": {
        "tags": [
          "分段"
        ],
        "summary": "获取文档中的分段详情",
        "description": "获取指定分段的详细信息，包括内容、关键词和索引状态。",
        "operationId": "getSegmentDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          }
        ],
        "responses": {
          "200": {
            "description": "分段详情。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Segment"
                    },
                    "doc_form": {
                      "type": "string",
                      "description": "该文档使用的分块模式。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": {
                        "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                        "position": 1,
                        "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "content": "Dify is an open-source LLM app development platform.",
                        "sign_content": "",
                        "answer": "",
                        "word_count": 9,
                        "tokens": 12,
                        "keywords": [
                          "dify",
                          "platform",
                          "llm"
                        ],
                        "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
                        "index_node_hash": "abc123def456",
                        "hit_count": 0,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "status": "completed",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "updated_at": 1741267200,
                        "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "indexing_at": 1741267200,
                        "completed_at": 1741267200,
                        "error": null,
                        "stopped_at": null,
                        "child_chunks": [],
                        "attachments": [],
                        "summary": null
                      },
                      "doc_form": "text_model"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "分段"
        ],
        "summary": "更新文档中的分段",
        "description": "更新分段的内容、关键词或回答。修改后的分段将重新触发索引。",
        "operationId": "updateSegment",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "segment"
                ],
                "properties": {
                  "segment": {
                    "type": "object",
                    "properties": {
                      "content": {
                        "type": "string",
                        "description": "分段文本内容。"
                      },
                      "answer": {
                        "type": "string",
                        "description": "QA 模式的回答内容。"
                      },
                      "keywords": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "分段的关键词。"
                      },
                      "enabled": {
                        "type": "boolean",
                        "description": "分段是否已启用。"
                      },
                      "regenerate_child_chunks": {
                        "type": "boolean",
                        "default": false,
                        "description": "是否重新生成子分段。"
                      },
                      "attachment_ids": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "附件文件 ID。"
                      },
                      "summary": {
                        "type": "string",
                        "nullable": true,
                        "description": "摘要索引的摘要内容。"
                      }
                    },
                    "description": "要更新的分段数据。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分段更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Segment"
                    },
                    "doc_form": {
                      "type": "string",
                      "description": "该文档使用的分块模式。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": {
                        "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                        "position": 1,
                        "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                        "content": "Dify is an open-source LLM app development platform.",
                        "sign_content": "",
                        "answer": "",
                        "word_count": 9,
                        "tokens": 12,
                        "keywords": [
                          "dify",
                          "platform",
                          "llm"
                        ],
                        "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
                        "index_node_hash": "abc123def456",
                        "hit_count": 0,
                        "enabled": true,
                        "disabled_at": null,
                        "disabled_by": null,
                        "status": "completed",
                        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "created_at": 1741267200,
                        "updated_at": 1741267200,
                        "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                        "indexing_at": 1741267200,
                        "completed_at": 1741267200,
                        "error": null,
                        "stopped_at": null,
                        "child_chunks": [],
                        "attachments": [],
                        "summary": null
                      },
                      "doc_form": "text_model"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "分段"
        ],
        "summary": "删除文档中的分段",
        "description": "从文档中永久删除一个分段。",
        "operationId": "deleteSegment",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          }
        ],
        "responses": {
          "204": {
            "description": "Success."
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": {
      "post": {
        "tags": [
          "分段"
        ],
        "summary": "创建子分段",
        "description": "在父分段下创建子分段。仅适用于使用 `hierarchical_model` 分块模式的文档。",
        "operationId": "createChildChunk",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "子分段文本内容。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "子分段创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChildChunk"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": {
                        "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
                        "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                        "content": "Dify is an open-source platform.",
                        "position": 1,
                        "word_count": 6,
                        "type": "automatic",
                        "created_at": 1741267200,
                        "updated_at": 1741267200
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`invalid_param` : 创建子分段索引失败。",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_param": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Create child chunk index failed: {error details}"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "分段"
        ],
        "summary": "获取子分段",
        "description": "返回特定父分段下子分段的分页列表。",
        "operationId": "getChildChunks",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "要获取的页码。"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1
            },
            "description": "每页的项目数量。服务器上限为 `100`。"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "搜索关键词。"
          }
        ],
        "responses": {
          "200": {
            "description": "子分段列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChildChunk"
                      },
                      "description": "子分段列表。"
                    },
                    "total": {
                      "type": "integer",
                      "description": "子分段总数。"
                    },
                    "total_pages": {
                      "type": "integer",
                      "description": "总页数。"
                    },
                    "page": {
                      "type": "integer",
                      "description": "当前页码。"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "每页条目数。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
                          "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                          "content": "Dify is an open-source platform.",
                          "position": 1,
                          "word_count": 6,
                          "type": "automatic",
                          "created_at": 1741267200,
                          "updated_at": 1741267200
                        }
                      ],
                      "total": 1,
                      "total_pages": 1,
                      "page": 1,
                      "limit": 20
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": {
      "patch": {
        "tags": [
          "分段"
        ],
        "summary": "更新子分段",
        "description": "更新现有子分段的内容。",
        "operationId": "updateChildChunk",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          },
          {
            "name": "child_chunk_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "子分段 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "子分段文本内容。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "子分段更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChildChunk"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": {
                        "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
                        "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                        "content": "Dify is an open-source platform.",
                        "position": 1,
                        "word_count": 6,
                        "type": "automatic",
                        "created_at": 1741267200,
                        "updated_at": 1741267200
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`invalid_param` : 更新子分段索引失败。",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_param": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Create child chunk index failed: {error details}"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "分段"
        ],
        "summary": "删除子分段",
        "description": "从父分段中永久删除一个子分段。",
        "operationId": "deleteChildChunk",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "文档 ID."
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Chunk ID."
          },
          {
            "name": "child_chunk_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "子分段 ID。"
          }
        ],
        "responses": {
          "204": {
            "description": "Success."
          },
          "400": {
            "description": "`invalid_param` : 删除子分段索引失败。",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_param": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Delete child chunk index failed: {error details}"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/retrieve": {
      "post": {
        "tags": [
          "知识库"
        ],
        "summary": "从知识库检索分段 / 测试检索",
        "description": "对知识库执行搜索查询，检索最相关的分段。此接口可用于生产环境检索和测试检索。",
        "operationId": "retrieveSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 250,
                    "description": "搜索查询文本。"
                  },
                  "retrieval_model": {
                    "$ref": "#/components/schemas/RetrievalModel",
                    "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
                  },
                  "external_retrieval_model": {
                    "type": "object",
                    "description": "外部知识库的检索设置。",
                    "properties": {
                      "top_k": {
                        "type": "integer",
                        "description": "返回的最大结果数。"
                      },
                      "score_threshold": {
                        "type": "number",
                        "description": "用于过滤结果的最低相关性分数阈值。"
                      },
                      "score_threshold_enabled": {
                        "type": "boolean",
                        "description": "是否启用分数阈值过滤。"
                      }
                    }
                  },
                  "attachment_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "nullable": true,
                    "description": "要包含在检索上下文中的附件 ID 列表。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "检索结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "description": "原始查询对象。",
                      "properties": {
                        "content": {
                          "type": "string",
                          "description": "查询文本。"
                        }
                      }
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "segment": {
                            "type": "object",
                            "description": "从知识库中匹配的分段。",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "分段的唯一标识符。"
                              },
                              "position": {
                                "type": "integer",
                                "description": "分段在文档中的位置。"
                              },
                              "document_id": {
                                "type": "string",
                                "description": "该分段所属文档的 ID。"
                              },
                              "content": {
                                "type": "string",
                                "description": "分段的文本内容。"
                              },
                              "sign_content": {
                                "type": "string",
                                "description": "用于完整性验证的签名内容哈希。"
                              },
                              "answer": {
                                "type": "string",
                                "description": "回答内容，用于问答模式文档。"
                              },
                              "word_count": {
                                "type": "integer",
                                "description": "分段内容的字数。"
                              },
                              "tokens": {
                                "type": "integer",
                                "description": "分段内容的令牌数。"
                              },
                              "keywords": {
                                "type": "array",
                                "description": "与该分段关联的关键词，用于基于关键词的检索。",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "index_node_id": {
                                "type": "string",
                                "description": "向量存储中索引节点的 ID。"
                              },
                              "index_node_hash": {
                                "type": "string",
                                "description": "索引内容的哈希值，用于检测变更。"
                              },
                              "hit_count": {
                                "type": "integer",
                                "description": "该分段在检索查询中被匹配的次数。"
                              },
                              "enabled": {
                                "type": "boolean",
                                "description": "该分段是否启用检索。"
                              },
                              "disabled_at": {
                                "type": "number",
                                "nullable": true,
                                "description": "分段被禁用的时间戳。启用时为 `null`。"
                              },
                              "disabled_by": {
                                "type": "string",
                                "nullable": true,
                                "description": "禁用该分段的用户 ID。启用时为 `null`。"
                              },
                              "status": {
                                "type": "string",
                                "description": "分段的索引状态。"
                              },
                              "created_by": {
                                "type": "string",
                                "description": "创建该分段的用户 ID。"
                              },
                              "created_at": {
                                "type": "number",
                                "description": "创建时间戳（Unix 纪元，单位为秒）。"
                              },
                              "indexing_at": {
                                "type": "number",
                                "nullable": true,
                                "description": "索引开始的时间戳。尚未开始时为 `null`。"
                              },
                              "completed_at": {
                                "type": "number",
                                "nullable": true,
                                "description": "索引完成的时间戳。尚未完成时为 `null`。"
                              },
                              "error": {
                                "type": "string",
                                "nullable": true,
                                "description": "索引失败时的错误消息。无错误时为 `null`。"
                              },
                              "stopped_at": {
                                "type": "number",
                                "nullable": true,
                                "description": "索引停止的时间戳。未停止时为 `null`。"
                              },
                              "document": {
                                "type": "object",
                                "description": "匹配分段的父文档信息。",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "文档的唯一标识符。"
                                  },
                                  "data_source_type": {
                                    "type": "string",
                                    "description": "文档的创建方式。"
                                  },
                                  "name": {
                                    "type": "string",
                                    "description": "文档名称。"
                                  },
                                  "doc_type": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "文档类型分类。未设置时为 `null`。"
                                  },
                                  "doc_metadata": {
                                    "type": "object",
                                    "nullable": true,
                                    "description": "文档的元数据值。未配置元数据时为 `null`。"
                                  }
                                }
                              }
                            }
                          },
                          "child_chunks": {
                            "type": "array",
                            "description": "使用分层索引时，分段内匹配的子分段。",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "子分段的唯一标识符。"
                                },
                                "content": {
                                  "type": "string",
                                  "description": "子分段的文本内容。"
                                },
                                "position": {
                                  "type": "integer",
                                  "description": "子分段在父分段中的位置。"
                                },
                                "score": {
                                  "type": "number",
                                  "description": "子分段的相关性得分。"
                                }
                              }
                            }
                          },
                          "score": {
                            "type": "number",
                            "description": "相关性得分。"
                          },
                          "tsne_position": {
                            "type": "object",
                            "nullable": true,
                            "description": "t-SNE 可视化位置。"
                          },
                          "files": {
                            "type": "array",
                            "description": "附加到该分段的文件。",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "附件文件标识符。"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "原始文件名。"
                                },
                                "size": {
                                  "type": "integer",
                                  "description": "文件大小（字节）。"
                                },
                                "extension": {
                                  "type": "string",
                                  "description": "文件扩展名。"
                                },
                                "mime_type": {
                                  "type": "string",
                                  "description": "文件的 MIME 类型。"
                                },
                                "source_url": {
                                  "type": "string",
                                  "description": "访问附件的 URL。"
                                }
                              }
                            }
                          },
                          "summary": {
                            "type": "string",
                            "nullable": true,
                            "description": "通过摘要索引检索到的摘要内容。"
                          }
                        }
                      },
                      "description": "匹配的检索记录列表。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "query": {
                        "content": "What is Dify?"
                      },
                      "records": [
                        {
                          "segment": {
                            "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
                            "position": 1,
                            "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                            "content": "Dify is an open-source LLM app development platform.",
                            "sign_content": "",
                            "answer": "",
                            "word_count": 9,
                            "tokens": 12,
                            "keywords": [
                              "dify",
                              "platform",
                              "llm"
                            ],
                            "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
                            "index_node_hash": "abc123def456",
                            "hit_count": 1,
                            "enabled": true,
                            "disabled_at": null,
                            "disabled_by": null,
                            "status": "completed",
                            "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                            "created_at": 1741267200,
                            "indexing_at": 1741267200,
                            "completed_at": 1741267200,
                            "error": null,
                            "stopped_at": null,
                            "document": {
                              "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
                              "data_source_type": "upload_file",
                              "name": "guide.txt",
                              "doc_type": null,
                              "doc_metadata": null
                            }
                          },
                          "child_chunks": [],
                          "score": 0.92,
                          "tsne_position": null,
                          "files": [],
                          "summary": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `dataset_not_initialized` : 知识库仍在初始化或索引中。请稍候。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.",
            "content": {
              "application/json": {
                "examples": {
                  "dataset_not_initialized": {
                    "summary": "dataset_not_initialized",
                    "value": {
                      "status": 400,
                      "code": "dataset_not_initialized",
                      "message": "The dataset is still being initialized or indexing. Please wait a moment."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "provider_quota_exceeded": {
                    "summary": "provider_quota_exceeded",
                    "value": {
                      "status": 400,
                      "code": "provider_quota_exceeded",
                      "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
                    }
                  },
                  "model_currently_not_support": {
                    "summary": "model_currently_not_support",
                    "value": {
                      "status": 400,
                      "code": "model_currently_not_support",
                      "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
                    }
                  },
                  "completion_request_error": {
                    "summary": "completion_request_error",
                    "value": {
                      "status": 400,
                      "code": "completion_request_error",
                      "message": "Completion request failed."
                    }
                  },
                  "invalid_param": {
                    "summary": "invalid_param",
                    "value": {
                      "status": 400,
                      "code": "invalid_param",
                      "message": "Invalid parameter value."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 权限不足。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Insufficient permissions."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 知识库未找到。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_server_error` : 检索过程中发生内部错误。",
            "content": {
              "application/json": {
                "examples": {
                  "internal_server_error": {
                    "summary": "internal_server_error",
                    "value": {
                      "status": 500,
                      "code": "internal_server_error",
                      "message": "An internal error occurred."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/tags": {
      "post": {
        "tags": [
          "标签"
        ],
        "summary": "创建知识库标签",
        "description": "创建新标签以组织知识库。",
        "operationId": "createKnowledgeTag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "Tag name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "标签创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "标签标识符。"
                    },
                    "name": {
                      "type": "string",
                      "description": "标签显示名称。"
                    },
                    "type": {
                      "type": "string",
                      "description": "标签类型。知识库标签始终为 `knowledge`。"
                    },
                    "binding_count": {
                      "type": "string",
                      "nullable": true,
                      "description": "绑定到该标签的知识库数量。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
                      "name": "Product Docs",
                      "type": "knowledge",
                      "binding_count": "0"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "标签"
        ],
        "summary": "获取知识库标签列表",
        "description": "返回工作区中所有知识库标签的列表。",
        "operationId": "getKnowledgeTags",
        "responses": {
          "200": {
            "description": "标签列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "标签标识符。"
                      },
                      "name": {
                        "type": "string",
                        "description": "标签显示名称。"
                      },
                      "type": {
                        "type": "string",
                        "description": "标签类型。知识库标签始终为 `knowledge`。"
                      },
                      "binding_count": {
                        "type": "string",
                        "nullable": true,
                        "description": "绑定到该标签的知识库数量。"
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": [
                      {
                        "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
                        "name": "Product Docs",
                        "type": "knowledge",
                        "binding_count": "0"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "标签"
        ],
        "summary": "修改知识库标签",
        "description": "重命名现有的知识库标签。",
        "operationId": "updateKnowledgeTag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tag_id",
                  "name"
                ],
                "properties": {
                  "tag_id": {
                    "type": "string",
                    "description": "要更新的标签 ID。"
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "新标签名称。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "标签更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "标签标识符。"
                    },
                    "name": {
                      "type": "string",
                      "description": "标签显示名称。"
                    },
                    "type": {
                      "type": "string",
                      "description": "标签类型。知识库标签始终为 `knowledge`。"
                    },
                    "binding_count": {
                      "type": "string",
                      "nullable": true,
                      "description": "绑定到该标签的知识库数量。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
                      "name": "Product Docs",
                      "type": "knowledge",
                      "binding_count": "0"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "标签"
        ],
        "summary": "删除知识库标签",
        "description": "永久删除知识库标签。不会删除已被标记的知识库。",
        "operationId": "deleteKnowledgeTag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tag_id"
                ],
                "properties": {
                  "tag_id": {
                    "type": "string",
                    "description": "要删除的标签 ID。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Success."
          }
        }
      }
    },
    "/datasets/tags/binding": {
      "post": {
        "tags": [
          "标签"
        ],
        "summary": "绑定标签到知识库",
        "description": "将一个或多个标签绑定到知识库。一个知识库可以有多个标签。",
        "operationId": "bindTagsToDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tag_ids",
                  "target_id"
                ],
                "properties": {
                  "tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "description": "要绑定的标签 ID。"
                  },
                  "target_id": {
                    "type": "string",
                    "description": "知识库 ID。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Success."
          }
        }
      }
    },
    "/datasets/tags/unbinding": {
      "post": {
        "tags": [
          "标签"
        ],
        "summary": "解除标签与知识库的绑定",
        "description": "移除知识库的标签绑定。",
        "operationId": "unbindTagFromDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tag_id",
                  "target_id"
                ],
                "properties": {
                  "tag_id": {
                    "type": "string",
                    "description": "要解绑的标签 ID。"
                  },
                  "target_id": {
                    "type": "string",
                    "description": "知识库 ID。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Success."
          }
        }
      }
    },
    "/datasets/{dataset_id}/tags": {
      "get": {
        "tags": [
          "标签"
        ],
        "summary": "获取知识库绑定的标签",
        "description": "返回绑定到特定知识库的标签列表。",
        "operationId": "queryDatasetTags",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "绑定到知识库的标签。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "标签标识符。"
                          },
                          "name": {
                            "type": "string",
                            "description": "标签显示名称。"
                          }
                        }
                      },
                      "description": "绑定到此知识库的标签列表。"
                    },
                    "total": {
                      "type": "integer",
                      "description": "绑定到该知识库的标签总数。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
                          "name": "Product Docs"
                        }
                      ],
                      "total": 1
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/metadata": {
      "post": {
        "tags": [
          "元数据"
        ],
        "summary": "创建元数据字段",
        "description": "为知识库创建自定义元数据字段。元数据字段可用于为文档添加结构化信息标注。",
        "operationId": "createMetadataFieldZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type",
                  "name"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "string",
                      "number",
                      "time"
                    ],
                    "description": "`string` 为文本值，`number` 为数值，`time` 为日期/时间值。"
                  },
                  "name": {
                    "type": "string",
                    "description": "元数据字段名称。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "元数据字段创建成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "元数据字段标识符。"
                    },
                    "name": {
                      "type": "string",
                      "description": "元数据字段名称。"
                    },
                    "type": {
                      "type": "string",
                      "description": "元数据字段类型。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
                      "name": "author",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "元数据"
        ],
        "summary": "获取元数据字段列表",
        "description": "返回知识库的所有元数据字段列表（包括自定义和内置字段），以及使用每个字段的文档数量。",
        "operationId": "listMetadataFieldsZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "知识库的元数据字段。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "doc_metadata": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "元数据字段标识符。"
                          },
                          "name": {
                            "type": "string",
                            "description": "元数据字段名称。"
                          },
                          "type": {
                            "type": "string",
                            "description": "元数据字段类型。"
                          },
                          "count": {
                            "type": "integer",
                            "description": "使用该元数据字段的文档数量。"
                          }
                        }
                      },
                      "description": "元数据字段定义列表。"
                    },
                    "built_in_field_enabled": {
                      "type": "boolean",
                      "description": "该知识库是否启用了内置元数据字段。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "doc_metadata": [
                        {
                          "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
                          "name": "author",
                          "type": "string",
                          "count": 3
                        }
                      ],
                      "built_in_field_enabled": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/metadata/{metadata_id}": {
      "patch": {
        "tags": [
          "元数据"
        ],
        "summary": "更新元数据字段",
        "description": "重命名自定义元数据字段。",
        "operationId": "updateMetadataFieldZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "metadata_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "元数据字段 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "新元数据字段名称。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "元数据字段更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "元数据字段标识符。"
                    },
                    "name": {
                      "type": "string",
                      "description": "元数据字段名称。"
                    },
                    "type": {
                      "type": "string",
                      "description": "元数据字段类型。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
                      "name": "author",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "元数据"
        ],
        "summary": "删除元数据字段",
        "description": "永久删除自定义元数据字段。使用此字段的文档将丢失其对应的元数据值。",
        "operationId": "deleteMetadataFieldZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "metadata_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "元数据字段 ID。"
          }
        ],
        "responses": {
          "204": {
            "description": "Success."
          }
        }
      }
    },
    "/datasets/{dataset_id}/metadata/built-in": {
      "get": {
        "tags": [
          "元数据"
        ],
        "summary": "获取内置元数据字段",
        "description": "返回系统提供的内置元数据字段列表（例如文档类型、来源 URL）。",
        "operationId": "getBuiltInMetadataFieldsZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "responses": {
          "200": {
            "description": "内置元数据字段。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "description": "系统提供的元数据字段列表。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "内置字段标识符。`document_name` 表示文档标题，`uploader` 表示创建者，`upload_date` 表示创建时间，`last_update_date` 表示最后修改时间，`source` 表示文档来源。"
                          },
                          "type": {
                            "type": "string",
                            "description": "字段数据类型。文本值为 `string`，日期/时间值为 `time`。"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "fields": [
                        {
                          "name": "document_name",
                          "type": "string"
                        },
                        {
                          "name": "uploader",
                          "type": "string"
                        },
                        {
                          "name": "upload_date",
                          "type": "time"
                        },
                        {
                          "name": "last_update_date",
                          "type": "time"
                        },
                        {
                          "name": "source",
                          "type": "string"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/metadata/built-in/{action}": {
      "post": {
        "tags": [
          "元数据"
        ],
        "summary": "更新内置元数据字段",
        "description": "启用或禁用知识库的内置元数据字段。",
        "operationId": "toggleBuiltInMetadataFieldZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "enable",
                "disable"
              ]
            },
            "description": "`enable` 启用内置元数据字段，`disable` 停用内置元数据字段。"
          }
        ],
        "responses": {
          "200": {
            "description": "内置元数据字段切换成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string",
                      "description": "操作结果。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "result": "success"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/metadata": {
      "post": {
        "tags": [
          "元数据"
        ],
        "summary": "批量更新文档元数据",
        "description": "批量更新多个文档的元数据值。请求中的每个文档将接收指定的元数据键值对。",
        "operationId": "batchUpdateDocumentMetadataZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation_data"
                ],
                "properties": {
                  "operation_data": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "document_id",
                        "metadata_list"
                      ],
                      "properties": {
                        "document_id": {
                          "type": "string",
                          "description": "要更新元数据的文档 ID。"
                        },
                        "metadata_list": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "元数据字段 ID。"
                              },
                              "name": {
                                "type": "string",
                                "description": "元数据字段名称。"
                              },
                              "value": {
                                "description": "元数据值。可以是字符串、数字或 `null`。"
                              }
                            }
                          }
                        },
                        "partial_update": {
                          "type": "boolean",
                          "default": false,
                          "description": "是否部分更新元数据，保留未指定字段的现有值。"
                        }
                      }
                    },
                    "description": "文档元数据更新操作数组。每个条目将一个文档 ID 映射到其元数据键值对。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档元数据更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string",
                      "description": "操作结果。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "result": "success"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/current/models/model-types/{model_type}": {
      "get": {
        "tags": [
          "模型"
        ],
        "summary": "获取可用模型",
        "description": "按类型获取可用模型列表。主要用于查询知识库配置所需的 `text-embedding` 和 `rerank` 模型。",
        "operationId": "getAvailableModelsZh",
        "parameters": [
          {
            "name": "model_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "text-embedding",
                "rerank",
                "llm",
                "tts",
                "speech2text",
                "moderation"
              ]
            },
            "description": "要获取的模型类型。对于知识库配置，使用 `text-embedding` 获取嵌入模型，使用 `rerank` 获取重排序模型。"
          }
        ],
        "responses": {
          "200": {
            "description": "指定类型的可用模型。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "模型提供商及其可用模型的列表。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": {
                            "type": "string",
                            "description": "模型提供商标识符，例如 `openai`、`cohere`。"
                          },
                          "label": {
                            "type": "object",
                            "description": "提供商的本地化显示名称。",
                            "properties": {
                              "en_US": {
                                "type": "string",
                                "description": "英文显示名称。"
                              },
                              "zh_Hans": {
                                "type": "string",
                                "description": "中文显示名称。"
                              }
                            }
                          },
                          "icon_small": {
                            "type": "object",
                            "description": "提供商小图标的 URL。",
                            "properties": {
                              "en_US": {
                                "type": "string",
                                "description": "小图标 URL。"
                              }
                            }
                          },
                          "icon_large": {
                            "type": "object",
                            "description": "提供商大图标的 URL。",
                            "properties": {
                              "en_US": {
                                "type": "string",
                                "description": "大图标 URL。"
                              }
                            }
                          },
                          "status": {
                            "type": "string",
                            "description": "提供商状态。凭证已配置且有效时为 `active`。"
                          },
                          "models": {
                            "type": "array",
                            "description": "该提供商的可用模型列表。",
                            "items": {
                              "type": "object",
                              "properties": {
                                "model": {
                                  "type": "string",
                                  "description": "模型标识符。创建或更新知识库时，将此值作为 `embedding_model` 参数使用。"
                                },
                                "label": {
                                  "type": "object",
                                  "description": "模型的本地化显示名称。",
                                  "properties": {
                                    "en_US": {
                                      "type": "string",
                                      "description": "英文模型名称。"
                                    },
                                    "zh_Hans": {
                                      "type": "string",
                                      "description": "中文模型名称。"
                                    }
                                  }
                                },
                                "model_type": {
                                  "type": "string",
                                  "description": "模型类型，与 `model_type` 路径参数匹配。"
                                },
                                "features": {
                                  "type": "array",
                                  "nullable": true,
                                  "description": "模型支持的功能，无功能时为 `null`。",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "fetch_from": {
                                  "type": "string",
                                  "description": "模型定义的来源。`predefined-model` 表示内置模型，`customizable-model` 表示用户自配置的模型。"
                                },
                                "model_properties": {
                                  "type": "object",
                                  "description": "模型特定的属性，例如 `context_size`。"
                                },
                                "status": {
                                  "type": "string",
                                  "description": "模型可用状态。就绪时为 `active`。"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "data": [
                        {
                          "provider": "openai",
                          "label": {
                            "en_US": "OpenAI",
                            "zh_Hans": "OpenAI"
                          },
                          "icon_small": {
                            "en_US": "https://example.com/openai-small.svg"
                          },
                          "icon_large": {
                            "en_US": "https://example.com/openai-large.svg"
                          },
                          "status": "active",
                          "models": [
                            {
                              "model": "text-embedding-3-small",
                              "label": {
                                "en_US": "text-embedding-3-small",
                                "zh_Hans": "text-embedding-3-small"
                              },
                              "model_type": "text-embedding",
                              "features": null,
                              "fetch_from": "predefined-model",
                              "model_properties": {
                                "context_size": 8191
                              },
                              "status": "active"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/pipeline/file-upload": {
      "post": {
        "tags": [
          "知识流水线"
        ],
        "summary": "上传流水线文件",
        "description": "上传文件以在知识流水线中使用。通过 `multipart/form-data` 接受单个文件。",
        "operationId": "uploadPipelineFileZh",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "要上传的文件。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "文件上传成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "已上传文件的唯一标识符。"
                    },
                    "name": {
                      "type": "string",
                      "description": "原始文件名。"
                    },
                    "size": {
                      "type": "integer",
                      "description": "文件大小（字节）。"
                    },
                    "extension": {
                      "type": "string",
                      "description": "文件扩展名。"
                    },
                    "mime_type": {
                      "type": "string",
                      "description": "文件的 MIME 类型。"
                    },
                    "created_by": {
                      "type": "string",
                      "description": "上传文件的用户 ID。"
                    },
                    "created_at": {
                      "type": "string",
                      "description": "上传时间戳（ISO 8601 格式）。"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": {
                      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                      "name": "report.pdf",
                      "size": 524288,
                      "extension": "pdf",
                      "mime_type": "application/pdf",
                      "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
                      "created_at": "2025-03-06T12:00:00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `no_file_uploaded` : 请上传文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `too_many_files` : 仅允许上传一个文件。",
            "content": {
              "application/json": {
                "examples": {
                  "no_file_uploaded": {
                    "summary": "no_file_uploaded",
                    "value": {
                      "status": 400,
                      "code": "no_file_uploaded",
                      "message": "Please upload your file."
                    }
                  },
                  "filename_not_exists_error": {
                    "summary": "filename_not_exists_error",
                    "value": {
                      "status": 400,
                      "code": "filename_not_exists_error",
                      "message": "The specified filename does not exist."
                    }
                  },
                  "too_many_files": {
                    "summary": "too_many_files",
                    "value": {
                      "status": 400,
                      "code": "too_many_files",
                      "message": "Only one file is allowed."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`file_too_large` : 文件大小超出限制。",
            "content": {
              "application/json": {
                "examples": {
                  "file_too_large": {
                    "summary": "file_too_large",
                    "value": {
                      "status": 413,
                      "code": "file_too_large",
                      "message": "File size exceeded."
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`unsupported_file_type` : 不允许的文件类型。",
            "content": {
              "application/json": {
                "examples": {
                  "unsupported_file_type": {
                    "summary": "unsupported_file_type",
                    "value": {
                      "status": 415,
                      "code": "unsupported_file_type",
                      "message": "File type not allowed."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/pipeline/datasource-plugins": {
      "get": {
        "tags": [
          "知识流水线"
        ],
        "summary": "获取数据源插件列表",
        "description": "列出知识流水线可用的所有数据源插件。根据 `is_published` 查询参数返回已发布或草稿状态的插件。",
        "operationId": "listDatasourcePluginsZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "is_published",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "获取已发布还是草稿状态的数据源插件。`true` 返回已发布的插件，`false` 返回草稿插件。"
          }
        ],
        "responses": {
          "200": {
            "description": "数据源插件列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "数据源插件的唯一标识符。"
                      },
                      "name": {
                        "type": "string",
                        "description": "数据源插件的显示名称。"
                      },
                      "type": {
                        "type": "string",
                        "description": "数据源插件类型。"
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "响应示例",
                    "value": [
                      {
                        "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
                        "name": "Web Scraper",
                        "type": "online_document"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": {
      "post": {
        "tags": [
          "知识流水线"
        ],
        "summary": "执行数据源节点",
        "description": "在知识流水线中执行单个数据源节点。返回包含节点执行结果的流式响应。",
        "operationId": "runDatasourceNodeZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          },
          {
            "name": "node_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "要执行的数据源节点 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "inputs",
                  "datasource_type",
                  "is_published"
                ],
                "properties": {
                  "inputs": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "数据源节点的输入变量。"
                  },
                  "datasource_type": {
                    "type": "string",
                    "enum": [
                      "online_document",
                      "local_file",
                      "website_crawl",
                      "online_drive"
                    ],
                    "description": "数据源类型。"
                  },
                  "credential_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "用于数据源认证的凭证 ID。"
                  },
                  "is_published": {
                    "type": "boolean",
                    "description": "运行节点的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "包含节点执行事件的流式响应。",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "包含节点执行进度和结果的 Server-Sent Events 流。"
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/pipeline/run": {
      "post": {
        "tags": [
          "知识流水线"
        ],
        "summary": "运行流水线",
        "description": "为知识库执行完整的知识流水线。支持流式和阻塞两种响应模式。",
        "operationId": "runPipelineZh",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "知识库 ID。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "inputs",
                  "datasource_type",
                  "datasource_info_list",
                  "start_node_id",
                  "is_published",
                  "response_mode"
                ],
                "properties": {
                  "inputs": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "流水线的输入变量。"
                  },
                  "datasource_type": {
                    "type": "string",
                    "enum": [
                      "online_document",
                      "local_file",
                      "website_crawl",
                      "online_drive"
                    ],
                    "description": "数据源类型。"
                  },
                  "datasource_info_list": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "description": "供流水线处理的数据源信息对象列表。"
                  },
                  "start_node_id": {
                    "type": "string",
                    "description": "流水线开始执行的节点 ID。"
                  },
                  "is_published": {
                    "type": "boolean",
                    "description": "运行流水线的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。"
                  },
                  "response_mode": {
                    "type": "string",
                    "enum": [
                      "streaming",
                      "blocking"
                    ],
                    "description": "流水线执行的响应模式。`streaming` 返回服务器发送事件流，`blocking` 等待并返回完整结果。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "流水线执行结果。格式取决于 `response_mode`：流式返回 `text/event-stream`，阻塞返回完整的 JSON 结果。",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "包含流水线执行进度和结果的服务器发送事件流。当 `response_mode` 为 `streaming` 时返回。"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "完整的流水线执行结果。当 `response_mode` 为 `blocking` 时返回。",
                  "additionalProperties": true
                },
                "examples": {
                  "success": {
                    "summary": "Blocking Response Example",
                    "value": {
                      "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                      "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
                      "data": {
                        "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
                        "status": "succeeded",
                        "outputs": {},
                        "created_at": 1741267200,
                        "finished_at": 1741267210
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : 禁止访问。",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Forbidden."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`not_found` : 未找到知识库。",
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Dataset not found."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`pipeline_run_error` : 流水线执行失败。",
            "content": {
              "application/json": {
                "examples": {
                  "pipeline_run_error": {
                    "summary": "pipeline_run_error",
                    "value": {
                      "status": 500,
                      "code": "pipeline_run_error",
                      "message": "Pipeline execution failed: connection timeout"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Dataset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "知识库的唯一标识符。"
          },
          "name": {
            "type": "string",
            "description": "知识库的显示名称。在工作区内唯一。"
          },
          "description": {
            "type": "string",
            "description": "描述知识库用途或内容的可选文本。"
          },
          "provider": {
            "type": "string",
            "description": "提供商类型。内部管理为 `vendor`，外部知识库连接为 `external`。"
          },
          "permission": {
            "type": "string",
            "description": "控制谁可以访问此知识库。可选值：`only_me`、`all_team_members`、`partial_members`。"
          },
          "data_source_type": {
            "type": "string",
            "description": "文档的数据源类型，尚未配置时为 `null`。"
          },
          "indexing_technique": {
            "type": "string",
            "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
          },
          "app_count": {
            "type": "integer",
            "description": "当前使用该知识库的应用数量。"
          },
          "document_count": {
            "type": "integer",
            "description": "知识库中的文档总数。"
          },
          "word_count": {
            "type": "integer",
            "description": "所有文档的总字数。"
          },
          "created_by": {
            "type": "string",
            "description": "创建该知识库的用户 ID。"
          },
          "author_name": {
            "type": "string",
            "description": "创建者的显示名称。"
          },
          "created_at": {
            "type": "number",
            "description": "创建时间戳（Unix 纪元，单位为秒）。"
          },
          "updated_by": {
            "type": "string",
            "description": "最后更新该知识库的用户 ID。"
          },
          "updated_at": {
            "type": "number",
            "description": "最后更新时间戳（Unix 纪元，单位为秒）。"
          },
          "embedding_model": {
            "type": "string",
            "description": "用于索引的嵌入模型名称。"
          },
          "embedding_model_provider": {
            "type": "string",
            "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
          },
          "embedding_available": {
            "type": "boolean",
            "description": "配置的嵌入模型当前是否可用。"
          },
          "retrieval_model_dict": {
            "type": "object",
            "description": "知识库的检索配置。",
            "properties": {
              "search_method": {
                "type": "string",
                "description": "用于检索的搜索方式。`keyword_search` 表示关键词匹配，`semantic_search` 表示基于嵌入的语义相似度，`full_text_search` 表示全文索引，`hybrid_search` 表示语义和关键词混合搜索。"
              },
              "reranking_enable": {
                "type": "boolean",
                "description": "是否启用重排序。"
              },
              "reranking_mode": {
                "type": "string",
                "nullable": true,
                "description": "重排序模式。`reranking_model` 表示基于模型的重排序，`weighted_score` 表示基于分数的加权。重排序禁用时为 `null`。"
              },
              "reranking_model": {
                "type": "object",
                "description": "重排序模型配置。",
                "properties": {
                  "reranking_provider_name": {
                    "type": "string",
                    "description": "重排序模型的提供商名称。"
                  },
                  "reranking_model_name": {
                    "type": "string",
                    "description": "重排序模型名称。"
                  }
                }
              },
              "weights": {
                "type": "object",
                "nullable": true,
                "description": "混合搜索的权重配置。",
                "properties": {
                  "weight_type": {
                    "type": "string",
                    "description": "平衡语义搜索和关键词搜索权重的策略。"
                  },
                  "vector_setting": {
                    "type": "object",
                    "description": "语义搜索权重设置。",
                    "properties": {
                      "vector_weight": {
                        "type": "number",
                        "description": "分配给语义（向量）搜索结果的权重。"
                      },
                      "embedding_provider_name": {
                        "type": "string",
                        "description": "用于向量搜索的嵌入模型提供商。"
                      },
                      "embedding_model_name": {
                        "type": "string",
                        "description": "用于向量搜索的嵌入模型名称。"
                      }
                    }
                  },
                  "keyword_setting": {
                    "type": "object",
                    "description": "关键词搜索权重设置。",
                    "properties": {
                      "keyword_weight": {
                        "type": "number",
                        "description": "分配给关键词搜索结果的权重。"
                      }
                    }
                  }
                }
              },
              "top_k": {
                "type": "integer",
                "description": "返回的最大结果数。"
              },
              "score_threshold_enabled": {
                "type": "boolean",
                "description": "是否启用分数阈值过滤。"
              },
              "score_threshold": {
                "type": "number",
                "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。"
              }
            }
          },
          "summary_index_setting": {
            "type": "object",
            "nullable": true,
            "description": "摘要索引配置。",
            "properties": {
              "enable": {
                "type": "boolean",
                "description": "是否已启用摘要索引。"
              },
              "model_name": {
                "type": "string",
                "description": "用于生成摘要的模型名称。"
              },
              "model_provider_name": {
                "type": "string",
                "description": "摘要生成模型的提供商。"
              },
              "summary_prompt": {
                "type": "string",
                "description": "用于摘要生成的提示词模板。"
              }
            }
          },
          "tags": {
            "type": "array",
            "description": "与该知识库关联的标签。",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "标签标识符。"
                },
                "name": {
                  "type": "string",
                  "description": "Tag name."
                },
                "type": {
                  "type": "string",
                  "description": "标签类型。知识库标签始终为 `knowledge`。"
                }
              }
            }
          },
          "doc_form": {
            "type": "string",
            "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。"
          },
          "external_knowledge_info": {
            "type": "object",
            "nullable": true,
            "description": "外部知识库的连接详情。当 `provider` 为 `external` 时存在。",
            "properties": {
              "external_knowledge_id": {
                "type": "string",
                "description": "外部知识库的 ID。"
              },
              "external_knowledge_api_id": {
                "type": "string",
                "description": "外部知识库 API 连接的 ID。"
              },
              "external_knowledge_api_name": {
                "type": "string",
                "description": "外部知识库 API 的显示名称。"
              },
              "external_knowledge_api_endpoint": {
                "type": "string",
                "description": "外部知识库 API 的端点 URL。"
              }
            }
          },
          "external_retrieval_model": {
            "type": "object",
            "nullable": true,
            "description": "外部知识库的检索设置。内部知识库时为 `null`。",
            "properties": {
              "top_k": {
                "type": "integer",
                "description": "从外部知识库返回的最大结果数量。"
              },
              "score_threshold": {
                "type": "number",
                "description": "最低相关性得分阈值。"
              },
              "score_threshold_enabled": {
                "type": "boolean",
                "description": "是否启用分数阈值过滤。"
              }
            }
          },
          "doc_metadata": {
            "type": "array",
            "description": "知识库的元数据字段定义。",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "元数据字段标识符。"
                },
                "name": {
                  "type": "string",
                  "description": "元数据字段名称。"
                },
                "type": {
                  "type": "string",
                  "description": "元数据字段值类型。"
                }
              }
            }
          },
          "built_in_field_enabled": {
            "type": "boolean",
            "description": "是否启用内置元数据字段（例如 `document_name`、`uploader`）。"
          },
          "pipeline_id": {
            "type": "string",
            "nullable": true,
            "description": "自定义处理流水线的 ID（如果已配置）。"
          },
          "runtime_mode": {
            "type": "string",
            "nullable": true,
            "description": "运行时处理模式。"
          },
          "chunk_structure": {
            "type": "string",
            "nullable": true,
            "description": "分段结构配置。"
          },
          "icon_info": {
            "type": "object",
            "nullable": true,
            "description": "知识库的图标显示配置。",
            "properties": {
              "icon_type": {
                "type": "string",
                "description": "图标类型。"
              },
              "icon": {
                "type": "string",
                "description": "图标标识符或表情符号。"
              },
              "icon_background": {
                "type": "string",
                "description": "图标的背景颜色。"
              },
              "icon_url": {
                "type": "string",
                "description": "自定义图标图片的 URL。"
              }
            }
          },
          "is_published": {
            "type": "boolean",
            "description": "知识库是否已发布。"
          },
          "total_documents": {
            "type": "integer",
            "description": "文档总数。"
          },
          "total_available_documents": {
            "type": "integer",
            "description": "已启用且可用的文档数量。"
          },
          "enable_api": {
            "type": "boolean",
            "description": "该知识库是否启用 API 访问。"
          },
          "is_multimodal": {
            "type": "boolean",
            "description": "是否启用多模态内容处理。"
          }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "文档的唯一标识符。"
          },
          "position": {
            "type": "integer",
            "description": "文档在列表中的显示位置。"
          },
          "data_source_type": {
            "type": "string",
            "description": "文档的创建方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。"
          },
          "data_source_info": {
            "type": "object",
            "description": "原始数据源信息，随 `data_source_type` 而异。"
          },
          "data_source_detail_dict": {
            "type": "object",
            "description": "详细的数据源信息，包括文件详情。"
          },
          "dataset_process_rule_id": {
            "type": "string",
            "description": "应用于该文档的处理规则 ID。"
          },
          "name": {
            "type": "string",
            "description": "文档名称。"
          },
          "created_from": {
            "type": "string",
            "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。"
          },
          "created_by": {
            "type": "string",
            "description": "创建该文档的用户 ID。"
          },
          "created_at": {
            "type": "number",
            "description": "创建时间戳（Unix 纪元，单位为秒）。"
          },
          "tokens": {
            "type": "integer",
            "description": "文档中的令牌总数。"
          },
          "indexing_status": {
            "type": "string",
            "description": "当前索引状态。`waiting` 表示排队中，`parsing` 表示正在提取内容，`cleaning` 表示正在去噪，`splitting` 表示正在分块，`indexing` 表示正在构建向量，`completed` 表示就绪，`error` 表示失败，`paused` 表示手动暂停。"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "索引失败时的错误消息。无错误时为 `null`。"
          },
          "enabled": {
            "type": "boolean",
            "description": "该文档是否启用检索。"
          },
          "disabled_at": {
            "type": "number",
            "nullable": true,
            "description": "文档被禁用的时间戳。启用时为 `null`。"
          },
          "disabled_by": {
            "type": "string",
            "nullable": true,
            "description": "禁用该文档的用户 ID。启用时为 `null`。"
          },
          "archived": {
            "type": "boolean",
            "description": "文档是否已归档。"
          },
          "display_status": {
            "type": "string",
            "description": "基于 `indexing_status` 和 `enabled` 状态派生的面向用户的显示状态。"
          },
          "word_count": {
            "type": "integer",
            "description": "文档的总字数。"
          },
          "hit_count": {
            "type": "integer",
            "description": "该文档在检索查询中被匹配的次数。"
          },
          "doc_form": {
            "type": "string",
            "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。"
          },
          "doc_metadata": {
            "type": "array",
            "description": "分配给该文档的元数据值。",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "元数据字段标识符。"
                },
                "name": {
                  "type": "string",
                  "description": "元数据字段名称。"
                },
                "type": {
                  "type": "string",
                  "description": "元数据字段值类型。"
                },
                "value": {
                  "type": "string",
                  "description": "此文档的元数据值。"
                }
              }
            }
          },
          "summary_index_status": {
            "type": "string",
            "nullable": true,
            "description": "该文档的摘要索引状态。未配置摘要索引时为 `null`。"
          },
          "need_summary": {
            "type": "boolean",
            "description": "是否需要为该文档生成摘要。"
          }
        }
      },
      "Segment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "分段的唯一标识符。"
          },
          "position": {
            "type": "integer",
            "description": "分段在文档中的位置。"
          },
          "document_id": {
            "type": "string",
            "description": "该分段所属文档的 ID。"
          },
          "content": {
            "type": "string",
            "description": "分段的文本内容。"
          },
          "sign_content": {
            "type": "string",
            "description": "用于完整性验证的签名内容哈希。"
          },
          "answer": {
            "type": "string",
            "description": "回答内容，用于问答模式文档。"
          },
          "word_count": {
            "type": "integer",
            "description": "分段内容的字数。"
          },
          "tokens": {
            "type": "integer",
            "description": "分段内容的令牌数。"
          },
          "keywords": {
            "type": "array",
            "description": "与该分段关联的关键词，用于基于关键词的检索。",
            "items": {
              "type": "string"
            }
          },
          "index_node_id": {
            "type": "string",
            "description": "向量存储中索引节点的 ID。"
          },
          "index_node_hash": {
            "type": "string",
            "description": "索引内容的哈希值，用于检测变更。"
          },
          "hit_count": {
            "type": "integer",
            "description": "该分段在检索查询中被匹配的次数。"
          },
          "enabled": {
            "type": "boolean",
            "description": "该分段是否启用检索。"
          },
          "disabled_at": {
            "type": "number",
            "nullable": true,
            "description": "分段被禁用的时间戳。启用时为 `null`。"
          },
          "disabled_by": {
            "type": "string",
            "nullable": true,
            "description": "禁用该分段的用户 ID。启用时为 `null`。"
          },
          "status": {
            "type": "string",
            "description": "分段的当前索引状态，例如 `completed`、`indexing`、`error`。"
          },
          "created_by": {
            "type": "string",
            "description": "创建该分段的用户 ID。"
          },
          "created_at": {
            "type": "number",
            "description": "创建时间戳（Unix 纪元，单位为秒）。"
          },
          "updated_at": {
            "type": "number",
            "description": "最后更新时间戳（Unix 纪元，单位为秒）。"
          },
          "updated_by": {
            "type": "string",
            "description": "最后更新该分段的用户 ID。"
          },
          "indexing_at": {
            "type": "number",
            "nullable": true,
            "description": "索引开始的时间戳。尚未开始时为 `null`。"
          },
          "completed_at": {
            "type": "number",
            "nullable": true,
            "description": "索引完成的时间戳。尚未完成时为 `null`。"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "索引失败时的错误消息。无错误时为 `null`。"
          },
          "stopped_at": {
            "type": "number",
            "nullable": true,
            "description": "索引停止的时间戳。未停止时为 `null`。"
          },
          "child_chunks": {
            "type": "array",
            "description": "属于该分段的子分段。仅在分层模式文档中存在。",
            "items": {
              "$ref": "#/components/schemas/ChildChunk"
            }
          },
          "attachments": {
            "type": "array",
            "description": "附加到该分段的文件。",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "附件文件标识符。"
                },
                "name": {
                  "type": "string",
                  "description": "原始文件名。"
                },
                "size": {
                  "type": "integer",
                  "description": "文件大小（字节）。"
                },
                "extension": {
                  "type": "string",
                  "description": "文件扩展名。"
                },
                "mime_type": {
                  "type": "string",
                  "description": "文件的 MIME 类型。"
                },
                "source_url": {
                  "type": "string",
                  "description": "访问附件的 URL。"
                }
              }
            }
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "AI 生成的分段内容摘要。未启用摘要索引时为 `null`。"
          }
        }
      },
      "ChildChunk": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "子分段的唯一标识符。"
          },
          "segment_id": {
            "type": "string",
            "description": "该子分段所属的父分段 ID。"
          },
          "content": {
            "type": "string",
            "description": "子分段的文本内容。"
          },
          "position": {
            "type": "integer",
            "description": "子分段在父分段中的位置。"
          },
          "word_count": {
            "type": "integer",
            "description": "子分段内容的字数。"
          },
          "type": {
            "type": "string",
            "description": "子分段的创建方式。系统生成为 `automatic`，手动创建为 `custom`。"
          },
          "created_at": {
            "type": "number",
            "description": "创建时间戳（Unix 纪元，单位为秒）。"
          },
          "updated_at": {
            "type": "number",
            "description": "最后更新时间戳（Unix 纪元，单位为秒）。"
          }
        }
      },
      "RetrievalModel": {
        "type": "object",
        "required": [
          "search_method",
          "reranking_enable",
          "top_k",
          "score_threshold_enabled"
        ],
        "properties": {
          "search_method": {
            "type": "string",
            "description": "用于检索的搜索方法。",
            "enum": [
              "keyword_search",
              "semantic_search",
              "full_text_search",
              "hybrid_search"
            ]
          },
          "reranking_enable": {
            "type": "boolean",
            "description": "是否启用重排序。"
          },
          "reranking_model": {
            "type": "object",
            "description": "重排序模型配置。",
            "properties": {
              "reranking_provider_name": {
                "type": "string",
                "description": "重排序模型的提供商名称。"
              },
              "reranking_model_name": {
                "type": "string",
                "description": "重排序模型名称。"
              }
            }
          },
          "reranking_mode": {
            "type": "string",
            "enum": [
              "reranking_model",
              "weighted_score"
            ],
            "nullable": true,
            "description": "重排序模式。当 `reranking_enable` 为 `true` 时必填。"
          },
          "top_k": {
            "type": "integer",
            "description": "返回的最大结果数。"
          },
          "score_threshold_enabled": {
            "type": "boolean",
            "description": "是否启用分数阈值过滤。"
          },
          "score_threshold": {
            "type": "number",
            "nullable": true,
            "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。"
          },
          "weights": {
            "type": "object",
            "nullable": true,
            "description": "混合搜索的权重配置。",
            "properties": {
              "weight_type": {
                "type": "string",
                "description": "平衡语义搜索和关键词搜索权重的策略。",
                "enum": [
                  "semantic_first",
                  "keyword_first",
                  "customized"
                ]
              },
              "vector_setting": {
                "type": "object",
                "description": "语义搜索权重设置。",
                "properties": {
                  "vector_weight": {
                    "type": "number",
                    "description": "分配给语义（向量）搜索结果的权重。"
                  },
                  "embedding_provider_name": {
                    "type": "string",
                    "description": "用于向量搜索的嵌入模型提供商。"
                  },
                  "embedding_model_name": {
                    "type": "string",
                    "description": "用于向量搜索的嵌入模型名称。"
                  }
                }
              },
              "keyword_setting": {
                "type": "object",
                "description": "关键词搜索权重设置。",
                "properties": {
                  "keyword_weight": {
                    "type": "number",
                    "description": "分配给关键词搜索结果的权重。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**"
      }
    }
  }
}