开发者可以通过安装 Node.js SDK 的方式将百宝箱的 OpenAPI 集成到自有系统中,从而在外部系统中发起智能体对话。

前提条件

在调用 SDK 前,请先完成应用的发布。

环境准备

百宝箱 Node.js SDK 适用于 node.js 18 或以上版本,且支持大部分主流浏览器。开发者可以执行下述命令确认 node 版本。

# 查询node版本
node --version

# 返回的版本信息
v18.18.1

安装 SDK

开发者可以执行下述 npm 命令,安装 SDK。

npm install tbox-nodejs-sdk

或者访问 npm 官网 Tbox 主页查看最新内容。

调用 SDK

1. 初始化客户端

import { TboxClient } from 'tbox-nodejs-sdk';

const client = new TboxClient({
  httpClientConfig: {
    authorization: 'TBox-your-token-xxx'
  }
});

其中,各请求参数说明如下。

参数名必填类型说明示例
authorizationString用于验证客户端身份的访问令牌,你可以在百宝箱中获取,获取方式可参见:授权管理。-

2. 调用对话型应用

2.1. 流式调用

const stream = client.chat({
  appId: "your-app-id",
  query: "今天杭州天气怎么样?",
  userId: "user123"
});

stream.on('data', (data) => {
  console.log('Received data:', data);
});

