Data Semantic Exploration Compiler #238

lanvendar · 2026-07-21T05:28:47Z

lanvendar
Jul 21, 2026

数据语义探索编译器工程设计

背景文档：[数据语义探索编译器：让 Data Agent 不止“会问数”]

1. 核心对象与边界

本文把 Data Agent 所需的语义分为三层。三层生命周期不同，不能混成一个“大语义对象”。

1.1 Ontology / SemanticView

Ontology / SemanticView 是面向 AI 问数的业务语义适配层。它描述某个组织、部门、角色和统计目的下的业务概念、常用说法、概念关系、权限边界与回答约束，并引用 Metric 或 Dataset 作为实现。

Ontology 不以跨企业通用复用为目标。可复用能力主要沉淀在 Metric；Ontology 负责把这些能力组织成特定业务视角。本文不强制把 Ontology 和 SemanticView 拆成两个对象：Ontology 限定作用域并发布给 AI 使用后，即形成 SemanticView。

1.2 Metric

Metric 是可执行、可复用的数据加工与统计逻辑，表达过滤、聚合、公式、时间计算以及对已确认关联路径的使用。Join Key、Join Type 和基数由 DatasetRelationship 定义，不直接写入 MetricNode。

不再引入与 Metric 平级的 Measure。基础聚合、过滤指标和派生指标都是 Metric，只是表达式根节点不同。

1.3 Dataset

Dataset 是物理数据源在语义系统中的标准描述，负责把 table | view | file | api 转换为统一的 Source、Field、主键、候选键、分区、数据范围及行级映射。

Dataset 只允许确定性的、保持粒度的标准化处理，不提供聚合、窗口计算或业务 KPI。

1.4 三层关系

flowchart TB
    O["Ontology / SemanticView<br/>业务概念、作用域、权限与回答约束"]
    M["Metric<br/>过滤、聚合、公式、时间计算与关联路径使用"]
    D["Dataset<br/>物理来源、字段与保持粒度的标准化"]
    S["Source<br/>Table / View / File / API"]

    O -->|"metric_ref"| M
    O -->|"dataset_ref / field_ref / predicate_ref"| D
    M -->|"引用 Field 与 DatasetRelationship"| D
    D -->|"映射"| S

对象	负责	不负责	主要复用范围
Ontology / SemanticView	业务概念、别名、关系、组织视角、权限入口和 AI 回答约束	物理接入、通用计算实现	特定企业、组织或业务视角
Metric	过滤、聚合、公式、时间计算、关联路径使用和计算血缘	Join 结构、用户权限、物理连接信息	企业内部跨部门、跨 SemanticView
Dataset	Source 描述、Field、键、分区、数据范围和行级映射	聚合、窗口和业务 KPI	同一物理数据资产的不同计算场景

边界约束：

Ontology 直接引用 Metric、Dataset 或 Field，暂不增加独立 SemanticBinding 层；
Metric、Dataset 不反向依赖某个 Ontology，反向关系只作为检索索引和影响分析结果；
KPI 的聚合、过滤和计算口径属于 Metric；Ontology 可用 predicate_ref 将分类概念映射为 Field 条件，但不在其中沉淀可复用计算；
数据权限引用属于 Ontology/SemanticView，并由 Policy Resolver 执行；用户临时条件属于 Query Request；
画像、假设、证据、反例和审核记录属于探索域，不进入运行时语义包；
只有经过人工确认并发布的 Dataset、Metric、Ontology 才能进入在线服务。

2. 工作方式：探索向上，运行向下

2.1 离线探索自底向上发现

系统从两条输入路径出发：物理数据经过 Source 接入、Dataset 映射和画像；已有计算逻辑经过 Parser 和 Calculation IR 形成 Metric 候选。Dataset 的 Field、粒度与 Join 约束用于验证 Metric，最后由人工把 Dataset 和 Metric 组织成 Ontology/SemanticView。

2.2 在线问数自顶向下执行

系统从用户问题和用户上下文出发：先选择已发布的 Ontology/SemanticView，再解析业务概念和 Metric，继而展开 Dataset、Field 与 Source 查询。

flowchart LR
    subgraph Discovery["离线探索：自底向上发现"]
        S1["Source、Schema 与数据样本"] --> A1["Source 接入映射"]
        A1 --> D1["Dataset 与画像"]
        L1["SQL / R / Python / BI 计算逻辑"] --> C1["Parser / Calculation IR"]
        C1 --> M1["Metric 候选"]
        D1 -->|"Field、粒度与 Join 约束"| M1
        D1 --> O1
        M1 --> O1["Ontology / SemanticView 制作"]
        O1 --> P1["审核、编译与发布"]
        R1["定向探索 / 增量验证"] -.-> A1
        R1 -.-> C1
    end

    subgraph Runtime["在线运行：自顶向下执行"]
        Q2["问题 + 用户上下文"] --> O2["已发布 Ontology / SemanticView"]
        O2 --> M2["Metric DAG"]
        O2 --> D2
        M2 --> D2["Dataset / Field"]
        D2 --> S2["Source 查询"]
        S2 --> A2["答案 + 口径 + 血缘"]
    end

    P1 --> O2
    F1["语义缺口 / 用户纠正"] -.-> R1
    N1["新数据 / 结构或逻辑变化"] -.-> R1

新增数据通常只验证已知规则。发现新枚举、反例、结构漂移或用户纠正时，系统重新进入局部探索和人工审核，不直接修改已发布语义。

3. 总体架构

flowchart LR
    DATA["数据源<br/>DB / File / API"]
    LOGIC["已有计算逻辑<br/>SQL / R / Python / BI"]

    subgraph Offline["① 离线语义探索"]
        MAP["语义接入映射<br/>SourceAdapter / Logic Parser"]
        EXP["语义探索<br/>画像、规则发现、反例验证"]
        STUDIO["人工审核工作台<br/>Dataset / Metric / Ontology 制作"]
        COMP["Semantic Compiler<br/>引用、DAG、权限与版本校验"]
        MAP --> EXP --> STUDIO --> COMP
    end

    subgraph Storage["② 语义存储"]
        DISC["Discovery Store<br/>画像、假设、证据、反例"]
        DRAFT["Semantic Draft Store<br/>待审核对象"]
        REG["Package Registry<br/>不可变发布版本"]
        INDEX["Runtime Index<br/>Ontology 检索与最小上下文索引"]
    end

    subgraph Online["③ 在线语义服务"]
        PUB["Ontology Publisher<br/>激活已发布 SemanticView"]
        RESOLVE["Semantic Resolver"]
        PLAN["Metric Planner"]
        POLICY["Policy Resolver"]
        CTX["Context Packager"]
        RESOLVE --> PLAN
        RESOLVE --> POLICY
        PLAN --> CTX
        POLICY --> CTX
    end

    AGENT["Data Agent"]

    DATA --> MAP
    LOGIC --> MAP
    MAP --> DISC
    MAP --> DRAFT
    EXP --> DISC
    EXP --> DRAFT
    STUDIO --> DRAFT
    DRAFT --> STUDIO
    COMP --> REG
    COMP --> INDEX
    REG --> PUB
    INDEX --> PUB
    PUB --> RESOLVE
    INDEX --> RESOLVE
    AGENT --> RESOLVE
    CTX --> AGENT
    AGENT --> DATA

架构只分为三个内部边界：

区域	子能力	主要产出
离线语义探索	语义接入映射、语义探索、人工审核工作台、语义编译	Dataset/Metric/Ontology 草稿、证据和已编译版本
语义存储	Discovery Store、Draft Store、Package Registry、Runtime Index	探索记录、草稿、不可变语义包和在线索引
在线语义服务	Ontology 发布、语义解析、Metric 规划、权限解析、最小上下文打包	与当前问题相关的可执行语义上下文

边界规则：

离线探索可以读写探索记录和语义草稿；在线服务只读取已发布版本；
人工审核工作台同时承担 Dataset、Metric、Ontology 的制作、修订和确认；
发布单元是包含 Dataset、Metric、Ontology 的 SemanticPackage，Ontology Publisher 负责激活其中面向 AI 的 SemanticView；
Discovery Store 中的大体量画像、样本和反例不进入在线 Prompt；
在线服务不重新探索语义，未命中或歧义时返回澄清并回流离线工作台。

