centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-26 13:18:34 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
dify-docs/zh/api-reference/openapi_knowledge.json
Riskey 21122c4282 Batch update apis (#715) 
* Batch update service apis

* final check and add zh/ja docs

* add temporary redirects for changed api links embedded in the product

* Restore original operationIds to preserve SDK compatibility

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* complete the missing descriptions

* correct the human input terminology

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:38:10 +08:00

6657 lines
239 KiB
JSON
Raw Permalink Blame History

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