stream.on('end', () => {
  console.log('Stream ended');
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

其中,各请求参数说明如下。

参数名必填类型说明示例
appIdString智能体唯一标识,需要替换为开发者在发布应用时,发布渠道上方显示的 AppID。-
queryString对话内容,可自定义输入“今天杭州天气怎么样?”
userIdString百宝箱用户 ID,由开发者自行定义以及维护的智能体用户 ID,无需在开放平台获取。-

EventEmitter 对象事件订阅说明如下。

  • data:接收到数据返回时触发;
  • error:发生错误时触发;
  • end:流结束时触发。

2.2. 常规调用

try {
  const response = await client.chatSync({
    appId: "your-app-id",
    query: "今天杭州天气怎么样?",
    userId: "user123"
  }, {
    sseFormat: true
  }); 
} catch (e) {
  console.error('Error', e)
}

其中,各请求参数说明如下。

参数名必填类型说明示例
appIdString智能体唯一标识,需要替换为开发者在发布应用时,发布渠道上方显示的 AppID。-
queryString对话内容,可自定义输入“今天杭州天气怎么样?”
userIdString百宝箱用户 ID,由开发者自行定义以及维护的智能体用户 ID,无需在开放平台获取。-
sseFormatBoolean是否格式化输出。- true:格式化输出; false:常规响应,默认值。false

返回参数说明:

  • 当 sseFormat 为 false 时,返回原始响应,返回示例可参见:默认标准返回。
  • 当 sseFormat 为 true 时,返回格式化后的响应,返回示例可参见:格式化返回。
    • chunk:解析后的 SSE chunk 数据;
    • think:解析后的 SSE think 数据;
    • raw:原始返回。

2.3. 返回示例

2.3.1. 默认标准返回(sseFormat = false)
#--------------------------------------------------------
#data: {'entity': {'node_type': 'output', 'execute_id': '2', 'node_name': '结束', 'node_id': 'output_isn9lm'}, 'lane': 'mvz20luv', 'payload': {'extraParams': {}, 'mediaType': 'text', 'name': '回答', 'requestId': '7a03c482-955d-4861-83c5-59024629ed26', 'sessionId': '20250523U1OO28836351'}, 'type': 'header'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '今天'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '杭州'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '的'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '天气就像是江南水墨'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '画,温婉'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '又带着几分朦胧'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '美。如果要'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '具体点说的话,'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '记得带上把小'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '伞哦,可能'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '偶尔会有几滴'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '细雨来添'}, 'type': 'chunk'}
#--------------------------------------------------------
#--------------------------------------------------------
#data: {'lane': 'mvz20luv', 'payload': {'text': '几分诗意呢!'}, 'type': 'chunk'}
#--------------------------------------------------------
2.3.2. 格式化返回(sseFormat = true)
{
  chunk: '今天杭州的天气像是大自然的心情,说变就变早上还阳光明媚,午后可能就有几朵调皮的云彩带来小雨点,记得带伞哦,别让这份突如其来的惊喜打湿了你的好心情!',
  think: '嗯,用户问的是今天杭州的天气怎么样,要求回答简洁生动现在杭州的时间是下午235分,所以我需要先确定今天的实际天气情况nn今天杭州应该是多云转晴的天气,早上有雾但下午放晴了,温度在2634度之间用户强调要生动活泼的回答,那就要避免枯燥的天气预报模式,而是营造画面感nn想到"秋老虎"这个词很贴切,可以突出晴热的特点"云雾纱衣"形容早晨的薄雾既诗意又形象结尾用阳光和西湖组合成"金箔洒满湖面"的意象,既有本地特色又能引发美好联想nn用户没有提供额外背景,但从简洁要求看可能是出行前快速查询,所以温度范围和时间特征(早凉午热)都要包含最后加个月亮符号增加一点活泼感,平衡实用性和趣味性n',
  raw: 'id:1nevent:messagendata:{"payload":"{"ext_data":{},"event":"flow.graph.start"}","type":"meta"}nnid:2nevent:messagendata:{"payload":"{"event":"flow.node.start","entity":{"node_type":"input","execute_id":"0","node_name":"开始","node_id":"input_hgtoen"}}","type":"meta"}nnid:3nevent:messagendata:{"payload":"{"ext_data":{"start_time":1752662013.4744685,"input_params":{"type":"json","value":{"currentChatByUser":"今天杭州天气怎么样?","currentChatRound":"1","requestId":"80c106d0-29a2-46f3-8c63-14017f49eb7d","conversationId":"20250716zLGg35257464","historyChat":[]}},"query":{"type":"text","value":"今天杭州天气怎么样?"},"end_time":1752662013.4792163},"event":"flow.node.end","entity":{"node_type":"input","execute_id":"0","node_name":"开始","node_id":"input_hgtoen"}}","type":"meta"}nnid:4nevent:messagendata:{"payload":"{"event":"flow.node.start","entity":{"node_type":"text-completion","execute_id":"1","node_name":"文本大模型","node_id":"text_completion_u27th0"}}","type":"meta"}nnid:5nevent:messagendata:{"payload":"{"event":"flow.node.start","entity":{"node_type":"output","execute_id":"2","node_name":"结束","node_id":"output_isn9lm"}}","type":"meta"}nnid:6nevent:messagendata:{"entity":{"node_type":"output","execute_id":"2","node_name":"结束","node_id":"output_isn9lm"},"lane":"output_isn9lm_text_1","payload":"{"extraParams":{},"mediaType":"text","requestId":"80c106d0-29a2-46f3-8c63-14017f49eb7d","sessionId":"20250716zLGg35257464"}","type":"header"}nnid:7nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"SDK 测试:"}","type":"chunk"}nnid:8nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"今天"}","type":"chunk"}nnid:9nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"杭州"}","type":"chunk"}nnid:10nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":""}","type":"chunk"}nnid:11nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"天气"}","type":"chunk"}nnid:12nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"像是大自然的心情,"}","type":"chunk"}nnid:13nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"说变就变"}","type":"chunk"}nnid:14nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"。早上还阳光"}","type":"chunk"}nnid:15nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"明媚,午后可能"}","type":"chunk"}nnid:16nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"就有几朵调皮"}","type":"chunk"}nnid:17nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"的云彩带来"}","type":"chunk"}nnid:18nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"小雨点,"}","type":"chunk"}nnid:19nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"记得带伞哦"}","type":"chunk"}nnid:20nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":",别让这份"}","type":"chunk"}nnid:21nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"突如其来的惊喜打"}","type":"chunk"}nnid:22nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"湿了你的好"}","type":"chunk"}nnid:23nevent:messagendata:{"lane":"output_isn9lm_text_1","payload":"{"text":"心情!"}","type":"chunk"}nnid:24nevent:messagendata:{"payload":"{"ext_data":{"run_id":"272d4f97c616434b83848303e4fa9ea3","usage":{"total_tokens":75,"output_tokens":50,"input_tokens":25}},"event":"flow.node.llm.end","entity":{"node_type":"text-completion","execute_id":"1","group_id":0,"parent_execute_id":"1","node_name":"文本大模型","node_id":"text_completion_u27th0"}}","type":"meta"}nnid:25nevent:messagendata:{"payload":"{"ext_data":{"start_time":1752662013.4981315,"model_name":"通义千问 • Max","output_type":"text","output_result":"今天杭州的天气像是大自然的心情,说变就变。早上还阳光明媚,午后可能就有几朵调皮的云彩带来小雨点,记得带伞哦,别让这份突如其来的惊喜打湿了你的好心情!","complete_time":1752662013.562182,"input_params":{"type":"json","value":{"currentChatByUser":"今天杭州天气怎么样?","currentChatRound":"1","requestId":"80c106d0-29a2-46f3-8c63-14017f49eb7d","conversationId":"20250716zLGg35257464","historyChat":[]}},"output_result_length":74,"input_prompt_length":0,"end_time":1752662017.4586399},"event":"flow.node.end","entity":{"node_type":"text-completion","execute_id":"1","node_name":"文本大模型","node_id":"text_completion_u27th0"}}","type":"meta"}nnid:26nevent:messagendata:{"payload":"{"ext_data":{"start_time":1752662013.5814104,"output_result_length":81,"end_time":1752662017.4764028},"event":"flow.node.end","entity":{"node_type":"output","execute_id":"2","node_name":"结束","node_id":"output_isn9lm"}}","type":"meta"}nnid:27nevent:messagendata:{"payload":"{"ext_data":{"start_time":1752662013.4624104,"end_time":1752662017.5004191},"event":"flow.graph.end"}","type":"meta"}nnid:28nevent:endndata:{"type":"end"}nn'
}

3. 调用生成型应用

3.1. 流式调用

const stream = client.completion({
  appId: "your-app-id",
  inputs: { feqeyrj5: '生成一个故事' },
  userId: 'user123'
})

stream.on('data', (response) => {
  console.log('Received completion data:', response);
})

stream.on('end', () => {
  console.log('Completion stream ended');
});

stream.on('error', (error) => {
  console.error('Error in completion:', error);
});

其中,请求参数说明详见下表。

参数名必填类型说明示例
AuthorizationString用于验证客户端身份的访问令牌,你可以在百宝箱中获取,获取方式可参见:授权管理。pat_2j4e******THUIVRH1
appIdString应用 ID,需要通过 API 进行集成的应用 ID。202506e******00450562
userIdString用户 ID。填入使用您产品的用户 ID。请尽量使用 OAID 或手机号,我们会根据此信息帮助您构建用户画像。-
queryString当应用类型为对话型应用时,必填。指用户发给智能体的问题内容。你好
inputsObject当应用类型为生成型应用时,必填。指用户发给智能体的内容。{"feqeyrj5":"生成一个故事"}
conversationIdString会话 ID,用于用户多轮对话时组装上下文信息。多轮对话时,按照SDK中之前返回的 conversationId 内容传入。
requestIdString请求 ID,主要用于失败重试时,标识上一次请求。uuid即可
withMetaBoolean是否接收百宝箱返回的meta 信息,默认为 False:不接收。False
clientPropertiesObject系统及环境变量参数。传入的 key 值请参考示例。如果你在对话型工作流应用中,开启了“系统及环境信息”中的变量开关(示例如下)
filesList文件列表,用于在对话中提供多模态(文档、图片、音频及视频)数据。**说明:**使用文件上传能力前,请先为智能体配置具有文件处理能力的大模型或插件。[{'type":“FILE", "fileId":"202502********001001"}]

3.2. 常规调用

const response = client.completionSync({
  appId: "your-app-id",
  inputs: { feqeyrj5: '生成一个故事' },
  userId: 'user123'
});
console.log(response);

其中,各请求参数说明如下。

参数名必填类型说明示例
AuthorizationString用于验证客户端身份的访问令牌,你可以在百宝箱中获取,获取方式可参见:授权管理。pat_2j4e******THUIVRH1
appIdString应用 ID,需要通过 API 进行集成的应用 ID。202506e******00450562
userIdString用户 ID。填入使用您产品的用户 ID。请尽量使用 OAID 或手机号,我们会根据此信息帮助您构建用户画像。-
queryString当应用类型为对话型应用时,必填。指用户发给智能体的问题内容。你好
inputsObject当应用类型为生成型应用时,必填。指用户发给智能体的内容。{"feqeyrj5":"生成一个故事"}
conversationIdString会话 ID,用于用户多轮对话时组装上下文信息。多轮对话时,按照SDK中之前返回的 conversationId 内容传入。
requestIdString请求 ID,主要用于失败重试时,标识上一次请求。uuid即可
withMetaBoolean是否接收百宝箱返回的meta 信息,默认为 False:不接收。False
clientPropertiesObject系统及环境变量参数。传入的 key 值请参考示例。如果你在对话型工作流应用中,开启了“系统及环境信息”中的变量开关(示例如下)
filesList文件列表,用于在对话中提供多模态(文档、图片、音频及视频)数据。**说明:**使用文件上传能力前,请先为智能体配置具有文件处理能力的大模型或插件。[{'type":“FILE", "fileId":"202502********001001"}]

3.3. 返回示例

'id:1nevent:messagendata:{"entity":{"node_type":"output","execute_id":"2","node_name":"结束","node_id":"output_isn9lm"},"lane":"pvmv10_y","payload":"{"extraParams":{"tboxData":{},"tboxType":"chatMessage.stream"},"mediaType":"text","name":"回答2","requestId":"579b480f-10ba-4720-a35f-f1cd4acb0d89","sessionId":"202509013Pnh43082939"}","type":"header"}nnid:2nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"西湖"}","type":"chunk"}nnid:3nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":""}","type":"chunk"}nnid:4nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":""}","type":"chunk"}nnid:5nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"柳如"}","type":"chunk"}nnid:6nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"烟,桥影"}","type":"chunk"}nnid:7nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"波光映画"}","type":"chunk"}nnid:8nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"船。n雷峰塔下"}","type":"chunk"}nnid:9nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"人声沸,一"}","type":"chunk"}nnid:10nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"曲笙歌醉晚"}","type":"chunk"}nnid:11nevent:messagendata:{"lane":"pvmv10_y","payload":"{"text":"天。"}","type":"chunk"}nnid:12nevent:endndata:{"type":"end"}'

4. 文件上传

4.1. 浏览器端调用

const fileInput = document.querySelector('input[type=file]');
fileInput. addEventListener('change', async () => {
const file = fileInput.files[0];
const response = await client.uploadFile(file);
console.log(response);
}) ;

其中,各参数说明如下。

参数名必填类型说明示例
fileBlob文件对象-
filenameString文件名称,当文件对象非 file 类型时,需要提供。-

4.2. Node.js 端调用

import { readFileSync } from 'node:fs';

const file = new Blob([readFileSync('local-file-path')]);
const response = await client.uploadFile(file, 'local-filename');
console.log(response);

其中,各参数说明如下。

参数名必填类型说明示例
fileBlob文件对象-
filenameString文件名称,当文件对象非 file 类型时,需要提供。-

4.3. 返回示例

{"code":"10000","data":"20250901orLH08254074","errorCode":"0","errorMsg":"success","msg":"Success","traceId":"0a4200d317567088002188358e6be4"}

5. 知识库管理

5.1. 创建知识库

const response = await client.createDatasets({
  name: 'new dataset name',
  description: 'new dataset description'
});
console.log(response);
5.1.1. 请求参数
参数名必填类型说明示例
nameString自定义知识库名称,最多支持输入 50 个字符。**说明:**知识库名称需在租户内保持唯一。demo知识库
descriptionString自定义知识库描述,最多支持输入 100 个字符这是一个demo知识库
5.1.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataString创建的知识库 ID。202508059********063
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.1.3. 返回示例
{
    "data": "202508059********063",
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b****4d9"
}
{
    "errorCode": "P_1_06_384",
    "errorMsg": "知识库名称已存在",
    "solution": "请更换知识库名称",
    "traceId": "0b446a1717543623264013347e386f"
}

5.2. 查询知识库列表

const response = await client.listDatasets({
  pageNum: 1,
  pageSize: 10
});
console.log(response);
5.2.1. 请求参数
参数名必填类型说明示例
pageNumInteger分页页码,默认为 1,从第一页数据开始返回。1
pageSizeInteger分页大小,默认为 10,最大为 50。10
5.2.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataPageObject知识库列表信息。-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.2.2.1. data 定义
参数名类型说明
currentPageInteger当前页
datasetsList知识库文件对象列表。
pageSizeInteger分页大小
totalInteger列表总数
5.2.2.2. datasets 定义
参数名类型说明
datasetIdString知识库 ID
descriptionString知识库描述
nameString知识库名称
storeSizeDouble知识库存储大小
5.2.3. 返回示例
{
    "data": {
        "currentPage": 1,
        "datasets": [
            {
                "datasetId": "202508059lUk00458063",
                "description": "测试2",
                "name": "测试1",
                "storeSize": 0.0
            },
            {
                "datasetId": "20250804tpAo00457894",
                "description": "测试2",
                "name": "测试2",
                "storeSize": 7808.0
            }
        ],
        "pageSize": 20,
        "total": 2
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b446a1717543635033032613e386f"
}
{
    "errorCode": "P_1_00_005",
    "errorMsg": "pageSize不能大于50",
    "solution": "请确认参数值是否正确!",
    "traceId": "0be8c63017543648690345786e1a1c"
}

5.3. 创建知识库文档

const response = await client.createDatasetDocument({
  datasetId: 'your-dataset-id',
  fileId: 'your-file-id',
});
console.log(response);
5.3.1. 请求参数
参数名必填类型说明示例
datasetIdString知识库 ID,指文件上传的目标知识库 ID。2555****sdf
fileIdString文件 ID,通过文件上传 API 或 SDK 上传文件时返回的文件标识。2156****112
5.3.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataString目标知识库 ID。202508059********063
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.3.3. 返回示例
{
    "data": "20250805****9457696",
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b446a1f17543847325624439e41a7"
}
{
    "errorCode": "P_1_06_361",
    "errorMsg": "不存在知识库",
    "solution": "请检查datasetId是否输错",
    "traceId": "1ee603881754385338419138937634"
}

5.4. 查询文档构建进度

const response = await client.queryDocumentProgress({
  documentId: 'your-document-id',
});
console.log(response);
5.4.1. 请求参数
参数名必填类型说明示例
documentIdString查询目标文件的 ID。2025****5552
5.4.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataDocumentProcess查询的文件构建详情。-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.4.2.1. data 定义
参数名类型说明示例
statusString文件构建状态,包含:- INIT:初始化 HANDLING:处理中 SUCCESS:构建成功 FAILED:构建失败SUCCESS
errorMsgString文件构建失败原因,仅当 status = FAILED 时返回。文档分段失败:excel文件解析异常,请检查文件内容后重试
5.4.3. 返回示例

请求成功且文件构建成功

{
    "data": {
        "status": "SUCCESS"
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0be8ed2517543866585838625e231f"
}

请求成功但文件构建失败

{
    "data": {
        "errorMsg": " 文档分段失败:excel文件解析异常,请检查文件内容后重试",
        "status": "FAILED"
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0be8ed2317543870606746859e39cb"
}

请求失败

{
    "errorCode": "P_1_06_385",
    "errorMsg": "知识库文档不存在",
    "solution": "请检查documentId是否输错",
    "traceId": "1ee603881754378335441132526365"
}

5.5. 查询知识库文档列表

const response = await client.listDatasetDocuments({
  datasetId: 'your-dataset-id',
  pageNum: 1,
  pageSize: 10
});
5.5.1. 请求参数
参数名必填类型说明示例
datasetIdString知识库 ID,指文件所在的目标知识库 ID。2555****sdf
pageNumInteger分页页码,默认为 1,从第一页数据开始返回。1
pageSizeInteger分页大小,默认为 10,最大为 50。10
5.5.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataPageObject知识库文件列表。-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.5.2.1. data 定义
参数名类型说明
currentPageInteger当前页
documentsList知识库文件对象列表。
pageSizeInteger分页大小
totalInteger列表总数
5.5.2.2. documents 定义
参数名类型说明
documentIdString文件 ID
nameString文件名
storeSizeDouble知识库存储大小
wordCountDouble文件大小
5.5.3. 返回示例

成功示例

{
    "data": {
        "currentPage": 1,
        "documentsList": [
            {
                "documentId": "20250805edFX7629458673",
                "name": "千岛湖.docx",
                "storeSize": 7808.0,
                "wordCount": 2286
            }
        ],
        "pageSize": 50,
        "total": 1
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b446a1717543881293953712e3875"
}

失败示例

{
    "errorCode": "P_1_00_005",
    "errorMsg": "pageSize不能大于50",
    "solution": "请确认参数值是否正确!",
    "traceId": "0be8c63017543648690345786e1a1c"
}

5.6. 删除知识库文档

const response = await client.deleteDatasetDocument({
  documentId: 'your-document-id',
});
console.log(response);
5.6.1. 请求参数
参数名必填类型说明示例
documentIdString知识库内指定文件 ID。2025****58063
5.6.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.6.3. 返回示例

成功示例

{
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0be8ed2317543652744847731e39a7"
}

返回示例

{
    "errorCode": "P_1_06_385",
    "errorMsg": "知识库文档不存在",
    "solution": "请检查documentId是否输错",
    "traceId": "1ee603881754378335441132526365"
}

5.7. 检索知识库内容

const response = await client.retrieveDataset({
  datasetId: 'your-dataset-id',
  query: 'query something',
  limit: 5,
});
console.log(response);
5.7.1. 请求参数
参数名必填类型说明示例
queryString查询内容库存商品
datasetIdString目标知识库 ID2025****58063
limitInterger返回召回内容的条数,默认是 5,上限是 105
5.7.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataList召回对象信息。-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.7.2.1. data 定义
参数名类型说明
contentString召回内容
originFileNameString原始文件名
scoreDouble关联度分
5.7.3. 返回示例

成功示例

{
    "data": [
        {
            "content": "{"商品名称":"猫粮","订单号":"","快递公司":"顺丰","省市区":"浙江省杭州市西湖区","订单编号":"1.0","收货人姓名":"","收货人电话号码":"","详细收货地址":"shippingAddress"}",
            "originFileName": "订单信息.xlsx",
            "score": 0.06375612
        }
    ],
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b446a3117543806882455710e5f2c"
}

失败示例

{
    "errorCode": "P_1_00_005",
    "errorMsg": "query不能为空",
    "solution": "请确认参数值是否正确!",
    "traceId": "0be8c63017543810866326652e1a1e"
}

5.8. 删除知识库

const response = await client.deleteDataset({
  datasetId: 'your-dataset-id',
});
console.log(response);
5.8.1. 请求参数
参数名必填类型说明示例
datasetIdString目标知识库 ID2025****58063
5.8.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
5.8.3. 返回示例

成功示例

{
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0be8ed2317543652744847731e39a7"
}

失败示例

{
    "errorCode": "P_1_06_361",
    "errorMsg": "不存在知识库",
    "solution": "请检查datasetId是否输错",
    "traceId": "1ee603881754378335441132526365"
}

6. 插件管理

6.1. 获取官方插件列表

const response = await client.getOfficialPlugins({
  pluginType: 'UTILITY_TOOL',
  pageNum: 1,
  pageSize: 20,
});
console.log(response);
6.1.1. 请求参数
参数名必填类型说明示例
pluginTypeEnum插件类别,不传查询全部插件,枚举值包括:- 实用工具:UTILITY_TOOL 生活服务: LIFE_SERVICE 内容搜索:CONTENT_SEARCH MCP工具:MCP_TOOLUTILITY_TOOL
pageNumInteger分页页码,默认为1,从第一页数据开始返回1
pageSizeInteger分页大小,默认为 20,最大为 2020
6.1.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataQueryPluginResult插件查询结果对象。-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
6.1.2.1. data 定义
参数名类型说明
pluginsList插件详情
currentPageInterger当前页码
pageSizeInterger分页大小
totalInterger总数据量
6.1.2.2. plugins 定义
参数名类型说明
pluginIdString插件 ID
nameString插件名称
descriptionString插件描述
pluginTypeEnum官方插件类别,枚举值包含:- 实用工具:UTILITY_TOOL 生活服务:LIFE_SERVICE 内容搜索:CONTENT_SEARCH MCP工具:MCP_TOOL
toolTypeEnum插件内工具所属类别,枚举值包含:- 基于已有服务创建的插件:OPENAPI 基于百宝箱 IDE 创建的插件:CLOUD_FUNCTION MCP 服务:MCP
avgExecTimeDouble平均执行时间,单位:毫秒
citationCountInteger当前插件被智能体引用次数
successRateDouble智能体调用成功率
toolCountInteger插件内部包含的工具数
toolsList工具详情
6.1.2.3. tools 定义
参数名类型说明
pluginToolIdString工具 ID
nameString工具名称
descriptionString工具描述
streamBoolean是否支持流式返回
avgExecTimeDouble平均执行时间,单位:毫秒
citationCountInteger当前工具被智能体引用次数
successRateDouble智能体调用成功率
inputParamsList当前工具的入参定义
outputParamsList当前工具的出参定义
6.1.2.4. paramsSchema 定义
参数名类型说明
nameString参数名
descriptionString参数描述
requiredBoolean是否必传
inEnum参数位置,仅 OPENAPI 插件有。枚举值包含:- body:请求体参数 path:路径参数 query:查询参数 header:请求头参数
schemaSchema参数结构
6.1.2.5. schema 定义
参数名类型说明
typeString参数类型,包括:- string:字符串 integer:整数 number:浮点数 boolean:布尔值 object:对象 array:数组
enumList枚举值,约束参数在一定范围内取值
defaultObject默认值
propertiesMap<String, Properties>- key:参数名 value:Properties仅 object 类型有,用来表示对象中每一个属性的结构
requiredList仅 object 类型有,参数名集合,表示必传的参数
itemsItems仅 array 类型有,用来定义数组中元素的约束
6.1.2.6. properties 定义

说明: 当前内容仅针对 Object 类型的参数,用来表示 Object 对象中每一个属性的结构。

参数名类型说明
typeString参数类型,包括:- string:字符串 integer:整数 number:浮点数 boolean:布尔值 object:对象 array:数组
enumList枚举值,约束参数在一定范围内取值
defaultObject默认值
propertiesMap<String, Properties>- key:参数名 value:Properties仅 object 类型有,用来表示对象中每一个属性的结构。
requiredList仅 object 类型有,参数名集合,表示必传的参数
itemsItems仅 array 类型有,用来定义数组中元素的约束。
6.1.2.7. items 定义
参数名类型说明
typeString参数类型,包括:- string:字符串 integer:整数 number:浮点数 boolean:布尔值 object:对象 array:数组
propertiesMap<String, Properties>- key:参数名 value:Properties仅 object 类型有,用来表示对象中每一个属性的结构。
requiredList仅 object 类型有,参数名集合,表示必传的参数
6.1.3. 返回示例

成功示例

{
    "data": {
        "currentPage": 1,
        "pageSize": 1,
        "plugins": [
            {
                "avgExecTime": 1609.0,
                "citationCount": 13828,
                "description": "利用夸克搜索引擎搜索相关内容,可以根据提示词要求来返回链接等信息。如:关于 OpenAI 有什么新闻?",
                "name": "夸克搜索",
                "pluginId": "20240611204300000001",
                "pluginType": "CONTENT_SEARCH",
                "successRate": 0.995,
                "toolCount": 3,
                "toolType": "OPENAPI",
                "tools": [
                    {
                        "avgExecTime": 1292.0,
                        "citationCount": 13443,
                        "description": "利用夸克搜索引擎搜索相关内容,可以根据提示词要求来返回链接等信息。如:关于 OpenAI 有什么新闻?",
                        "inputParams": [
                            {
                                "description": "搜索内容",
                                "in": "body",
                                "name": "q",
                                "required": true,
                                "schema": {
                                    "type": "string"
                                }
                            }
                        ],
                        "name": "夸克搜索",
                        "outputParams": [
                            {
                                "description": "搜索结果",
                                "name": "data",
                                "schema": {
                                    "items": {
                                        "properties": {
                                            "hostName": {
                                                "description": "站点名(可空)",
                                                "type": "string"
                                            },
                                            "publishTime": {
                                                "description": "发布时间",
                                                "type": "string"
                                            },
                                            "extra": {
                                                "description": "其它信息",
                                                "properties": {
                                                    "extraUrl": {
                                                        "description": "链接",
                                                        "type": "string"
                                                    },
                                                    "domain": {
                                                        "description": "来源",
                                                        "type": "string"
                                                    },
                                                    "sort": {
                                                        "description": "排序",
                                                        "type": "number"
                                                    },
                                                    "extraTitle": {
                                                        "description": "标题",
                                                        "type": "string"
                                                    }
                                                },
                                                "type": "object"
                                            },
                                            "channel": {
                                                "description": "输出平台",
                                                "type": "string"
                                            },
                                            "articleId": {
                                                "description": "数据ID",
                                                "type": "string"
                                            },
                                            "title": {
                                                "description": "标题",
                                                "type": "string"
                                            },
                                            "url": {
                                                "description": "网页地址",
                                                "type": "string"
                                            },
                                            "desc": {
                                                "description": "描述信息",
                                                "type": "string"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "type": "array"
                                }
                            },
                            {
                                "description": "请求结果",
                                "name": "success",
                                "schema": {
                                    "type": "boolean"
                                }
                            },
                            {
                                "description": "响应信息",
                                "name": "msg",
                                "schema": {
                                    "type": "string"
                                }
                            },
                            {
                                "description": "响应状态码",
                                "name": "code",
                                "schema": {
                                    "type": "number"
                                }
                            }
                        ],
                        "pluginToolId": "20240611204600000001",
                        "stream": false,
                        "successRate": 0.99
                    },
                    {
                        "citationCount": 0,
                        "description": "利用夸克搜索引擎搜索相关内容,可以根据提示词要求来返回链接等信息。如:关于 OpenAI 有什么新闻?",
                        "inputParams": [
                            {
                                "description": "搜索内容",
                                "in": "body",
                                "name": "q",
                                "required": true,
                                "schema": {
                                    "type": "string"
                                }
                            }
                        ],
                        "name": "新版夸克搜索",
                        "outputParams": [
                            {
                                "description": "traceId",
                                "name": "traceId",
                                "schema": {
                                    "type": "string"
                                }
                            },
                            {
                                "description": "响应信息",
                                "name": "msg",
                                "schema": {
                                    "type": "string"
                                }
                            },
                            {
                                "description": "响应状态码",
                                "name": "code",
                                "schema": {
                                    "type": "number"
                                }
                            },
                            {
                                "description": "搜索结果",
                                "name": "data",
                                "schema": {
                                    "items": {
                                        "properties": {
                                            "hostName": {
                                                "description": "站点名(可空)",
                                                "type": "string"
                                            },
                                            "publishTime": {
                                                "description": "发布时间",
                                                "type": "string"
                                            },
                                            "extra": {
                                                "description": "其它信息",
                                                "properties": {
                                                    "extraUrl": {
                                                        "description": "链接",
                                                        "type": "string"
                                                    },
                                                    "domain": {
                                                        "description": "来源",
                                                        "type": "string"
                                                    },
                                                    "extraTitle": {
                                                        "description": "标题",
                                                        "type": "string"
                                                    },
                                                    "sort": {
                                                        "description": "排序",
                                                        "type": "number"
                                                    }
                                                },
                                                "type": "object"
                                            },
                                            "channel": {
                                                "description": "输出平台",
                                                "type": "string"
                                            },
                                            "articleId": {
                                                "description": "数据ID",
                                                "type": "string"
                                            },
                                            "title": {
                                                "description": "标题",
                                                "type": "string"
                                            },
                                            "url": {
                                                "description": "网页地址",
                                                "type": "string"
                                            },
                                            "desc": {
                                                "description": "描述信息",
                                                "type": "string"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "type": "array"
                                }
                            },
                            {
                                "description": "请求结果",
                                "name": "success",
                                "schema": {
                                    "type": "boolean"
                                }
                            }
                        ],
                        "pluginToolId": "20250526JVW706618482",
                        "stream": false
                    },
                    {
                        "avgExecTime": 1925.0,
                        "citationCount": 385,
                        "description": "利用夸克搜索引擎搜索相关内容,可以根据提示词要求来返回链接等信息,搜索结果中包含文章的正文字段。如:关于 OpenAI 有什么新闻?",
                        "inputParams": [
                            {
                                "description": "搜索内容",
                                "in": "body",
                                "name": "q",
                                "required": true,
                                "schema": {
                                    "type": "string"
                                }
                            }
                        ],
                        "name": "夸克搜索(含正文)",
                        "outputParams": [
                            {
                                "description": "响应状态码",
                                "name": "code",
                                "schema": {
                                    "type": "number"
                                }
                            },
                            {
                                "description": "搜索结果",
                                "name": "data",
                                "schema": {
                                    "items": {
                                        "properties": {
                                            "publishTime": {
                                                "description": "发布时间",
                                                "type": "string"
                                            },
                                            "hostName": {
                                                "description": "站点名(可空)",
                                                "type": "string"
                                            },
                                            "extra": {
                                                "description": "其它信息",
                                                "properties": {
                                                    "extraUrl": {
                                                        "description": "链接",
                                                        "type": "string"
                                                    },
                                                    "domain": {
                                                        "description": "来源",
                                                        "type": "string"
                                                    },
                                                    "extraTitle": {
                                                        "description": "标题",
                                                        "type": "string"
                                                    },
                                                    "sort": {
                                                        "description": "排序",
                                                        "type": "number"
                                                    }
                                                },
                                                "type": "object"
                                            },
                                            "channel": {
                                                "description": "输出平台",
                                                "type": "string"
                                            },
                                            "articleId": {
                                                "description": "数据id",
                                                "type": "string"
                                            },
                                            "title": {
                                                "description": "标题",
                                                "type": "string"
                                            },
                                            "url": {
                                                "description": "网页地址",
                                                "type": "string"
                                            },
                                            "content": {
                                                "description": "正文",
                                                "type": "string"
                                            },
                                            "desc": {
                                                "description": "描述信息",
                                                "type": "string"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "type": "array"
                                }
                            },
                            {
                                "description": "描述简介",
                                "name": "success",
                                "schema": {
                                    "type": "boolean"
                                }
                            },
                            {
                                "description": "响应信息",
                                "name": "msg",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        ],
                        "pluginToolId": "20250528mgnR06685343",
                        "stream": false,
                        "successRate": 1.0
                    }
                ]
            }
        ],
        "total": 17
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0b44******1814"
}

失败示例

{
    "errorCode": "P_1_00_005",
    "errorMsg": "不合法的插件类型",
    "solution": "请检查入参:pluginType是否有效"
}

6.2. 调用插件工具

const response = await client.invokePlugin({
  pluginToolId: 'official-plugin-tool-id',
  params: {
    key: 'value',
  },
});
console.log(response);
6.2.1. 请求参数
参数名必填类型说明示例
pluginToolIdString工具 ID,由查询官方插件列表接口获取。-
paramsMap<String, Object>- key: 参数名 value:参数值工具调用所需参数,由查询官方插件列表接口获取。-
6.2.2. 返回参数
参数名类型说明示例
errorCodeString错误码,为 0 表示成功。0
errorMsgString错误信息。success
dataToolResponse插件调用结果详情-
traceIdString本次请求的唯一标识,通常用于发生错误时的排查定位。0b****4d9
6.2.2.1. data 定义
参数名类型说明
successBoolean是否调用成功
responseObject工具响应结果,结构请参考查询官方插件列表接口获取的工具输出参数定义。
6.2.3. 返回示例

成功示例

{
    "data": {
        "response": {
            "msg": "操作成功",
            "code": 0,
            "data": [
                {
                    "hostName": "",
                    "publishTime": "1755355752",
                    "extra": {
                        "extraUrl": "https://www.jinjia.com.cn/",
                        "domain": "quark",
                        "sort": 0,
                        "extraTitle": "金价网-今日金价查询表"
                    },
                    "channel": "quark",
                    "articleId": "quark_f9bc6e9d934638a361ec0bc85042aef2",
                    "title": "金价网-今日金价查询表",
                    "url": "https://www.jinjia.com.cn/",
                    "desc": "金价网是一个专业的黄金价格查询平台,提供黄金市场行情,包括国际国内黄金、今日金价、上海黄金、银行黄金价格、香港黄金价格行情行情等内容,全力为广大投资者提供黄金的信息服务。"
                },
                {
                    "hostName": "",
                    "publishTime": "1755579111",
                    "extra": {
                        "extraUrl": "https://www.jinrijinjia.cn/",
                        "domain": "quark",
                        "sort": 1,
                        "extraTitle": "今日黄金价格查询_现在金价黄金多少钱一克_国际金价实时行情_黄金金价网"
                    },
                    "channel": "quark",
                    "articleId": "quark_c1643b6a5b01737aa37ff505fcdee306",
                    "title": "今日黄金价格查询_现在金价黄金多少钱一克_国际金价实时行情_黄金金价网",
                    "url": "https://www.jinrijinjia.cn/",
                    "desc": "国内金价 778.61 -9.58 -1.22% 788.30 777.00 788.00 788.19 克/人民币 国内银价 9388.00 -87.00 -0.92% 9498.00 9355.00 9474.00 9475.00 千克/人民币 24小时黄金实时快讯 2025年7月23日黄金价格多少钱一克今日查询"
                },
                {
                    "hostName": "",
                    "publishTime": "1755404286",
                    "extra": {
                        "extraUrl": "http://guojijinjia.com/",
                        "domain": "quark",
                        "sort": 2,
                        "extraTitle": "国际金价_今日金价实时行情最新黄金价格查询"
                    },
                    "channel": "quark",
                    "articleId": "quark_bf6d40e5c901948bc8c67979df037da5",
                    "title": "国际金价_今日金价实时行情最新黄金价格查询",
                    "url": "http://guojijinjia.com/",
                    "desc": "伦敦金价现货走势图纽约黄金期货走势图中国上海黄金走势图今日国际金价行情使用说明提供今天黄金即时价格走势查询,实时报价更..."
                },
                {
                    "hostName": "",
                    "publishTime": "1755273600",
                    "extra": {
                        "extraUrl": "http://www.huangjinjiage.cn/golden/113761.html",
                        "domain": "quark",
                        "sort": 3,
                        "extraTitle": "国内金价实时查询(24小时行情走势图|回收价格|今日价格)金价查询网"
                    },
                    "channel": "quark",
                    "articleId": "quark_20c83ec8f20e02af69f8ca74b3e828d7",
                    "title": "国内金价实时查询(24小时行情走势图|回收价格|今日价格)金价查询网",
                    "url": "http://www.huangjinjiage.cn/golden/113761.html",
                    "desc": "国内金价今日多少钱一克?提供国内金价实时查询、国内金价行情走势图、国内金价回收多少钱一克、国内金价最低多少钱一克等国内金价今天什么价格查询。今日国内金价实时查询黄金品种回收价格销售..."
                },
                {
                    "hostName": "",
                    "publishTime": "1755273600",
                    "extra": {
                        "extraUrl": "http://www.huangjinjiage.cn/jinrijinjia.html",
                        "domain": "quark",
                        "sort": 4,
                        "extraTitle": "今日金价(实时更新)黄金价格今日多少钱一克_金价查询网"
                    },
                    "channel": "quark",
                    "articleId": "quark_0cc918acaf7b8c7ef28607741439a2c1",
                    "title": "今日金价(实时更新)黄金价格今日多少钱一克_金价查询网",
                    "url": "http://www.huangjinjiage.cn/jinrijinjia.html",
                    "desc": "本页面提供今日金价在线查询,包括国际金价、国内金价、今日金价、上海黄金价格、银行黄金价格、金店黄金价格、黄金回收价格等实时行情报价。黄金价格今日实时报价名称卖出价格今日价格最高价格最低价格价格..."
                },
                {
                    "hostName": "",
                    "publishTime": "1755273600",
                    "extra": {
                        "extraUrl": "http://www.huangjinjiage.cn/quote/113124.html",
                        "domain": "quark",
                        "sort": 5,
                        "extraTitle": "金价国际今日价格(走势图|24小时实时|金条价格|回收)金价查询网"
                    },
                    "channel": "quark",
                    "articleId": "quark_cbf5cbd99ca272cf052d5bc5b8bb1541",
                    "title": "金价国际今日价格(走势图|24小时实时|金条价格|回收)金价查询网",
                    "url": "http://www.huangjinjiage.cn/quote/113124.html",
                    "desc": "提供黄金金价国际今日价格在线查询,通过走势图实时了解金价的变化,还提供金条价格和回收价格的最新报价查询,无论你是购买黄金、投资黄金还是回收黄金,在这里都可以查到实时金价行情。金价..."
                }
            ],
            "success": true
        }
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0be8*******e477"
}

失败示例

{
    "errorCode": "P_1_03_200",
    "errorMsg": "必传参数缺少参数值",
    "solution": ""
}
本站提供的所有下载资源均来自互联网,仅提供学习交流使用,版权归原作者所有。如需商业使用,请联系原作者获得授权。 如您发现有涉嫌侵权的内容,请联系我们 邮箱:[email protected]