3.1 离线探索与发布交互

sequenceDiagram
    participant S as 数据源/计算逻辑
    participant M as 语义接入映射
    participant E as 语义探索
    participant W as 人工审核工作台
    participant C as Semantic Compiler
    participant R as 语义存储
    participant P as Ontology Publisher

    S->>M: 读取结构、样本与逻辑定义
    M->>R: 保存标准 Source/Dataset 草稿与逻辑快照
    M->>E: 提交统一结构和 Calculation IR
    E->>E: 画像、发现约束、生成假设、寻找反例
    E->>R: 保存证据、反例与 Metric/Ontology 候选
    R-->>W: 加载候选及证据
    W->>W: 制作并确认 Dataset/Metric/Ontology
    W->>C: 提交已确认的语义对象
    C->>C: 引用、DAG、权限与版本校验
    C->>R: 发布 SemanticPackage 与 Runtime Index
    R->>P: 通知新发布版本
    P->>P: 校验制品并原子切换 active 版本

3.2 在线问数交互

sequenceDiagram
    participant U as 用户
    participant A as Data Agent
    participant S as 在线语义服务
    participant P as 权限服务
    participant D as 数据源

    U->>A: 提交问题
    A->>S: resolve(question, user_context)
    S->>S: 选择 SemanticView、解析 Concept、展开 Metric DAG
    S->>P: 获取当前用户的数据范围
    P-->>S: 返回权限谓词
    S-->>A: 返回最小语义上下文和查询约束
    A->>D: 执行生成的 SQL/API 请求
    D-->>A: 返回结果
    A-->>U: 答案、指标口径、数据范围和语义包版本

4. 范围与非目标

本期覆盖：Source 自动接入、Dataset 标准化、画像与约束发现、计算逻辑解析、Metric/Ontology 制作与审核、语义包发布、在线解析、增量验证和纠正回流。

本期不建设通用 ETL、主数据或权限中心；不直接执行不受信任的 SQL/R/Python；不承诺自动生成唯一正确的业务本体；不解决跨企业 Ontology 复用；不在 MVP 中训练或托管模型。

5. 运行时语义包数据结构

5.1 根对象 SemanticPackage

spec_version: 0.1.0

package:
  id: finance-management-reporting
  version: 1.0.0
  status: released
  created_at: 2026-07-20T10:00:00+08:00
  content_hash: sha256:...

datasets: []
dataset_relationships: []
metrics: []
ontologies: []

约束：

package.id 在注册中心全局唯一；
package.version 使用语义化版本；
已发布版本不可原地修改；
content_hash 用于完整性校验和缓存失效；
所有对象引用必须在编译期解析成功。

5.2 Dataset

Dataset 表示可寻址的物理数据资产及其标准化字段映射。

它不与传统数仓分层一一对应：Source 可以来自源系统、ODS、DWD、DIM、事实表、宽表或 ADS。这里的“物理层”表示对象已经有确定、可查询的位置，而不是特指 ODS。

Dataset 的核心价值是屏蔽不同 Source 类型的访问差异。table、view、file、api 等 Source 经过对应的 SourceAdapter 后，转换成统一的 Dataset 和 Field；各类 Source 特有的定位、读取和结构信息仍保留在各自结构中。

# 方式一：内联 Source 描述
datasets:
  - id: finance_fact
    name: MainTable_1u44q
    description: 财务实际、预算和预测事实数据
    dataset_role: fact | dimension
    source: {}

---

# 方式二：引用外部 Source 描述
datasets:
  - id: finance_fact
    name: MainTable_1u44q
    description: 财务实际、预算和预测事实数据
    dataset_role: fact | dimension
    source_uri: source-registry://finance/finance_fact@1.0.0

字段含义：

字段	是否必填	含义
`datasets[].id`	是	Dataset 的稳定唯一标识，供 Metric、Ontology 和 API 引用
`datasets[].name`	是	Dataset 展示名称
`datasets[].description`	否	Dataset 的业务和数据内容说明
`datasets[].dataset_role`	是	Dataset 的分析角色：`fact
`datasets[].source`	与 `source_uri` 二选一	内联的来源定位、读取方式、结构和画像结果；具体结构由 `source.type` 决定
`datasets[].source_uri`	与 `source` 二选一	外部 Source 描述的 URI；解析结果必须是一份完整的 `SourceSchema`

dataset_role 不放入 Source：事实或维度是 Dataset 在分析模型中的角色，同一个物理 Source 在不同模型中可能承担不同角色。

source 与 source_uri 必须且只能出现一个。source_uri 解决的是 Source 描述的外部存储和复用，不是新的物理 Source 类型；URI 解析后仍必须得到本节定义的 table | view | file | api 结构。编译器在发布前解析 URI、校验内容，并记录不可变版本或内容哈希，避免外部描述变化导致同一语义包产生不同结果。URI 中不得包含账号、Token 或其他凭据。

不建议把 Dataset 级字段直接命名为 uri。使用 source_uri 可以明确表示它引用的是整个 Source 描述，而 File 内部的物理地址由 directory_uri、file_name 或 file_pattern 表达。工程实现中的类型或 JSON Schema 可以命名为 SourceSchema。

Source 类型

table | view | file | api

type 决定 Source 的 YAML 结构和使用的 SourceAdapter：table/view 使用数据库适配器，file 使用文件适配器，api 使用 API 适配器。三类结构不能互相照搬。

5.2.1 Table | View

table 和 view 使用相同定位结构，区别只在 type。视图的主键和候选键通常不能从数据库约束中直接读取，可以由人工声明或探索确认。

source:
  type: table | view
  connection: finance-prod
  catalog: finance
  database: finance
  schema: public
  object: shys_main_table_1u44q_ys
  mode: incremental | full
  update_frequency: realtime | hourly | daily | weekly | monthly | manual

  data_ranges:
    - field: day_pt
      from: 2026-07-15
      to: 2026-07-18

  row_count: 6495
  size_bytes: 1048576
  primary_key: [id, day_pt]
  unique_keys:
    - [period, year, scenario_code, version_code, entity, account,
       flow, report_currency, intercompany, object_type, cost_type,
       other1, other2]
  partition_keys: [day_pt]
  bucket_keys: [entity, account]
  fields: []

字段含义：

字段	是否必填	含义
`type`	是	`table
`connection`	是	数据库连接配置的引用；账号和密钥不进入语义包
`catalog`	否	Catalog 名称，仅在数据库支持时填写
`database`	否	Database 名称，是否需要取决于数据库命名体系
`schema`	否	Schema 名称，是否需要取决于数据库命名体系
`object`	是	表名或视图名
`mode`	是	读取方式：`incremental
`update_frequency`	否	预期更新频率：`realtime
`data_ranges`	否	数组；最近一次画像在一个或多个字段上的数据范围
`data_ranges[].field`	是	该范围对应的标准 Field 名称
`data_ranges[].from`	是	当前观察到的最小值或起始值
`data_ranges[].to`	是	当前观察到的最大值或结束值
`row_count`	否，自动生成	当前画像范围内的记录数
`size_bytes`	否，自动生成	当前画像范围内的数据大小，单位为字节
`primary_key`	否	数据库声明或人工确认的主键，可为复合键
`unique_keys`	否	二维数组；每个内层数组表示一个唯一约束或已确认候选键
`partition_keys`	否	数据库表的物理分区键
`bucket_keys`	否	数据库表的分桶、聚簇或分布键
`fields`	发布时必填	标准 Field 数组；已发布 Dataset 至少包含一个 Field

其他补充说明：

table 与 view 的定位结构相同；type 用于区分读取对象及元数据能力。
catalog、database、schema 按数据库能力填写，不要求同时存在。
View 通常不携带可读取的主键和唯一约束；这类键只能由人工声明或语义探索确认。
update_frequency 是元数据提示，不表示语义编译器负责调度。

自动转换包括：

读取数据库列定义，并将原生类型转换成统一 type；
读取列名、可空性、默认值和注释，生成标准 Field 元数据；
在数据库支持时读取主键、唯一约束、分区键和分桶或分布键；
从数据库元数据、任务配置或画像结果获取更新方式、更新频率、数据范围、记录数和数据大小；
对不能可靠读取或推断的信息留空，不进行静默猜测。

