文件精确查询与分片读取

用于查询指定知识库内的文件元信息和解析分片。文件导入、目录、文本与 QA 管理见知识库接口。

凭据与读取权限

两个接口均要求 Authorization: Bearer tk-... 平台 API Key，并检查密钥创建人是否具备目标知识库读取权限。只具有 ASK_ONLY 问答权限不足以读取原文，渠道契约或旧应用 Token 不能替代本页的平台密钥。

接口	模块	最低权限
文件精确查询	`knowledge_file`	`READ`
分片列表	`knowledge_preview`	`READ`

两个接口都必须传 containerId（知识库 code）。不能沿用早期资料中“仅传文件 code、自动补齐知识库”的调用方式。

精确查询文件

GET /openapi/paas/v1/knowledge/file/query

Query 参数	类型	必填	说明
`containerId`	string	是	当前租户内的知识库 code
`code`	string	条件必填	文件业务编码；与 `name` 至少一个非空
`name`	string	条件必填	文件名精确匹配；同时传 code 时优先 code

即使按 code 查询也受 containerId 限制。按名称查到多个同名文件时返回参数错误，请改用唯一文件 code。

curl --get "${BASE_URL}/openapi/paas/v1/knowledge/file/query" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "containerId=partner_kb_001" \
  --data-urlencode "name=产品白皮书.pdf"

响应字段

外层使用普通响应。element 的完整字段见 KnowledgeElement，包括处理、准入状态与内容版本字段；这些字段依资源状态填充。

字段	类型	说明
`data.element`	object	文件元信息
`data.element.id`、`data.element.code`	integer / string	文件记录主键、文件业务编码
`data.element.containerId`	string	知识库 code
`data.element.eleName`、`eleSuffix`	string	名称、后缀
`data.element.eleUrl`、`elePreviewUrl`	string	原文件及预览地址，可能为空
`data.element.eleSize`	integer	文件大小，字节
`data.element.processStatus`、`processPercent`	integer	处理状态与进度
`data.container`	object	所属知识库基本信息
`data.tags`	array[string]	所属知识库的标签，不是分片标签

所属知识库 data.container 的完整字段：

字段	JSON 类型	说明
`id`	integer	知识库主键，不替代 code
`code`	string	知识库业务编码
`name`	string	名称
`category`	string	知识库类别
`description`	string / null	描述
`type`	string	容器类型
`parentCode`	string / null	父级编码
`visibilityRange`	string / null	可见范围；不能替代服务端权限判定

响应示例（省略可选展示和版本字段）：

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "element": {
      "id": 1001,
      "code": "partner_file_001",
      "containerId": "partner_kb_001",
      "eleName": "产品白皮书.pdf",
      "eleSuffix": "pdf",
      "eleSize": 102400
    },
    "container": {
      "code": "partner_kb_001",
      "name": "产品知识库"
    },
    "tags": ["产品"]
  }
}

已通过知识库权限校验但未找到匹配文件时，返回业务码 8404；知识库不存在或不可读时认证/权限检查失败。

分片列表

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

Query 参数	类型	必填	说明
`containerId`	string	是	知识库 code
`code`	string	是	文件 code
`content`	string	否	分片内容检索词
`pageNo`	integer	否	默认 1
`pageSize`	integer	否	默认 10

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

返回标准分页，data[] 是分片：

字段	类型	说明
`id`、`paragraphId`	string	分片、段落标识
`containerId`、`dataId`	string	知识库 code、文件 code
`category`	string	分片类型，如 `paragraph`、`table`
`page`	integer	页码
`content`	string	分片内容
`summary`	string	有摘要产物时返回
`tags`	array[string]	有标签产物时返回
`tokenSize`	integer	内容 Token 估算值
`createTime`	integer	创建时间戳
`enable`	string	分片启用状态

响应示例：

{
  "code": 8200,
  "message": "SUCCESS",
  "pageNo": 1,
  "pageSize": 10,
  "total": 1,
  "totalPage": 1,
  "data": [{
    "id": "chunk_001",
    "paragraphId": "paragraph_001",
    "containerId": "partner_kb_001",
    "dataId": "partner_file_001",
    "category": "paragraph",
    "page": 1,
    "content": "产品部署要求说明。",
    "summary": null,
    "tags": [],
    "tokenSize": 12,
    "createTime": 1788575400000,
    "enable": null
  }]
}

分页顶层字段见分页响应。createTime 是毫秒时间戳；enable 是字符串型状态，未填充时可空，不应当作 JSON 布尔值。

在知识库可读的前提下，文件不存在或文件不属于给定知识库时返回空分页；尚未产生分片的文件也可能没有结果。不要仅凭空分页判断文档已完成解析。先查询文件状态，再分页获取内容。

接口返回的文件/预览地址可能为受控地址或临时地址，应使用实际返回值，不拼接对象存储地址或长期保存签名链接。

凭据与读取权限​

精确查询文件​

响应字段​

分片列表​

凭据与读取权限

精确查询文件

响应字段

分片列表