# Text-to-SQL 智能体的成败，取决于客户的业务定义

> Vercel 删掉智能体的大部分工具后它仍然好用，因为语义层早已写得清清楚楚。

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

Vercel 删掉了其 Text-to-SQL 智能体的大部分工具，智能体依然运行良好。原因既不在提示词，也不在模型。据有关该案例的介绍，这种做法之所以奏效，是因为 Vercel 的语义层早已文档完备。

对前线部署工程师（FDE）来说，这个细节很能说明问题：当客户要你“做一个查数据的聊天机器人”时，你的时间会花在哪里。大部分时间不会花在智能体代码上，而是花在把客户数据仓库里每个数字的计算方式清楚地写下来。

本指南正是按这个顺序构建一个小型智能体：先定义，再选择上下文、生成 SQL，最后评分。文中的代码片段是伪代码或临时配置，为简洁起见做了删减，请套用到你所用的框架和模型中。

## 开始之前需要准备什么？

三样东西：足以自己写出正确查询的 SQL 功底，一个能在笔记本上运行的示例数据库，以及任意一个 LLM 的访问权限。如果你从没做过智能体，先学一下 DeepLearning.AI 与 Microsoft 合作的短课程 *Building Your Own Database Agent*。这是一门约 1 小时 8 分钟的入门课程，教你构建一个把自然语言转换为 SQL 的智能体。

课程的既定目标是用自然语言处理表格数据和 SQL 数据库，让分析更快、门槛更低。课程能给你一个跑得起来的智能体，本指南其余部分则帮它答对。

举个贯穿全文的例子：假设客户是一家零售连锁企业，有两张表：

```sql
-- 假设的 schema，已简化
orders(order_id, customer_id, amount, status, created_at)
refunds(refund_id, order_id, refund_amount, refunded_at)
```

## 第 1 步：写提示词之前，先问清“收入”是什么意思

客户输入的第一个问题几乎一定是“9 月收入是多少？”。未经调教的智能体会生成这样的查询：

```sql
SELECT SUM(amount)
FROM orders
WHERE created_at >= '2026-09-01' AND created_at < '2026-10-01';
```

它运行无误。现在代入数字：9 月共有 1,000 笔订单，总额 5 亿越南盾。其中 60 笔订单、合计 3000 万已取消，其余订单中有合计 1000 万的退款。

智能体报告 5 亿。财务团队按扣除取消和退款后的口径计算收入，报告的是 5 亿 − 3000 万 − 1000 万 = 4.6 亿。才问了一个问题，客户就失去了信任。

一篇关于数据智能体上下文工程的文章描述的正是这类失败：错误出在语义，而不是语法。该文作者供职于一家销售语义层产品的公司，所以请在自己的数据上验证这一说法。不过上面的收入例子表明，这种失败完全可能发生。

因此，第一项工作是和客户那边负责数字的人坐下来，把定义写下来。下面是一个最小的定义文件，采用临时格式，不遵循任何特定工具的标准。（键名含义：`revenue` 为收入，`description` 为描述，`tables` 为相关表，`notes` 为备注。）

```yaml
# semantic_layer.yaml（自定义格式，已简化）
metrics:
  revenue:
    description: "统计期内未取消订单的收入，减去这些订单的退款"
    sql_file: revenue.sql
    tables: [orders, refunds]
    notes: "统计期以订单的 created_at 为准。orders 和 refunds 须分两个查询分别求和"
```

这里的描述是：统计期内未取消订单的收入，减去这些订单的退款。备注写明统计期以订单的 `created_at` 为准，且 `orders` 和 `refunds` 必须分两个查询分别求和。该指标的标准 SQL 单独放在一个文件里：

```sql
-- revenue.sql（已简化）
(SELECT COALESCE(SUM(amount), 0) FROM orders
  WHERE status <> 'cancelled'
    AND created_at >= :from_date AND created_at < :to_date)
-
(SELECT COALESCE(SUM(r.refund_amount), 0)
   FROM refunds r JOIN orders o ON r.order_id = o.order_id
  WHERE o.status <> 'cancelled'
    AND o.created_at >= :from_date AND o.created_at < :to_date)
```

