# 创建和管理语义模型

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

## 前提条件

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

## 创建模型

```bash
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 值 | 否 | 旧式文件来源定义。新任务优先使用独立来源接口。 |

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

```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，不根据当前数组长度推断已经到达末页。

## 校验模型

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

```bash
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"
```

```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 和名称筛选 | 清除筛选并从第一页重新读取。 |
| 删除被拒绝 | 模型引用、来源任务和当前权限 | 先解除绑定并等待运行任务结束。 |

## 下一步

- [添加业务指标和术语](entries.md)
- [添加表或文件来源](sources-processing.md)