Manage Kg Schema

知识图谱本体模型管理（manage-kg-schema）

1. Scenario Description

数据架构师通过阿里云 CLI 管理知识图谱的本体模型（Schema）。当前 KG Schema OpenAPI 仅提供整体 Schema 级别的操作（导出 / 导入 / 发布），不提供实体类型、关系类型的细粒度单独 CRUD 接口。因此新增 / 修改 / 删除实体类型、关系类型、属性，均通过「导出 YAML → 本地编辑 → 整体导入 → 发布」的流程完成。

业务流程：

导出当前 Schema（基线）→ 本地编辑 YAML（增删改类型/属性）→ 整体导入 Schema → 发布 Schema → 查询发布结果

资源拓扑：

知识图谱空间（Workspace）
├── 实体类型（EntityType）
│   ├── 属性定义（Properties）
│   └── 继承关系（ParentTypeId）
├── 关系类型（RelationType）
│   ├── 起始/目标实体类型
│   ├── 基数（Cardinality）
│   └── 关系属性
├── Schema 版本
│   ├── 草稿态（Draft）
│   └── 已发布版本（Published）
└── 发布任务（PublishTask）
    ├── 四项校验（连接/完整性/兼容性/偏离）
    └── 数据调整策略（BackfillDefault）

前置条件：

• 知识图谱空间（Workspace）已存在，当前用户有空间管理权限
• OpTenantId（租户 ID）已知

CLI 原生支持：KG OpenAPI 已正式发布（CLI --help 实测显示 Online version: v6.1.1，以 aliyun dataphin-public export-kg-schema --help 实际输出为准），并注册到 aliyun-cli-dataphin-public 插件（>= 0.7.1）。本 Skill 全部使用 CLI 原生命令 export-kg-schema / import-kg-schema / publish-kg-schema / get-kg-schema-publish-result。独立部署低于该版本（< v6.1.1）的旧环境未发布 KG OpenAPI，可退回 Python Tea SDK 泛化调用（辅助脚本 scripts/export-schema.py / scripts/import-schema.py）。

重要（能力边界）：当前 KG Schema OpenAPI 仅支持整体 Schema 操作——导出、导入、发布及查询发布结果。不存在 CreateKgEntityType / UpdateKgEntityType / DeleteKgEntityType / CreateKgRelationType 等细粒度单类型 CRUD 接口。所有类型/属性的增删改，请编辑导出的 YAML 后整体重新导入。

🚨 建模前先确认图引擎：导出/导入/发布这 4 个接口本身引擎无关，但 YAML 里的 dataType 与业务识别规则随引擎变化（Lindorm 图引擎自 V6.2.3 支持）：

建模项	Neo4j	Lindorm 图引擎
日期/时间 DATE TIMESTAMP DURATION	✅	❌ 不支持 → 用 STRING 存 ISO 8601 字串
多值	LIST ✅ / SET ❌	LIST ❌ / SET ✅（V6.2.3 新增）
嵌套 EMBEDDED / MAP<K,V>	✅	❌ 不支持 → 用 STRING 存 JSON 文本
UNKNOWN（AI 抽取待确认）	✅	❌ 不支持
GEOPOINT	✅ Point	✅（底层落 String）
业务识别规则	含编辑距离、时间类规则	❌ 无编辑距离、无时间类规则（其余精确/忽略大小写/包含/等于/数值/语义相似度均支持）

完整类型映射表与替代写法见 图引擎能力矩阵。向 Lindorm 空间导入含不支持类型的 YAML 会在导入/发布阶段失败或被静默降级，请在编辑阶段就按引擎裁剪。

2. Installation

Pre-check: Aliyun CLI >= 3.4.8 required

运行 aliyun version 确认版本 >= 3.4.8。未安装或版本过低，请从 https://aliyuncli.alicdn.com 安装/升级（各操作系统一键脚本见 ./references/cli-installation-guide.md）。

Pre-check: Aliyun CLI plugin update required

