知识库定义、引用和导出统计公共说明¶
知识库定义导入、向已有知识库导入条目、来源文件处理及任务统计是不同操作。先确认目标、请求形状和结果,再决定后续处理。
身份与变量¶
使用目标工作区个人访问令牌、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 不能解释为校验通过。
工作区、模型、文件、任务与凭据不跨环境复用。