Skip to main content

文件、目录与文本导入

将文件、网页或文本写入知识库,并管理其名称和处理状态。本页使用平台 API Key。读取要求 knowledge_file=READ;写入要求 WRITE;预览接口按 knowledge_preview 权限单独授权。

选择导入流程

需求接口顺序保存的标识
直接批量导入文件importFiles → 查询文件状态 → 检索验证返回每个文件的 code
先确认预览再入库upload/preview 或 web → addFiles → 查询文件临时 dataId 用于提交,入库后再取得文件 code
抓取网页并直接入库importWebs → 文件列表 → 状态查询入库后的文件 code
写入业务系统已有文本text → 状态查询data.code
整理目录directory → 使用其 code 作为 parentCodedata.code

预览成功不等于入库成功,入库成功不等于解析、索引或准入发布完成。需要原文/分片读取时见 文件查询。上传仅使用有权处理的文件和网址;容量、格式支持和网关体积限制以目标部署为准。

分页查询知识资源

GET /openapi/paas/v1/knowledge/file/list

列出知识库中的文件、目录、文本或 QA,Query 参数如下。

权限:knowledge_file=READ

请求参数

参数JSON/表单类型必填说明
pageNointeger当前页,默认 1
pageSizeinteger每页条数,默认 10
containerIdstring建议填写知识库 code
parentCodestring父目录 code
eleNamestring名称模糊查询
categorystring资源类别,使用实际返回枚举
processStatusinteger处理状态,例如 0 未处理、20 完成、30 失败
enableinteger启用状态
includeRelationTypeboolean是否返回 Agent 来源类型,默认 false

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/file/list" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "containerId=partner_kb_001" \
--data-urlencode "pageNo=1" \
--data-urlencode "pageSize=10"

响应字段

顶层使用 分页响应

字段JSON 类型说明
dataarray[object]字段完整定义见 响应数据字典;示例只保留业务所需字段
data[].idinteger资源数字主键
data[].codestring文件/文本业务编码
data[].containerIdstring所属知识库 code
data[].eleNamestring资源名称
data[].eleSizeinteger / null文件大小,字节
data[].processStatusinteger / null处理状态:0 未处理、20 完成、30 失败;其他处理中阶段按实际值处理
data[].errorMessagestring / null处理失败提示,可空

响应示例

{
"code": 8200,
"message": "SUCCESS",
"pageNo": 1,
"pageSize": 10,
"total": 1,
"totalPage": 1,
"data": [
{
"id": 1001,
"code": "partner_file_001",
"containerId": "partner_kb_001",
"eleName": "产品白皮书.pdf",
"eleSuffix": "pdf",
"eleSize": 102400,
"processStatus": 0,
"processPercent": 0
}
]
}

字段完整定义见 KnowledgeElement。编码精确定位优先使用 文件精确查询,不要依赖名称模糊查询始终返回唯一结果。

创建目录

POST /openapi/paas/v1/knowledge/file/directory

在指定知识库内创建目录,用来组织后续文件。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
namestring目录名称
containerIdstring知识库 code
parentCodestring父目录 code,顶级为 0

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/directory" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"name": "产品资料",
"containerId": "partner_kb_001",
"parentCode": "0"
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataobject字段完整定义见 响应数据字典;示例只保留业务所需字段
data.codestring新目录业务编码
data.namestring目录名称
data.parentCodestring父目录编码
data.containerCodestring所属知识库 code,注意字段名
data.urlstring / null目录资源地址,可空

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": {
"code": "partner_dir_001",
"name": "产品资料",
"url": null,
"parentCode": "0",
"containerCode": "partner_kb_001"
}
}

返回字段 containerCode 与多数文件响应的 containerId 名称不同。使用新目录 code 作为导入请求 parentCode。

新增文本知识

POST /openapi/paas/v1/knowledge/file/text