[MUST] 运行 aliyun configure set --auto-plugin-install true 开启插件自动安装。 [MUST] 运行 aliyun plugin update 确保已装插件保持最新（KG 命令要求插件 >= 0.7.1）。

# 安装 aliyun CLI（>= 3.4.8）：https://github.com/aliyun/aliyun-cli
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 开启插件自动安装并更新已装插件
aliyun configure set --auto-plugin-install true
aliyun plugin update

# 安装 dataphin-public 插件（>= 0.7.1，KG 命令自 0.7.x 起注册）
aliyun plugin install --names aliyun-cli-dataphin-public

# 安装 Python 依赖（YAML 预校验脚本需要 pyyaml；SDK 兜底脚本另需 tea-openapi）
pip3 install pyyaml

# 验证：KG Schema 命令已注册
aliyun dataphin-public export-kg-schema --help

详见 CLI 安装指南。

3. Environment Variables

凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

# 检查凭证配置
aliyun configure list

# 检查 CLI 版本
aliyun version
# 要求 >= 3.4.8

# 检查 KG 命令已注册（插件 >= 0.7.1）
aliyun dataphin-public export-kg-schema --help

凭证不可打印：任何时候不得将 AccessKey ID/Secret 输出到终端或日志。

5. RAM Policy

本 Skill 涉及的最小 RAM 权限：

{
  "Effect": "Allow",
  "Action": [
    "dataphin:ExportKgSchema",
    "dataphin:ImportKgSchema",
    "dataphin:PublishKgSchema",
    "dataphin:GetKgSchemaPublishResult"
  ],
  "Resource": "*"
}

Permission Failure Handling

若遇到权限错误（HTTP 403 或 ErrorCode 含 Forbidden/NoPermission/Dataphin.KG.NoPermission），请：

1. 确认 RAM 用户已附加上述策略
2. 确认策略中 Resource 范围覆盖目标租户
3. 确认当前用户具有知识图谱空间的管理权限
4. 联系租户管理员授权

详见 RAM 策略参考。

6. Parameter Confirmation

IMPORTANT: Parameter Confirmation 执行前必须确认以下业务参数：

WorkspaceId 无自助发现途径：KG OpenAPI 不提供列出 KG 空间的接口（全部 18 个 KG 命令中无任何 list-workspace 类命令），WorkspaceId 必须向用户索取（32 位小写 hex 字符串，可在控制台知识图谱空间列表页查到）。不要尝试猜命令或翻 help 探索。

详细 API 入参/出参见 KG Schema API 参数参考。

7. Observability

本子 Skill 的 session-id 继承自父 Skill alibabacloud-dataphin-skills，不重新生成。

所有 CLI 命令携带：

--user-agent AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}

其中 {SESSION_ID} 为父 Skill 生成的 32 字符小写十六进制字符串。

8. Core Workflow

能力边界（务必先读）：KG Schema OpenAPI 仅支持整体 Schema 操作——export-kg-schema（导出）、import-kg-schema（导入）、publish-kg-schema（发布）、get-kg-schema-publish-result（查询发布结果）。不存在 CreateKgEntityType / UpdateKgEntityType / DeleteKgEntityType / CreateKgRelationType 等细粒度单类型 CRUD 接口。新增 / 修改 / 删除实体类型、关系类型、属性，统一通过「导出 YAML → 本地编辑 → 整体导入 → 发布」完成。

步骤 1：导出当前 Schema（基线）

# 导出 YAML 并直接提取 Schema 内容存为基线文件
aliyun dataphin-public export-kg-schema \
  --op-tenant-id "{OpTenantId}" \
  --workspace-id "{WorkspaceId}" \
  --output-format yaml \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}" \
  --cli-query 'SchemaInfo.Content'

可选参数：

• --output-format：yaml（默认）/ json
• --version-id：空或 -1 返回草稿态；0 返回最新已发布版本；正整数返回指定版本

响应处理：

