“近 30 天各品类的客单价是多少？”模型很容易写出语法正确的 SQL，也很容易在业务上完全错掉。客单价可能是支付金额除以支付订单数，也可能排除退款、按买家数计算，或者只看签收订单。
这不是 SQL 技巧问题，而是业务术语尚未绑定到可执行语义。
一个指标至少有五组约束
实体与人群定义谁被统计；分子和分母规定公式；时间说明事件时间、窗口和时区；粒度决定按订单、用户还是商品聚合；有效期和版本说明这套口径何时生效。
指标名只是入口，指标契约才是可执行对象。契约还应包含允许关联、默认过滤、空值处理、Owner、验证查询和已知例外。
为什么需要读取代码和元数据
数据开发代码包含真实的派生、过滤和关联逻辑，表元数据描述字段、分区和血缘。二者结合可以生成语义模型草稿，再由业务和数据 Owner 编辑确认。只读 Schema 很难发现“已支付但未取消”这样的隐含条件。
阿里云 DataWorks 的相关路线值得关注，正因为它把语义生成放在数据开发与分析工作流之间：语义不是旁边的一份说明文档，而是 Agent 查询时要加载的约束。
生成语义模型后还要验证
可编辑 YAML 或其他语义定义只是载体。上线前应使用已知问句与可信查询做双向测试：同义表达是否绑定同一指标；边界日期是否一致；跨表 Join 是否改变粒度；新版本是否破坏历史结果。
一个可落地的最小闭环
先从十个高频指标开始，提取代码与元数据，生成草稿，由 Owner 确认后写入版本化语义仓库；查询时记录命中的指标版本；结果异常时，把修正回写为新的测试，而不是临时提示词。
Data Agent 真正理解“客单价”，不是因为模型见过这个词，而是因为词被绑定到了有版本、有 Owner、可验证的计算契约。
语义层还需要运行时观测
上线后应统计每个指标契约被哪些问题命中、哪些同义词频繁无法解析、哪些查询在 Join 后产生异常膨胀，以及用户在哪些答案上反复追问。它们能揭示语义定义缺口，比单纯统计问答满意度更接近根因。
契约变更也要区分兼容更新与破坏性更新。增加一个同义词通常可以直接发布；改变分母、默认过滤或时间窗口，则需要新版本、影响分析和历史回放。语义层不是一张静态指标表，而是一套面向 Agent 执行的变更管理系统。
对跨部门指标，还应显式声明适用组织与展示名称，避免销售口径覆盖财务口径。若用户问题没有足够信息选择版本，Agent 应展示候选定义并请求确认，而不是依赖语料中的多数用法替用户决定。
语义命中记录也可以反哺治理：高频歧义进入术语清单，反复失败的 Join 进入禁止规则，常用且稳定的问句沉淀为验证样例。每次失败都应改善契约，而不是只修补当次回答。