数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载本文是 toolbox/mdcode/docs/semantic-model/fidelity.md 的深度解读与扩展。核心主题是在kcmd本仓库toolbox/mdcode中的语义模型命令行工具中一份语义模型文档被kcmd push推送到 Knowledge Catalog 与 BigQuery / Spanner 属性图、再由kcmd pull拉回时每个方向分别保留什么、丢弃什么、规范化什么。读完本文你将掌握往返矩阵round-trip matrix的每一格含义、BigQuery 与 Spanner 两个后端的差异、pull返回的规范化视图为何不等于你的原始文件以及如何围绕这些保真度限制组织你的工作流——结论是始终以你亲手编写的模型文档为唯一事实来源source of truth。kcmd是语义模型Semantic Model的部署工具它以一份 YAML 文档描述业务的实体、字段、关系、度量把模型一次性部署到两类目的地——Knowledge Catalog治理与检索元数据和属性图BigQuery Graph 或 Spanner Graph供查询。推与拉都不是无损的目录只保存元数据图只保存它可查询的部分而pull只能返回目录当初被给予的内容。本文档就是一张每个方向存活什么的权威对照图。一、先理解三个目的地各自的内存在逐格分析前先明确三个目的地的本质差异这是理解整个保真度矩阵的前提Knowledge Catalog持有元数据而非模型全量拷贝。它用一组系统类型dataplex-types/global下的内置类型记录模型的条目、方面aspect与链接。唯一的例外是自定义类型semantic-action与semantic-constraint由kcmd init预置见 Reference → What gets created in Knowledge Catalog。push 只引用这些类型从不创建它们。BigQuery Graph部署一个CREATE OR REPLACE PROPERTY GRAPH实体→节点表NODE TABLE、关系→边表EDGE TABLE、度量→MEASURE描述性元数据写入每个元素的OPTIONS(...)可用--print查看生成的 DDL。Spanner Graph同样的CREATE OR REPLACE PROPERTY GRAPH但没有MEASURE、没有OPTIONS元数据——只保留可查询的结构节点表、边表、LABEL层次。哪个后端接收 push不由命令行标志决定而是由模型的deployment target或所选绑定 profile决定。详见 部署指南 与 binding profiles。二、往返矩阵round-trip matrix一图看懂每个要素的宿命行是你编写authored的模型要素列是它在每个方向上的结局✓ 按原样返回— 在该目的地不存在。BigQuery 与 Spanner 各占一列两者在所有结构性行上一致仅在有 Spanner 目标无MEASURE、无OPTIONS元数据之处不同。编写的要素→ Knowledge Catalogpull恢复→ BigQuery→ Spanner实体name、sourcesemantic-entity条目¹⁰✓NODE TABLENODE TABLE字段schema方面列✓类型收缩²节点表上的列¹节点表上的列¹字段labelschema逐字段注解✓并入OPTIONS(description)— 丢弃字段表达式规范 SQL仅--emit-expressions仅当随表达式推送生成 DDL生成 DDL字段维度角色is_time仅--emit-expressions³仅当随表达式推送³记入OPTIONS(description)— 丢弃主键schema.primaryKey✓节点表KEY(...)节点表KEY(...)唯一键schema.uniqueConstraints✓— 丢弃只发主键— 丢弃只发主键度量semantic-metric条目name、entity、description、instructions、type⁵MEASURE⁴— 丢弃无MEASURE关系1:1 / 1:Nschema-join链接✓名称规范化⁶EDGE TABLEEDGE TABLE关系M:N /association— 不存储—EDGE TABLE经 junction 表EDGE TABLE经 junction 表实体extends— 未建模—LABEL子句 字段展平LABEL子句 字段展平动作Actionsemantic-action条目¹²✓¹²— 不部署¹²— 不部署¹²约束Constraintsemantic-constraint条目¹³✓¹³— 不部署¹³— 不部署¹³description实体/度量/字段/关系条目描述 / 方面✓OPTIONS(description)— 丢弃ai_context.synonyms— 不存储—OPTIONS(synonyms[...])— 丢弃ai_context.instructionsguidelines方面⁷✓⁷并入OPTIONS(description)— 丢弃ai_context.examples— 不存储—并入OPTIONS(description)Examples:行— 丢弃模型级description/instructions模型条目上✓⁸— 丢弃⁸— 丢弃⁸模型级ai_context.synonyms/examples— 不存储—— 丢弃— 丢弃部署目标记录在模型条目上✓命名图命名图绑定 profile备选物理绑定— 只记录被选中的那个¹⁴—¹⁴每个 BigQuery 绑定的 profile 一张图每个 Spanner 绑定的 profile 一张图厂商方言expression变体非规范的dialects[]条目¹¹— 不存储—回退——仅当无规范expression时用于生成 DDL回退——仅当无规范expression时用于生成 DDLcustom_extensions超出部署目标— 不存储—⁹— 不在图中— 不在图中脚注详解单元格背后的细微差别字段类型来源。图使用源列source column自身的类型字段编写的datatype不会被携带。也就是说字段类型在图中由物理列决定而不是由逻辑声明决定。字段类型收缩collapses。字段类型基本可往返仅有两处收缩无类型 →Opaque以及String→ 无类型。两者在目录中都存为dataType STRING靠metadataType区分OTHER→ 读回OpaqueSTRING→ 读回无类型——这正是它们能以不同方式往返的原因。这一点在源码中有直接印证knowledge_catalog.ts 的 schemaAspectData 中无类型字段发布为OpaqueSTRING metadataType OTHER显式的类型未知标记使 pull 恢复为Opaque而非丢弃类型编写的String映射为 STRING。测试夹具 actions_place_order.knowledge_catalog.golden.json 与 actions_place_order.pull.golden.yaml 分别展示了这一发布与恢复形态。维度角色。默认推送省略逐字段的semantics块因此维度角色只有在--emit-expressions下才会写入——且回来后只是一个裸dimension: {}标记不带is_time等细节。默认推送则完全丢弃该标记。度量形态。一个度量必须解析到恰好一个实体否则 push 被拒绝并且归约到一个受支持的聚合——SUM/AVG/COUNT/MIN/MAX——作用于单个操作数否则以警告跳过。度量类型。度量的表达式受--emit-expressions门控其数据类型仅在为具体类型如Decimal时可往返——无类型、String或Opaque度量回来时无类型。原因在源码中可见metricAspectData 的注释说明度量方面模板只携带dataType而没有metadataType所以Opaque序列化为 STRINGpull 将度量恢复为无类型。关系名称。关系名称回来时被小写化/连字符化Places Order→places-order——目录只在链接 id 中保存名称。见下文Writer-side follow-up。guidelines 方面。guidelines方面只存在于模型、实体和度量上——字段与关系没有。因此字段级、关系级的ai_context.instructions在 Knowledge Catalog 中没有归宿关系的 instructions 仍会到达 BigQuery折入边的OPTIONS(description)。源码印证见 guidelinesAspectData只有ai_context.instructions被路由进该方面synonyms/examples在该方面没有位置。模型级元数据。两个图都没有语句级元数据的归宿——BigQuery 静默丢弃图语句的OPTIONSSpanner 完全没有OPTIONS——所以模型的description与ai_context.instructions改由 Knowledge Catalog 承载。其他自定义扩展。在香草0.2.0.dev0profile 下custom_extensions块GOOGLE 部署目标之外的是厂商元数据的唯一载体它在 push 时惰性、不持久化到 Knowledge Catalog因此pull永远不会恢复它。pull还发出扩展的0.2.0.dev0/googleprofile它没有custom_extensions载体所以这样的块也不会被重新序列化——保留你的编写文件。OWL 导入器不发出任何此类块它只导入见 导入 OWL 本体。逻辑未绑定模型。无绑定的模型仍然发布到 Knowledge Catalog每个实体的source记录为空resources: []因为背后没有表不带连接列的关系以警告跳过。当同一次 push 还部署了图时目录条目首先被裁剪为图所绑定的部分——见下文To Knowledge Catalog。厂商方言回退。你编写的是expression.dialects[]列表图从规范BigQuery/ANSI变体构建。importedExpression/importedDialect不是编写键——loader 从非规范方言条目例如度量导入自的 MAQL 或 Snowflake 形式推导它们并在无规范变体时逐字用作回退。见 Model spec §2.5。动作Actions。动作只到达 Knowledge Catalog——作为模型条目下的一个semantic-action条目pull从该条目读回。其他每个 push 目标都不为它部署任何东西并警告一次。其guards以约束名存储并逐字往返。名称所引用的约束若在一次 pull 中缺失会被保留而非丢弃因此部分 pull 绝不会静默改写作者的模型pull 对保留的名称发出警告push 在约束回归前拒绝该模型。名称被方面重复是唯一例外——会被丢弃到单一出现因为 loader 拒绝重复且文档必须保持可加载。其affects以同样方式往返对重复的 concept-and-operation 对也遵循同样的例外。见 Modeling write operations。约束Constraints。约束只到达 Knowledge Catalog——作为模型条目下的一个semantic-constraint条目pull读回它。其他每个 push 目标都不为它部署任何东西并警告一次。发布是 push 对约束所做的全部解决它的是运行run而应用所嵌入的运行时是在写入前把每个 guard 交给 judge 的东西。绑定 profiles。一个模型可以定义多个物理实现每个绑定 profile 一个。--all-profiles为每个声明了部署目标的 profile 部署一张图各自部署到其目标命名的后端没有目标的 profile 被跳过两个 profile 声称同一张图则在任何部署前被拒绝。Knowledge Catalog 仍只记录一个绑定——--profile命名的那个否则是默认绑定——而--all-profiles运行总是记录默认绑定两个标志互斥。见 Binding profiles。三、To Knowledge Catalog目录记录什么、以什么为条件目录保存元数据而非模型的完整拷贝。它使用的每个资源类型都是dataplex-types/global下的内置系统类型唯有kcmd init预置的自定义semantic-action/semantic-constraint类型对除外。push 引用这些类型从不创建它们。记录什么取决于 push 的类型仅目录的 push--no-profile或无绑定的纯逻辑模型记录整个模型文档声明的每个实体、度量和关系。同时部署图的 push先把模型裁剪为图所绑定的部分因此未绑定字段——以及任何依赖它的实体、度量或关系——也一并被排除在目录条目之外。对这类 push 的 pull 返回的是绑定视图而非完整编写模型。逻辑模型仍产生完整条目每个实体的source记录为空resources: []因为背后没有表不带连接列的关系以警告跳过。这一行为在源码中有明确注释与实现deploy_knowledge_catalog.ts 中对source.resources的处理空列表是诚实的尚无绑定测试 deploy_knowledge_catalog.test.ts 验证了逻辑模型的发布形态。一次绑定而非全部绑定。模型可定义多个物理实现——比如一个面向 BigQuery 的分析绑定和一个面向 Spanner 的操作绑定——kcmd push --all-profiles为每个部署一张图。目录这条腿不随之扇出它只运行一次针对--profile命名的 profile否则针对默认绑定。因此裸kcmd push与kcmd push --all-profiles写入相同的条目区别仅在于部署了多少张图。连续 push 不会累积。条目 id 只从逻辑名推导——模型、实体、度量——不带 profile 成分所以推送第二个 profile 会把目录调和到那个绑定而不是叠加到第一个写的内容上共享元素把source换成新 profile 的表在部署图因此会裁剪的 push 上新绑定无法回答的实体或度量被删除而非遗留。目录因此一次只描述一个物理实现它记录该绑定的部署目标和表但从不记录 profile 的名字也从不记录其他 profile 存在。pull返回最后写入的那个。保留 profile 文件——目录不是它们的仓库。默认不存 SQL 表达式。已发布的系统类型模板尚未携带逐字段semantics块或semantic-metric.expression字段因此默认 push 省略它们。传入--emit-expressions可在模板获得这些字段后写入规范的 GoogleSQL/ANSI 表达式。该门控在源码中明确实现knowledge_catalog.ts 第 125 行const emitExpr opts.emitExpressions ?? false;并在 schemaAspectData 与 metricAspectData 中据以决定是否发出semantics/expression键KcGenerateOptions.emitExpressions的声明见 deploy_knowledge_catalog.ts。目录从不存储ai_context.synonyms/examples、字段级ai_context只有模型、实体、度量的instructions在guidelines方面有归宿、以及原始厂商 SQLimportedExpression——例如度量导入自的 MAQL 或 Snowflake 形式。这些留在你的编写文档中厂商 SQL 与表达式在生成图 SQL 时仍会被使用。动作Actions在目录中的往返每个动作遵循与其他一切相同的每条目一元素规则各自成为模型条目下的一个semantic-action条目在semantic-action方面携带其 executor、类型化参数、guards与affects。它们通过pull无损往返名称、描述、executor、类型化参数、guards、affects、instructions。从字段投影的参数以其编写时的投影形式往返方面存储concept与field连同解析出的标量typepull 把投影写回时不带类型因此重新加载时从同一字段解析、得到同一参数。两样东西不随投影往返其label与ai_context被丢弃——方面没有地方放它们——所以 pull 恢复的是参数的description而非这两者。且 pull 恢复的措辞以参数自身的面目出现loader 在模型加载时把继承的description解析进参数下游无法区分其与作者手写的差别所以 pull 出的文档把它写在原作者留白的位置。重新加载得到同一参数但字段与参数如今各持一份副本改字段不再联动。投影字段不在 pull 文档中裁剪丢弃了无绑定可达的实体时参数以声明参数出现并携带解析出的type——因为发出一个解析不到任何东西的concept/field对会写出无法加载的文档。sqlexecutor随其余内容往返其statements它们是写入本身不是关于写入的注释因此丢弃它们的目录会描述一个无人能重新部署的动作。条目类型是自定义的所以kcmd init创建它不声明任何动作的模型永远不需要它。affects作为事实而非原文往返。两种编写形态——裸名称与记录——在模型中是同一形态所以只携带 concept 的记录- concept: Account回来时是裸Account说的是同一件事。首遍之后逐字节稳定。affects只存储作者所写的内容这正是它能在部分 pull 下完好存活的原因。一个concept是实体还是边不记录所以没有任何东西需要重新解析——也就不会有东西变陈旧。这对多对多关系最重要它根本到不了目录pull 从 schema-join 条目链接恢复关系而链接只携带外键边因此命名 M:N 边的 concept 在一个完全良构的模型上会显得无法解析——它却原样返回。约束Constraints在目录中的往返每个约束以同样方式发布各自成为模型条目下的一个semantic-constraint条目规则与任何instructions放在semantic-constraint方面description作为条目自身的摘要。名称、描述、on_violation、severity、instructions以及声明规则的任一体——expression或judgment——通过pull无损往返。声明了两种路由词的约束会原样返回不填充默认值。方面还携带一个派生的evaluation字段deterministic或judgedpull 从规则体重新计算而非读取它因此它永远不会与旁边的规则不一致它不会写入编写文档因为编写文件中的派生值是会变陈旧的值。同时声明两种规则体或都不声明的条目以警告跳过而不是被 pull 成一个自己 push 时会失败的模型。该条目类型也是自定义的不声明任何约束的模型永远不需要它。四、To BigQuery结构与描述元数据的分流push 同时保留可查询的结构与附着其上的描述性元数据。结构变成节点表、边表与度量描述性元数据写入图中每个元素的OPTIONS(...)用--print可见。BigQuery 图的OPTIONS给元素一个description字符串与一个synonyms数组。synonyms是唯一拥有专属选项的部分因此它结构性地、作为自己的数组携带过去。其余部分——description、instructions、examples和字段的label——共享单一的description字符串因此被合并进它examples 以Examples: …行呈现。它们的内容被保留它们的独立结构没有。模型自身的语句级元数据无处可去BigQuery 静默丢弃图语句的OPTIONS所以模型的description/ai_context不在图中——description与ai_context.instructions改由 Knowledge Catalog 承载。主键之外的唯一键也被丢弃只发主键。导入的厂商 SQL 不作为独立形式携带图在规范expression存在时从中构建仅当模型从未被转译成规范形式时才逐字回退到导入的厂商 SQL。extends层次在 BigQuery 端以LABEL子句 字段展平呈现一个实体可extends: [Parent, …]push 把超类型字段展平到每个子类子类表携带自己的KEY与全部继承属性的列绑定——具体规则与 SQL 示例见 Reference → Class hierarchies 与 Modeling class hierarchies。五、To Spanner只保留可查询的结构Spanner 目标保留可查询的结构丢弃描述性元数据。节点表、边表与LABEL含extends层次字段展平与 BigQuery 完全一致地部署但使用裸的表名与图名。两样东西按设计不上船度量Metrics。Spanner 没有MEASURE所以每个模型级度量都以警告丢弃。BigQuery 独有的度量必须解析到单个实体规则在此不适用。照常编写你的度量——BigQuery 目标仍会发出它们Knowledge Catalog 仍记录每个semantic-metric条目——它们只是不在 Spanner 图中。OPTIONS元数据。Spanner 不携带逐元素OPTIONS所以description、synonyms、instructions、examples与字段label不写入 Spanner DDL。它们在同一次 push 中仍到达 Knowledge Catalog模型/实体/度量的描述与instructions落在条目与guidelines方面上因此描述层活在目录中而非 Spanner 图中。这镜像了 BigQuery 丢弃图语句OPTIONS而保留逐元素OPTIONS的方式。其余一切——键、关系、标签层次——与上文的→ BigQuery列一致。动作与约束不到达任一图它们发布到 Knowledge Catalog各为一个semantic-action/semantic-constraint条目并通过pull无损往返。Spanner 端还使用异步 DDL语句经 Spanner AdminupdateDatabaseDdl长时运行操作应用并轮询完成BigQuery 经jobs.query运行其 DDL。见 Reference → What gets created in Spanner。六、What pull recovers返回的是规范化视图pull返回 push 写入的内容——上文pull恢复列即摘要。当 push 部署了图时push 写入的已被裁剪为绑定视图所以 pull 返回该视图。关于它如何回来有两类规范化Normalized——内容幸存形式改变关系名称回来时被小写化/连字符化Places Order→places-order目录只在链接 id 中存名称。测试验证了这一 id 形态deploy_knowledge_catalog.test.ts 断言直接外键关系写为一条schema-join链接、链接 id 为sales-orders-to-customeraction_affects.test.ts 与 actions.test.ts 则确认 pull 仅从schema-join条目链接重建关系。见下文Writer-side follow-up。字段类型往返除两处收缩无类型字段回来为OpaqueString字段回来为无类型两者都存dataType STRING靠字段的metadataType区分——见脚注²。度量的数据类型仅在具体类型如Decimal下往返无类型、String或Opaque度量回来为无类型因为度量方面存数据类型但不存标记其为Opaque的元数据类型。字段的维度角色仅当以--emit-expressions推送时存在回来为裸dimension: {}标记不带其细节is_time等。顺序每个实体内的字段顺序被保留但实体与度量的顺序不保留——它们按目录自己的顺序回来而非编写顺序。原 YAML 中的注释不被保留。因此push 后接 pull 不会返回你的原始文件。把 pull 出的文档视为目录元数据的忠实副本而非编写模型的副本并把编写文档保留为事实来源。七、Writer-side follow-up当前 push 写入侧的已知限制上文有一处缩减是 push 当前写入的限制而非 pull 能恢复的极限。它在此记录为写入侧后续事项读者pull已返回目录持有的全部内容。关系名称。schema-join方面类型的metadataTemplate没有关系名称的字段因此 push 无法存储它pull 从链接 id 恢复它——而链接 id 被小写化与连字符化条目链接 id 格式禁止原始大小写/下划线。逐字返回名称需要在 Knowledge Catalog服务端为内置schema-join方面类型添加名称字段之后客户端写/读是小事这与门控--emit-expressions的semantics字段属于同一类缺口。非规范的部署目标不是pull 缺口push 在任何一条腿运行前就在验证门拒绝它因此它永远不会被写入——见 Validation。八、实操建议围绕保真度组织工作流把上面的矩阵落到日常操作几条可执行的结论把编写文档当唯一事实来源。目录是元数据视图、图是可查询视图、pull 是目录视图——三者都非你的 YAML。pull适合恢复工作区、查看目录实际持有内容、或确认别人部署的模型但不适合作为编辑主副本。删除模型文档不会自动清目录条目跨模型删除需要--force-remove见 README → Updating and removing models。需要表达式与维度角色进目录时用--emit-expressions。默认关闭开启后规范表达式与semantics角色随条目发布并可被 pull 恢复。kcmd push --print与--validate-only可在写任何东西前预览生成的 DDL 与条目计划。区分后端能力。Spanner 目标丢弃度量与全部OPTIONS描述层描述活在目录中BigQuery 目标把描述合并进OPTIONS(description)但丢弃图语句级元数据与唯一键。为查询性选后端时先对照本文矩阵确认你依赖的要素在目标后端有归宿。绑定 profile 与目录的关系是一次一个。--all-profiles部署多张图但目录只记录一个绑定默认绑定连续推送不同 profile 会调和替换source、删除新绑定无法回答的元素而非累积。保留 profile 文件——目录不是它们的仓库。动作与约束只活在目录。它们不到达任一图依赖目录的semantic-action/semantic-constraint条目做治理与发现别指望图 DDL 中出现它们。kcmd init --semantic-model会预置这两个自定义类型对。九、相关文档与源码指引fidelity.md本文来源原文档Deploying a semantic model部署总览Model specification格式规范§2.5 表达式、§6 扩展机制、§7 绑定层Binding profiles一个逻辑模型、多个物理绑定ReferenceCLI 标志、各目的地创建物、验证、权限Modeling write operations动作与约束的完整建模指南源码实现knowledge_catalog.ts目录条目/方面生成、deploy_knowledge_catalog.ts目录推送选项、deploy_bigquery.ts 与 deploy_spanner.ts图 DDL 生成、pull_kc.tspull 重建测试验证deploy_knowledge_catalog.test.ts、actions.test.ts、action_affects.test.ts以及 golden 夹具如 actions_place_order.knowledge_catalog.golden.json赞分享数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载相关推荐Apache HBase 的 ACID 语义它到底保证什么、不保证什么以及如何按需调节Apache HBase 的 ACID 语义它到底保证什么、不保证什么以及如何按需调节 本文以 Apache HBase 官网的 ACID 语义说明为骨架数据库大数据列式数据库分布式数据库后端这个PR做了什么对用户有什么影响这个PR做了什么对用户有什么影响 如何测试这个更改 逐行检查代码注意 代码是否覆盖了所有边界情况 代码是否遵循命名、格式、模块化等约定 测试步骤数据可视化前端Open edX 平台错误监控决策为什么移除了 EXPECTED_ERRORS 并只保留 IGNORED_ERRORSOpen edX 平台错误监控决策为什么移除了 EXPECTED_ERRORS 并只保留 IGNORED_ERRORS 本文为 Open edX 平台ope后端教育上一篇5分钟生成IDA脚本iblessing的Objective-C方法交叉引用可视化方案下一篇前端性能分析终极指南如何快速提升Lighthouse评分到90创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考