把已有文本写入知识库,无需构造文件流。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
containerIdstring知识库 code,不是数字主键
parentCodestring父目录 code,默认 0
neverExpireinteger1 永久有效,0 限定有效期
startTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
endTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
namestring文本标题,非空
contentstring文本内容,非空
originContentstring原始富文本;传入时可能参与 Markdown 转换,应与正文一致

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/text" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"containerId": "partner_kb_001",
"parentCode": "0",
"neverExpire": 1,
"name": "产品部署要求",
"content": "请按项目交付方案准备运行环境。"
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataobject字段完整定义见 响应数据字典;示例只保留业务所需字段
data.idinteger资源数字主键
data.codestring文件/文本业务编码
data.containerIdstring所属知识库 code
data.eleNamestring资源名称
data.eleSizeinteger / null文件大小,字节
data.processStatusinteger / null处理状态:0 未处理、20 完成、30 失败;其他处理中阶段按实际值处理
data.errorMessagestring / null处理失败提示,可空

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": {
"id": 1002,
"code": "partner_text_001",
"containerId": "partner_kb_001",
"eleName": "产品部署要求",
"answer": "请按项目交付方案准备运行环境。",
"processStatus": 0
}
}

保存 data.code。若设置有限有效期,明确传入起止时间;不把空字符串当有效日期。

上传文件并预览

POST /openapi/paas/v1/knowledge/file/upload/preview

上传文件并生成有限预览,不创建最终知识库文件。使用 multipart/form-data。

权限:knowledge_preview=WRITE

请求参数

参数JSON/表单类型必填说明
filefile[]文件流,可重复 file 字段上传多个文件
containerIdstring知识库 code;用于预览处理上下文,不可省略

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/upload/preview" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--form "containerId=partner_kb_001" \
--form "file=@/path/to/product.pdf"

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataobject字段完整定义见 响应数据字典;示例只保留业务所需字段
data.dataIdstring临时预览批次标识,用于提交导入
data.responsesarray[object]各文件预览结果
data.responses[].eleNamestring文件名称
data.responses[].eleMd5string / null文件摘要,用于提交时排除指定文件
data.responses[].statusboolean单个文件是否预览成功
data.responses[].errorMsgstring / null单文件失败原因
data.responses[].chunksarray[object]有限预览片段,非完整分片列表

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": {
"dataId": "preview_batch_001",
"responses": [
{
"category": "FILES",
"eleName": "产品白皮书.pdf",
"eleSuffix": "pdf",
"eleUrl": "https://example.com/preview/product.pdf",
"eleSize": 102400,
"tokenSize": 1200,
"eleMd5": "example-md5",
"pageCount": 1,
"status": true,
"errorMsg": null,
"chunks": [
{
"page": 1,
"content": "产品部署要求。",
"tokenSize": 7
}
]
}
]
}
}

同时检查 data.responses[].status。外层 8200 只说明预览请求得到处理,不代表所有文件均成功。临时 dataId 用于下一步 addFiles,不能拿它调用文件精确查询。

预览网页内容

POST /openapi/paas/v1/knowledge/file/web

抓取允许访问的 HTTP/HTTPS 网页并预览,尚未导入知识库。

权限:knowledge_preview=READ

请求参数

参数JSON/表单类型必填说明
containerIdstring知识库 code
urlsarray[object]非空网页列表
urls[].urlstringhttp:// 或 https:// 网页地址
urls[].selectorstringCSS 选择器,限定提取区域
limitinteger预览块数量配置,默认 10;不是最终完整分片数

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/web" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"containerId": "partner_kb_001",
"urls": [
{
"url": "https://example.com/product",
"selector": "main"
}
],
"limit": 10
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataobject字段完整定义见 响应数据字典;示例只保留业务所需字段
data.dataIdstring临时预览批次标识,用于提交导入
data.responsesarray[object]各文件预览结果
data.responses[].eleNamestring文件名称
data.responses[].eleMd5string / null文件摘要,用于提交时排除指定文件
data.responses[].statusboolean单个文件是否预览成功
data.responses[].errorMsgstring / null单文件失败原因
data.responses[].chunksarray[object]有限预览片段,非完整分片列表

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": {
"dataId": "preview_web_001",
"responses": [
{
"category": "WEB",
"eleName": "产品介绍",
"eleSuffix": "html",
"status": true,
"errorMsg": null,
"chunks": [
{
"page": 1,
"content": "产品介绍内容",
"tokenSize": 6
}
]
}
]
}
}

