语义模型

MOI 产品中的语义配置覆盖维度、指标、表关联、术语、过滤器等多种条目。当前官方 SDK 没有对应这套 UI 模型的专用类型；公开能力是通用的 NL2SQL knowledge entry。它可以保存供 NL2SQL 使用的键和值，但调用方必须使用服务支持的 knowledge_type 和内容格式，不能自行发明枚举。

SDK 提供的操作

操作

Python RawClient

Go RawClient

创建

create_knowledge

CreateKnowledge

更新

update_knowledge

UpdateKnowledge

删除

delete_knowledge

DeleteKnowledge

详情

get_knowledge

GetKnowledge

分页列表

list_knowledge

ListKnowledge

按类型和 Key 搜索

search_knowledge

SearchKnowledge

Go SDK 为这些操作定义了 NL2SQLKnowledge*Request 类型；Python 传入使用相同 JSON 字段的字典。

写入字段

创建和更新请求公开以下字段：

JSON 字段

Go 字段

说明

knowledge_type

Type

服务支持的知识类别

knowledge_key

Key

条目的检索键或名称

knowledge_value

Value

字符串数组，保存条目内容

embedding

Embedding

浮点数组；只有调用方已明确掌握模型和维度约束时才传

associate_tables

AssociateTables

关联表名数组

explanation_type

ExplanationType

服务支持的解释类别

更新和删除使用数值 id。列表请求使用 knowledge_type、page_number、page_size；搜索请求再增加 knowledge_key。响应条目包含 id、type、key、value、可选 embedding、meta 和时间字段。

Python 示例

下面示例刻意把知识类别作为配置输入。请从已部署服务或现有条目取得有效值，不要照抄一个未经确认的类别。

from moi import RawClient

raw = RawClient("https://api.example.com", "your-api-key")

created = raw.create_knowledge(
    {
        "knowledge_type": configured_type,
        "knowledge_key": "paid_order",
        "knowledge_value": ["Orders whose status is in the approved paid-state set."],
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)
knowledge_id = created["id"]

entry = raw.get_knowledge({"id": knowledge_id})

Python 方法直接接受字典并返回服务端 data。如果应用不负责生成 Embedding，传空数组还是省略字段应以当前服务契约为准。

Go 示例

client, err := sdk.NewRawClient("https://api.example.com", apiKey)
if err != nil {
    return err
}

created, err := client.CreateKnowledge(ctx, &sdk.NL2SQLKnowledgeCreateRequest{
    Type:            configuredType,
    Key:             "paid_order",
    Value:           []string{"Orders whose status is in the approved paid-state set."},
    Embedding:       []float64{},
    AssociateTables: []string{"orders"},
    ExplanationType: configuredExplanationType,
})
if err != nil {
    return err
}

entry, err := client.GetKnowledge(ctx, &sdk.NL2SQLKnowledgeGetRequest{
    ID: created.ID,
})

安全更新

  1. 先用 get_knowledge 读取目标条目，不要只依赖本地缓存。

  2. 用 id 更新，保留仍需存在的字段；公开更新请求不是补丁语义。

  3. 更新后重新读取并用代表性问题验证。

  4. 删除是永久操作。删除前记录条目内容，并确认没有调用链依赖该 ID。

列表和搜索均分页返回。同步全部条目时，根据响应 total 继续翻页，不要假设一页包含全部结果。

与产品语义配置的边界

产品界面提供的十类语义条目及导入、导出、校验流程，参见分段与语义。当前两个公开 SDK 没有这些 UI 条目的专用 CRUD 或语义模型全量导入/导出方法。若集成必须管理这些能力，应先确认部署版本提供的服务契约，再扩展客户端；不要把通用 create_knowledge 当成所有语义类型的无损替代。

下一步