更新时间:2025-07-22 GMT+08:00
分享

查询文档接口

功能介绍

在当前知识库查询名称为xx的文件。

URI

GET /v1/{project_id}/applications/{application_id}/uni-search/{repo_id}/files/search

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释:

项目ID,获取方法请参见获取项目ID

约束限制:

不涉及

取值范围:

1~64个字符,只能包含数字、字母、中划线和下划线,且必须以字母开头。

默认取值:

不涉及

application_id

String

参数解释:

应用ID,获取方法请参见获取应用ID

约束限制:

字符串

取值范围:

1~64个字符,只能包含数字、字母、中划线和下划线,且必须以字母开头。

默认取值:

不涉及

repo_id

String

参数解释:

知识库ID。

获取方式:

账号登录KooSearch体验平台,在左侧导航栏选择:"知识库管理" ,在此界面获取"知识库ID"字段的值,表示该知识库在向量数据库中存储的ID,具有唯一性。

约束限制:

不涉及

取值范围:

1~64个字符,只能包含数字、字母、中划线和下划线。

默认取值:

不涉及

表2 Query参数

参数

是否必选

参数类型

描述

file_name

String

参数解释:

文件名。

约束限制:

不涉及

取值范围:

字符串小于1024个字符, 输入不能包含\ / : * ? " < > | <br>不能以 . 结尾。

默认取值:

不涉及

file_type

String

参数解释:

文件类型。

约束限制:

不涉及

取值范围:

只能包含1到64位英文字母、数字、中划线或者下划线。

默认取值:

不涉及

category

String

参数解释:

文档目录,单值,对应目录树中的叶子节点

建议格式为 叶子节点目录名称(目录ID),如:专利(3166-1)

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

tags

Array of strings

参数解释:

文档标签,查询时取交集。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

file_status

String

参数解释:

文件状态。

约束限制:

不涉及

取值范围:

只能包含1到128位英文字母、逗号、中划线或者下划线。

默认取值:

不涉及

ids

Array of strings

参数解释:

查询文件id列表。

约束限制:

不涉及

取值范围:

文件id长度不能超过64个字符。

默认取值:

不涉及

chat_id

String

参数解释:

对话id。

约束限制:

不涉及

取值范围:

长度不能超过64个字符。

默认取值:

不涉及

page_num

Integer

参数解释:

当前请求的页码,表示从第几页开始获取数据。默认值为1,表示第一页。

约束限制:

不涉及

取值范围:

1~65535

默认取值:

1

page_size

Integer

参数解释:

每页显示的记录数,表示一次请求返回的数据条数。默认值为10,表示一页展示10条数据。

约束限制:

不涉及

取值范围:

1-65535

默认取值:

10

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

参数解释:

接口鉴权使用的Token,Token获取方式参考:获取IAM用户Token

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

total

Integer

参数解释:

返回的文档总数。

取值范围:

不涉及

page_num

Integer

参数解释:

页码。

取值范围:

不涉及

page_size

Integer

参数解释:

每页数量。

取值范围:

不涉及

files

Array of FileInfo objects

参数解释:

文件列表。

取值范围:

不涉及

表5 FileInfo

参数

参数类型

描述

id

String

参数解释:

文件ID。

取值范围:

不涉及

name

String

参数解释:

文件名。

取值范围:

不涉及

repo_id

String

参数解释:

知识库id。

取值范围:

不涉及

type

String

参数解释:

文件类型。

取值范围:

不涉及

status

String

参数解释:

文件状态。

取值范围:

不涉及

  • SUCCESS 执行成功

  • ERROR 执行失败

  • POST_PROCESSING 表示文件已完成主要流程,但需要后续操作

  • CREATE 等待后台任务处理,即将进入PENDING状态

  • PENDING 初始状态,未处理

  • RUNNING 执行中

  • INBOUND 执行完成,数据入库中

  • IMPORT_EXCEPTION 导入异常

  • FILE_ENCODING_ERROR 编码错误。

chat_id

String

参数解释:

对话ID。

取值范围:

不涉及

category

String

参数解释:

文档目录,单值,对应目录树中的叶子节点。

建议格式为 叶子节点目录名称(目录 ID),如:专利(3166-1)。

取值范围:

不涉及

tags

Array of strings

参数解释:

文档标签,可以使用标签对文档进行自动分组,用于筛选过滤。

取值范围:

不涉及

注意事项:

  1. 建议不区分大小写,例如, Approved and approved 是同一个标签

  2. 文档可以有一个或多个标签

  3. 建议格式为:标签名称:标签值 ,如果能够保证标签值不冲突,也可以直接使用 标签值,例如

  • 《冰箱使用说明书》对应的产品型号:ProductModel:BCD-551WLCTDAFA5U1

  • 《一句顶一万句》的作者是:刘震云

  • 《外观设计专利交底书模板》 的专业领域是:法务领域。

size

Long

参数解释:

文件大小(bytes)。

取值范围:

不涉及

process

Integer

参数解释:

文件解析进度。

取值范围:

不涉及

fail_count

Integer

参数解释:

上传失败的数据条数。

取值范围:

不涉及

fail_records_expire_time

String

参数解释:

上传失败的时间戳。

取值范围:

不涉及

create_user

String

参数解释:

创建者,指上传文件的用户,可能不存在该键值。

取值范围:

不涉及

create_time

String

参数解释:

创建时间,指上传文件的时间,例如:1692848139119。

取值范围:

不涉及

update_time

String

参数解释:

更新时间,可能不存在该键值。

取值范围:

不涉及

upload_desc

String

参数解释:

上传说明,可能不存在该键值。

取值范围:

不涉及

has_html

Boolean

参数解释:

是否可以用html进行预览。

取值范围:

不涉及

file_extract_conf

FileExtractConf object

参数解释:

文件抽取配置项。

取值范围:

不涉及

project_id

String

参数解释:

知识库id。

取值范围:

不涉及

application_id

String

参数解释:

项目id。

取值范围:

不涉及

file_path

String

参数解释:

文档路径。

取值范围:

不涉及

表6 FileExtractConf

参数

参数类型

描述

parse_conf

ParseConf object

参数解释:

文档解析配置,包含是否使用OCR增强、是否解析图片、解析图片是否需要提取文字、是否解析页眉页脚、是否解析目录页。

取值范围:

不涉及

split_conf

SplitConf object

参数解释:

拆分配置,包括分段方式设置、层级解析模式设置、标题层级深度设置、标题保存方式设置、分段长度配置、标题匹配pattern配置等。

取值范围:

不涉及

id

String

参数解释:

文档解析ID。

约束限制:

不涉及

取值范围:

0-128个字符。

默认取值:

不涉及

表7 ParseConf

参数

参数类型

描述

ocr_enabled

Boolean

参数解释:

ocr增强。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

mllm_model

String

参数解释:

多模态模型名称。

约束限制:

必须是平台上配置的mllm_plan模型。平台上配置的模型可以通过ListModels接口查看。

取值范围:

只能包含1到32位英文字母、中文、数字、中划线或者下划线,并且以字母、数字或者中文开头。

默认值:

不涉及

image_enabled

Boolean

参数解释:

图片解析。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

header_footer_enabled

Boolean

参数解释:

解析页眉页脚。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

catalog_enabled

Boolean

参数解释:

解析目录页。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

image_conf

String

参数解释:

图片解析开启(image_enable为True)时,使用的图片解析方式。

约束限制:

当需要使用图文并茂返回答案时,必须使用IMAGE模式,保留原图。

取值范围:

  • TEXT 提取图片文本

  • IMAGE 保留原图

  • IMAGE_TEXT,解析文本和保留原图

默认取值:

TEXT

footnote_enabled

Boolean

参数解释:

解析脚注尾注。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

表8 SplitConf

参数

参数类型

描述

split_mode

String

参数解释:

文档切分的模式选择。

取值范围:

枚举值:

  • AUTO- 自动拆分,自动识别文档格式匹配适合的拆分解析方式。

  • LENGTH-按长度拆分,例如每500字分一段。

  • CATALOG-层级分段下-自动解析。自动识别文章的层级结构,按照文章的层级结构分片。例如1.1.2章节为一个分片,1.1.3章节为一个分片。

  • RULE- 层级分段下-规则解析。自定义层级标题的匹配规则,并依据自定义的规则进行章节匹配、切分。

约束限制:

不涉及

默认取值:

AUTO

separator_ids

Array of strings

参数解释:

自动分段和长度分段模式下的,分段标识符ID列表。

分段标识符:用于决定分片切片时的结束符。

约束条件:

不涉及

取值范围:

取值映射:

  • period_zh: "中文句号 。",

  • period_en: "英文句号 .",

  • exclamation_mark_zh: "中文叹号 !",

  • exclamation_mark_en: "英文叹号 !",

  • question_mark_zh: "中文问号 ?",

  • question_mark_en: "英文问号 ?",

  • question_mark_ar: "阿语问号 ؟",

  • comma_zh: "中文逗号 ,",

  • comma_en: "英文逗号 ,",

  • space_en: "空格"

默认取值:

{"period_zh", "period_en", "exclamation_mark_zh", "exclamation_mark_en", "question_mark_zh", "question_mark_en"}

rule_regex_id

String

参数解释:

用户定义解析规则ID。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

chunk_size

Integer

参数解释:

文档分段切片的最大长度。文档切片时根据该最大长度进行切片。

约束限制:

不涉及

取值范围:

0-6000

默认取值:

500

title_level

Integer

参数解释:

分片保留的标题层级深度。

例如:

深度为3时:当前段落为1.1.3,父标题1.1 和 父标题1 均会保留。

深度为2时:当前段落为1.1.3,父标题1.1 保留,父标题1 舍弃。

约束限制:

不涉及

取值范围:

1-10

默认取值:

3

combine_title

Boolean

参数解释:

是否保留层级标题组合。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

merge_titles

Boolean

参数解释:

是否跨标题合并,不同标题段落文字较少时,会自动合并到指定的分段长度,有助于生成更全面的结果。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

false

rule_regexs

Array of strings

参数解释:

用户定义解析规则。

约束限制:

不涉及

取值范围:

列表长度限制1-100。

默认取值:

不涉及

merge_last_chunk

Boolean

参数解释:

是否合并最近修改的分段。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

状态码:400

表9 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

取值范围:

不涉及

error_msg

String

参数解释:

错误描述。

取值范围:

不涉及

状态码:500

表10 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

取值范围:

不涉及

error_msg

String

参数解释:

错误描述。

取值范围:

不涉及

请求示例

在当前知识库查询名称为xx的文件。

/v1/b25446daeb1a41a7953c5deba2b2677a/applications/cefb2a59-2f9e-4268-b56b-eab15dc0b9d6/uni-search/0e7a261c-a543-4f98-915d-7a83ac96595c/files/search?file_name=%E8%A7%86%E9%A2%91%E7%9B%B4%E6%92%AD%20Live%20%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5.pdf&page_size=100&page_num=1

响应示例

状态码:200

文档列表响应体。

{
  "total" : 1,
  "files" : [ {
    "id" : "45938a076274b530fa0c600af354ea4b",
    "name" : "视频直播 Live 最佳实践.pdf",
    "type" : "pdf",
    "status" : "SUCCESS",
    "size" : 396838,
    "process" : 100,
    "create_user" : "ei_css_011",
    "create_time" : "1745827605498",
    "has_html" : false,
    "file_extract_conf" : {
      "id" : "ff4b453f-5126-4768-a8ab-efbbc71e9a04",
      "parse_conf" : {
        "ocr_enabled" : true,
        "image_enabled" : true,
        "image_conf" : "TEXT",
        "header_footer_enabled" : false,
        "catalog_enabled" : false
      },
      "split_conf" : {
        "split_mode" : "AUTO"
      }
    }
  } ],
  "page_num" : 1,
  "page_size" : 100
}

状态码

状态码

描述

200

文档列表响应体。

400

请求体参数错误。

500

内部异常。

错误码

请参见错误码

相关文档