FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 一位任职于语义层产品公司的作者认为,生产环境中的 Text-to-SQL 主要败在语义而非语法。请在自己的数据上验证这一说法。
  • 业务定义还模糊时就把智能体丢进杂乱的数据里,只会得到错误答案。真正的价值在于构建并持续完善语义层。
  • Vercel 的智能体在删掉大部分工具后依然运行良好,因为它的语义层早已文档完备。
堆叠柱状图:智能体报告的 9 月收入总额 5 亿越南盾,由财务部门认可的 4.6 亿、已取消订单 3000 万和退款 1000 万三部分组成。
SUM(amount) 查询运行无误,却把已取消订单和退款也算了进去,因此智能体报告 5 亿,而财务只认可 4.6 亿。来源:文中的假设示例(零售连锁企业,9 月)。

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

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

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

开始之前需要准备什么?

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

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

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

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

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

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

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 为备注。)

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

这里的描述是:统计期内未取消订单的收入,减去这些订单的退款。备注写明统计期以订单的 created_at 为准,且 orders 和 refunds 必须分两个查询分别求和。该指标的标准 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。最简单的路径是借助语义层:问题匹配到哪个指标,就只取该指标声明的那几张表。

# 伪代码,已简化
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,就优先使用。

# 伪代码,已简化
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 聊天机器人”,而要写明你与业务方商定了多少个指标定义、测试集有多少道题、正确率提升了多少。

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

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 3: AI 应用robots.txt 不是客户网页 Agent 的许可证演示之后,403 错误、对不上论点的引用,还有追问爬取授权的法务团队接连出现。