知识条目

在当前 SDK 中，Explore 数据来源和 NL2SQL 知识项是两类不同对象：

• 来源是 Catalog 中真实存在的表或文件。Explore 请求通过数据库、表名和文件 ID 选择它们。

• 知识项是独立的 NL2SQL 上下文记录，由 knowledge_type、knowledge_key、字符串值和关联表等字段组成。

创建知识项不会上传文件、创建表或把 Catalog 对象绑定到产品知识库；删除知识项也不会删除表或文件。

先取得可靠的来源标识

Python 和 Go SDK 都提供 Catalog、Database、Table、Volume、File 和 Folder API。构造 Explore 数据范围之前，应通过这些 API 取得真实标识，不要把界面显示名称当作 ID。

Explore 选择	所需值	建议来源
指定表	数据库名称、表名列表	数据库和表详情 API
数据库中的全部表	数据库名称、数据库数值 ID	数据库详情 API
指定文件	文件 ID 列表	文件列表或详情 API
数据库中的全部文件	数据库数值 ID	数据库详情和 Catalog 树

Explore 的 DataAskingTableConfig 使用表名，而 FileConfig 使用文件 ID。这两种值不能互换。

产品知识库对来源还会执行解析、分段、索引、启停和版本治理。当前公开 Python/Go SDK 没有这些知识库来源的专用方法；Catalog 文件存在不代表已经完成知识库处理。需要该流程时参阅创建与数据源。

管理 NL2SQL 知识项

最小的可靠流程是创建、回读、测试，再决定是否保留：

from moi import RawClient

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

created = raw.create_knowledge(
    {
        "knowledge_type": configured_type,
        "knowledge_key": "net_revenue",
        "knowledge_value": [
            "Use the reviewed net-revenue definition maintained by the finance team."
        ],
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)

saved = raw.get_knowledge({"id": created["id"]})

Go 使用相同字段的 NL2SQLKnowledgeCreateRequest 和 NL2SQLKnowledgeGetRequest。完整字段说明参见语义模型。

分页同步

list_knowledge 返回 list 和 total。Python 示例：

page = 1
page_size = 100
entries = []

while True:
    result = raw.list_knowledge(
        {
            "knowledge_type": configured_type,
            "page_number": page,
            "page_size": page_size,
        }
    )
    entries.extend(result.get("list", []))
    if len(entries) >= result.get("total", 0):
        break
    page += 1

不要使用某一页的长度判断远端已清空。同步程序应先读完所有页，再计算创建、更新和删除差异。

搜索与去重

search_knowledge 接受 knowledge_type、knowledge_key、page_number 和 page_size。写入前可以按类型和 Key 搜索，但搜索结果不是数据库唯一约束。并发写入仍可能产生重复项，因此：

1. 在应用侧为业务 Key 规定稳定命名规则。

2. 写入前搜索，写入后按返回 ID 回读。

3. 定期列出全部条目，报告相同类型和 Key 的重复记录。

4. 删除重复项前，比较 value、associate_tables 和调用方引用。

更新和删除

Python 更新请求使用 id，并携带完整知识字段：

raw.update_knowledge(
    {
        "id": saved["id"],
        "knowledge_type": configured_type,
        "knowledge_key": saved["key"],
        "knowledge_value": revised_values,
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)

delete_knowledge({"id": ...}) 是永久删除。执行批量清理前，先导出列表结果并限制删除 ID 集合；不要根据模糊搜索结果直接删除。

排查

现象	检查
Explore 没有使用某知识项	knowledge_type、关联表、Explore 数据范围和服务支持的类别
指定表无结果	数据库名称、表名、调用身份的表权限
指定文件无结果	是否传了文件 ID，以及该文件是否可访问、可用于当前服务
列表数量不稳定	是否完整翻页，是否有并发写入
更新后字段消失	更新请求是否遗漏必须保留的字段

下一步

• 数据源

• 流式查询

• Catalog SDK