• Schema 内容位于 SchemaInfo.Content（字符串），输出格式位于 SchemaInfo.OutputFormat
• 用 --cli-query 'SchemaInfo.Content' 可直接提取内容（输出为 JSON 引号包裹的字符串，需反序列化：python3 -c "import json,sys; print(json.load(sys.stdin))" < raw.txt > schema.yaml）
• 响应不含 VersionId（版本号通过 get-kg-schema-publish-result 获取）

将导出的 YAML 保存为本地文件（如 schema.yaml）作为编辑基线。若空间为空、首次建模，可跳过导出直接从零编写 YAML。

步骤 2：本地编辑并预校验 YAML

在导出的 YAML 上直接增删改实体类型 / 关系类型 / 属性——这是唯一的类型级变更方式（无单类型 CRUD API）：

• 新增类型/属性：在 entityTypes / relationTypes / properties 下追加条目
• 修改类型/属性：直接改对应字段值
• 删除类型/属性：从 YAML 移除对应条目，随后以 Replace 策略导入（见步骤 3）

编辑完成后运行 scripts/validate-schema.py 预校验，提前发现常见错误：

# 仅校验
python3 alibabacloud-dataphin-skills/references/knowledge-graph/manage-kg-schema/scripts/validate-schema.py <yaml_file>

# 自动修复可处理的问题（dataType 大小写、补充缺失 boolean 字段等）：
python3 alibabacloud-dataphin-skills/references/knowledge-graph/manage-kg-schema/scripts/validate-schema.py <yaml_file> --fix

校验规则覆盖：

• 实体/属性/关系编码格式
• 每个实体至少一个 isPrimaryKey: true（useSysPk=false 时）
• 每个实体至少一个 isUsedShow: true
• dataType 全大写
• cardinalType 合法值
• 属性/关系引用的实体存在性
• 唯一性：实体/关系的编码与名称各自空间内唯一，且编码与名称均跨类型（实体↔关系）唯一；属性编码/名称在同一类型内唯一

YAML Schema 格式要点：

isUsedShow 标记用于展示的属性（每个实体类型必须至少有一个）。useSysPk: true 时使用系统主键，所有属性 isPrimaryKey 为 false。

按图引擎裁剪 dataType（Lindorm 空间必看）

两引擎均不支持：DECIMAL / BIGINTEGER / DATETIMERANGE（高精度数值用 STRING 存，时间区间拆两个字段）。完整矩阵见 图引擎能力矩阵。

业务识别规则（实体消歧）也随引擎：Lindorm 不支持编辑距离与时间类型规则（控制台选项隐藏）。需要“名称近似去重”时，在 Lindorm 空间改用语义相似度 / 忽略大小写 / 包含策略（识别规则本身在控制台配置，OpenAPI 不提供规则管理接口）。

开启语义检索（isSemanticEnabled，引擎无关）

语义检索（SearchKgBySemantic 的语义路径）的开启方式是属性层开关：在实体/关系属性上置 isSemanticEnabled: true，导入并发布后平台自动创建向量索引（Neo4j 上自动执行 CREATE VECTOR INDEX ... ON (n.__system_kg_embedding__<prop>__)）。不需要也不能用 Cypher 手建向量索引（exec-kg-cypher 只读，CREATE 会被拒）。

Neo4j 版本门槛 5.11+（trace 72c13131 实测）：CREATE VECTOR INDEX 是 Neo4j 5.11+ 语法，低版本实例发布带语义属性的 Schema 必失败，发布结果日志里报 Invalid input 'VECTOR': expected "(", "allShortestPaths" or "shortestPath"。这是引擎版本限制不是操作错误，重试无效；正解是升级 Neo4j 到 5.11+，或由管理员确认实例支持向量索引。详见 图引擎能力矩阵 §语义检索开启方式与向量索引。

YAML 示例片段：

name: 我的知识图谱
description: 示例 Schema
workspaceId: "{WorkspaceId}"
entityTypes:
- code: COMPANY
  name: 公司
  useSysPk: false
  description: 企业实体
  properties:
  - code: name
    name: 公司名称
    dataType: STRING
    isPrimaryKey: true
    isRequired: true
    isIndexed: true
    isUsedShow: true
    defaultValue: ''
  - code: industry
    name: 行业
    dataType: STRING
    isPrimaryKey: false
    isRequired: false
    isIndexed: false
    isUsedShow: false
    defaultValue: ''
