AI总选错表，先查你的dbt文档

一位数据工程师搭好了 MCP 服务器，让 AI Agent 能检索并查询公司数据。演示一次跑通，但交付之后，他的时间几乎全部耗在一个问题上：Agent 为什么总选错表？排查到最后，答案不在模型，不在向量库，而在 dbt 文档。

这个案例指向一个正在被普遍低估的判断：当数据的主要消费者从人变成 Agent，你写下的每一行表描述和字段描述，才是 Agent 的真提示词。模型再强，读到的语义是错的、空的，它就注定犯蠢。

🔍 花时间的不是服务器，是选错表

瓶颈从来不在最亮眼的那个组件，而在没人愿意看的那一页文档。

这位工程师的复盘很直白：搭建 MCP 服务器本身并不难，协议是标准的，工具注册、权限控制、查询执行，都是成熟工程活。真正的时间黑洞，是搞清楚 Agent 为什么在一堆结构相似的表里，偏偏选中那张不该选的表。排查过检索参数，怀疑过嵌入模型，最后发现，答案几乎总是 dbt 文档本身。

这个现象背后有一条容易被忽略的链路变化。过去数仓的消费者是分析师和 BI 工具，人是带着业务上下文来的：知道哪张表是核心表、哪个口径是权威口径，选错了还能靠经验纠正。Agent 没有这些隐性上下文，它唯一的信息来源就是元数据。选错表，SQL 就错；SQL 错，结论就错。上游偏一格，下游全盘错。

不少正在做 AI 数据工程的人私下都有同感：问题看似出在 Agent 的推理环节，实际出在喂给它的语义质量上。这意味着数据平台的价值评估点正在迁移——从「能不能查到」，转向「能不能被正确理解」。

✂️ Agent 只读得进第一行

给检索看的文档和给人看的文档，是两种文体。

这位工程师在给 dbt 模型建索引时遇到了一个硬约束：没办法把所有描述都完整嵌入。长文本会被截断，实际进入检索系统的，只有模型描述的第一行，以及每个字段描述的前两句话。第一行之后写了什么，Agent 永远看不到。

⚠️ 这不是某个工具的 bug，而是成本结构的必然。嵌入和索引是有预算的，几万个字段、几十万字的描述，不可能全量塞进检索。这意味着文档的「首屏」决定命运，逻辑和 SEO 时代标题党抢首屏、邮件抢主题行是一回事：结论前置，否则等于没写。

由此得出的写作规则非常具体：第一句话必须说清这张表是什么、粒度是什么、它不是什么。如果某个字段因为特殊业务原因为 NULL，这个例外也要放进第一句。把铺垫和背景留在后面，Agent 一个字都收不到。

对习惯了「先铺垫、末尾给结论」的企业文档文化来说，这是一次写作范式的倒逼。为人类读者写的文档可以容忍冗长，为检索消费写的文档，废话就是噪音，噪音就是错误率。

🤖 AI写的文档，AI自己都看不懂

让 AI 给 AI 写文档，是这条路上最大的陷阱。

场景非常真实：三百个模型等着补描述，团队没时间，于是顺手让 AI 读 SQL 自动生成 YAML。产出物长什么样？user_id: Identifier of user——用户标识。这句话等于什么都没说。Agent 本来就能看到字段名叫 user_id，它真正需要知道的是怎么用：该 JOIN 到哪张表、可不可以为 NULL、它是「玩家」还是「账号」的粒度、还有哪几个形似 user_id 的字段绝不能和它混用。

一位 AI 从模型里只能复述模型，Agent 再去读这段复述，什么新信息也得不到。整个系统陷入一个死循环：代码向代码解释自己。看起来文档补齐了，语义债务一分没还。

差异有多直观，看一张表就够了：

🔁 这份对照表其实就是给所有团队的镜子：如果你的描述栏内容偏向左列，那 Agent 的每一次查数，都在浪费一次检索、烧一遍 token，最后还可能给出错口径的数字。

🧭 把描述当接口文档来写

描述不是注释，是 Agent 调用数据的接口文档。

这条判断有个关键前提：描述必须出自真正懂业务口径的人。AI 能从 SQL 里读出结构，读不出「这个字段为什么在月末为 NULL」「这张表和那张表口径差在哪」。这些信息只存在于建模者和业务方脑子里。所以语义补齐本质是一项组织工作，不是一项自动化工作。

接口文档的类比很贴切：开发者调用 API 靠文档知道参数含义、边界条件和错误码，Agent 查数靠描述知道表含义、粒度规则和禁区。文档写得差的 API 没人用，描述写得差的表，Agent 用一次错一次，用两次就被拉黑。

落到工程实践，一套「可被 Agent 消费」的描述至少要覆盖三类信息：

更进一步，描述应该进入研发流程而不是躺在文档里：改表必改描述，描述变更走评审，核心表的首行描述单独验收。把语义质量当作代码质量来管，才谈得上 Agent 可靠。

📉 语义质量，是下一个平台指标

数据平台团队的考核表，该加一行新指标了。

过去衡量数据平台，看的是管道稳定性、时效、成本。Agent 时代要加一条：语义可消费性——Agent 拿着元数据自主选表选字段的准确率。这条指标不达标，前面三条做得再好，终端体验依然是「AI 不靠谱」。这位工程师的复盘之所以有代表性，就在于它暴露了行业的一种错位：大家在 Agent 和检索层卷得热火朝天，真正决定成败的语义层却无人问津。

实践上的动作清单并不复杂：盘点现有 dbt 模型，按被检索频率排序，优先补齐核心表的首行描述；把「不许让 AI 从 SQL 自动生成描述」写进团队规范；把描述更新纳入变更管理。先做这三件事，再谈更复杂的语义层产品，性价比高得多。

往大处看，这类实践正在沉淀出一个共识：文档债务会被重新定价。原来被认为是「写给人看的补充材料」的元数据，在 Agent 成为数据消费者之后，升级成了系统正确性的第一道闸门。谁先把 dbt 文档当提示词工程来做，谁的 Agent 就先少犯蠢。

小结

检索框架会换，Agent 框架会换，模型更会一茬一茬地换，但「Agent 靠描述理解数据」这件事不会变。那句被截断后仍能存活的第一行描述，就是 Agent 眼中你的数据平台的全部门面。接下来可以预见，语义文档质量评估、描述驱动的选表能力，会从个人技巧变成数据平台的标配组件——而这一次的基础设施革命，写的不是代码，是句子。