网址须可从 AIS 服务端访问;网页认证、反爬或空选择器结果可能使预览失败。先验证 responses 条目状态,再提交导入。

提交预览结果入库

POST /openapi/paas/v1/knowledge/file/addFiles

提交已成功预览的数据集,创建知识资源。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
containerIdstring知识库 code,不是数字主键
parentCodestring父目录 code,默认 0
neverExpireinteger1 永久有效,0 限定有效期
startTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
endTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
dataSetsarray[object]待导入预览批次列表
dataSets[].dataIdstring预览响应 data.dataId
dataSets[].fileNamestring覆盖该批次导入文件的展示名称,谨慎用于多文件批次
dataSets[].deleteFilesarray[string]本批次不导入的文件 MD5 集合,使用预览 eleMd5;不是文件 code 或 dataId

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/addFiles" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"containerId": "partner_kb_001",
"parentCode": "0",
"neverExpire": 1,
"dataSets": [
{
"dataId": "preview_batch_001",
"deleteFiles": []
}
]
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

成功返回结果字符串,不返回最终文件数组。通过文件列表回查入库资源并保存 code。临时预览失效时重新预览;结果未知时先回查,避免重复导入。

直接批量导入文件

POST /openapi/paas/v1/knowledge/file/importFiles

使用 multipart/form-data 直接导入文件,无需先调用预览接口。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
containerIdstring知识库 code,不是数字主键
parentCodestring父目录 code,默认 0
neverExpireinteger1 永久有效,0 限定有效期
startTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
endTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
filefile[]文件流,多个文件重复 file 字段

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/importFiles" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--form "containerId=partner_kb_001" \
--form "parentCode=0" \
--form "neverExpire=1" \
--form "file=@/path/to/product.pdf"

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataarray[object]字段完整定义见 响应数据字典;示例只保留业务所需字段
data[].idinteger已创建文件主键
data[].codestring文件 code,后续查询使用
data[].containerIdstring所属知识库 code
data[].eleNamestring文件名称
data[].eleSizeinteger文件大小,字节

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": [
{
"id": 1001,
"code": "partner_file_001",
"containerId": "partner_kb_001",
"parentCode": "0",
"category": "FILES",
"eleName": "产品白皮书.pdf",
"eleSuffix": "pdf",
"eleSize": 102400
}
]
}

data 是已创建文件条目数组,不是单对象,也不是处理完成通知。逐项保存 code,后续通过文件查询检查 processStatus。重复内容处理、部分条目返回和异步处理状态以实际结果核对,不按上传文件数推断入库数。

直接批量导入网页

POST /openapi/paas/v1/knowledge/file/importWebs

抓取网页并直接写入知识库,适合已确认来源与提取规则的批量同步。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
containerIdstring知识库 code,不是数字主键
parentCodestring父目录 code,默认 0
neverExpireinteger1 永久有效,0 限定有效期
startTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
endTimestring条件必填neverExpire=0 时填写,yyyy-MM-dd HH:mm:ss
urlsarray[object]网页列表
urls[].urlstringHTTP/HTTPS 地址
urls[].selectorstringCSS 内容选择器

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/file/importWebs" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"containerId": "partner_kb_001",
"parentCode": "0",
"neverExpire": 1,
"urls": [
{
"url": "https://example.com/product",
"selector": "main"
}
]
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

成功 data 为结果字符串;通过知识资源列表回查入库对象,不能从此响应取得逐文件 code。抓取与解析错误需结合资源状态诊断。

读取已有文件预览

GET /openapi/paas/v1/knowledge/file/loader