relationTypes: []

步骤 3：导入 Schema（YAML）

前置检查：空间状态必须可编辑

导入前先跑 get-kg-schema-publish-result（见步骤 5，不带 --version-id 返回最近一次发布记录）检查空间状态：若 Data.Status 为 RollbackFailed（发布失败且回滚失败），空间处于不可编辑状态，import-kg-schema / publish-kg-schema 均会返回 400 DPN.Planning.KgWorkspaceStatusNotEditable（「知识图谱空间处于不可编辑状态:ROLLBACK_FAILED」）。此状态 OpenAPI 侧无任何恢复/重置命令，请勿重试，唯一出路是到 Dataphin 控制台人工恢复该空间。

HITL 确认（写操作 / 高危）

执行前确认：

• Schema YAML 内容来源
• 合并策略：Replace（替换）/ Merge（合并）
• 影响范围：Replace 会删除空间中 YAML 未包含的类型（删除类型即通过此方式：从 YAML 移除后 Replace 导入）
• Merge 不删除：Merge 只新增/更新，不会删除 YAML 中未列出的已有类型（即使响应/日志显示"已删除"，草稿态仍保留）。需删除已有类型时必须用 Replace。

确认后执行：

# YAML 内容含换行/引号，建议用 python3 组装 ImportCommand JSON 再传入
python3 -c "
import json
content = open('schema.yaml').read()
cmd = {'Content': content, 'InputFormat': 'yaml', 'MergeStrategy': 'Merge'}
open('import-cmd.json', 'w').write(json.dumps(cmd, ensure_ascii=False))
"

aliyun dataphin-public import-kg-schema \
  --op-tenant-id "{OpTenantId}" \
  --workspace-id "{WorkspaceId}" \
  --import-command "$(cat import-cmd.json)" \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}"

字段名注意：--import-command JSON 结构为 {Content, InputFormat, MergeStrategy}——格式字段名是 InputFormat（取值 yaml/json），不是 Format。

响应处理：

• ImportResult.EntityTypeCount / RelationTypeCount：计数不可信，不可作为导入验证依据——实测以 Replace 导入 7 实体/9 关系的基线，响应却返回 9/10（导入前草稿态的计数），Merge 场景同样不可信。唯一可信验证是导入/发布后 export-kg-schema 核对类型清单
• 导入仅写入草稿态；须经步骤 4 发布后才在图引擎生效

步骤 4：发布 Schema

HITL 确认（写操作 / 高危 / 异步）

执行前确认：

• 发布备注描述
• 是否有破坏性变更（如非必填→必填）需要数据调整策略
• 影响范围：将草稿态 Schema 发布为正式版本并同步到图引擎

确认后执行：

aliyun dataphin-public publish-kg-schema \
  --op-tenant-id "{OpTenantId}" \
  --workspace-id "{WorkspaceId}" \
  --publish-command '{
    "Description": "新增公司实体类型及投资关系类型",
    "DataAdjustmentPolicies": []
  }' \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}"

响应处理：

• 提取 Data.VersionId（预期发布后的最新模型版本号），用于步骤 5 查询发布结果
• 返回 ok 只是受理成功：向量索引创建等实际执行结果必须到步骤 5 复核（trace 72c13131 实测：publish 返回成功，但发布结果里向量索引创建失败），不要凭发布返回 ok 就宣布成功

步骤 5：查询发布结果

# 不带 --version-id 时返回最近一次发布记录
aliyun dataphin-public get-kg-schema-publish-result \
  --op-tenant-id "{OpTenantId}" \
  --workspace-id "{WorkspaceId}" \
  --version-id {VersionId} \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}"

响应处理：

