{ "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": { "get": { "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": "string", "description": "重新排序模式。", "default": "reranking_model", "enum": [ "reranking_model", "weighted_score" ] }, "reranking_model": { "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' 权限可访问的成员列表。", "items": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "成员的用户 ID。" } } } } } }, "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" } } } } } }