AI 老查错表？真凶藏在 dbt 文档里

导语

一位工程师给公司搭了个 MCP 服务，让 AI Agent 能自己找数、查数。服务本身一周就上线了，剩下大半时间他都卡在同一个问题上：为什么 Agent 总选错表？

答案出人意料——不在模型能力，不在检索算法，而在他自家 dbt 项目的描述文档里。这个故事背后是一个正在成型的产业判断：当 AI 开始直接消费企业数据，元数据的质量就不再是文档洁癖，而是系统能不能用的生死线。

🎯 服务一周上线，选表问题磨了一个月

先看场景。这位工程师要做的事情，如今几乎所有数据团队都在排期：给 AI Agent 接一个 MCP 服务器，让它能理解『上个季度华东区活跃用户有多少』这类自然语言问题，自己去数据仓库里找对表、写对 SQL、返回数字。

服务器本身不难写。协议现成，接口清晰，接入 dbt 模型清单、暴露查询能力，几天就能跑通 demo。

真正的时间黑洞，是那个反复出现的故障模式：Agent 选错了表。

用户问的是订单粒度的收入，它拿用户维度的表来算；用户问的是退款后的净额，它取的是未过滤的原始流水。SQL 语法全对，执行不报错，答案全错——这是最危险的错误形态，因为业务方拿到一个『看起来很自信』的错误数字。

排障到最后，他把嫌疑锁定在一个所有数据工程师都嫌麻烦的环节：dbt docs。那些写在 YAML 里的模型描述和列描述，过去是给同事看的注释，如今成了 Agent 唯一的『地图』。

据多位在做同类项目的从业者反馈，这个故障模式的优先级常被排得很低——大家默认先把 Agent 跑起来，元数据『后面再补』。结果就是 demo 惊艳、生产翻车。

这里的产业逻辑很硬：Agent 时代的数据质量，前置了一层。 过去我们说数据质量，说的是数值对不对、管道稳不稳；现在，在数值被计算之前，还有一道『选表』的质量关，而这一关完全由元数据把守。元数据错，后面全错，且错得悄无声息。

✂️ Agent 只读你描述的第一句话

第二个发现更反直觉：Agent 根本不看你精心写的大部分文档。

当这位工程师把 dbt 模型索引进搜索系统时，遇到了所有做 RAG 的人都会撞上的墙——长文本没法全量做向量嵌入，必须截断。截断之后，真正能进入检索的，只剩每个模型描述的第一行，和每列描述的前两句。

后面写的所有内容，从来没有到达过搜索。写了等于没写。

这不是 bug，是工程约束下的必然。向量库的 chunk 大小、嵌入成本、检索精度之间的权衡，决定了『开头即全部』。

这意味着文档写作的规则要彻底重写：

• 第一句话必须说清三件事：这张表是什么、粒度是什么、它不是什么。
• NULL 语义前置。如果某列因为特殊业务原因为空，必须在第一句话里讲明白——否则 Agent 会把『空』当作『没有』，直接算错。
• 长背景、历史沿革、口径演变，往后放，或者干脆放在 Agent 够不到的地方就别放。

下表是同一张表描述的两种写法，在检索系统里的实际效果差异：

有从业者私下形容这个局面：过去写文档是写给『三个月后的自己』看的，现在是写给一个没有组织记忆、只看第一句话的外包实习生看的。

判断也在这里：元数据写作正在从『文档规范』变成『提示词工程』。 第一句话就是 Agent 的 system prompt。数据团队如果不建立『首句即关键信息』的写作纪律，等于在给 AI 系统的入口处埋雷。

🤖 别让 AI 给数仓写说明书

接下来是整篇文章里最值得所有 CDO 划重点的陷阱。

场景太常见了：300 个 dbt 模型，文档缺口一堆，人手不够，于是有人提议——『让 AI 看着 SQL 把描述补了呗，几秒钟一个。』

结果是什么？user_id 的描述变成：『用户的标识符。』