• Data.Status：Publishing（执行中）/ Published（成功）/ Partial（部分完成）/ Failed（失败）/ RollbackFailed（发布失败且回滚失败——空间进入不可编辑状态，后续 import-kg-schema / publish-kg-schema 均报 400 DPN.Planning.KgWorkspaceStatusNotEditable）
• Data.Content：发布过程日志（含各阶段时间戳与校验结果）；含 isSemanticEnabled 属性时重点看向量索引创建记录——出现「属性新增向量索引：X 失败」+ Invalid input 'VECTOR' 即 Neo4j 版本 < 5.11（见步骤 2 专节，不要重试）
• Data.VersionId：本次发布的版本号
• 如为 Publishing 状态，间隔 5 秒后重新查询，直到终态
• 如为 RollbackFailed：不要重试导入/发布——OpenAPI 侧无恢复/重置命令，必须到 Dataphin 控制台人工恢复空间后再继续

兜底：旧版本独立部署（SDK 泛化调用）

独立部署低于 KG OpenAPI 发布版本（< v6.1.1）时，使用辅助脚本（Python Tea SDK call_api()）：

pip3 install pyyaml alibabacloud-tea-openapi alibabacloud-tea-util
export ALIBABA_CLOUD_ACCESS_KEY_ID=... ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
export DATAPHIN_ENDPOINT={endpoint} DATAPHIN_TENANT_ID={OpTenantId} DATAPHIN_WORKSPACE_ID={WorkspaceId}

# 只读导出基线（--output 存文件；独立部署自签证书加 --ignore-ssl）
python3 scripts/export-schema.py --ignore-ssl --output schema.yaml

# 端到端导入（本地校验 → 导出基线 → 导入 → 验证 → 发布 → 轮询）
python3 scripts/import-schema.py <yaml_file> --ignore-ssl [--skip-publish] [--merge-strategy Merge]

SDK 调用细节见 Python SDK 模板 与 scripts/README.md。

9. Success Verification

1. Schema 内容：export-kg-schema 返回的 SchemaInfo.Content 含预期的实体类型和关系类型
2. 发布成功：get-kg-schema-publish-result 返回 Data.Status: Published
3. 发布日志：Data.Content 日志显示各阶段（版本快照/类型处理）均完成、无报错
4. 语义检索（若开启）：Data.Content 中向量索引创建无失败记录；可再用 SearchKgBySemantic 验证 MatchSource 含 semantic/both（全为 keyword 说明语义路径未生效）

10. Cleanup

无细粒度删除接口。清理某个实体类型/关系类型的方式：从 YAML 中移除对应条目，再以 Replace 策略整体导入并发布：

# 1. 导出当前 Schema 作为基线
aliyun dataphin-public export-kg-schema \
  --op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
  --output-format yaml \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}" \
  --cli-query 'SchemaInfo.Content'

# 2. 本地编辑 YAML，删除不需要的 entityTypes / relationTypes 条目
#    （删除实体类型前，需一并删除 YAML 中引用该类型的所有关系类型）

# 3. 以 Replace 策略整体导入（Replace 会删除空间中 YAML 未包含的类型）
aliyun dataphin-public import-kg-schema \
  --op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
  --import-command '{"Content": "...(移除目标类型后的 YAML)...", "InputFormat": "yaml", "MergeStrategy": "Replace"}' \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}"

# 4. 发布使删除生效（见步骤 4）

11. Command Tables

KG Schema OpenAPI 仅提供以上 4 个整体 Schema 命令，无实体类型/关系类型的细粒度 CRUD 命令。命令已注册到 CLI 插件（>= 0.7.1，--help 实测 Online version v6.1.1）。

详见 相关命令索引。

12. Best Practices