5.2.2 File

File Source 同时覆盖结构化、半结构化和非结构化文件。结构化或半结构化文件解析为记录和标准 Field，可供 Metric 使用；非结构化文件先提取原始内容，再生成多级 ai_context，供 Data Agent 按需加载。

# 结构化或半结构化文件
source:
  type: file
  structure: structured | semi_structured
  file_scope: single | batch
  directory_uri: s3://finance-data/main-table/
  file_name: part-00001.parquet                 # single 时填写
  file_pattern: day_pt=*/part-*.parquet         # batch 时填写
  format: parquet | orc | avro | csv | xlsx | json | jsonl | xml
  compression: none | gzip | snappy | zstd
  encoding: UTF-8
  delimiter: ","
  header: true
  record_path: $[*]
  mode: incremental | full
  update_frequency: realtime | hourly | daily | weekly | monthly | manual

  file_count: 128
  row_count: 6495
  file_size: 1048576
  unique_keys:
    - [id, day_pt]
    - [period, year, scenario_code, version_code, entity, account]
  fields: []

---

# 非结构化文件
source:
  type: file
  structure: unstructured
  file_scope: single
  directory_uri: s3://finance-documents/management-report/
  file_name: 2026-07-management-report.pdf
  format: pdf | docx | pptx | txt | md | html | png | jpeg | tiff | wav | mp3 | mp4

  extraction:
    method: text | layout | ocr | speech | multimodal
    unit: document | page | paragraph | chunk

  file_size: 10485760

  ai_context:
    level_100: 约 100 Token 的核心语义摘要
    level_1000: 约 1000 Token 的详细语义摘要
    full: 完整语义内容

字段含义：

字段	是否必填	含义
`type`	是	固定为 `file`
`structure`	是	文件的数据形态：`structured
`file_scope`	是	文件选择范围：`single` 表示单个文件，`batch` 表示一组文件
`directory_uri`	是	不含通配符的目录或对象存储 Prefix，例如 `s3://bucket/path/`
`file_name`	`single` 必填	相对于 `directory_uri` 的精确文件名或相对路径，不允许包含通配符
`file_pattern`	`batch` 必填	相对于 `directory_uri` 的文件路径匹配表达式，例如 `day_pt=/part-.parquet`
`format`	是	文件格式；结构化与半结构化文件例如 `parquet
`compression`	否	压缩格式；未填写时由文件扩展名或文件元数据读取
`encoding`	文本格式可选	文本编码；主要用于 CSV、JSON、JSONL、XML、TXT、Markdown 和 HTML，默认 `UTF-8`
`delimiter`	CSV 可选	CSV 分隔符，默认逗号
`header`	CSV 可选	CSV 是否包含表头
`record_path`	半结构化文件按需填写	记录集合在文档中的路径，例如 JSONPath 或 XPath；JSONL 通常不需要
`extraction`	非结构化文件必填	将文件中的文本、版面、图像或语音转换为可理解内容的提取契约
`extraction.method`	非结构化文件必填	原始内容提取方式：`text
`extraction.unit`	非结构化文件必填	内容提取和语义生成的处理粒度：`document
`mode`	结构化、半结构化文件必填	读取方式：`incremental
`update_frequency`	结构化、半结构化文件可选	预期更新频率：`realtime
`file_count`	结构化、半结构化文件自动生成	同一次画像中，定位规则匹配到的文件总数；`single` 时必须为 `1`
`row_count`	结构化、半结构化文件自动生成	匹配文件解析后的总记录数；只有完整解析时才填写
`file_size`	否，自动生成	原始文件大小，单位为字节；`single` 表示单文件大小，`batch` 表示匹配文件的总大小
`unique_keys`	结构化、半结构化文件可选	二维数组；保存文件契约、人工声明或探索确认的逻辑候选键
`fields`	结构化、半结构化文件发布时必填	解析后生成的标准 Field 数组；非结构化文件不使用
`ai_context`	非结构化文件编译后必填	面向 AI 的多级语义上下文；至少包含一个级别
`ai_context.level_100`	否，自动生成	不超过约 100 Token 的核心摘要，用于召回和快速路由
`ai_context.level_1000`	否，自动生成	不超过约 1000 Token 的详细摘要，用于理解和任务规划
`ai_context.full`	否，自动生成	完整语义内容，用于深度解析；不是原始二进制文件

其他补充说明：

File 使用 directory_uri 加文件选择规则定位资源，不定义 connection，也不使用数据库的 catalog、database、schema 和 object。
运行时根据 directory_uri 的 Scheme 和 Authority 选择文件系统或对象存储适配器，例如 file://、s3://、oss://、hdfs://。访问凭据、私有 Endpoint 和网络配置保存在语义包之外。
file_scope: single 时必须填写 file_name 且不得填写 file_pattern，最终只能解析出一个文件；file_scope: batch 时必须填写 file_pattern 且不得填写 file_name，统计值按匹配到的整个文件集合汇总。
directory_uri 不支持通配符。MVP 的 file_pattern 统一使用 Glob：* 匹配单层路径内任意字符，? 匹配单个字符，** 匹配零层或多层目录；禁止使用 .. 跳出 directory_uri。
file_scope: single | batch 同时适用于三种 structure。它只描述定位结果的数量；结构化和半结构化文件的读取方式另由 mode: full | incremental 表达。
structured 包括 Parquet、CSV、Excel 等行列型文件；semi_structured 包括 JSON、JSONL、XML 等需要记录路径的文件；unstructured 包括文档、图片、音频和视频。
encoding、delimiter、header 仅适用于对应的文本或表格格式；列式文件通常从文件元数据读取 Schema。
File 没有通用、可移植的数据库分桶语义，因此不定义 bucket_keys。
非结构化文件不生成 fields，也不定义 mode、update_frequency、file_count、row_count 或 unique_keys。extraction 负责读取内容，ai_context 负责表达面向模型的分级语义。
ai_context 的数字级别表示近似 Token 预算，而不是字符数。在线解析优先返回较小级别，只有语义不足时才逐级加载 level_1000 或 full。
结构化和半结构化文件的 file_count、row_count、file_size 是当前定位规则在同一次 ProfileSnapshot 下的汇总。只有所有目标文件均成功解析时才填写 row_count；抽样、漏读或部分失败时必须留空并输出覆盖率和诊断。
File 不定义 primary_key。结构化和半结构化文件使用一个二维 unique_keys 数组即可：每个内层数组表示一个单列或复合候选键。

自动转换包括：

根据 directory_uri 选择存储适配器，使用 file_name 或 file_pattern 枚举文件，校验结果数量是否符合 file_scope，再读取格式、压缩方式、文件大小、修改时间和可识别的路径字段；
对结构化文件读取内置 Schema、表头或工作表结构，生成标准 Field 元数据；
对半结构化文件按 record_path 提取记录，合并样本 Schema，并报告字段缺失、类型漂移和冲突；
对非结构化文件严格按照 extraction.method 和 extraction.unit 执行文本解析、版面分析、OCR、语音识别或多模态抽取，再生成多个 Token 预算级别的 ai_context；
对所有 File 生成 file_size；仅对结构化和半结构化 File 生成 file_count，并在完整解析后生成 row_count；
对无法解析、加密、损坏或格式不一致的文件输出诊断，不静默跳过；不从文件名、目录或内容中静默猜测主键、唯一键和业务含义。

5.2.3 API

API Source 复用完整 OpenAPI 契约，不再重复定义 Server、Path、Method、参数、请求体和响应 Schema。Dataset 只补充两类 OpenAPI 无法表达的信息：选择哪个 Operation，以及响应中的哪个节点构成本 Dataset 的单个对象或记录集合。

# 批量结果：分页查询数据表
source:
  type: api

  openapi:
    spec_uri: object://openapi/metadata-management-v0.json
    operation_id: pageTableInfos

  result:
    scope: batch
    status_code: "200"
    media_type: "*/*"
    data_path: $.data.dataList[*]

    pagination:
      type: page
      request:
        page_path: $.current
        size_path: $.size
        page_start: 1
        page_size: 100
      response:
        total_path: $.data.total

  fields: []

---

# 单个结果：根据 ID 查询数据表
source:
  type: api

  openapi:
    spec_uri: object://openapi/metadata-management-v0.json
    operation_id: getTableInfo

  result:
    scope: single
    status_code: "200"
    media_type: "*/*"
    data_path: $.data

  fields: []

字段含义：

字段	是否必填	含义
`type`	是	固定为 `api`
`openapi`	是	OpenAPI 契约引用和 Operation 选择信息
`openapi.operation_id`	是	当前 Dataset 使用的 OpenAPI `operationId`；必须在文档中唯一解析
`openapi.spec`	与 `openapi.spec_uri` 二选一	内联的标准 OpenAPI 文档，不改变 OpenAPI 原有字段结构
`openapi.spec_uri`	与 `openapi.spec` 二选一	外部 OpenAPI JSON 或 YAML 文档的 URI
`openapi.content_hash`	发布时必填	原始 OpenAPI 文档规范化后的内容哈希，用于版本追踪和变更检测
`openapi.resolved_spec`	发布时必填	仅包含目标 Operation 及其依赖闭包的、自包含的最小 OpenAPI 文档
`result`	是	将 OpenAPI 响应映射成 Dataset 结果的规则
`result.scope`	是	结果粒度：`single
`result.status_code`	否	选用的成功响应状态码；只有一个成功响应时可自动确定
`result.media_type`	否	选用的响应 Media Type；只有一个时可自动确定
`result.data_path`	是	业务对象或记录集合在完整响应中的 JSONPath；`batch` 时应定位到数组元素
`result.pagination`	Batch 分页接口必填	OpenAPI 未充分描述的分页执行规则
`result.pagination.type`	是	分页类型：`page
`result.pagination.request`	是	分页字段在 Operation 输入中的位置和初始值
`result.pagination.request.page_path`	Page 分页必填	页码字段在请求参数或请求体中的路径
`result.pagination.request.size_path`	Page 分页必填	每页数量字段在请求参数或请求体中的路径
`result.pagination.request.page_start`	Page 分页必填	起始页码，例如 `0` 或 `1`
`result.pagination.request.page_size`	Page 分页必填	每次请求的记录数量
`result.pagination.response.total_path`	否	总记录数在响应中的 JSONPath；缺失时以空页等结束条件停止
`fields`	结构化响应发布时必填	根据选中操作的成功响应 Schema 转换出的标准 Field 数组

OpenAPI 文档字段的含义：

字段	是否必填	含义
`openapi.spec.openapi`	是	OpenAPI 规范版本，例如 `3.0.1`
`openapi.spec.info`	是	API 文档的基本信息
`openapi.spec.info.title`	是	API 标题
`openapi.spec.info.version`	是	当前 API 文档或接口版本
`openapi.spec.servers`	执行时至少一个	可调用的服务器列表；可以使用 OpenAPI Server Variables 表达环境差异
`openapi.spec.servers[].url`	是	API 基础 URL
`openapi.spec.servers[].description`	否	服务器或环境说明
`openapi.spec.paths`	是	API 路径集合
`openapi.spec.paths.<path>.<method>`	是	某个路径下的 OpenAPI Operation，例如 `post`
`tags`	否	Operation 的分类标签
`summary`	否	Operation 的简短业务说明
`operationId`	是	Operation 的稳定唯一标识，供 `openapi.operation_id` 选择
`parameters`	否	Path、Query、Header 或 Cookie 参数列表
`parameters[].name`	是	参数名称
`parameters[].in`	是	参数位置：`path
`parameters[].required`	Path 参数必为 `true`	参数是否必填
`parameters[].schema`	是	参数的 OpenAPI Schema
`parameters[].schema.type`	是	参数类型，例如 `string
`parameters[].schema.format`	否	类型格式，例如 `uuid
`requestBody`	否	请求体定义；POST 等 Operation 可以通过它声明输入结构
`requestBody.required`	否	请求体是否必填
`requestBody.content`	`requestBody` 存在时必填	按 Media Type 组织的请求体，例如 `application/json`
`requestBody.content.<media-type>.schema`	是	请求体的内联 Schema 或 `$ref`
`responses`	是	按 HTTP 状态码组织的响应定义
`responses.<status>.description`	是	响应说明
`responses.<status>.content`	自动转换数据时必填	按 Media Type 描述响应体，例如 `application/json`
`responses.<status>.content.<media-type>.schema`	自动转换数据时必填	响应数据的 OpenAPI Schema，是生成标准 Field 的依据
`openapi.spec.components`	否	可复用组件集合；当前文件使用其中的 `schemas`
`openapi.spec.components.schemas`	否	请求和响应复用的 Schema 字典
`openapi.spec.components.schemas.<name>.type`	否	Schema 类型，例如 `object
`openapi.spec.components.schemas.<name>.required`	否	对象中必填属性的名称数组
`openapi.spec.components.schemas.<name>.properties`	Object Schema 可选	对象属性及其子 Schema
`$ref`	否	对其他 Schema 的引用，例如 `#/components/schemas/TableInfoDto`
`items`	Array Schema 必填	数组元素的内联 Schema 或 `$ref`