注意 `notes` 这一行。如果把 `orders` JOIN 到 `refunds`，再在同一个查询里对 `amount` 求和，退款过两次的订单，其 `amount` 就会被算两次。SQL 照样运行，数字照样出错，所以这条规则必须直接写进定义。

这一步完成后，把每条 `description` 念给客户方负责数字的人听。只要对方改动了哪怕一个词，这条定义就还没写完。

## 第 2 步：只给模型它需要的表

真实客户的数据仓库可能有数百张表。上述上下文工程文章建议，针对每个问题只挑选少数相关的表和列，而不是传入整个 schema。最简单的路径是借助语义层：问题匹配到哪个指标，就只取该指标声明的那几张表。

```python
# 伪代码，已简化
def build_context(question, semantic_layer):
    metrics = match_metrics(question, semantic_layer)   # 关键词或向量匹配
    tables = {t for m in metrics for t in m["tables"]}
    return {
        "metrics": metrics,                 # 定义 + 标准 SQL
        "schema": describe(tables),         # 只包含相关表的列
    }
```

检查方法：打印 10 个问题的上下文。如果一个收入问题带进了 `inventory` 表，说明匹配函数过于宽泛。如果上下文缺了 `refunds`，问题出在定义文件，而不是代码。

## 第 3 步：生成 SQL，并以只读权限执行

此时的提示词会比你预想的短得多。传入定义、精简后的 schema 和问题，并告诉模型：只要指标有标准 SQL，就优先使用。

```python
# 伪代码，已简化
ctx = build_context(question, semantic_layer)
sql = llm.generate(PROMPT.format(**ctx, question=question))
result = run_readonly(sql)   # 数据库账号只有 SELECT 权限
return {"sql": sql, "result": result, "metrics_used": ctx["metrics"]}
```

第一个版本就要做到两点。智能体的数据库账号只有读权限。每个答案都附上 SQL 和所用指标的名称，方便客户方的人自行核对。

一位为 Forbes Tech Council 撰稿的作者提醒，AI 驱动的分析存在治理风险：透明度、公平性和问责。随答案一起返回 SQL，是满足透明度要求成本最低的办法。

## 第 4 步：用带陷阱的问题评分

如果测试集只检查 SQL 能否运行，上面那个 5 亿的答案也能拿满分。因此每道测试题都必须配一个答案：由客户自己的人确认过的数字。

| 问题 | 语义陷阱 | 核对依据 |
|---|---|---|
| 9 月收入是多少？ | 已取消订单、退款 | 财务报表中的数字 |
| 第三季度有多少客户购买过？ | 数了订单而不是客户 | 分析师写的 COUNT(DISTINCT customer_id) |
| 上周的取消率是多少？ | 分母包含哪些订单 | semantic_layer.yaml 中的定义 |

答案出错时，别急着改提示词，先问是不是缺了某条定义。为生产环境构建分析智能体的 Wobby 认为，构建并持续完善语义层的过程，才是创造价值的地方。

每发现一个错误，都应把它变成一行 `notes` 和测试集里的一道新题。备注并不能保证智能体不再犯同样的错，但这道测试题能在它再犯时立刻告诉你。

**要点:** 智能体答错时，先修定义，再修提示词。

## 第 5 步：让智能体保持精简

出现错误时，本能反应是加工具：一个查看 schema，一个推测 join，一个修复 SQL。Vercel 的案例反其道而行之：它删掉了大部分工具，从中得出的教训是，为弥补模型当前弱点而搭建的架构，会随着模型进步变成负担。

所以，把精力投入语义层，这部分在模型更新换代后依然有价值；模型外围的脚手架则尽量少。每次想加工具时，先问一句：把定义里的某一行写得更好，能否解决问题？

