数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载导读本文围绕 knowledge-catalog 仓库中 ossie 参考示例目录展开它原样收纳了 Apache Ossie 官方仓库中的 OSI 语义模型文档tpcds_semantic_model.yaml与核心 JSON Schemaosi-schema.json作为互操作测试夹具fixture证明语义模型加载器能够直接摄取由规范所有者撰写的真实 OSI 文档版本0.2.0.dev0。读完本文你将理解 OSI 文档的顶层结构与核心对象数据集、字段、关系、指标、扩展机制掌握仓库如何在进程内用 ajv 复现 Apache 官方校验器第一步的 JSON-Schema 检查并学会在自己的语义模型工作中复用这套规范即守卫的校验思路。一、为什么需要Vendored 参考示例互操作 fixture 的定位在 ossie/README.md 中这个目录被明确定义为Vendored Apache Ossie reference examples收纳自 Apache Ossie 的参考示例。它包含两个文件均声明为从上游项目原样复制、未做任何修改文件来源用途许可证tpcds_semantic_model.yamlApache Ossie 官方 examples互操作 fixture验证加载器能摄取一份真实的、由规范所有者编写的 OSI 文档v0.2.0.dev0Apache License 2.0保留原始 ASF 许可头osi-schema.jsonApache Ossie 官方 core-specOSI 核心 JSON SchemaDraft 2020-12用于对所有 YAML fixture 做结构校验Apache License 2.0两个关键点定义了这套 fixture 的价值不修改。tpcds_semantic_model.yaml是spec-owner-authored规范所有者亲自撰写的文档原样入库意味着任何加载器/解析器改动都不能只迎合仓库自己的手写样例还必须通过这份外部权威样本。仅作测试输入。README 明确说明 These are test inputs only; they are not part of the shipped package即它不进入发布包纯粹服务于测试链路。从项目整体看这与 model_spec.md 中对格式基线的定义互为印证该规范文档声明kcmd的语义模型格式是Apache Ossie0.2.0.dev0的 profile并把这份 vendored 的osi-schema.json视为什么是 Ossie 所定义的权威依据——That schema, notkcmds parser, is the authority for what Ossie defines该 schema 而非解析器才是 Ossie 定义的权威。二、osi-schema.json 解剖OSI 核心元数据规范的 JSON-Schema 表达osi-schema.json 使用JSON Schema Draft 2020-12编写标题为 Apache Ossie Core Metadata Specification。它把 OSI 文档定义为一张严格的、闭合的对象图2.1 顶层形状{ version: { type: string, const: 0.2.0.dev0 }, semantic_model: { type: array, items: { $ref: #/$defs/SemanticModel } } }version是const固定值0.2.0.dev0不是任意字符串semantic_model是模型数组顶层required: [version, semantic_model]且additionalProperties: false——任何未知顶层键都会导致校验失败。2.2 关键 $defs 一览$defs核心约束说明Dialectenum: [ANSI_SQL, SNOWFLAKE, MDX, TABLEAU, DATABRICKS, MAQL, BIGQUERY]受支持的 SQL/表达式方言枚举Vendor任意字符串含COMMON/SNOWFLAKE/SALESFORCE/DBT/DATABRICKS/GOODDATA/WISDOM示例自定义扩展的厂商命名空间DataTypeenum: [String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz, Opaque]逻辑数据类型。注释特别区分Decimal是精确 base-10精度/标度未指定Float是近似值DateTime无时区/偏移DateTimeTz用偏移或时区上下文标识瞬间类型未知时省略datatype已知但超出可移植词汇时用Opaquecustom_extensionsAIContextoneOf字符串或对象instructions/synonyms/examples供 AI 工具使用的附加上下文CustomExtensionrequired: [vendor_name, data]additionalProperties: falsedata为承载厂商特定数据的 JSON 字符串DialectExpressionrequired: [dialect, expression]特定方言下的表达式Expressionrequired: [dialects]minItems: 1多方言表达式定义Fieldrequired: [name, expression]可选dimension/label/description/datatype/ai_context/custom_extensions行级属性用于分组、过滤与指标表达式Dimension仅is_time布尔时间角色标记is_time缺省时若datatype属于Date/Time/DateTime/DateTimeTz则默认为true显式false可将审计时间戳之类的时态列排除出时间维度Datasetrequired: [name, source]primary_key/unique_keys为字符串数组unique_keys是数组的数组逻辑数据集事实表或维度表Relationshiprequired: [name, from, to, from_columns, to_columns]from_columns/to_columns均minItems: 1数据集间外键关系from为多侧、to为一侧Metricrequired: [name, expression]定量度量SemanticModelrequired: [name, datasets]datasetsminItems: 1完整语义模型容器值得注意的是所有对象都闭合additionalProperties: false一个拼写错误的多余键、一个方言枚举外的值都会让整份文档校验失败。这正是仓库把它当作格式守卫的根本原因。三、tpcds_semantic_model.yaml 实战解析一份真实的 OSI 文档长什么样tpcds_semantic_model.yaml 基于 TPC-DS 基准 schema 编写演示了 OSI Core Metadata Spec 的完整用法。它保留着原始 ASF 许可头并在首行通过# yaml-language-server: $schema../core-spec/osi-schema.json声明了编辑时的 schema 关联。3.1 文档头与模型级元数据version: 0.2.0.dev0 semantic_model: - name: tpcds_retail_model description: TPC-DS retail semantic model for sales and customer analytics ai_context: instructions: Use this semantic model for retail analytics. ...ai_context.instructions直接面向 AI 代理给出使用指引——这体现了 OSI 文档既是机器 schema 又是代理语义上下文的双重属性。3.2 数据集事实表与维度表模型声明了 5 个数据集1 张事实表store_salessource: tpcds.public.store_sales与 4 张维度表date_dim、customer、item、store。复合主键store_sales用primary_key: [ss_item_sk, ss_ticket_number]声明复合主键并用unique_keys再次列出item ticket number uniquely identifies a line item简单主键维度表如date_dim用primary_key: [d_date_sk]业务键与代理键并存customer同时有c_customer_sk代理键和c_customer_id业务键。3.3 字段表达式、数据类型与时间角色每个字段都以expression.dialects包裹至少给出一种方言本文件统一使用ANSI_SQL- name: ss_sold_date_sk expression: dialects: - dialect: ANSI_SQL expression: ss_sold_date_sk description: Foreign key to date dimension datatype: Integer dimension: is_time: false ai_context: synonyms: [sale date, transaction date]几个值得注意的细节计算字段customer_full_name的表达式是c_first_name || || c_last_name说明字段表达式可以是任意 SQL 表达式而不只是裸列名时间角色的两种声明方式d_yearInteger显式is_time: trued_dateDate写dimension: {}依靠 schema 的缺省规则自动成为时间维度而d_quarter_name、d_month_name无 datatype仅凭is_time: true就声明了时间角色——文件注释明确指出 Both datatype and is_time are independently optionaldatatype 与 is_time 相互独立、均可选数量与金额字段ss_quantityInteger、ss_sales_price/ss_ext_sales_price/ss_net_profitDecimal符合 TPC-DS 零售事实表的典型形态。3.4 关系事实表到各维度的星形连接模型声明了 4 条关系全部从store_sales多侧from指向维度表一侧to例如- name: store_sales_to_date from: store_sales to: date_dim from_columns: [ss_sold_date_sk] to_columns: [d_date_sk] ai_context: synonyms: [sales date relationship, when sale occurred]store_sales_to_customerwho bought、store_sales_to_itemwhat was sold、store_sales_to_storewhere sale occurred遵循同一模式每条的ai_context.synonyms都用自然语言补充了业务语义。3.5 指标跨数据集的量化度量模型级指标使用entity.field限定符引用逻辑字段且不直接声明所属数据集——数据集由表达式引用的实体推导而来- name: total_sales expression: dialects: - dialect: ANSI_SQL expression: SUM(store_sales.ss_ext_sales_price) description: Total sales revenue across all transactions datatype: Decimalcustomer_lifetime_valueSUM(...) / COUNT(DISTINCT customer.c_customer_sk)、store_productivity用NULLIF(SUM(store.s_number_employees), 0)防除零、sales_by_brand注释说明需按item.i_brand分组展示了跨实体指标的写法。3.6 自定义扩展厂商命名空间的载体模型底部用custom_extensions携带厂商特定数据data是字符串化的 JSONcustom_extensions: - vendor_name: SALESFORCE data: | { tableau_workbook_id: tpcds_retail_dashboard, einstein_enabled: true, crm_sync: { enabled: true, sync_frequency: daily, ... } } - vendor_name: DBT data: {project_name: tpcds_analytics, models_path: models/semantic}这印证了 schema 中Vendor定义Any string value is accepted的开放性——厂商扩展通过命名空间隔离OSI 文档因此可以无限扩展而不破坏核心结构。四、校验机制在进程内用 ajv 复现 Apache 官方校验的第一步osi_schema.test.ts 是整个守卫机制的核心实现。它的注释明确写道这套检查与 Apache 官方校验器validation/validate.py的第一步完全相同但用ajv 在进程内完成因此不需要 Python/PyPI 依赖。4.1 递归发现与全量校验const fixturesDir join(__dirname, fixtures); const schema JSON.parse(readFileSync(join(fixturesDir, ossie, osi-schema.json), utf8)); function yamlFixtures(dir: string): string[] { // 递归收集 *.yaml / *.yml跳过 profiles/ 子树 }测试递归收集tests/libts/semantic/fixtures下每一个.yaml/.yml文件profiles/子树除外——那里是绑定 profile 的编写输入属于有意的OSI 前超集因此新增一个 fixture 会自动纳入校验无需改动测试文件本身。校验器用Ajv2020({ allErrors: true, strict: false })编译 schemastrict: false是因为 schema 由第三方编写只校验文档、不校验 schema 自身的元风格。4.2 精确的容错边界只放行已知超集因为仓库自身还定义了若干超出已发布 OSI 的构造测试实现了多个只针对特定错误的放行谓词除此之外的任何漂移仍然失败谓词放行内容依据onlyMissingExpression仅放行.pull.golden.yaml中缺少expression这一种 required 错误对应 TODO(#290)默认无表达式的 KC push 会省略 OSI 必需的expression待 #290 修复后无需特判onlyExtendsExtension仅放行datasets/n路径上extends/abstract两个额外属性实体级继承OWLrdfs:subClassOf的目标是有意超集上游发布版 schema 尚不认识该关键字onlyLogicalGoldenDeviations仅放行 OWL 导入 golden.osi.golden.yaml缺失source/expression/from_columns/to_columns以及额外extends/abstract纯逻辑模型没有物理表先于绑定存在onlyExtendedModelBlocks仅放行semantic_model/n路径上的actions/constraints写操作块是 Extended-spec 提案中的超集onlyExpressionGapAndExtendedBlocks上述两类错误的并集仅用于同时命中两种的 pull golden此外还有toSchemaShape()归一化把0.2.0.dev0/google版本折叠回0.2.0.dev0、把entities别名还原为datasets、删除原生deployment_target键使扩展版文档仍能通过发布版 schema 的深层检查方言、数据类型、字段/指标形状。测试失败信息会打印每个错误的 instancePath 与 message方便定位。4.3 与格式规范的呼应这套容错边界并非临时补丁而是与 model_spec.md 的版本设计一致格式提供两个版本面——vanilla0.2.0.dev0扩展搭载在custom_extensions载体中去掉GOOGLE块即是纯 OSI 文档与扩展版0.2.0.dev0/googleentities/deployment_target/extends/abstract等成为原生键。drift from the spec偏离规范——比如方言超出 OSI 枚举——会让 fixture 校验失败这正是把规范约束变成可执行测试的方式。五、实操指南如何查看与运行这套校验仓库是只读的你可以通过以下方式亲自验证这套机制在仓库根目录toolbox/mdcode下执行# 安装依赖含 ajv、yaml 与 bun 测试运行器 cd toolbox/mdcode npm install # 运行 OSI schema 校验测试 bun test tests/libts/semantic/osi_schema.test.ts测试输出会对fixtures/下每个 YAML 文件断言 validates against the OSI schema。想体验漂移即失败可以在本地副本中临时把某个 fixture 的dialect改成枚举外的值——测试会以明确的 instancePath 与 message 拒绝它。日常编写语义模型时你也可以直接复用这份osi-schema.json把它放入自己的校验管线ajv、Python jsonschema 均可并参考 README 的格式基线version必填、entities/datasets二选一、模型名与文件名一致来组织文档。六、小结ossie 参考示例目录以零修改 vendored的方式把 Apache Ossie 官方的权威样本与 schema 引入仓库并通过 osi_schema.test.ts 把它们变成自动化的格式守卫规范所有者撰写的文档是互操作性的试金石官方 JSON Schema 是结构正确性的权威标尺。对任何一个以 OSI/语义模型为中心的工具链这套原样收纳上游规范 进程内 schema 校验 对有意超集精确容错的组合都是一份可直接借鉴的工程实践。赞分享数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载相关推荐knowledge-catalog 语义模型规范深度解析kcmd 如何基于 Apache Ossie 定义、校验与绑定语义模型knowledge catalog 语义模型规范深度解析kcmd 如何基于 Apache Ossie 定义、校验与绑定语义模型 导读 本文是 knowledg数据目录AI Agent人工智能知识管理示例工程knowledge-catalog 语义模型写操作建模指南Action 声明、guards 约束与 kcmd skills-generate 实战knowledge catalog 语义模型写操作建模指南Action 声明、guards 约束与 kcmd skills generate 实战 本篇指南围数据目录AI Agent人工智能知识管理示例工程knowledge-catalog 数据表实战Stack Overflow Votes 表 Schema、查询模式与枚举语义深度解析knowledge catalog 数据表实战Stack Overflow Votes 表 Schema、查询模式与枚举语义深度解析 本文以 knowledg数据目录AI Agent人工智能知识管理示例工程上一篇如何用 DeepSeek Coder 1.3B Base 提升编程效率10个实用代码补全技巧下一篇SymPy符号计算完整指南10分钟从安装到解方程零踩坑创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考