# 导入知识库定义与语义条目

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

根据定义创建知识库，并在同一批次写入其语义条目。

```text
POST https://api.moi.matrixorigin.cn/v5/semantic-models/import
```

## 调用前准备

准备当前工作区凭据及相应资源权限。变量、导入文件和操作边界见[公共说明](objects.md)。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/import" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @"$MODELS_IMPORT_JSON"
```

:::::
:::::{tab-item} 参数说明

示例从JSON 数组文件读取一个 FAQ 定义。服务预校验各项与依赖后，在同一租户事务中创建模型和条目；不是按 ID 更新，也不是把文件上传、解析或重建索引作为同步完成结果。请求只描述当前支持的定义字段，不是图纸配置、向量索引、分段历史和所有知识库状态的完整备份恢复。结果未知或收到异常时先回查，不能断言任何错误都等价于未创建。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `请求根` | object 或 object[] | 是 | 单对象导入一个，或非空数组导入多个；响应形状随根类型改变。 |
| `name` | string | 每项必填 | 知识库名称；导入时去除首尾空白后须非空。 |
| `description` | string | 否 | 描述；去除首尾空白后保存。 |
| `tables` | object[] | 否 | 来源表声明；每项含 db_name 和非空 table_names 字符串数组。 |
| `files` | object | 否 | 来源文件声明，含 file_ids 字符串数组；不是上传文件内容。 |
| `entries` | object[] | 否 | 该知识库的语义条目；空列表表示没有条目。 |
| `entries[].domain` | string | 否 | 按条目种类选择 nl2sql 或 rag；条目默认与规范见公共说明。 |
| `entries[].kind` | string | 有条目时必填 | 该 domain 允许的条目种类，示例 standard_qa。 |
| `entries[].key` | string | 有条目时必填 | 同一领域和种类下的条目标识。 |
| `entries[].tables` | string[] | 否 | 条目引用的来源表；须与模型表集合一致。 |
| `entries[].spec` | JSON | 有条目时必填 | 与 domain/kind 匹配的条目定义。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "id": 101,
        "name": "Operations FAQ",
        "tables": [],
        "created_at": 1794408000,
        "updated_at": 1794408000,
        "source_counts": {
          "files": 0,
          "tables": 0,
          "total": 0
        },
        "semantic_model_kind": "standard",
        "drawing_number_policy": "overwrite_current"
      }
    ],
    "total": 1
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 当前动作结果；单对象导入时直接为知识库对象。 |
| `data.items` | object[] | 数组请求的创建结果；单对象请求时 data 直接为一个知识库对象。 |
| `data.total` | integer | 数组请求本次返回的创建对象数；不是工作区总数。 |
| `data.items[].id` | integer | 新知识库 ID；用于后续详情与来源操作。 |
| `data.items[].name` | string | 保存后的名称。 |
| `data.items[].description` | string | 存在时为描述。 |
| `data.items[].tables` | JSON | 来源表声明。 |
| `data.items[].files` | JSON | 存在时为来源文件声明。 |
| `data.items[].created_at` | integer | Unix 秒时间戳。 |
| `data.items[].updated_at` | integer | Unix 秒时间戳。 |
| `data.items[].source_counts` | object | 当前创建响应的计数投影；不表示解析或索引完成。 |
| `data.items[].semantic_model_kind` | string | 知识库类型；当前导入定义采用标准模型配置。 |
| `data.items[].drawing_number_policy` | string | 当前模型元数据；本请求未提供图纸专用配置字段。 |

:::::
::::::
:::::::

## 错误响应

成功 HTTP 状态为 201；校验、依赖或权限错误不能当作成功导入。按[错误与环境](objects.md#错误与环境)保留请求信息并回查。
