创建和管理语义模型¶

创建一个空语义模型，保存模型 ID，并使用校验接口检查模型定义。数据来源和业务 Entry 可以在模型创建后分别添加。

前提条件¶

已准备 Product API Base URL、个人访问令牌和工作区 ID。
当前身份具有语义模型创建和读取权限。
如果创建时直接添加来源，已取得数据目录（Catalog）表 ID、文件 ID 及其卷 ID。

创建模型¶

curl -X POST "$PRODUCT_API_BASE_URL/semantic-models" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<SEMANTIC_MODEL_NAME>",
    "description": "<DESCRIPTION>"
  }'

字段	类型	必需	说明
`name`	string	是	语义模型名称。
`description`	string	否	模型覆盖的业务范围和使用约束。
`tables`	任意 JSON 值	否	旧式表来源定义。新任务优先使用独立来源接口。
`files`	任意 JSON 值	否	旧式文件来源定义。新任务优先使用独立来源接口。

成功响应直接返回模型信息：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 401,
    "name": "<SEMANTIC_MODEL_NAME>",
    "description": "<DESCRIPTION>",
    "source_counts": {
      "files": 0,
      "tables": 0,
      "total": 0
    }
  }
}

模型 ID 是数值，但路径参数使用其字符串表示。保存 data.id，后续接口使用 /semantic-models/{model_id}。

读取和更新模型¶

方法与路径	用途
`GET /semantic-models`	分页列出模型
`GET /semantic-models/tags`	读取模型标签统计
`GET /semantic-models/{model_id}`	读取模型详情和来源数量
`PUT /semantic-models/{model_id}`	更新名称、说明或旧式来源字段
`DELETE /semantic-models/{model_id}`	删除模型

列表响应使用 items[]、total 和 next_page_token。遍历时继续使用服务端返回的 Token，不根据当前数组长度推断已经到达末页。

校验模型¶

在绑定给智能体或其他任务前调用校验接口：

curl -X POST "$PRODUCT_API_BASE_URL/semantic-models/$MODEL_ID/validate" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json"

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "valid": true,
    "errors": []
  }
}

HTTP 请求成功但 valid 为 false 时，模型仍未通过业务校验。根据 errors[] 修正 Entry 或来源后重新校验。

导入和导出¶

GET /semantic-models/{model_id}/export 返回模型和 Entry，可用于审阅或迁移。POST /semantic-models/{model_id}/import 接收 entries[]，每项包含 kind、key、可选的 tables 和 spec。

导入会写入 Entry。提交前先导出当前模型或列出现有 Entry，避免重复键或覆盖调用方未读取的修改。

删除模型¶

删除前列出来源和 Entry，并确认智能体、工作流或应用不再引用该模型。删除模型不会恢复或删除来源所在的数据目录表和文件，也不会撤销已产生的回答或工作流结果。

常见问题¶

现象	先检查	下一步
创建模型后没有内容	`source_counts` 和 Entry 列表	添加来源和 Entry；空模型本身不包含可检索内容。
校验返回 `valid: false`	`errors[]`、Entry 和来源状态	修正指出的模型定义后重新校验。
列表找不到模型	工作区 ID、分页 Token 和名称筛选	清除筛选并从第一页重新读取。
删除被拒绝	模型引用、来源任务和当前权限	先解除绑定并等待运行任务结束。

下一步¶

最后更新于 2026 年 8 月 14 日