OpenAPI 解析复制要求

OpenAPI 解析分为两个状态：

配置态：spec_uri 或 spec + operation_id
  ↓ OpenAPI 编译
发布态：来源信息 + content_hash + resolved_spec + result + fields

发布态 API Source 示例：

source:
  type: api

  openapi:
    spec_uri: object://openapi/metadata-management-v0.json
    content_hash: sha256:...
    operation_id: pageTableInfos

    resolved_spec:
      openapi: 3.0.1
      info:
        title: OpenAPI definition
        version: v0
      servers:
        - url: https://sz-dev-datafusion.indusmind.me
          description: Generated server url
      paths:
        /api/metadata/table/page:
          post:
            tags: [【表结构管理】]
            summary: 分页查询数据表
            operationId: pageTableInfos
            requestBody:
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/PageQueryTableInfoQueryDto"
              required: true
            responses:
              "200":
                description: OK
                content:
                  "*/*":
                    schema:
                      $ref: "#/components/schemas/ResultPageResponseTableInfoDto"
      components:
        schemas:
          PageQueryTableInfoQueryDto: {}
          TableInfoQueryDto: {}
          ResultPageResponseTableInfoDto: {}
          PageResponseTableInfoDto: {}
          TableInfoDto: {}
          JsonNode: {}

  result:
    scope: batch
    status_code: "200"
    media_type: "*/*"
    data_path: $.data.dataList[*]
    pagination:
      type: page
      request:
        page_path: $.current
        size_path: $.size
        page_start: 1
        page_size: 100
      response:
        total_path: $.data.total

  fields: []

示例为突出复制边界，将 components.schemas 的内容写成 {}；实际发布结果必须包含这些 Schema 的完整定义，不允许保留空对象或未解析的外部引用。

配置态允许只保存 openapi.spec_uri + openapi.operation_id，也允许通过 openapi.spec 内联完整文档。
发布时必须生成 openapi.resolved_spec。运行时以该快照为准，不依赖再次访问原始 spec_uri。
对原始 OpenAPI 规范化为确定性 JSON 后计算 content_hash；只改变空格或字段顺序不应改变哈希。
operation_id 必须唯一解析为一个 Path 和 HTTP Method；找不到或重复时编译失败。
resolved_spec 保持标准 OpenAPI 根结构，复制 openapi、info、当前 Operation 生效的 servers、目标 Path、Path 级参数和目标 Operation，不转换成另一套自定义 API Schema。
Operation 的 tags、summary、description、parameters、requestBody、responses、security、callbacks、deprecated 等原生字段应完整保留；编译器不支持的结构必须报错，不能静默删除。
从 Path 和 Operation 中的参数、请求体、响应、Header、Link、Callback 和 Security 开始递归扫描 $ref，将所有可达 Components 完整复制到 resolved_spec.components。
内部 $ref 保持引用形式，避免重复展开和循环引用；外部 $ref 必须下载并复制到本地 Components，再改写为 #/components/...。发布结果不得依赖外部 $ref。
Server 按 OpenAPI 的 Operation、Path、Root 优先级计算生效范围；Server Variables 保留定义，环境值由部署配置绑定。
securitySchemes 可以复制认证机制，但账号、Token、Cookie、API Key 和证书不得写入 resolved_spec。
result 和 fields 是 Dataset 编译结果，不写回标准 OpenAPI 对象；result.data_path 必须能在选中响应 Schema 中解析，fields 必须来自该节点对应的 Schema。
原始 OpenAPI 的 content_hash、选中 Operation 或可达 Schema 发生变化时，触发契约漂移检测并生成新的 Dataset 或语义包版本，不修改已发布快照。

