AI选错表，锅不在模型在文档

企业里跑AI Agent查数，最后卡住大家的不是大模型，而是一行没人认真写的dbt描述。

这是最近数据圈里被反复验证的一个判断：当你把企业数据开放给AI Agent，决定它能不能用对的表、 join 对的列的，不是模型的推理能力，而是你数据仓库里那些三年没人更新过的元数据文档。一位亲手给公司搭了 MCP 服务器的工程师，把踩坑过程公开之后，圈内流传的一句话是——『Agent选错表，别急着换模型，先去看看你的dbt文档写成了什么样。』

这句话的分量，比很多人想象的要重。

🔍 真正的工作量，不在MCP服务器上

故事很简单：这位工程师要让公司内部的AI Agent能自主找到数据、发起查询，于是搭了一个 MCP 服务器作为Agent与数仓之间的通道。

按理说，工程难点应该在这里——协议对接、权限控制、SQL执行、结果回传。但事后复盘，他花了最多时间的地方，是一个看起来『不性感』的问题：为什么Agent总是选错表？

排查到最后，答案几乎每次都指向同一个地方：dbt docs，也就是那些伴随数据模型一起提交的YAML描述文件。

这不是个例。随着 Agent 查数成为主流场景，数据团队开始发现一个反直觉的事实：过去元数据文档是『给人看的、可以敷衍的』，因为看文档的分析师脑子够好，能容忍模糊表述；而现在文档的第一读者是检索系统和LLM，它们不会脑补，你写什么它就用什么。

产业逻辑随之改变了一层：元数据不再是数据平台的附属品，它就是Agent调用数据的API契约。 过去你觉得文档写得好坏只影响新人上手速度，现在它直接决定Agent回答的对错率。数据治理从『合规成本』变成了『AI可用性投资』，这是这轮Agent浪潮里最实在的变量之一。

Agent查询链路其实很清楚：

其中C和D两步，完全依赖元数据的质量。索引里的文档写得含糊，后面每一步都在放大误差。

⚠️ 搜索会截断，所以首句就是一切

第二个发现更技术、也更致命：Agent只能看到你描述的开头部分。

这位工程师在为 dbt 模型建检索索引时发现，文本没法全量嵌入——长文本会被截断。实际生效的只有：模型描述的第一行，以及每个列描述的前两句话。后面写再多的补充说明，根本进不了检索，对Agent来说等于不存在。

这意味着写文档的方式要彻底改：

• 第一句必须说清这张表是什么、粒度是什么、它不是什么；
• 某个列有特殊的NULL逻辑？必须在第一句里讲出来；
• 任何『详见下文』『另外需要注意的是』式的写法，都是在给Agent埋雷。

这是一套全新的写作纪律。老数据团队写文档的习惯是开头铺垫业务背景、中间讲口径演进、最后附注注意事项——对人类读者友好，对检索系统灾难。

对比一下两种写法的差距：

左边那种描述在人类团队里混了很多年没人出事，右边才是Agent时代的基本盘。据多位做过类似改造的数据平台负责人私下反馈，把存量模型的描述按『首句要点化』重写一遍之后，Agent选错表的比例出现肉眼可见的下降——这也是为什么有人开始把这项工作称为『面向检索的提示词工程』。

判断很直接：元数据写作正在变成一门手艺，它的验收标准不是『文档齐不齐』，而是『Agent的检索命中率』。未来数据平台的SLA清单里，大概率会多出一条：元数据检索可用性。

🚫 最大的陷阱：让AI从SQL反写文档

如果说前两条是技术细节，那这一条就是圈内公认的『头号大坑』。

场景你一定熟悉：手里有300个 dbt 模型，文档欠账一大堆，人力又不够。怎么办？很自然的想法——让AI读SQL，自动生成YAML描述。看起来是标准的降本增效。

结果是什么？你得到的是 user_id：用户的标识符 这种句子。

这话等于没说。Agent本来就能看到这个列叫user_id，它真正需要知道的是：这个ID该和哪张表join、能不能为NULL、它是『玩家』还是『账号』、绝对不能和哪些别的user_id混在一起。这些信息不在SQL里，只在业务的人脑子里。

问题的本质是一个自我指涉的循环：AI读模型生成的描述，只能复述模型本身；Agent再去读这段描述，学不到任何新东西。用原作者的话说——『代码在向它自己解释它自己』。

看这张象限图就很清楚：所有『从代码到代码』的自动化，都挤在左下角。真正有价值的文档，必须包含模型本身无法推导出的信息——业务语义、使用禁忌、历史口径。这些只能来自懂业务的人。

所以合理的分工应该是：AI做草稿和格式化，人做语义判断。让AI把工程师口述的业务要点整理成规范的YAML结构没问题，但『该join哪张表』『为什么这里允许NULL』这类判断，不能外包给模型。

一位做过大规模元数据重写的数据负责人私下吐槽得干脆：『用AI写文档省下的时间，会在Agent出错排查时加倍还回去。』

📈 从给人看的文档，到给Agent用的接口

把这几个发现串起来，能看到一个正在发生的结构性变化。

过去十年，数据平台的建设重心是一条清晰的链路：建模 → 编排 → 质量 → 目录。元数据管理在整个链路里长期扮演『合规需要』的角色，投入有限、优先级靠后。真正的原因是：数据的消费者是人，而人会问、会猜、会回头找人对齐。

现在消费者换成了Agent。它的特点是非交互或弱交互——大部分场景里它不会回头问你『这张表到底是什么口径』，它只根据检索到的描述直接生成SQL。描述里的每一个模糊点，都会变成一次错误的查询。

推演下去，几个变化值得押注：

第一，元数据工具的价值重估。 数据目录、语义层这类过去『叫好不叫座』的产品，会因为Agent的普及获得真实付费理由——它们不再是治理部门的报表，而是Agent的取数地图。

第二，『描述即提示词』成为新的工程岗位。 就像当年Prompt Engineering从边缘技巧变成正经技能一样，为机器读者写作的元数据工程，会从dbt best practice的注脚，变成数据团队的核心工种。

第三，文档欠账成了Agent落地的隐形门槛。 很多公司会发现，Agent项目的瓶颈不在算力也不在模型，而在那300个模型的YAML到底有多少年没更新过。据圈内人观察，已经有人在Agent立项前先做一轮『元数据体检』，把这个前置项写进排期。

一句话概括这个转向：过去文档是给来的人看的路标，现在是给机器执行的合同。 合同写得含糊，违约的是Agent，买单的是业务。

小结

这轮Agent浪潮里，最被低估的资产不是算力，也不是向量库，而是数据团队手里那套描述质量过关的元数据。MCP服务器半天就能搭好，但『Agent为什么选错表』这个问题，答案永远写在文档的首句里。对数据团队的建议很朴素：别急着接Agent框架，先把元数据按机器读者的标准重写一遍——这是当下ROI最高的一笔AI投资。