# Text-to-SQL 跑通了，收入数字照样会算错

> 表结构不会告诉模型财务怎么算 MRR；指标在语义层只定义一次，模型和报表就能共用同一口径。

原文: https://fdetimes.net/zh/guides/semantic-layer-text-to-sql-revenue/

设想这样一个场景：你刚在一家 SaaS 公司部署了一个智能体，财务团队问它：“1 月的 MRR 是多少？”它给出一个数字，还附上一段整洁的 SQL，运行时没有任何报错。到了下午，这个数字和财务自己的报表对不上，差得还不少，被叫去开会的是你。

几乎每个做“用自然语言查数据”项目的前线部署工程师（FDE）都会走到这一步。问题不在模型，也不在提示词，而在于“收入”的定义从来没有以机器能读懂的形式写下来过。

本文介绍如何从源头解决这个问题：在语义层把每个指标定义一次，再让 LLM 和客户的报表都使用这同一个定义。

## 语法正确的 SQL，照样可能答错问题

Omni 团队把这个问题讲得很清楚。在他们看来，LLM 写出的 SQL 本身并不差，难点在于它写出的 SQL 看起来合理，含义却是错的。Omni 举的例子正是一个 MRR 问题：模型直接把 orders 连接到 products，跳过了订阅表，返回的是订单总金额，整个过程没有任何报错。

Cube 指出了模型犯这种错的原因：数据仓库的表结构不会说明贵公司如何定义收入。一个叫 `amount` 的字段，看不出它是实收现金、已确认收入，还是每月应收金额。这些规则存在于财务团队的脑子里、某张电子表格里，或者某个只有一个人还记得的视图里。

在客户现场，这正是 FDE 的工作：把业务语言里的定义转化成机器能执行的东西。这一步模型替你做不了。

## 同一个客户，两个数字

看一个具体例子（数字仅作示意）。客户 A 购买了一份 12,000 美元的年度套餐，1 月一次性付清。如果走 orders → products 这条捷径汇总订单金额，1 月显示 12,000 美元，之后 11 个月都是零。如果经过订阅表计算，全年每个月的 MRR 都是 12,000 / 12 = 1,000 美元。

两条查询都能运行，但只有第二条回答了财务的问题。仅一份年度套餐，就让 1 月的 MRR 虚高了 12 倍。如果客户有几百份这样的合同，错误的数字就很难靠肉眼发现。

第二类常见错误是扇出（fan-out）。一笔 100 美元的订单包含三条商品明细。把 orders 连接到 order_items 再执行 `SUM(order_total)`，得到的是 300 美元，因为订单总额在每一行明细上都重复了一次。dbt 文档把这类错误称为扇出连接（fan-out join）和断层连接（chasm join），MetricFlow 在选择连接路径时会专门避开它们。

## 只定义一次，处处按名称调用

语义层把连接路径固定在模型里，从而同时解决这两类错误。据 Omni 介绍，把同一个 MRR 问题改为基于语义层提问时，连接路径已经事先定义好，指标每次都按同一种方式计算。Cube 的思路也一样：智能体查询的是有名称的度量和维度，而不是根据表名和字段名去重建业务逻辑。

在 dbt 生态里，承担这项工作的引擎是 MetricFlow。它规定了定义语义模型和指标的约定，并根据这些定义生成 SQL。每个语义模型包含三部分：实体（entity）是连接键，也就是把模型连在一起的边；维度（dimension）是切分数据的角度；指标（metric）则建立在它们之上。

下面是 MRR 的示例写法，具体语法取决于你使用的 dbt 版本：

```yaml
semantic_models:
  - name: subscriptions
    model: ref('fct_subscriptions')
    defaults:
      agg_time_dimension: billing_month
    entities:
      - name: subscription
        type: primary
        expr: subscription_id
      - name: customer
        type: foreign
        expr: customer_id
    dimensions:
      - name: billing_month
        type: time
        type_params:
          time_granularity: month
      - name: plan_tier
        type: categorical
    measures:
      - name: mrr_amount
        agg: sum
        expr: monthly_amount

metrics:
  - name: mrr
    label: 月度经常性收入
    type: simple
    type_params:
      measure: mrr_amount
```