对 /Users/lanvendar/Downloads/元数据管理_OpenAPI.json 的结构检查结果：

项目	结果
根字段	`openapi`、`info`、`servers`、`paths`、`components`
OpenAPI 版本	`3.0.1`
Path 数量	43
Operation 数量	46：GET 12、POST 31、DELETE 3
`operationId`	46 个且全部唯一
带 `requestBody` 的 Operation	28
带响应 `content/schema` 的 Operation	45
缺少响应 Schema 的 Operation	`exportDevice`，即 `/api/metadata/{tableId}/exportTable`
Components Schema 数量	80
`$ref` 数量	123
响应 Media Type	45 个已声明响应均使用 `/`
Security 定义	当前文档未声明 `securitySchemes`

其他补充说明：

openapi.spec 与 openapi.spec_uri 必须且只能出现一个。外部文档在编译时解析并固定版本或内容哈希，避免同一语义包对应不同接口契约。
对当前这种包含大量 Path 和 Components 的文档，优先使用 openapi.spec_uri + openapi.operation_id，避免在每个 Dataset 中重复内联整份 OpenAPI。编译器只展开目标 Operation 以及它通过 $ref 可达的 Schema 闭包。
servers.url、paths、HTTP Method、parameters、requestBody 和 responses 均直接使用 OpenAPI，不再重复定义 connection、endpoint、method、request 和 response。
openapi.operation_id 必须与一个 OpenAPI Operation 的 operationId 完全一致；重复或找不到时编译失败。
OpenAPI 的 securitySchemes 和 security 只描述认证机制，Token、Cookie、API Key 等实际凭据仍由运行时 Secret 系统注入。
当前文件中的 exportDevice 操作，其 200 响应只有 description，可以用于调用，但不足以自动生成 Field。只有响应声明 content 和 schema 后，Adapter 才能可靠识别结果结构；不得根据一次样本响应静默补齐契约。
当前文件的 45 个已声明响应都使用 */*。它不影响 $ref 解析，但不能准确表达返回格式；JSON 响应应优先声明 application/json，导出文件应声明实际 Media Type 或 application/octet-stream。
JSON 对象或数组响应可以转换成标准 Field。文件流响应应在 OpenAPI 中声明相应 Media Type 和 Binary Schema，获取后交给 FileAdapter 继续处理。
result 不重复描述响应 Schema，只负责选中状态码、Media Type 和业务数据节点。OpenAPI 可以说明返回对象的类型，但无法知道统一响应包装中的哪个节点才是 Dataset 数据。
OpenAPI 没有统一规定分页行为。若 Operation 已提供 x-pagination，编译器优先读取；否则由 result.pagination 作为不修改原 OpenAPI 文档的本地映射补充。

自动转换包括：

解析内联 openapi.spec 或下载 openapi.spec_uri，校验 OpenAPI 版本和文档结构，并计算 content_hash；
根据 openapi.operation_id 定位唯一 Operation，组合 Server、Path、HTTP Method、参数、请求体和安全要求；
递归解析参数、请求体、响应和安全定义引用的 $ref，复制目标 Path、Operation 及其 Components 闭包，生成自包含的 openapi.resolved_spec；
将参数及请求体的 OpenAPI Schema 转换为调用参数定义，并在运行时校验输入；
根据 result.status_code、result.media_type 和 result.data_path 选择业务数据节点，将对应 OpenAPI Schema 的原生类型转换为统一 type 并生成标准 Field；
对文件流响应生成 FileAdapter 读取计划；对未声明响应 Schema 的操作只保留调用能力，不生成 Field；
对无法解析的 $ref、重复的 operationId、未声明的响应类型和不兼容 Schema 输出编译错误，不进行静默猜测。

5.2.4 Field 与行级映射

Field 数组位于 Dataset.source.fields，不同 SourceAdapter 均输出统一字段结构。数据库列和表格型文件列使用 source_column；API 和嵌套 JSON 字段使用 source_path。

fields:
  - name: today
    source_column: today
    type: VARCHAR(255)
    length: 32
    nullable: false
    comment: 当天日期
    default_value: null

  - name: amount_value
    source_column: decimal_val
    type: DECIMAL(19,6)
    nullable: true
    comment: 财务数值
    default_value: "0.000000"
    transform:
      type: cast
      target_type: DECIMAL(19,6)

  - name: scenario_code
    source_column: scenario
    type: VARCHAR(255)
    length: 8
    nullable: false
    comment: 实际、预算或预测场景
    transform:
      type: mapping
      unknown_value_policy: reject
      values:
        Actual: actual
        Budget: budget
        Forecast: forecast

  - name: version_code
    source_column: version
    type: VARCHAR(255)
    nullable: false
    transform:
      type: normalize_string
      trim: true
      case: upper

Field 字段含义：

字段	是否必填	含义
`name`	是	Dataset 内唯一的标准字段名，也是 Field 引用名称
`source_column`	条件必填	Table、View 和表格型 File 中的原始列名
`source_path`	条件必填	API 响应记录或嵌套 JSON 记录中的字段路径，例如 `$.customer.id`
`type`	是	完整声明类型，例如 `VARCHAR(255)`、`DECIMAL(19,6)`；不再单列数据库 `precision`、`scale` 和声明长度
`length`	否，自动生成	数据画像计算出的实际最大内容长度，不是数据库声明长度
`nullable`	是	Source 声明的可空性；观察到的 NULL 情况进入 ProfileSnapshot
`comment`	否	Source 注释或人工补充说明
`default_value`	否	Source 默认值；没有默认值时为 `null`
`transform`	否	统一化后的行级映射或值转换；没有转换时直接使用原值
`transform.type`	`transform` 存在时必填	转换类型，例如 `cast
`transform.target_type`	`cast` 必填	类型转换后的目标类型
`transform.unknown_value_policy`	`mapping` 可选	未知枚举值的处理方式，例如 `reject
`transform.values`	`mapping` 必填	原始值到标准值的映射表
`transform.trim`	`normalize_string` 可选	是否去除字符串首尾空格
`transform.case`	`normalize_string` 可选	大小写标准化方式：`upper

每个 Field 必须提供 source_column 或 source_path 之一，不能同时缺失。Adapter 可以把二者编译成统一的字段提取表达式，但不应在 YAML 中混淆列名和 JSONPath。

length 属于观察属性，随着数据增长可能变化。编译时应记录它对应的 ProfileSnapshot 和观察时间；需要稳定类型约束时始终以 type 为准。

允许的 MVP Transform：

类型	作用	粒度要求
`column`	原列直出	保持
`rename`	重命名	保持
`cast`	类型转换	保持
`normalize_string`	Trim、大小写等	保持
`coalesce`	空值标准化	保持
`mapping`	内联枚举映射	保持
`scalar_expression`	受限标量表达式	保持
`lookup`	唯一键多对一映射	必须证明不扩行

禁止在 Field Transform 中出现：

聚合函数；
窗口函数；
子查询；
不受控的一对多 Join；
引用 Metric；
依赖 Ontology 权限或部门上下文。

5.3 DatasetRelationship

DatasetRelationship 只描述可执行 Join 路径，不承载业务概念关系。

dataset_relationships:
  - id: finance_fact_to_account
    from_dataset: finance_fact
    to_dataset: account_dimension
    cardinality: many_to_one
    join_type: left
    keys:
      - from_field: account
        to_field: account_code
    null_match: never

编译期必须验证：

引用的 Dataset、Field 存在；
两侧字段类型兼容；
many_to_one 的一端键已声明或已验证唯一；
复合键顺序一致；
Metric 使用 Join 后不会产生未经声明的事实行膨胀。

5.4 Metric

Metric 是各种数据加工和分析计算逻辑的统一、可执行表示，可以由工作台人工制作，也可以从已有逻辑中自动发现候选。

Metric 来源与自动探索

Metric 可由工作台人工制作，也可通过 6.1 节的跨语言解析流程生成候选。本节只定义审核发布后的运行时结构。

Metric 可以包含编译器生成的 dependencies.datasets 和 dependencies.relationships，但不要求人工重复维护。自动发现的 Metric 还可使用 origin 记录语言、原始逻辑 URI 和内容哈希；这些元数据只用于血缘、重编译和漂移检测。

metrics:
  - id: amount
    name: 财务金额
    value_type: decimal
    definition:
      type: aggregate
      function: sum
      input:
        type: field_ref
        field: finance_fact.amount_value
      null_handling: ignore

每个 Metric 必须有且只有一个根 definition。

MetricNode 联合类型

MetricNode
├── FieldRefNode
├── MetricRefNode
├── AggregateNode
├── FilterNode
├── FormulaNode
├── TimeShiftNode
├── CumulativeNode
├── WindowNode
└── RankNode

AggregateNode

type: aggregate
function: sum
input:
  type: field_ref
  field: finance_fact.amount_value
group_by: []
distinct: false
null_handling: ignore

MVP 聚合函数：

sum | count | count_distinct | avg | min | max

group_by 是可选的 Field 引用数组。只有原始计算逻辑把分组粒度作为指标定义的一部分时才固化；如果分组只是某次报表查询的展示维度，则不写入 Metric，由运行时查询上下文提供。

FilterNode

Filter 必须包含一个可产生值的 input，不能独立存在。

type: filter
input:
  type: metric_ref
  metric: amount
predicate:
  all:
    - field: finance_fact.scenario_code
      operator: eq
      value: actual
    - field: finance_fact.account
      operator: in
      values: [revenue]

Predicate 使用递归布尔结构：

Predicate = Comparison | All | Any | Not

predicate:
  any:
    - all:
        - field: finance_fact.scenario_code
          operator: eq
          value: actual
        - field: finance_fact.account
          operator: in
          values: [revenue, other_revenue]
    - field: finance_fact.account
      operator: is_null

MVP 比较操作符：

eq | ne | gt | gte | lt | lte
in | not_in | between
is_null | is_not_null
like

Metric Predicate 只能引用 Dataset Field 或常量，不能引用 Ontology Concept。Ontology 中的业务概念必须先解析为具体 Metric 或 Field 条件，才能进入 Metric Planner。

FormulaNode

type: formula
operator: divide
inputs:
  - type: metric_ref
    metric: actual_revenue
  - type: metric_ref
    metric: budget_revenue
zero_division: null

Metric 示例

metrics:
  - id: amount
    name: 金额
    definition:
      type: aggregate
      function: sum
      input:
        type: field_ref
        field: finance_fact.amount_value

  - id: actual_amount
    name: 实际金额
    definition:
      type: filter
      input:
        type: metric_ref
        metric: amount
      predicate:
        field: finance_fact.scenario_code
        operator: eq
        value: actual

  - id: actual_revenue
    name: 实际营业收入
    definition:
      type: filter
      input:
        type: metric_ref
        metric: actual_amount
      predicate:
        field: finance_fact.account
        operator: in
        values: [revenue]

  - id: budget_achievement_rate
    name: 预算达成率
    value_type: percentage
    definition:
      type: formula
      operator: divide
      inputs:
        - type: metric_ref
          metric: actual_revenue
        - type: metric_ref
          metric: budget_revenue
      zero_division: null

Metric 编译约束

Metric DAG 不允许环；
field_ref 必须指向存在且类型兼容的 Field；
metric_ref 必须指向存在且可访问的 Metric；
Filter 必须有 Input 和 Predicate；
Formula 的参数个数必须符合 Operator 定义；
除法必须声明除零行为；
时间节点必须声明时间 Field；
跨 Dataset 引用必须存在可解析的 Join 路径；
Metric 的安全策略不能弱化被引用 Metric 的安全级别。

5.5 Ontology / SemanticView

Ontology / SemanticView 是面向 AI 问数模型的业务语义适配层。它在确定的组织、部门、角色和统计目的下，把业务概念、常用说法、Metric、Dataset、权限边界和回答约束组织成可检索、可规划、可解释的语义视图。

本设计不强制把 Ontology 和 SemanticView 拆成两个独立对象：Ontology 表达概念及其关系，限定作用域并发布给 AI 使用后，即形成 SemanticView。该层服务企业内部的具体统计视角，不以跨企业通用复用为目标；可复用的计算逻辑应优先沉淀在 Metric 层。

ontologies:
  - id: finance_management_view
    name: 财务管理报表语义视图
    description: 面向财务管理人员的实际、预算和预测分析视图

    scope:
      organization: group
      department: finance
      roles: [finance_manager, finance_analyst]
      purpose: management_reporting

    ai_semantics:
      supported_intents:
        - metric_query
        - period_comparison
        - trend_analysis
        - variance_analysis
      clarification_policy: ask_when_ambiguous
      answer_requirements:
        - metric_definition
        - time_scope
        - currency
        - data_freshness

    concepts: []
    relationships: []
    access_policy: {}

其中：

scope 决定该视图对谁、在什么统计目的下成立；
ai_semantics 描述 AI 可以如何理解问题、何时澄清以及回答必须携带哪些信息；
concepts 将业务语言绑定到 Metric、Dataset 或 Field；
relationships 组织业务概念关系，不代替物理 Join；
access_policy 引用运行时权限策略，不能仅依赖模型记忆执行权限控制。

Ontology 对 Metric、Dataset 的引用是单向的：Concept 可以通过 metric_ref、field_ref、predicate_ref 或 dataset_ref 指向实现对象；Metric 和 Dataset 不反向依赖某个 Ontology。编译器可以生成反向索引用于检索和影响分析，但不把该索引写成运行时强依赖。

Concept

concepts:
  - id: actual_revenue
    name: 实际营业收入
    kind: kpi
    aliases: [实际收入, 实际销售收入]
    description: 实际场景下归属于营业收入科目的金额
    implementation:
      type: metric_ref
      metric: actual_revenue

  - id: organization
    name: 组织
    kind: dimension
    description: 法人或成本中心，不包含装置
    implementation:
      type: field_ref
      field: finance_fact.entity

  - id: actual_scenario
    name: 实际场景
    kind: classification
    implementation:
      type: predicate_ref
      predicate:
        field: finance_fact.scenario_code
        operator: eq
        value: actual

implementation.type 支持：

metric_ref | field_ref | predicate_ref | dataset_ref | none

none 用于纯概念节点，例如“财务报表”或“盈利能力”，其作用是组织其他概念而不是直接执行。

OntologyRelationship

relationships:
  - subject: actual_revenue
    predicate: measures
    object: revenue

  - subject: actual_revenue
    predicate: constrained_by
    object: actual_scenario

  - subject: gross_margin_rate
    predicate: belongs_to
    object: profitability_analysis

OntologyRelationship 描述业务概念关系，不用于生成物理 Join。

权限与业务过滤边界

过滤类型	所属对象	示例
业务口径	Metric	`scenario = Actual`、`account IN Revenue`
数据权限	Ontology/SemanticView	用户只能查看授权组织
用户条件	Query Request	`period = 2026-06`

最终查询条件为三者的合取，但权限条件不能写回 Metric。

训练与评测语料导出

Ontology / SemanticView 首先是在线问数的运行时契约，不直接等同于训练集。后期可由独立的 Corpus Compiler 将“已发布 SemanticView + Metric/Dataset 血缘 + 已审核问数、纠正和反例”编译为模型/Agent 路由、领域小模型 SFT/蒸馏、偏好学习和回归评测语料。这里的“模型协调器”指选择 SemanticView、模型、Agent 或工具的路由层；Sakana AI 的模型组合与任务适配研究可作为参考方向。

Corpus 与运行时 Ontology 分开版本化，并遵守：

只使用已发布语义对象和经过授权、审核的交互记录；
每条样本记录语义包版本、来源血缘、生成方式和审核状态；
敏感值脱敏、租户隔离，不把具体用户权限固化进模型权重；
动态财务数值默认不作为长期答案标签，确需使用时记录数据快照；
按时间或版本切分训练/评测集，并支持随来源撤销重建语料。

6. 离线语义探索

6.1 语义接入映射

接入层把不同来源转换为后续探索可使用的统一结构：

输入	解析方式	输出
Table / View	Catalog、DDL、约束和物理布局采集	Dataset 草稿
Structured / Semi-structured File	文件格式、Schema 和记录路径解析	Dataset 草稿
Unstructured File	文本、版面、OCR、语音或多模态提取	分级 `ai_context`
OpenAPI	契约登记或解析复制	API Source 与 Field 草稿
SQL / R / Python / BI	Parser、Framework Adapter 或 Logical Plan	Calculation IR 与 Metric 候选

计算逻辑统一经过以下过程：

原始逻辑
→ AST / 调用图 / Logical Plan
→ Dataset 与 Field 绑定
→ filter / join / group / aggregate / calculate / window 等原子操作
→ Calculation IR
→ Metric 与 DatasetRelationship 候选
→ 结果等价性验证和人工确认

原子语义	SQL	R / Python	编译结果
数据来源	`FROM`、CTE	`tbl()`、`read_*()`、`read_sql()`	Dataset、Field 引用
过滤	`WHERE`	`filter()`、Boolean Mask、`query()`	FilterNode、Predicate
关联	`JOIN ... ON`	`left_join()`、`merge()`、`join()`	DatasetRelationship 候选和 Metric 依赖
分组与聚合	`GROUP BY`、`SUM/AVG/...`	`group_by()`、`summarise()`、`groupby().agg()`	AggregateNode
标量计算	四则运算、`CASE`、函数	`mutate()`、`assign()`、列运算	FormulaNode
窗口计算	`OVER`、排名、累计	Window Function、`rolling()`、`rank()`	Window/Rank/Cumulative Node

Join 不保存为原始 SQL 片段，也不作为数值型 MetricNode。接入层先生成 DatasetRelationship 候选；确认后，Metric 依赖闭包引用该关联路径。dependencies 由 Metric DAG 自动计算，不要求人工重复维护。

SQL 使用匹配方言的 Parser 并解析 Catalog、CTE、别名和函数；R/Python 使用 AST 与 Framework Adapter。引擎能够提供 Logical Plan 时优先读取 Logical Plan。

静态解析不能可靠处理动态 SQL、eval、反射、任意 UDF、外部调用或有副作用代码时，必须标记为 opaque，不得猜测或直接执行不受信任的代码。

候选发布前必须验证 Dataset/Field 绑定、Join Key/Type/基数、操作顺序、NULL/Distinct/时区/精度/窗口语义，以及原逻辑与 Metric 在相同输入和粒度下的结果等价性。代码只能证明“如何计算”，业务名称和统计口径仍需人工确认。

6.2 数据画像与规则发现

单字段与组合画像；
候选事实粒度和最小唯一组合搜索；
函数依赖、条件依赖、枚举和映射发现；
跨分区反例验证；
基于覆盖范围、时间跨度、新鲜度和反例率的可解释评分。

代理主键、数值事实值、审计字段、分区字段、自由文本和预留字段默认不参加业务粒度组合搜索。自动搜索采用近似 Distinct、低阶组合优先和 Apriori 式剪枝；业务声明的宽候选键直接进入验证队列，不受自动搜索宽度限制。

置信度只用于候选排序和风险控制，不是业务正确性的概率承诺。人工确认仍是进入运行时语义包的必要条件。

6.3 探索记录

探索记录与运行时语义包分开存储：

对象	关键内容
ExplorationJob	Dataset、任务类型、数据范围、策略和状态
ProfileSnapshot	字段/组合画像、行数、范围和生成时间
Hypothesis	候选规则、作用域、来源、语义类型、置信度和状态
Evidence	验证范围、查询、统计结果和生成时间
Counterexample	违反规则的数据范围、数量和脱敏样本 URI
ReviewDecision	确认、驳回、限定范围、审核人和时间

hypothesis:
  id: hyp-scenario-version-001
  dataset_id: finance_fact
  type: functional_dependency
  expression:
    determinant: [scenario_code]
    dependent: [version_code]
  scope:
    partitions: [2026-07-15, 2026-07-16, 2026-07-17, 2026-07-18]
  origin: discovered
  semantics: observational
  confidence:
    score: 0.91
    coverage: 1.0
    counterexample_rate: 0.0
  status: review_pending

origin 支持 declared | discovered | user_feedback | imported。observational 规则被反例击中时进入局部重探；normative 规则优先触发数据质量告警。

6.4 人工审核与语义制作

人工审核工作台提供三类入口：

接受、驳回或限定自动发现候选的作用域；
手工新建、组合或修改 Dataset、Metric、Ontology；
补充 opaque 逻辑、业务名称、统计口径、权限引用和回答约束。

工作台必须同时展示来源、画像、证据、反例、计算血缘和版本差异。自动发现只能提出候选，不能绕过人工确认发布业务语义。

6.5 候选状态机

stateDiagram-v2
    [*] --> Candidate
    Candidate --> Observed: 数据验证通过
    Candidate --> Rejected: 无效或无业务意义
    Observed --> ReviewPending: 达到审核阈值
    Observed --> Candidate: 新反例或范围变化
    ReviewPending --> Confirmed: 人工确认
    ReviewPending --> Rejected: 人工否决
    ReviewPending --> Observed: 需要更多证据
    Confirmed --> Deprecated: 口径下线
    Confirmed --> ReviewPending: 重大反例或业务变更
    Deprecated --> [*]
    Rejected --> [*]

6.6 持续探索 Loop

任务类型包括：

initial_discovery
incremental_validation
periodic_rediscovery
drift_triggered_discovery
question_triggered_discovery

首次接入执行完整画像和候选发现；新增分区、文件或 API 数据默认只验证已知规则。出现新枚举、结构变化、分布漂移、规则反例、代码变化、语义未命中或用户纠正时，才触发局部重探。

用户纠正先写入 FeedbackRecord，再经历“候选 → 验证 → 人工审核 → 新版本发布”，不得直接修改线上版本。

7. 编译、存储与发布

7.1 Semantic Compiler

Semantic Compiler 只接收人工确认或人工制作的语义对象：

阶段	处理内容
Collect	收集 Dataset、Metric、Ontology、权限引用和确认规则
Normalize	统一标识符、类型、枚举和表达式节点
Resolve	解析 Field、Metric、Dataset 和 Ontology 引用，计算依赖闭包
Validate	校验 Schema、Metric DAG、Join 基数、粒度、权限和发布策略
Emit	输出不可变 SemanticPackage、运行时索引、血缘和诊断信息

Ontology 发布时必须同时固定其引用的 Metric、Dataset 和 DatasetRelationship 依赖闭包，不能发布一个会随外部依赖变化而漂移的孤立对象。编译失败返回结构化诊断，并禁止发布。

7.2 语义存储

存储	内容	在线可见性
Metadata DB	Job、Hypothesis、ReviewDecision、语义对象元数据和版本	不直接读取
Object Store	完整画像、样本、证据、AST、Calculation IR、验证结果和发布附件	不直接进入在线上下文
Draft Store	待审核 Dataset、Metric、Ontology 和版本差异	不可见
Package Registry	不可变 SemanticPackage、校验和、状态和制品 URI	发布加载
Runtime Index	Concept、别名、Metric 依赖和最小上下文检索索引	在线读取

大体量内容保存在 Object Store，Metadata DB 只保存摘要、状态和 URI。Source 凭据不进入任何语义包。

Package Registry 状态：

draft → validating → released → deprecated → revoked

Draft Store 保存可编辑的单个语义对象草稿；Registry 的 draft 表示已编译但尚未通过发布校验的包版本，两者不是同一生命周期。

7.3 版本与激活

已发布版本不可原地修改；
在线服务按 package_id + version 读取，单次请求不得跨版本；
新版本构建 Runtime Index 后，通过原子指针切换为 active；
回答记录实际使用的 package version 和 Metric plan hash；
删除对象或修改统计口径使用 Major，新增兼容对象使用 Minor，纯文案修正使用 Patch；
同一 Dataset、同一探索范围只运行一个深度探索任务，审核修改使用乐观锁。

8. 在线语义服务

在线服务只加载已发布并激活的 SemanticPackage，不读取 Hypothesis 或未审核草稿。一次解析按以下顺序执行：

根据用户的组织、部门、角色和统计目的选择 Ontology/SemanticView；
将问题解析为 Concept、Metric 和维度；
展开 Metric DAG、DatasetRelationship、Dataset 和 Field；
合并 Metric 业务口径、Ontology 权限和用户条件；
返回当前问题所需的最小上下文、版本和血缘。

语义服务不执行最终数据查询，查询由 Data Agent 或 Query Engine 完成。

resolved_context:
  ontology: finance_management_view
  concepts: [actual_revenue, organization]
  metric_plan:
    root: actual_revenue
    dependencies: [actual_amount, amount]
  datasets: [finance_fact]
  fields:
    - finance_fact.amount_value
    - finance_fact.scenario_code
    - finance_fact.account
    - finance_fact.entity
  policy:
    entity_scope: [E001, E002]
  package_version: 1.0.0

返回内容采用按需展开：先召回 SemanticView 和 Concept，再加载命中的 Metric 依赖闭包，最后补充相关 Dataset/Field 与权限谓词；不返回整个语义包，也不返回探索证据原文。

9. 工程接口与运行保障

9.1 核心 API

所属边界	接口	用途
离线语义探索	`POST /v1/exploration-jobs`	创建首次探索、增量验证或局部重探任务
离线语义探索	`GET /v1/exploration-jobs/{jobId}`	查询任务状态和摘要
人工审核工作台	`GET /v1/hypotheses`	查询待审核候选
人工审核工作台	`POST /v1/hypotheses/{id}/decisions`	确认、驳回或限定候选作用域
编译与发布	`POST /v1/semantic-packages/{id}/compile`	编译语义包
编译与发布	`POST /v1/semantic-packages/{id}/releases`	发布不可变版本
在线语义服务	`POST /v1/semantic-context/resolve`	返回在线最小语义上下文
在线语义服务	`GET /v1/metrics/{id}/lineage`	查询 Metric 血缘
在线回流	`POST /v1/feedback`	提交语义未命中、歧义或用户纠正

在线解析请求至少包含 question 和 userContext；ontology 可由调用方指定，也可由服务按作用域路由：

{
  "question": "查询2026年各组织的实际营业收入",
  "ontology": "finance_management_view",
  "userContext": {
    "userId": "u-1001",
    "organization": "group",
    "department": "finance",
    "roles": ["finance_analyst"],
    "purpose": "management_reporting"
  }
}

9.2 安全与治理

Source 凭据不进入语义包；
连接凭据由 Secret Manager 管理；
Profiler 使用只读账号；
画像默认不保存敏感字段原值；
反例样本按字段敏感级别脱敏；
Ontology 权限引用外部策略 ID，不复制完整用户授权表；
编译器禁止 Metric 绕过外部数据访问策略；
所有审核、发布、回滚和权限变更记录审计日志；
自定义 SQL 片段和 scalar_expression 使用白名单语法树，不执行任意文本。

9.3 可观测性

核心指标：

exploration_job_duration_seconds
exploration_job_failure_total
profile_rows_scanned_total
hypothesis_created_total
hypothesis_confirmed_total
hypothesis_violation_total
semantic_compile_failure_total
semantic_resolve_latency_ms
metric_plan_cache_hit_ratio
agent_semantic_fallback_total

必备追踪标识：

job_id
hypothesis_id
package_id
package_version
metric_plan_hash
agent_request_id
source_query_id

一次 Data Agent 回答必须能够追溯到：

用户问题
→ Ontology Concept
→ Metric DAG
→ Dataset Field
→ Source Query
→ Semantic Package Version

9.4 故障和降级策略

故障	策略
探索任务超时	保存部分画像，标记 incomplete，不生成高置信规则
新分区验证失败	保留上一发布版本，产生告警和重探任务
编译失败	禁止发布，返回结构化诊断
Registry 不可用	在线服务使用最后一个已验证本地缓存版本
Ontology 未命中	返回澄清问题，不直接猜测字段
Metric 解析歧义	返回候选口径及差异，要求用户选择
权限服务不可用	Fail closed，不执行查询
数据源不可用	返回可重试错误，并保留语义解析结果

10. MVP 与后续演进

10.1 实施阶段

阶段	主要交付	验收结果
Phase 1：接入与画像	SourceAdapter、Dataset/Field、ProfileSnapshot、Metadata DB/Object Store	Table、View、File、API 能转换为统一结构；`MainTable_1u44q` 的画像可重复
Phase 2：规则探索	粒度、依赖、Evidence、Counterexample、状态机和审核工作台	能区分业务声明与样本观察，并展示范围和反例
Phase 3：Metric	Calculation IR、核心 MetricNode、DAG/Join 校验和不可变发布	能表达金额、实际收入、预算收入和预算达成率
Phase 4：Ontology 与在线服务	Concept、作用域、权限引用、Semantic Resolver 和最小上下文	问题能解析为确定的 Metric、Dataset/Field 和权限范围
Phase 5：持续 Loop	增量验证、漂移检测、局部重探、纠正回流和回滚	新反例不覆盖线上版本，只生成告警或待审核候选

10.2 MVP 完成标准

同一数据快照能够生成一致画像；
候选规则能够追溯到范围、证据和反例；
未经人工确认的对象不能进入在线服务；
Metric 通过引用、DAG、Join 和粒度校验后才能发布；
Ontology 能引用 Metric、Dataset/Field，并按用户作用域解析；
Agent 只获取最小上下文，每次回答可追溯到语义包版本和 Metric plan；
新数据和用户纠正通过验证、审核和新版本进入闭环。

10.3 后续演进

TimeShift、Cumulative、Window、Rank、多事实表粒度对齐和更完整的非结构化提取器；
Metric 公共库、跨语义包版本约束、Ontology 外部标准映射和 Ossie 格式互转；
基于历史问数的语义缺口发现、自动验证查询和回归测试集；
在出现独立生命周期和多环境复用需求后，再评估 SemanticBinding；
将已发布 SemanticView、Metric/Dataset 血缘与已审核交互编译为模型/Agent 路由、SFT、蒸馏、偏好和评测语料。

Dataset 保持粒度，Metric 负责计算，Ontology 负责解释，DiscoveryRecord 负责证明。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Data Semantic Exploration Compiler #238

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Data Semantic Exploration Compiler #238

Uh oh!

lanvendar Jul 21, 2026

数据语义探索编译器工程设计

1. 核心对象与边界

1.1 Ontology / SemanticView

1.2 Metric

1.3 Dataset

1.4 三层关系

2. 工作方式：探索向上，运行向下

2.1 离线探索自底向上发现

2.2 在线问数自顶向下执行

3. 总体架构

3.1 离线探索与发布交互

3.2 在线问数交互

4. 范围与非目标

5. 运行时语义包数据结构

5.1 根对象 SemanticPackage

5.2 Dataset

Source 类型

5.2.1 Table | View

5.2.2 File

5.2.3 API

OpenAPI 解析复制要求

5.2.4 Field 与行级映射

5.3 DatasetRelationship

5.4 Metric

Metric 来源与自动探索

MetricNode 联合类型

AggregateNode

FilterNode

FormulaNode

Metric 示例

Metric 编译约束

5.5 Ontology / SemanticView

Concept

OntologyRelationship

权限与业务过滤边界

训练与评测语料导出

6. 离线语义探索

6.1 语义接入映射

6.2 数据画像与规则发现

6.3 探索记录

6.4 人工审核与语义制作

6.5 候选状态机

6.6 持续探索 Loop

7. 编译、存储与发布

7.1 Semantic Compiler

7.2 语义存储

7.3 版本与激活

8. 在线语义服务

9. 工程接口与运行保障

9.1 核心 API

9.2 安全与治理

9.3 可观测性

9.4 故障和降级策略

10. MVP 与后续演进

10.1 实施阶段

10.2 MVP 完成标准

10.3 后续演进

Replies: 0 comments

lanvendar
Jul 21, 2026