知识库定义、引用和导出统计公共说明

知识库定义导入、向已有知识库导入条目、来源文件处理及任务统计是不同操作。先确认目标、请求形状和结果,再决定后续处理。

身份与变量

使用目标工作区个人访问令牌、WORKSPACE_ID 与相应模型创建/读取、智能体列表或导出统计权限。MODEL_ID 是正整数知识库 ID;API 路径可用该值的十进制字符串。短期任务身份也须由服务端校验,不能跨环境复用授权或资源。

批量定义例子从JSON 数组读取,设置 MODELS_IMPORT_JSON 为文件路径;每项是一个定义。单对象请求创建一个对象,数组请求批量创建,不能在客户端无条件按同一种响应形状解析。

定义、条目与文件分别处理

动作

输入与结果

不能据此判断

POST /semantic-models/import

一个定义或非空定义数组;HTTP 201 返回新知识库或 items/total

文件已上传、来源已解析、索引已完成,或图纸/分段历史等所有状态已恢复。

POST /semantic-models/{model_id}/import

向已有知识库导入语义条目,可有 append/overwrite、dry_run 等选项

创建了完整知识库。

CLI semantic-model import/export/validate

操作已有知识库的条目;export 与 validate 读取结果

三个命令都接受 JSON 输入或都修改内容。

定义请求中的 tables 为 {db_name, table_names} 对象数组,每项数据库名非空且表名列表非空;files 为 {file_ids:[...]},引用既有文件,不包含文件字节。服务在写入前核对依赖。批次模型与条目创建在同一租户事务中,但结果未知或返回异常时仍需回查,不把任意 HTTP 错误等价为一定未写入。

条目的 domain 省略时当前归一化为 nl2sql;RAG 条目应显式设为 rag。kind、key 与 spec 须符合该领域;示例 standard_qa 的 spec 含 question/answer。表引用与知识库表集合要一致;历史停用标记条目在定义导入准备时可被跳过。条目全部联合类型、旧格式迁移与每项覆盖细节另需按现有语义条目规范逐项核对,这些接口三页不代替完整嵌套字段验收。

定义导入响应不提供条目逐项回执,也不证明后续解析/索引完成。保存新知识库 ID,再读取定义、条目、数据源和处理作业。当前定义字段不包含图纸专用配置、向量索引与分段历史;不要把此动作当作通用完整备份恢复。

引用查询的可见性与分页

引用查询先检查知识库读取,再读取当前身份可见的智能体有效绑定;合并工作区/系统定义及工作区覆盖后匹配引用,返回时排除归档智能体。它不是全局引用计数或删除前置检查的替代品。

正常分页默认 50,显式正整数超过 200 会取 200;当前权限投影完全没有可见候选时,早返回分支的结果 limit 可能为 0。以返回值为准,续页只由非空 next_cursor 决定,不因为 items 为空或少于页大小而提前停止。归档过滤在分页之后,也可能产生仍有下一游标的空页。

NEXT_CURSOR 第一页可不设置,后续从响应读取并保持原值;不能解码改写或移用于其他工作区、资源。响应没有 total,knowledge_base_count 是单个智能体的有效知识库绑定数,不是本资源的全局引用总数。

统计范围

导出统计没有任务 ID、分页或列表筛选参数。它统计当前工作区对应范围,排除生命周期未就绪或正在删除的记录;总数含已完成任务,因此 pending、running、failed 相加可以小于 total。统计不带每个任务本次运行的结果,操作判断应再读详情、文件和目标数据。

错误与环境

动作

已核对边界

处理

定义导入

空请求/空数组、名称、来源或条目无效;依赖与权限校验;创建/响应阶段异常

读取 HTTP 与业务码,保存原输入,先回查,不能自动按“未创建”重复导入。

引用智能体

知识库读取先于引用列表;无效 limit/cursor 为参数错误,授权及服务不可用分别处理

保持同一模型与工作区;空页不代表全局无人引用。

导出统计

工作区/统计权限、存储读取及状态计数异常

按实际 HTTP 与业务码处理,不能将空/错误响应作为零任务。

Go/Python SDK 与 CLI 均有这些接口三个操作入口。普通条目导入方法只构造 entries 封装;Go 便捷方法与 CLI 未提供覆盖/预演选项。Python 另有 import_entries_raw 保留完整对象入口,因此不能写成 Python 完全没有相关能力。本次不修改产品实现或编造 CLI 参数。

CLI 的 validate 退出状态为 0 只说明调用成功,仍须明确检查结果 valid: true 并处理 errors。当前 CLI 输出中,false 的 valid 字段可能被省略,只留下 errors;缺少 valid 不能解释为校验通过。

工作区、模型、文件、任务与凭据不跨环境复用。

最后更新于