## 应该自己埋哪些陷阱？

最常见的错误是把智能体直接丢进现状下的数据仓库，指望它自己摸清门道。Wobby 明确表示，在数据组织混乱、业务定义模糊的情况下这样做，只会得到错误结果。下面这些陷阱是假设的示例，可以埋进你的示例数据库，看智能体会不会掉进去。

时区陷阱：假设 `created_at` 以 UTC 存储，而客户按越南时间（UTC+7）看报表。一笔越南时间 10 月 1 日凌晨 3 点下的订单，存储为 UTC 9 月 30 日晚 8 点，于是被计入 9 月收入。

插入几笔这样的订单，然后问客户方负责数字的人它们属于哪个月，并把答案记进 `notes`。

跨期退款陷阱：一笔 9 月 28 日创建的订单在 10 月 5 日退款。按第 1 步的定义，这笔退款从 9 月扣除，也就是说，今天和下周查到的 9 月收入可能不同。如果智能体按 `refunded_at` 过滤，就会从 10 月扣除这笔金额，两个月的数字都对不上报表。

JOIN 放大行数陷阱：为同一笔订单添加两条退款记录，看智能体是否先 JOIN 再对 `amount` 求和。最后一个陷阱是：仗着上下文窗口够大，把整个 schema 塞进提示词，然后按 SQL 能否运行而不是数字是否正确来评分。

建议练习：埋下上述三个数据陷阱，写三道对应的问题并手算答案，在加入 `notes` 备注前后各运行一次智能体。两次结果之间的差距，就是你要向客户展示的内容。

## 这项技能在客户现场是什么样子？

你会和负责数字的人坐在一起，商定 5 到 10 个最重要的指标，并申请数据仓库的只读权限。

Devfi 在一篇关于 AI 驱动数据分析的评论中列出了落地的三大障碍：文化阻力、数据隐私顾虑和技术基础设施的局限。

只读账号和附带 SQL 的答案，能在一定程度上缓解数据方面的顾虑；答案由客户自己人审定的测试集，则让他们有办法自行核验结果。文化阻力和基础设施局限超出了上述任何技术的能力范围，这一点应从一开始就向客户说明。

阅读 FDE 或偏数据方向的解决方案工程师岗位描述时，留意“semantic layer”“metrics definition”“evaluation”这类词。简历上不要只写“构建了一个 Text-to-SQL 聊天机器人”，而要写明你与业务方商定了多少个指标定义、测试集有多少道题、正确率提升了多少。

你这周做的智能体，终会被更好的模型取代。而到那时，客户签字确认的收入定义仍会继续使用。

**本周动手试试:**

- 选一个示例数据库，为收入、活跃客户和取消率等 3 个指标编写定义文件，每个指标附上标准 SQL
- 编写 10 道附正确答案的测试题，其中至少 5 道内置语义陷阱，例如已取消订单、退款或时区
- 学习 DeepLearning.AI 的 Building Your Own Database Agent 课程（约 1 小时 8 分钟），先做出一个能运行的智能体，再用你的测试集跑一遍

## 信源

- [Building Your Own Database Agent](https://www.deeplearning.ai/short-courses/building-your-own-database-agent/)

- [How AI Will Transform Data Analysis in 2025](https://www.devfi.com/ai-transform-data-analysis-2025/)

- [How AI Has Changed The World Of Analytics And Data Science](https://www.forbes.com/councils/forbestechcouncil/2025/01/28/how-ai-has-changed-the-world-of-analytics-and-data-science/)

- [Building Production Analytics Agents with Semantic Layer Integration](https://zenml.io/llmops-database/building-production-analytics-agents-with-semantic-layer-integration)

- [Simplifying Text-to-SQL Agents by Removing 80% of Tools](https://www.zenml.io/llmops-database/simplifying-text-to-sql-agents-by-removing-80-of-tools)

- [Context Engineering for Data Agents](https://datalakehousehub.com/blog/context-engineering-for-data-agents)
