技术速查深度场景内容2 分钟阅读技术速查

FastGPT 4.17.3 接口分页与附件基准

"依据 FastGPT v4.17.3 官方更新说明,说明接口分页参数的上限与优先级、附件类型的枚举变化与导出接口的库范围,便于按当前版本核对分页、过滤与备份行为。"

分页、附件分类与导出范围是三处容易照旧文档写错的接口口径。v4.17.3 的取值与兼容规则如下,单位分别是条、枚举值与知识库。

分页参数的上限与优先级

通用 pageSize 超过 500 时按 500 处理,不再返回报错;offset 的优先级高于 pageNum,取值为 0 时同样生效。核对动作是每页请求只保留一个游标参数,把 pageSize 控制在 500 以内,并在返回条数少于 pageSize 时先判断是否已到末页,再判断是否被截断。边界:业务接口允许比 500 更小的上限,具体数值以该接口自己的文档为准,通用上限不覆盖业务限制。

末页按该接口的分页契约判断。若请求值高于有效上限,返回少于请求条数仍可能有下一页。空页也可能来自筛选条件或数据为空。排查时记录实际 offset、有效页大小与已取得的记录数,并分别测试空集合和超过末页的请求。

附件类型的枚举变化

附件分类新增 document 与 unknown 两个值,旧的 file 仍被兼容。核对动作是自定义客户端需要处理 document 和 unknown,同时兼容历史 file 记录。文档类附件进入解析链路,未知文件可由文档读取工具尝试读取。验收时分别准备历史入参、已识别文档与未知类型。

导出接口的库范围

/api/core/dataset/exportAll 按单个知识库导出;启用文件级权限后,导出内容只包含当前成员可读的文件。核对动作是把批量备份脚本改为逐库调用,并在导出后比对导出文件数与库内当前可见文件数。边界:导出范围随成员身份变化,用不同账号导出同一个库会得到不同结果,因此备份记录里要写明执行账号。

导出记录包含四项:库标识、执行账号、导出时间、条目数。缺一项,事后就无法判断这份备份覆盖了哪些文件,也无法在两次备份之间做差异比对。

接口调用的三个核对点

把上述三项合成一次例行核对:先按 pageSize 与 offset 拉全量列表,确认最后一页的返回条数与总数字段一致;再按附件类型统计 document、unknown、file 的数量,确认没有分类遗漏;最后逐库触发导出,核对导出条目数与文件级权限下的可见数。三项都通过,才说明分页、过滤与备份三条链路口径一致。把这三项写成一条可重复执行的脚本,比每次人工比对列表可靠;脚本输出留档,两次之间的差异一眼能看出来。

数据来源

SourceVersionDocument
FastGPTv4.17.3self-host/upgrading/4-17/4173
FastGPTv4.17.2self-host/upgrading/4-17/4172