创建知识处理任务

POST

/api/open/v4/butler/knowledge/tasks

创建一个异步知识处理任务，支持三种来源类型，系统将自动处理所有来源并上传到知识库。

支持的来源类型：

uploaded_file：引用通过 /files 接口上传的文件，需提供 fileId

remote_file：指定外部可访问的文件 URL，系统将自动下载处理

raw_text：直接传入文本内容，无需先上传文件

设计原则：

输入源统一为 sources[] 数组，每个任务可包含多个来源，便于批量导入

创建后返回 taskId，由系统异步处理，可通过查询接口或回调获取进度

单个文件失败不会中断整个任务，其他文件会继续处理

任务状态说明：

task.progress：任务进行中

task.completed：任务完成（所有文件处理完毕，即使文件全部处理失败，只要没有任务级错误）

task.failed：任务失败（任务级错误）

回调示例：

{
  "id": "df53ce97-2138-4898-8926-919bd7e161e8",
  "type": "file.completed",
  "createdAt": 1778050876442,
  "data": {
    "task": {
      "taskId": "07adc997-2ce8-4dc4-89b9-08ede5bd9356",
      "status": "task.progress",
      "sourceSummary": {
        "total": 1,
        "accepted": 1,
        "rejected": 0,
        "queued": 0,
        "uploading": 0,
        "parsing": 0,
        "completed": 1,
        "failed": 0
      },
      "entitlement": {
        "resourceType": "knowledge_unit",
        "estimatedConsume": 1,
        "actualConsume": 1,
        "balanceRemain": 5
      },
      "errors": [],
      "createdAt": 1778050592419,
      "updatedAt": 1778050875495
    },
    "file": {
      "sourceId": "my_sr_x1",
      "internalId": "7b06a742-8593-4246-9f74-45e4cbeebbaa",
      "type": "uploaded_file",
      "displayName": "渠道下多活跃对话逻辑处理.pdf",
      "status": "file.completed"
    }
  }
}

请求参数

Header 参数

Body 参数application/json必填

示例

引用已上传文件远程文件原始文本批量导入多个来源

{
    "sources": [
        {
            "sourceId": "my_src_1",
            "type": "uploaded_file",
            "fileId": "5f4dd5be-e35a-4c4d-b4a0-104ca2b4383c",
            "displayName": "医学库.xlsx"
        },
        {
            "sourceId": "my_src_2",
            "type": "remote_file",
            "url": "https://newqa-3chat.frp.newcoretech.com/openapi/24268a6c-b0a4-414d-b03b-74ed200d31b6/%E6%B5%8B%E8%AF%95openAPI%E4%B8%8A%E4%BC%A0.xlsx",
            "displayName": "联系人.xlsx"
        },
        {
            "sourceId": "my_src_3",
            "type": "raw_text",
            "title": "文本知识库",
            "content": "文本知识库内容",
            "contentType": "text/plain"
        }
    ],
    "parseConfig": {
        "extractImageElements": true,
        "parseScannedDocument": false,
        "language": "zh-CN",
        "normalizeWhitespaceAndLineBreaks": false,
        "removeUrlsAndEmails": false
    },
    "chunkConfig": {
        "mode": "hierarchical",
        "hierarchical": {
            "level": 1,
            "preserveHierarchyInfo": true
        }
    },
    "callback": {
        "url": "https://client.example.com/webhooks/3chat/knowledge",
        "events": [
            "file.uploading",
            "file.parsing",
            "file.completed",
            "file.failed"
        ],
        "secret": "860CCCB3FF77A98CDE0722284B40A371"
    }
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

cURL

引用已上传文件远程文件原始文本批量导入多个来源

curl --location 'https://c2.xinheyun.com/api/open/v4/butler/knowledge/tasks' \
--header 'Cookie;' \
--header 'Content-Type: application/json' \
--data '{
    "sources": [
        {
            "sourceId": "my_src_1",
            "type": "uploaded_file",
            "fileId": "5f4dd5be-e35a-4c4d-b4a0-104ca2b4383c",
            "displayName": "医学库.xlsx"
        },
        {
            "sourceId": "my_src_2",
            "type": "remote_file",
            "url": "https://newqa-3chat.frp.newcoretech.com/openapi/24268a6c-b0a4-414d-b03b-74ed200d31b6/%E6%B5%8B%E8%AF%95openAPI%E4%B8%8A%E4%BC%A0.xlsx",
            "displayName": "联系人.xlsx"
        },
        {
            "sourceId": "my_src_3",
            "type": "raw_text",
            "title": "文本知识库",
            "content": "文本知识库内容",
            "contentType": "text/plain"
        }
    ],
    "parseConfig": {
        "extractImageElements": true,
        "parseScannedDocument": false,
        "language": "zh-CN",
        "normalizeWhitespaceAndLineBreaks": false,
        "removeUrlsAndEmails": false
    },
    "chunkConfig": {
        "mode": "hierarchical",
        "hierarchical": {
            "level": 1,
            "preserveHierarchyInfo": true
        }
    },
    "callback": {
        "url": "https://client.example.com/webhooks/3chat/knowledge",
        "events": [
            "file.uploading",
            "file.parsing",
            "file.completed",
            "file.failed"
        ],
        "secret": "860CCCB3FF77A98CDE0722284B40A371"
    }
}'

返回响应

🟢200

application/json

任务创建成功

Bodyapplication/json

示例

{
    "code": 200,
    "message": "success",
    "requestId": "req_01K23P7R4M6W8Q9JAB",
    "data": {
        "taskId": "ktask_01K23P7W8D5N2X4QYZ",
        "status": "task.progress",
        "sourceSummary": {
            "total": 3,
            "accepted": 3,
            "rejected": 0
        },
        "parseConfig": {
            "extractImageElements": true,
            "parseScannedDocument": false,
            "language": "zh-CN",
            "normalizeWhitespaceAndLineBreaks": false,
            "removeUrlsAndEmails": false
        },
        "chunkConfig": {
            "mode": "hierarchical",
            "hierarchical": {
                "level": 1,
                "preserveHierarchyInfo": true
            }
        },
        "entitlement": {
            "resourceType": "knowledge_unit",
            "estimatedConsume": 3,
            "actualConsume": 0,
            "balanceRemain": 1000
        },
        "errors": [],
        "createdAt": 1776667072000
    }
}

🟠400

修改于 2026-05-08 06:12:05

上传文件

查询知识处理任务