这句话的信息量是零。Agent 自己就能看到列名叫 user_id，它不需要 AI 复述一遍列名。它真正需要知道的是如何使用：这个 ID 该和哪张表 join、可不可以为 NULL、它指的是玩家还是账号体系里的用户、还有哪些长得一样的 user_id 列绝对不能和它混用。

原作者的判断一针见血：一个只能读模型的 AI，只能复述模型。然后 Agent 再来读这段复述，什么新信息都得不到。整个系统陷入一个死循环——代码在向代码解释它自己。

这个陷阱为什么如此普遍？因为它在成本上极度诱人：AI 批量补文档，一晚上覆盖 300 个模型，KPI 漂亮，覆盖率 100%。但覆盖率是假指标——补出来的是语料的膨胀，不是知识的注入。真正的语义——粒度、口径、业务排除项、join 边界——从来不在 SQL 里，它在写这张表的人的脑子里。

原作者给出的结论同样直接：描述必须来自知道这张表为什么存在的人。

这里的产业逻辑值得展开一层。AI 生成的元数据还有一层隐性风险：它会把错误语义制度化。人写的坏描述，同事看了还会起疑；AI 生成的『用户标识符』配上流畅的排版，反而获得了虚假权威。当这些描述被索引、被 Agent 消费、错误答案再回流到业务决策，排查起来比没有文档更难——因为你以为你有文档。

📐 元数据治理，从成本中心变成生命线

把前面的发现拼起来，能看到一条清晰的产业脉络。

过去十年，元数据治理在多数公司里的处境是：重要，但排不上优先级。数据目录买过，血缘系统部署过，最后大多沦为合规审计的工具，业务团队写文档靠情怀和代码评审时的死缠烂打。

AI Agent 正在改变这个成本结构。

关键区别在最后一行：以前文档写砸了，有人的判断力兜底；现在 Agent 直接消费，没有人兜底。 元数据从『锦上添花的注释』变成了『系统运行的输入』。

时间线大致是这样的：

• 传统数仓时代 : 文档写给同事看，靠代码评审维持
• dbt 普及后 : docs 成为团队标准，但读者仍以人为主
• RAG 与向量检索兴起 : 元数据被截断索引，首句决定可见性
• MCP 与 Agent 落地 : 元数据成为 Agent 选表和写 SQL 的直接依据

沿着这条线，能推演出几个接下来的动作：

第一，dbt 项目的 description 需要一套面向机器的写作规范。 粒度、排除项、NULL 语义、join 边界，首句交付。这不是文风偏好，是接口规范——Agent 读的就是接口。

第二，『AI 补元数据』需要正确的用法。 AI 不是不能用，而是不能让它闭环自证。合理的位置是：人提供业务语义（这张表为什么存在、不能和什么混用），AI 负责格式化、一致性检查、检测缺失和矛盾。AI 当编辑，人当事实来源。

第三，一批围绕元数据质量的新工具位会空出来。 描述完整性检测、『首句信息密度』评估、面向 Agent 消费的元数据分级索引——这些现在都还是手工活。数据目录厂商如果不把『AI 可消费性』当核心指标，可能会被从工具链里绕过去。

一位接近多家数据平台公司的业内人士私下说，今年各家 Demo 里 Agent 查数都演示得很漂亮，差异全在客户看不见的元数据底座上——demo 用自家调好的数据，客户用自己的，高下立判。

小结

这个故事最讽刺的地方在于：让 AI 用好数据的最大瓶颈，不是 AI 不够聪明，而是人类自己都没把数据讲清楚。MCP 服务器一周就能搭好，让 Agent 选对表却要重写整个团队的文档纪律。

往前看，当 Agent 成为数据的最大消费方，元数据质量会从工程细节升格为平台竞争力——文档写得好的公司，AI 立刻能用；写不好的公司，买再强的模型也是浪费。下一轮数据基础设施的分化，可能就从第一句话开始。