读取已入库文件的预览对象,参数为文件数字主键。

权限:knowledge_preview=READ

请求参数

参数JSON/表单类型必填说明
idinteger文件数字主键

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/file/loader" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "id=1001"

响应字段

顶层使用 普通响应

字段JSON 类型说明
dataobject继承完整 KnowledgeElement 字段,见响应数据字典
data.convertStatusboolean预览转换状态
data.contentstring / null支持文本预览类型的内容,其他类型可能为空
data.onlineobject / nullsource、target、iframeUrl 预览地址对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": {
"id": 1001,
"code": "partner_file_001",
"containerId": "partner_kb_001",
"eleName": "产品白皮书.pdf",
"eleSuffix": "pdf",
"eleSize": 102400,
"processStatus": 20,
"processPercent": 0,
"convertStatus": true,
"content": "产品预览内容。"
}
}

基础字段见 KnowledgeElement,地址字段见 MaterialPreview。预览不是分片分页接口;完整分片按 分片列表 获取。

按主键重命名资源

PUT /openapi/paas/v1/knowledge/file/rename

修改文件、目录等知识资源名称,不替换文件内容。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
idinteger目标资源数字主键
eleNamestring新的非空名称

请求示例

curl --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/file/rename" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"id": 1001,
"eleName": "产品白皮书-新版.pdf"
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

成功 data 为结果字符串;查询文件确认展示名称。不要假定名称全局唯一。

按编码重命名资源

PUT /openapi/paas/v1/knowledge/file/renameByCode

修改文件、目录等知识资源名称,不替换文件内容。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
codestring目标资源业务编码
eleNamestring新的非空名称

请求示例

curl --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/file/renameByCode" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"code": "partner_file_001",
"eleName": "产品白皮书-新版.pdf"
}'

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

成功 data 为结果字符串;查询文件确认展示名称。不要假定名称全局唯一。

按主键删除资源

DELETE /openapi/paas/v1/knowledge/file/delete

删除知识资源。执行前确认对象类型和目录影响范围。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
idinteger目标资源数字主键

请求示例

curl --get --request DELETE "${BASE_URL}/openapi/paas/v1/knowledge/file/delete" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "id=1001"

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

删除会影响后续检索及来源访问。超时后先查询,不自动重复删除;不存在和无权限按错误码处理。

按编码删除资源

DELETE /openapi/paas/v1/knowledge/file/deleteByCode

删除知识资源。执行前确认对象类型和目录影响范围。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
codestring目标资源业务编码

请求示例

curl --get --request DELETE "${BASE_URL}/openapi/paas/v1/knowledge/file/deleteByCode" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "code=partner_file_001"

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

删除会影响后续检索及来源访问。超时后先查询,不自动重复删除;不存在和无权限按错误码处理。

重置文件处理状态

PUT /openapi/paas/v1/knowledge/file/reset

重置已有资源的处理状态,影响后续处理流程。只对确需重新处理的文件执行。

权限:knowledge_file=WRITE

请求参数

参数JSON/表单类型必填说明
idinteger文件数字主键,Query 参数

请求示例

curl --get --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/file/reset" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "id=1001"

响应字段

顶层使用 普通响应

字段JSON 类型说明
datastring操作结果;成功时可以为空字符串,不包含新资源对象

响应示例

{
"code": 8200,
"message": "SUCCESS",
"data": ""
}

成功不代表已经重新解析完成。继续读取 processStatus、processPercent、errorMessage;不要密集重复重置同一文件。

导入后的验收

检查项预期
资源身份在目标 containerId 中查到预期文件 code
处理状态processStatus 为已完成;失败时先读取 errorMessage
内容可用性有分片产物;需要审核的知识还须满足准入发布与有效期要求
检索验证用已知正文短句检索,确认命中目标 dataSetId
权限隔离未授权用户不能读取原文或不应访问的知识

入库失败、配额不足、预览失效等按 错误处理 处理。不要通过降低权限或移除隔离条件绕过失败。