值得注意的是 `monthly_amount`。年度套餐除以 12 的处理已经在 `fct_subscriptions` 表里完成，这张表经过评审，也有明确的负责人。之后 LLM 只需按 `billing_month` 和 `plan_tier` 调用 `mrr`。财务的看板调用的也是同一个指标，智能体和财务从此不再各有各的数字。

## 报错失败，好过悄无声息地失败

2026 年，dbt Labs 在 ACME Insurance 数据集上做了一次基准测试：11 个问题，每个问 20 次，覆盖多个 LLM。最值得记住的结论不是准确率，而是两种方法失败的方式。Text-to-SQL 失败时，给出的是一个听起来合理但错误的答案；语义层失败时，给出的是一条错误信息。

对 FDE 来说，这个区别非常关键。看到错误信息，用户会重新提问，或者来找你。一个看似合理的错误数字，却可能在董事会材料里待上整整一个季度。

这次基准测试有几点局限值得了解。为了让 Text-to-SQL 能够工作，作者把整个表结构都放进了上下文，他们自己也承认，数据集更大时这种做法行不通。

Atlan 在总结这次测试时也指出，这是厂商在测试自家产品。结果只能作为参考，还是要用客户的数据跑你自己的评测。

dbt 的建议并不要求二选一。凡是要报给董事会、交给审计、计入 OKR、KPI 或周报的数字，都应该来自接入语义层的 LLM。Text-to-SQL 留给临时的探索性问题。

**要点:** 看似合理的错误数字，远比一条错误信息危险。

## 在客户现场从哪里入手

不要一上来就给整个数据仓库建模。拿出每周的 KPI 报表或最近一份董事会材料，挑出出现最频繁的指标。这份清单就是第一轮的范围。

接下来，和真正负责每个定义的人坐下来谈，通常是财务或 RevOps。写 YAML 之前，先用大白话写下定义，例如：“MRR 中年度套餐按 12 等分计算，不含开通费，按计费月份确认。”每个定义都记下批准人的名字。

然后编写语义模型，用几个已结账的月份跑一遍指标，把每个数字和客户现有的报表逐一核对。凡是对不上的地方，回去找定义的负责人，不要自己猜。

数字对上之后，再接入 LLM。这时要把路由规则写明确：涉及已定义指标的问题走语义层，其余问题才交给 Text-to-SQL。

## 常见陷阱

第一个陷阱是按字段名定义指标。数据仓库里叫 `revenue` 的字段，不一定是会计意义上的收入。第二个陷阱是语义层报错时，悄悄退回 Text-to-SQL。这样做等于丢掉了语义层最大的优势：错误会暴露出来，而不是被掩盖。

第三个陷阱是让 LLM 临时创建新指标。新指标应该像其他任何改动一样经过代码评审。最后一个陷阱是只信厂商的基准测试，而没有自己的评测集。评测集应该由客户的真实问题组成，每个问题都配有财务确认过的答案。

## 这项技能该怎么写进简历？

浏览 FDE 或解决方案工程师的岗位描述时，留意 dbt、MetricFlow、Cube、语义层（semantic layer）或“指标定义”（metrics definitions）这类关键词。它们说明这家公司需要的是能保证数字准确的人，而不只是把 LLM 接到数据库上的人。

简历上写一句“在语义层统一核心 KPI 的定义，并在开放给智能体之前与财务报表完成核对”，分量远远超过“搭建了一个 Text-to-SQL 聊天机器人”。

LLM 写 SQL 的能力会越来越强。但要弄清客户怎么算收入，还是得去问人，再把答案写在唯一的一个地方。

**本周动手试试:**

- 选一个客户问得最多的指标（例如 MRR），让 LLM 为它写五次 SQL，把结果和财务团队的报表对比
- 为这个指标编写一个 YAML 语义模型，包含实体、维度和度量，检查算出的数字是否与现有报表一致
- 建一张表，列出每个指标的大白话定义、定义负责人和来源表

## 信源

- [Why text-to-SQL fails](https://omni.co/blog/why-text-to-sql-fails)

- [Introducing Cube's Claude Connector and Skills](https://cube.dev/blog/cube-connector-and-skills-for-claude)

- [About MetricFlow | dbt Developer Hub](https://docs.getdbt.com/docs/build/about-metricflow)

- [Semantic Layer vs. Text-to-SQL: 2026 Benchmark Update](https://docs.getdbt.com/blog/semantic-layer-vs-text-to-sql-2026)
