文档中心

数据智能体

结构化知识库导入

创建结构化数据资产

创建结构化数据资产

调用本接口创建 CSV、Excel、ClickHouse 或 Hive 数据资产及字段草稿。

调用方：开放平台应用、外部 Agent 或集成服务。
前置条件：调用者拥有知识库编辑权限，文件来源已先完成文件上传，并提供 Idempotency-Key。

接口说明

接口名称：create_asset_structured_knowledge_v1_kbs__kb_id__assets_post
接口地址：/structured_knowledge/v1/kbs/{kb_id}/assets
请求方式：POST

请求参数

参数名	类型	是否必传	描述
Idempotency-Key	String	是	调用方生成的写请求幂等键；同一租户、操作和请求体重试时必须保持不变

Path

参数名	类型	是否必传	描述
kb_id	String	是	结构化知识库 ID，由创建知识库或查询知识库列表接口返回

请求体

Object 类型，包含参数如下：

参数名	类型	是否必传	描述
asset_name	String	是	结构化数据资产名称，长度 1 到 255 个字符
folder_id	String	否	目标目录 ID；不传或传 0 表示知识库根目录
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
source_config	Object	是	配置。详情请参见下文 source_config 表
schema_draft	Object	是	可选的字段草稿；不传时可在后续配置字段后再发起导入。详情请参见下文 schema_draft 表

source_config

参数名	类型	是否必传	描述
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
file_id	String	否	Excel/CSV 上传后的文件 ID
dataset_id	String	否	Prep 数据集 ID
dataset_name	String	否	创建资产时记录的 Prep 数据集名称
database_name	String	否	CK/Hive 库名
table_name	String	否	CK/Hive 表名
partition_type	String	否	分区类型 NON_PARTITION FULL_PARTITION INCREMENTAL_PARTITION
partition_fields	Array	否	分区字段，最多两个
task_name	String	否	Prep 导入任务名称
auto_update_config	Object	否	Prep 输入算子增量配置及 scheduleConf 定时配置。详情请参见下文 auto_update_config 表
sheet_config	Object	否	Excel/CSV sheet 解析配置。详情请参见下文 sheet_config 表

auto_update_config

参数名	类型	是否必传	描述
isIncrement	Boolean	否	是否按增量字段读取数据；false 表示由 Prep 执行全量读取
incrementField	String	否	增量读取使用的源表字段名，仅 isIncrement=true 时必填
incrementFieldType	String	否	增量字段类型，由 Prep 用于解释增量游标值
timeFormat	String 或 Object	否	时间型增量字段的格式配置，具体格式遵循 Prep 输入算子协议
timeRange	Number	否	增量读取向前回溯的时间范围，单位由 Prep 输入算子配置解释
batchSize	Number	否	Prep 单批读取或写入的建议行数，必须大于等于 1
writeMode	writeMode	否	Prep 写入模式：full 为全量覆盖，incremental 为增量写入
scheduleConf	Object	是	Prep 调度配置。详情请参见下文 scheduleConf 表

scheduleConf

参数名	类型	是否必传	描述
scheduleType	Number	是	0 表示手动执行，1 表示定时执行
scheduleTimeType	Number	否	Prep 调度时间类型，当前固定为 0
scheduleFrequency	String	否	定时频率，当前支持 daily/monthly
scheduleTimeSettings	Array	否	daily 为 [HH:mm]，monthly 为 [日期, HH:mm]
dependencyNodes	Array	否	由 Verag 调用 Prep 获取，前端只能传空数组

sheet_config

参数名	类型	是否必传	描述
sheet_name	String	否	Excel sheet 名称
header_row_index	Number	否	表头所在行，从 1 开始
data_start_row_index	Number	否	数据起始行，从 1 开始

schema_draft

参数名	类型	是否必传	描述
source	Object	是	源配置。详情请参见上文 source_config 表
logical_fields	Array	是	结构化数据的逻辑字段定义，至少包含一个字段。详情请参见下文 logical_fields 表
primary_key_fields	Array	否	初次导入可选的业务主键字段；追加或覆盖导入可在导入请求中重新指定唯一标识列

logical_fields

参数名	类型	是否必传	描述
source_column_name	String	否	原始字段/列名；用户新增字段为空
field_name	String	是	导入后字段名，作为产品语义字段 key
display_name	String	是	字段展示名
data_type	String	是	数据类型 string int long float bool datetime
enabled	Boolean	否	是否启用并参与召回/展示候选
vector_enabled	Boolean	否	是否开启向量索引
filter_enabled	Boolean	否	是否允许作为过滤条件
return_enabled	Boolean	否	是否允许作为返回字段
description	String	否	字段描述
allowed_operators	Array	否	允许的过滤操作符；不传则按类型默认 eq ne gt ge lt le between is_null is_not_null contains not_contains in not_in

响应参数

参数名	类型	是否必传	描述
code	Number	是	响应码：0=成功，非0=失败
msg	String	否	Code非0时，返回错误信息
message	String	否	错误信息
data	Object	是	数据。详情请参见下文 data 表

data

参数名	类型	是否必传	描述
asset_id	String	是	结构化数据资产唯一 ID
kb_id	String	是	资产所属的结构化知识库 ID
asset_name	String	是	结构化数据资产名称
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
status	String	是	状态 DRAFT READY_PENDING_IMPORT READY DISABLED DELETED CREATE_FAILED IMPORTING IMPORT_FAILED DELETING DELETE_FAILED
source	Object	是	源配置。详情请参见下文 source 表
folder_id	String	否	资产所属目录 ID
source_file_name	String	否	原始上传文件名；数据集来源可为空
file_size	Number	否	原始文件大小，单位字节；数据集来源可为空
row_count	Number	否	当前已写入 OpenSearch 的数据行数
last_error	String	否	最近一次处理失败原因；无失败时为空
created_by	String	否	创建人账号
create_time	Number	否	创建时间，Unix 毫秒时间戳
update_time	Number	否	最近更新时间，Unix 毫秒时间戳

souce

参数名	类型	是否必传	描述
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
file_id	String	否	Excel/CSV 上传后的文件 ID
dataset_id	String	否	ClickHouse/Hive 的 Prep 数据集 ID
dataset_name	String	否	ClickHouse/Hive 的 Prep 数据集名称
database_name	String	否	源数据库名称
table_name	String	否	源数据表名称
sheet_name	String	否	Excel 工作表名称；CSV 通常为 default

最近更新时间：2026.09.17 19:26:42

这个页面对您有帮助吗？

有用

有用

无用

无用