# 管理语义模型

在工作区中创建语义模型和模型条目，然后单独执行校验。只有校验结果表明模型有效时，才将它用于后续任务。

(sdk-ai-studio-semantic-model-flow)=
## 任务流程

1. 调用方提供模型名称、关联表和条目定义。
2. SDK 创建模型并返回模型资源。
3. 使用模型资源创建条目，并返回条目资源。
4. 使用同一个模型资源执行校验，根据结果决定是否继续使用。

(sdk-ai-studio-semantic-model-prepare)=
## 准备

| 需要的内容 | 在本页中的作用 |
| --- | --- |
| 已认证的客户端和已选择的工作区 | 确定模型和条目的资源作用域。 |
| 模型名称和关联表 | 创建模型。 |
| 条目类型、引用键和定义 | 创建条目。 |
| 可访问的表或文件 | 作为模型配置所引用的数据资源。 |

模型名称同时是不可变的 Catalog 数据库名称。更新模型时必须继续提供原名称。

(sdk-ai-studio-semantic-model-create)=
## 创建模型和条目

下面的函数创建一个模型和一个指标条目，再返回模型资源供后续校验使用。模型创建或条目创建成功不表示模型已经通过校验。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import moi_product_sdk as sdk


def create_sales_model(workspace):
    model, _ = workspace.create_semantic_model(
        "sales_model", sdk.with_semantic_model_tables(["orders"])
    )
    entry, _ = model.create_entry(
        sdk.SemanticEntryInput(
            "metric", "total_rows", {"expr": "COUNT(*)"}, ["orders"]
        )
    )
    return model, entry
```

::::

::::{tab-item} Go
:sync: go

```go
import (
	"context"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func createSalesModel(ctx context.Context, workspace *sdk.WorkspaceHandle) (*sdk.SemanticModelHandle, *sdk.SemanticEntryHandle, error) {
	model, _, err := workspace.CreateSemanticModel(
		ctx, "sales_model", sdk.WithSemanticModelTables([]string{"orders"}),
	)
	if err != nil {
		return nil, nil, err
	}
	entry, _, err := model.CreateEntry(ctx, sdk.SemanticEntryInput{
		Kind: "metric", Key: "total_rows", Tables: []string{"orders"},
		Spec: map[string]any{"expr": "COUNT(*)"},
	})
	if err != nil {
		return nil, nil, err
	}
	return model, entry, nil
}
```

::::

:::::

示例创建一个指标条目。条目类型决定其定义的结构；提供的条目必须符合对应类型的校验规则。

(sdk-ai-studio-semantic-model-validate)=
## 校验模型

使用上一步返回的模型资源执行校验。校验结果中的有效标志是继续使用模型的依据。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
validated = model.validate()
if not validated.valid:
    raise ValueError("semantic model validation failed")
```

::::

::::{tab-item} Go
:sync: go

```go
validated, err := model.Validate(ctx)
if err != nil {
	return err
}
isValid := validated.GetValid()
_ = isValid
```

::::

:::::

(sdk-ai-studio-semantic-model-exchange)=
## 导入或导出条目

模型资源可以导出模型及其条目定义，也可以导入非空且有效的条目列表。导入后再次执行校验，以确认当前模型是否仍然有效。

(sdk-ai-studio-semantic-model-result)=
## 结果确认

保留模型资源和条目资源，用于后续读取、更新或删除。删除仅确认删除请求的结果；需要确认最终状态时，再读取或列出相应资源。

(sdk-ai-studio-semantic-model-limit)=
## 限制

- 条目创建和更新不代表模型已经通过校验。
- 表、文件和字段绑定应来自已确认的工作区资源或调用方选择；不要把另一个工作区的资源标识直接用于当前模型。
- 如果本次只为验证而创建模型和条目，先删除条目，再删除模型。

(sdk-ai-studio-semantic-model-next)=
## 下一步

- [管理 Catalog、数据库和表](catalog-tables.md)