{
  "openapi": "3.0.1",
  "info": {
    "title": "知识库 API",
    "description": "用于管理知识库（数据集）、文档和段落的 API，包括创建、检索和配置功能。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{apiBaseUrl}",
      "description": "知识库 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": "用于检索可用模型的操作。"
    }
  ],
  "paths": {
    "/datasets": {
      "post": {
        "tags": [
          "数据集"
        ],
        "summary": "创建空知识库",
        "description": "使用指定配置创建一个新的空知识库（数据集）。",
        "operationId": "createDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDatasetRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功创建数据集。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/DatasetNameDuplicate"
          }
        }
      },
      "get": {
        "tags": [
          "数据集"
        ],
        "summary": "获取知识库列表",
        "description": "检索知识库列表，支持分页和过滤选项。",
        "operationId": "listDatasets",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "description": "按名称过滤数据集的搜索关键词。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag_ids",
            "in": "query",
            "description": "要过滤的标签 ID 列表。数据集必须具有所有指定的标签。",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          },
          {
            "name": "page",
            "in": "query",
            "description": "分页的页码。",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "每页返回的项目数。",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "include_all",
            "in": "query",
            "description": "是否包含所有数据集。这仅对工作区所有者有效。",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "数据集的分页列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}": {
      "get": {
        "tags": [
          "数据集"
        ],
        "summary": "获取知识库详情",
        "description": "通过 ID 获取特定知识库的详细信息。",
        "operationId": "getDatasetDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的唯一标识符。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "关于数据集的详细信息。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetDetail"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "数据集"
        ],
        "summary": "更新知识库",
        "description": "更新特定知识库的设置。",
        "operationId": "updateDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的唯一标识符。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDatasetRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功更新数据集详情。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetDetail"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/DatasetNameDuplicate"
          }
        }
      },
      "delete": {
        "tags": [
          "数据集"
        ],
        "summary": "删除知识库",
        "description": "删除知识库及其所有相关文档和数据。",
        "operationId": "deleteDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "要删除的知识库的唯一标识符。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "成功删除数据集。"
          }
        }
      }
    },
    "/datasets/{dataset_id}/document/create-by-text": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "从文本创建文档",
        "description": "直接从文本内容在现有知识库中创建新文档。",
        "operationId": "createDocumentFromText",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "要添加文档的知识库 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDocumentByTextRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档创建成功，正在被索引。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentCreationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/document/create-by-file": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "从文件创建文档",
        "description": "通过上传文件在现有知识库中创建新文档。",
        "operationId": "createDocumentFromFile",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "要添加文档的知识库 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "string",
                    "description": "包含文档元数据和处理规则的 JSON 字符串。详情请参见 `CreateDocumentByFileRequestData` 模式。",
                    "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}}}"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "要上传的文件。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档创建成功，正在被索引。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentCreationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/FileError"
          },
          "413": {
            "$ref": "#/components/responses/FileTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedFileType"
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/update-by-text": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "用文本更新文档",
        "description": "使用文本更新现有文档的内容或设置。",
        "operationId": "updateDocumentByText",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "包含文档的知识库 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "要更新的文档 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDocumentByTextRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentCreationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/update-by-file": {
      "post": {
        "tags": [
          "文档"
        ],
        "summary": "用文件更新文档",
        "description": "通过上传新文件更新现有文档，替换其内容。",
        "operationId": "updateDocumentByFile",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "包含文档的知识库 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "要更新的文档 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "string",
                    "description": "包含可选文档名称和处理规则的 JSON 字符串。请参见 `UpdateDocumentByFileRequestData` 模式。",
                    "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "要上传的新文件。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文档更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentCreationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{batch}/indexing-status": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取文档嵌入状态（进度）",
        "description": "检索文档批次的索引状态，显示嵌入和处理的进度。",
        "operationId": "getDocumentIndexingStatus",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "batch",
            "in": "path",
            "required": true,
            "description": "从文档创建端点返回的批次号。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "批次中文档的索引状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/IndexingStatus"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取文档详情",
        "description": "检索单个文档的详细信息，包括其处理规则和状态。",
        "operationId": "getDocumentDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "metadata",
            "in": "query",
            "description": "元数据过滤器：`all` 返回所有元数据，`only` 仅返回自定义元数据，`without` 不返回元数据。",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "only",
                "without"
              ],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "关于文档的详细信息。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentDetail"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "文档"
        ],
        "summary": "删除文档",
        "description": "从知识库中删除特定文档。",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "要删除的文档 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "成功删除文档。"
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents": {
      "get": {
        "tags": [
          "文档"
        ],
        "summary": "获取知识库的文档列表",
        "description": "检索指定知识库中所有文档的分页列表。",
        "operationId": "listDocuments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "在文档名称中搜索的关键词。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "分页的页码。",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "每页返回的项目数。",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "文档的分页列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/status/{action}": {
      "patch": {
        "tags": [
          "文档"
        ],
        "summary": "更新文档状态",
        "description": "执行批量操作以更新一个或多个文档的状态（例如，启用、禁用、归档）。",
        "operationId": "batchUpdateDocumentStatus",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "action",
            "in": "path",
            "required": true,
            "description": "对文档执行的操作。",
            "schema": {
              "type": "string",
              "enum": [
                "enable",
                "disable",
                "archive",
                "un_archive"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_ids"
                ],
                "properties": {
                  "document_ids": {
                    "type": "array",
                    "description": "要执行操作的文档 ID 列表。",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments": {
      "post": {
        "tags": [
          "文档块"
        ],
        "summary": "向文档添加块",
        "description": "向特定文档添加一个或多个新块（段落）。这对于手动添加精心策划的内容很有用。",
        "operationId": "createSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSegmentsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "新创建的段落列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentListResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "文档块"
        ],
        "summary": "从文档获取块",
        "description": "从特定文档检索块（段落）的分页列表。",
        "operationId": "listSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "按内容过滤段落的关键词。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "按索引状态过滤段落。",
            "schema": {
              "type": "string",
              "example": "completed"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "分页的页码。",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "每页返回的项目数。",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "段落的分页列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentPaginatedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": {
      "get": {
        "tags": [
          "文档块"
        ],
        "summary": "获取文档中的块详情",
        "description": "检索文档中特定块（段落）的详情。",
        "operationId": "getSegmentDetail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "段落的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "关于段落的详细信息。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDetailResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "文档块"
        ],
        "summary": "更新文档中的块",
        "description": "更新特定块（段落）的内容、关键词或状态。",
        "operationId": "updateSegment",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "要更新的段落 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSegmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "更新的段落详情。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDetailResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "文档块"
        ],
        "summary": "删除文档中的块",
        "description": "从文档中删除特定块（段落）。",
        "operationId": "deleteSegment",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "要删除的段落 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "成功删除段落。"
          }
        }
      }
    },
    "/datasets/{dataset_id}/retrieve": {
      "post": {
        "tags": [
          "数据集"
        ],
        "summary": "从知识库检索块",
        "description": "对知识库执行搜索查询以检索最相关的块（段落）。",
        "operationId": "retrieveSegments",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "要检索的知识库 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrieveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "与查询匹配的检索段落列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrieveResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/current/models/model-types/text-embedding": {
      "get": {
        "tags": [
          "模型"
        ],
        "summary": "获取可用的嵌入模型",
        "description": "获取可用于创建和查询知识库的所有可用文本嵌入模型列表。",
        "operationId": "getAvailableEmbeddingModels",
        "responses": {
          "200": {
            "description": "按提供商分组的可用嵌入模型列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelProvider"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": {
      "post": {
        "tags": [
          "文档块"
        ],
        "summary": "创建子块",
        "description": "使用分层模式在文档中的父段落下创建新的子块。",
        "operationId": "createChildChunk",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "父段落的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChildChunkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功创建子块。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChildChunkResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "文档块"
        ],
        "summary": "获取子块",
        "description": "检索特定父段落的子块列表。",
        "operationId": "getChildChunks",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "父段落的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "过滤子块的搜索关键词。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "分页的页码。",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "每页返回的项目数。",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "子块的分页列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChildChunkListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/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,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "父段落的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "child_chunk_id",
            "in": "path",
            "required": true,
            "description": "要更新的子块 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateChildChunkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功更新子块。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChildChunkResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "文档块"
        ],
        "summary": "删除子块",
        "description": "删除特定的子块。",
        "operationId": "deleteChildChunk",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "知识库的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "description": "文档的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "segment_id",
            "in": "path",
            "required": true,
            "description": "父段落的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "child_chunk_id",
            "in": "path",
            "required": true,
            "description": "要删除的子块 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "成功删除子块。"
          }
        }
      }
    },
    "/datasets/tags": {
      "post": {
        "tags": [
          "元数据和标签"
        ],
        "summary": "创建新的知识库类型标签",
        "description": "创建可用于分类知识库的新标签。",
        "operationId": "createKnowledgeTag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "新标签的名称。",
                    "maxLength": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功创建标签。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "元数据和标签"
        ],
        "summary": "获取知识库类型标签",
        "description": "检索所有可用知识库标签的列表。",
        "operationId": "getKnowledgeTags",
        "responses": {
          "200": {
            "description": "标签列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tag"
                  }
                }
              }
            }
          }
        }
      },
      "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。",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string",
                    "description": "标签的新名称。",
                    "maxLength": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功更新标签。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          }
        }
      },
      "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。",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    },
    "/datasets/tags/binding": {
      "post": {
        "tags": [
          "元数据和标签"
        ],
        "summary": "将数据集绑定到知识库类型标签",
        "description": "将一个或多个标签绑定到特定知识库。",
        "operationId": "bindTagsToDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target_id", "tag_ids"],
                "properties": {
                  "target_id": {
                    "type": "string",
                    "description": "要绑定标签的数据集 ID。",
                    "format": "uuid"
                  },
                  "tag_ids": {
                    "type": "array",
                    "description": "要绑定的标签 ID 列表。",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    },
    "/datasets/tags/unbinding": {
      "post": {
        "tags": [
          "元数据和标签"
        ],
        "summary": "解绑数据集和知识库类型标签",
        "description": "从知识库解绑特定标签。",
        "operationId": "unbindTagFromDataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target_id", "tag_id"],
                "properties": {
                  "target_id": {
                    "type": "string",
                    "description": "数据集的 ID。",
                    "format": "uuid"
                  },
                  "tag_id": {
                    "type": "string",
                    "description": "要解绑的标签 ID。",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    },
    "/datasets/{dataset_id}/tags": {
      "post": {
        "tags": [
          "元数据和标签"
        ],
        "summary": "查询绑定到数据集的标签",
        "description": "检索当前绑定到特定数据集的所有标签。",
        "operationId": "queryDatasetTags",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "required": true,
            "description": "数据集的 ID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "绑定到数据集的标签列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "format": "uuid" },
                          "name": { "type": "string" }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "API-Key 鉴权。所有 API 请求都应在 `Authorization` HTTP Header 中包含您的 API-Key，格式为 `Bearer {API_KEY}`。**强烈建议开发者把 API-Key 放在后端存储，而非分享或者放在客户端存储，以免 API-Key 泄露，导致财产损失。**"
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功。",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "result": {
                  "type": "string",
                  "example": "success"
                }
              }
            }
          }
        }
      },
      "FileError": {
        "description": "与文件上传相关的错误请求。可能是 `no_file_uploaded` 或 `too_many_files`。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "FileTooLarge": {
        "description": "文件大小超出限制。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnsupportedFileType": {
        "description": "不允许的文件类型。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "DatasetNameDuplicate": {
        "description": "数据集名称已存在。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "机器可读的错误代码。"
          },
          "message": {
            "type": "string",
            "description": "人类可读的错误消息。"
          },
          "status": {
            "type": "integer",
            "description": "HTTP 状态码。"
          }
        },
        "example": {
          "code": "no_file_uploaded",
          "message": "请上传您的文件。",
          "status": 400
        }
      },
      "RetrievalModel": {
        "type": "object",
        "properties": {
          "search_method": {
            "type": "string",
            "description": "用于检索的搜索方法。",
            "enum": [
              "hybrid_search",
              "semantic_search",
              "full_text_search",
              "keyword_search"
            ]
          },
          "reranking_enable": {
            "type": "boolean",
            "description": "是否启用重新排序模型以改善搜索结果。"
          },
          "reranking_mode": {
            "type": "object",
            "description": "重新排序模型的配置。",
            "properties": {
              "reranking_provider_name": {
                "type": "string",
                "description": "重新排序模型的提供商。"
              },
              "reranking_model_name": {
                "type": "string",
                "description": "重新排序模型的名称。"
              }
            },
            "nullable": true
          },
          "top_k": {
            "type": "integer",
            "description": "返回的顶部匹配结果数量。"
          },
          "score_threshold_enabled": {
            "type": "boolean",
            "description": "是否应用分数阈值来过滤结果。"
          },
          "score_threshold": {
            "type": "number",
            "format": "float",
            "description": "结果包含的最低分数。",
            "nullable": true
          },
          "weights": {
            "type": "number",
            "format": "float",
            "description": "混合搜索模式中语义搜索的权重。",
            "nullable": true
          }
        }
      },
      "PreprocessingRule": {
        "type": "object",
        "description": "文档内容预处理规则。",
        "properties": {
          "id": {
            "type": "string",
            "description": "预处理规则的唯一标识符。",
            "enum": [
              "remove_extra_spaces",
              "remove_urls_emails"
            ]
          },
          "enabled": {
            "type": "boolean",
            "description": "此规则是否启用。"
          }
        }
      },
      "SegmentationRule": {
        "type": "object",
        "description": "将文档内容分割成块的规则。",
        "properties": {
          "separator": {
            "type": "string",
            "description": "用于分离段落的自定义分隔符。"
          },
          "max_tokens": {
            "type": "integer",
            "description": "单个段落中允许的最大令牌数。"
          }
        }
      },
      "SubChunkSegmentationRule": {
        "type": "object",
        "description": "将父块分割为较小子块的规则（用于分层模式）。",
        "properties": {
          "separator": {
            "type": "string",
            "description": "子块的分隔符。"
          },
          "max_tokens": {
            "type": "integer",
            "description": "子块的最大令牌长度。"
          },
          "chunk_overlap": {
            "type": "integer",
            "description": "相邻子块之间的重叠令牌数。"
          }
        }
      },
      "ProcessRule": {
        "type": "object",
        "description": "用于处理文档的规则集，包括清理和分割。",
        "properties": {
          "mode": {
            "type": "string",
            "description": "处理模式：automatic、custom 或 hierarchical。",
            "enum": [
              "automatic",
              "custom",
              "hierarchical"
            ]
          },
          "rules": {
            "type": "object",
            "description": "要应用的特定规则，当模式为 'custom' 或 'hierarchical' 时使用。",
            "properties": {
              "pre_processing_rules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PreprocessingRule"
                }
              },
              "segmentation": {
                "$ref": "#/components/schemas/SegmentationRule"
              },
              "parent_mode": {
                "type": "string",
                "description": "分层模式中父块的检索模式。",
                "enum": [
                  "full-doc",
                  "paragraph"
                ]
              },
              "subchunk_segmentation": {
                "$ref": "#/components/schemas/SubChunkSegmentationRule"
              }
            },
            "nullable": true
          }
        }
      },
      "CreateDocumentByTextRequest": {
        "type": "object",
        "required": [
          "name",
          "text"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "文档名称。"
          },
          "text": {
            "type": "string",
            "description": "文档的完整文本内容。"
          },
          "indexing_technique": {
            "type": "string",
            "description": "文档的索引技术。",
            "enum": [
              "high_quality",
              "economy"
            ]
          },
          "doc_form": {
            "type": "string",
            "description": "索引内容的格式。",
            "enum": [
              "text_model",
              "hierarchical_model",
              "qa_model"
            ]
          },
          "doc_language": {
            "type": "string",
            "description": "文档的语言，在 Q&A 模式中很重要。",
            "example": "中文"
          },
          "process_rule": {
            "$ref": "#/components/schemas/ProcessRule"
          },
          "retrieval_model": {
            "$ref": "#/components/schemas/RetrievalModel"
          },
          "embedding_model": {
            "type": "string",
            "description": "要使用的嵌入模型名称。"
          },
          "embedding_model_provider": {
            "type": "string",
            "description": "嵌入模型的提供商。"
          }
        }
      },
      "CreateDocumentByFileRequestData": {
        "type": "object",
        "description": "从文件创建文档的元数据和规则。",
        "properties": {
          "original_document_id": {
            "type": "string",
            "description": "要重新上传或修改的现有文档 ID。",
            "format": "uuid"
          },
          "indexing_technique": {
            "type": "string",
            "enum": [
              "high_quality",
              "economy"
            ]
          },
          "doc_form": {
            "type": "string",
            "enum": [
              "text_model",
              "hierarchical_model",
              "qa_model"
            ]
          },
          "doc_language": {
            "type": "string",
            "example": "中文"
          },
          "process_rule": {
            "$ref": "#/components/schemas/ProcessRule"
          },
          "retrieval_model": {
            "$ref": "#/components/schemas/RetrievalModel"
          },
          "embedding_model": {
            "type": "string"
          },
          "embedding_model_provider": {
            "type": "string"
          }
        }
      },
      "UpdateDocumentByTextRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "文档的新名称（可选）。"
          },
          "text": {
            "type": "string",
            "description": "文档的新文本内容（可选）。"
          },
          "process_rule": {
            "$ref": "#/components/schemas/ProcessRule"
          }
        }
      },
      "UpdateDocumentByFileRequestData": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "文档的新名称（可选）。"
          },
          "process_rule": {
            "$ref": "#/components/schemas/ProcessRule"
          }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "position": {
            "type": "integer"
          },
          "data_source_type": {
            "type": "string"
          },
          "data_source_info": {
            "type": "object",
            "nullable": true
          },
          "dataset_process_rule_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "name": {
            "type": "string"
          },
          "created_from": {
            "type": "string"
          },
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "integer",
            "format": "int64"
          },
          "tokens": {
            "type": "integer"
          },
          "indexing_status": {
            "type": "string"
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_at": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "disabled_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "archived": {
            "type": "boolean"
          },
          "display_status": {
            "type": "string"
          },
          "word_count": {
            "type": "integer"
          },
          "hit_count": {
            "type": "integer"
          },
          "doc_form": {
            "type": "string"
          }
        }
      },
      "DocumentCreationResponse": {
        "type": "object",
        "properties": {
          "document": {
            "$ref": "#/components/schemas/Document"
          },
          "batch": {
            "type": "string",
            "description": "用于跟踪索引进度的批次标识符。"
          }
        }
      },
      "CreateDatasetRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "知识库的名称。"
          },
          "description": {
            "type": "string",
            "description": "知识库的描述（可选）。"
          },
          "indexing_technique": {
            "type": "string",
            "description": "要使用的索引技术。",
            "enum": [
              "high_quality",
              "economy"
            ]
          },
          "permission": {
            "type": "string",
            "description": "知识库的访问权限。",
            "enum": [
              "only_me",
              "all_team_members",
              "partial_members"
            ]
          },
          "provider": {
            "type": "string",
            "description": "知识库的提供商。",
            "enum": [
              "vendor",
              "external"
            ]
          },
          "external_knowledge_api_id": {
            "type": "string",
            "description": "外部知识 API 的 ID（如果提供商是 'external'）。"
          },
          "external_knowledge_id": {
            "type": "string",
            "description": "外部知识的 ID（如果提供商是 'external'）。"
          },
          "embedding_model": {
            "type": "string",
            "description": "嵌入模型的名称。"
          },
          "embedding_model_provider": {
            "type": "string",
            "description": "嵌入模型的提供商。"
          },
          "retrieval_model": {
            "$ref": "#/components/schemas/RetrievalModel"
          }
        }
      },
      "Dataset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "provider": {
            "type": "string"
          },
          "permission": {
            "type": "string"
          },
          "data_source_type": {
            "type": "string",
            "nullable": true
          },
          "indexing_technique": {
            "type": "string",
            "nullable": true
          },
          "app_count": {
            "type": "integer"
          },
          "document_count": {
            "type": "integer"
          },
          "word_count": {
            "type": "integer"
          },
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "integer",
            "format": "int64"
          },
          "updated_by": {
            "type": "string",
            "format": "uuid"
          },
          "updated_at": {
            "type": "integer",
            "format": "int64"
          },
          "embedding_model": {
            "type": "string",
            "nullable": true
          },
          "embedding_model_provider": {
            "type": "string",
            "nullable": true
          },
          "embedding_available": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "DatasetListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataset"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          }
        }
      },
      "DatasetDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Dataset"
          },
          {
            "type": "object",
            "properties": {
              "retrieval_model_dict": {
                "$ref": "#/components/schemas/RetrievalModel"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "doc_form": {
                "type": "string",
                "nullable": true
              }
            }
          }
        ]
      },
      "UpdateDatasetRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "知识库的新名称。"
          },
          "description": {
            "type": "string",
            "description": "知识库的新描述。"
          },
          "indexing_technique": {
            "type": "string",
            "enum": [
              "high_quality",
              "economy"
            ]
          },
          "permission": {
            "type": "string",
            "enum": [
              "only_me",
              "all_team_members",
              "partial_members"
            ]
          },
          "embedding_model_provider": {
            "type": "string"
          },
          "embedding_model": {
            "type": "string"
          },
          "retrieval_model": {
            "$ref": "#/components/schemas/RetrievalModel"
          },
          "partial_member_list": {
            "type": "array",
            "description": "'partial_members' 权限的成员 ID 列表。",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "IndexingStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "indexing_status": {
            "type": "string"
          },
          "processing_started_at": {
            "type": "number",
            "format": "float"
          },
          "parsing_completed_at": {
            "type": "number",
            "format": "float"
          },
          "cleaning_completed_at": {
            "type": "number",
            "format": "float"
          },
          "splitting_completed_at": {
            "type": "number",
            "format": "float"
          },
          "completed_at": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "paused_at": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "stopped_at": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "completed_segments": {
            "type": "integer"
          },
          "total_segments": {
            "type": "integer"
          }
        }
      },
      "DocumentListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          }
        }
      },
      "DocumentDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Document"
          },
          {
            "type": "object",
            "properties": {
              "dataset_process_rule": {
                "$ref": "#/components/schemas/ProcessRule"
              },
              "document_process_rule": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ProcessRule"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "dataset_id": {
                        "type": "string"
                      }
                    }
                  }
                ]
              },
              "indexing_latency": {
                "type": "number",
                "format": "float",
                "nullable": true
              },
              "segment_count": {
                "type": "integer"
              },
              "average_segment_length": {
                "type": "integer"
              },
              "doc_language": {
                "type": "string",
                "nullable": true
              }
            }
          }
        ]
      },
      "Segment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "position": {
            "type": "integer"
          },
          "document_id": {
            "type": "string",
            "format": "uuid"
          },
          "content": {
            "type": "string"
          },
          "answer": {
            "type": "string",
            "nullable": true
          },
          "word_count": {
            "type": "integer"
          },
          "tokens": {
            "type": "integer"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "index_node_id": {
            "type": "string"
          },
          "index_node_hash": {
            "type": "string"
          },
          "hit_count": {
            "type": "integer"
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_at": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "disabled_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "status": {
            "type": "string"
          },
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "integer",
            "format": "int64"
          },
          "indexing_at": {
            "type": "integer",
            "format": "int64"
          },
          "completed_at": {
            "type": "integer",
            "format": "int64"
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "stopped_at": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        }
      },
      "CreateSegmentsRequest": {
        "type": "object",
        "properties": {
          "segments": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "content"
              ],
              "properties": {
                "content": {
                  "type": "string",
                  "description": "块的文本内容（Q&A 模式中为问题）。"
                },
                "answer": {
                  "type": "string",
                  "description": "答案内容，如果文档处于 Q&A 模式则必需。"
                },
                "keywords": {
                  "type": "array",
                  "description": "与块关联的关键词。",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "SegmentListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Segment"
            }
          },
          "doc_form": {
            "type": "string"
          }
        }
      },
      "SegmentPaginatedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SegmentListResponse"
          },
          {
            "type": "object",
            "properties": {
              "has_more": {
                "type": "boolean"
              },
              "limit": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              },
              "page": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "SegmentDetailResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Segment"
          },
          "doc_form": {
            "type": "string"
          }
        }
      },
      "UpdateSegmentRequest": {
        "type": "object",
        "properties": {
          "segment": {
            "type": "object",
            "required": [
              "content"
            ],
            "properties": {
              "content": {
                "type": "string"
              },
              "answer": {
                "type": "string"
              },
              "keywords": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "enabled": {
                "type": "boolean"
              },
              "regenerate_child_chunks": {
                "type": "boolean",
                "description": "是否重新生成子块（分层模式）。"
              }
            }
          }
        }
      },
      "RetrieveRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "搜索查询字符串。"
          },
          "retrieval_model": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RetrievalModel"
              },
              {
                "type": "object",
                "properties": {
                  "metadata_filtering_conditions": {
                    "type": "object",
                    "description": "基于元数据过滤结果的条件。",
                    "properties": {
                      "logical_operator": {
                        "type": "string",
                        "enum": [
                          "and",
                          "or"
                        ]
                      },
                      "conditions": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "description": "元数据字段的名称。"
                            },
                            "comparison_operator": {
                              "type": "string",
                              "description": "比较的运算符。"
                            },
                            "value": {
                              "oneOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "number"
                                }
                              ],
                              "nullable": true,
                              "description": "要比较的值。"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            ]
          }
        }
      },
      "RetrievedSegment": {
        "type": "object",
        "properties": {
          "segment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Segment"
              },
              {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "data_source_type": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            ]
          },
          "score": {
            "type": "number",
            "format": "float"
          }
        }
      },
      "RetrieveResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string"
              }
            }
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RetrievedSegment"
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "label": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "model_type": {
            "type": "string"
          },
          "features": {
            "type": "array",
            "items": {},
            "nullable": true
          },
          "fetch_from": {
            "type": "string"
          },
          "model_properties": {
            "type": "object",
            "properties": {
              "context_size": {
                "type": "integer"
              }
            }
          },
          "deprecated": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "load_balancing_enabled": {
            "type": "boolean"
          }
        }
      },
      "ModelProvider": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string"
          },
          "label": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon_small": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          },
          "icon_large": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          },
          "status": {
            "type": "string"
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "ChildChunk": {
        "type": "object",
        "description": "表示分层分割中的子块。",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "segment_id": { "type": "string", "format": "uuid" },
          "content": { "type": "string" },
          "word_count": { "type": "integer" },
          "tokens": { "type": "integer" },
          "index_node_id": { "type": "string" },
          "index_node_hash": { "type": "string" },
          "status": { "type": "string" },
          "created_by": { "type": "string", "format": "uuid" },
          "created_at": { "type": "integer", "format": "int64" },
          "indexing_at": { "type": "integer", "format": "int64" },
          "completed_at": { "type": "integer", "format": "int64" },
          "error": { "type": "string", "nullable": true },
          "stopped_at": { "type": "integer", "format": "int64", "nullable": true }
        }
      },
      "CreateChildChunkRequest": {
        "type": "object",
        "required": ["content"],
        "properties": {
          "content": {
            "type": "string",
            "description": "子块的内容。"
          }
        }
      },
      "UpdateChildChunkRequest": {
        "type": "object",
        "required": ["content"],
        "properties": {
          "content": {
            "type": "string",
            "description": "子块的更新内容。"
          }
        }
      },
      "ChildChunkResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ChildChunk"
          }
        }
      },
      "ChildChunkListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChildChunk"
            }
          },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" },
          "page": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      },
      "UploadFileResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "size": { "type": "integer" },
          "extension": { "type": "string" },
          "url": { "type": "string", "format": "uri", "description": "文件的预览 URL。" },
          "download_url": { "type": "string", "format": "uri", "description": "文件的下载 URL。" },
          "mime_type": { "type": "string" },
          "created_by": { "type": "string", "format": "uuid" },
          "created_at": { "type": "integer", "format": "int64" }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "type": { "type": "string", "example": "knowledge" },
          "binding_count": { "type": "integer" }
        }
      }
    }
  }
}