• 仅整体 Schema 操作（重要）：无 CreateKgEntityType 等细粒度单类型 API。类型/属性的增删改一律「导出 YAML → 编辑 → 整体导入 → 发布」；删除类型用 Replace 策略导入移除了该类型的 YAML
• 先确认图引擎再编辑 YAML（重要）：dataType 可用集合随引擎变化——Lindorm 不支持 DATE/TIMESTAMP/LIST/DURATION/EMBEDDED/MAP/UNKNOWN（时间类改 STRING 存 ISO 字串，多值改 SET，嵌套改 STRING 存 JSON），而 SET 仅 Lindorm 支持。引擎不明时先问用户，详见 图引擎能力矩阵
• 业务识别规则的引擎差异：Lindorm 无编辑距离与时间类规则，近似去重改用语义相似度/忽略大小写/包含（规则在控制台配置，OpenAPI 无规则管理接口）
• CLI 原生优先：KG API 已注册到 CLI 插件（>= 0.7.1），直接使用 aliyun dataphin-public <cmd>；命令报 unknown command 时先 aliyun plugin update
• InputFormat 字段名（重要）：--import-command JSON 的格式字段是 InputFormat（不是 Format），取值 yaml/json
• YAML 传参用文件组装：YAML 内容含换行/引号，直接内联 shell 易转义出错，建议用 python3 组装 ImportCommand JSON 文件后 "$(cat import-cmd.json)" 传入
• 编码唯一性：EntityCode / RelationCode 在空间内唯一，编辑 YAML 时保证不重复
• 导入 YAML 必填字段：每个属性必须包含 code/name/dataType/isPrimaryKey/isRequired/isIndexed/isUsedShow/defaultValue；每个实体至少一个 isPrimaryKey: true 和一个 isUsedShow: true
• dataType 全大写：STRING / INTEGER / FLOAT / BOOLEAN / DATE / TIMESTAMP / DECIMAL（具体可用范围按图引擎裁剪，见上文）
• useSysPk：实体级别 useSysPk: true 表示系统自动生成主键（此时所有属性 isPrimaryKey 为 false）；false 表示业务主键模式
• cardinalType 枚举：MULTI_TO_MULTI / ONE_TO_MANY / ONE_TO_ONE（关系基数）
• 导入策略选择：Replace（完整替换，慎用）vs Merge（增量合并，推荐日常使用）
• Merge 删除语义（重要）：Merge 只做新增/更新，不会删除 YAML 中未列出的已有类型——实测即使 Import 响应报 count 减少、发布日志写"处理被删除…完成"，草稿态实际仍保留原类型。如需删除已有类型，必须改用 Replace 策略（从 YAML 移除该类型后 Replace 导入并发布）。
• ImportResult 计数不可信（重要）：ImportResult.EntityTypeCount / RelationTypeCount 在 Merge / Replace 两种策略下均不可作为验证依据（实测 Replace 导入返回的是导入前草稿态的计数）。唯一可信验证是导入/发布后 export-kg-schema 核对类型清单
• 导入前空间状态前置检查（重要）：导入/发布前先跑 get-kg-schema-publish-result 检查空间状态；遇 400 DPN.Planning.KgWorkspaceStatusNotEditable（如 RollbackFailed 发布失败且回滚失败）时 API 侧无解、盲目重试无效，需到 Dataphin 控制台人工恢复空间。注意：Schema 面不可编辑不影响数据面读写（create-kg-entity / exec-kg-cypher 等基于已发布版本仍正常，见 manage-kg-knowledge）
• 发布是异步的：publish-kg-schema 返回 Data.VersionId，需轮询 get-kg-schema-publish-result 获取最终状态（Data.Status）
• 破坏性变更：非必填→必填时需提供 DataAdjustmentPolicies 中的 BackFillDefaultValuePolicy 策略，否则返回 Dataphin.KG.RequiredDefaultMissing
• 版本查询：export-kg-schema --version-id：空/-1=草稿态、0=最新已发布版本、正整数=指定版本
• 大整数 ID：WorkspaceId 等 ID 用字符串传参
• 独立部署 Endpoint：--endpoint dataphin-openapi.<env>.aliyun.com（不带 https:// 前缀）
• 旧环境兜底：独立部署低于 KG OpenAPI 发布版本（< v6.1.1，以 --help 显示的 Online version 为准）无 KG OpenAPI，退回 scripts/export-schema.py / scripts/import-schema.py SDK 泛化调用