数据管道智能体(dbt 与 Airflow)

12 分钟读完

U33
实战手册 · 编码与计算机操作智能体

数据管道智能体:测试套件不是裁判,输出 diff 才是。

一处能编译、能通过全部测试、却悄悄把昨天 4% 的行丢掉的管道改动,是这里的常规失效,而你写过的任何一条测试都没在找它——因为一次转换的正确性活在它产出的那些行里,不在产出它们的那段代码里。请围绕「把改动过的模型与生产状态做行级 diff」来造这个智能体,把合并闸门设在「差值已被解释」上,并接受基准给你的那道自主度天花板:在唯一一份已公开的仓库级 dbt 基准上,跑在参考框架上的最强前沿模型只解出约三分之一的任务。

步骤 1从实测的天花板出发,而不是从演示出发。

Text-to-SQL 看上去快被解决了,而仓库级的管道工作并没有。在单条查询的基准 BIRD 上,截至一份 2026 年 10 月的提交,已公布的测试集执行准确率最高为 83.40%,而其标明的人类基线是 92.96%。再看 Spider 2.0-DBT,作者把它描述为「a comprehensive code generation agent task that includes 68 examples」,要求模型「understand project code, navigating complex SQL environments and handling long contexts」。按 2026 年 11 月 18 日取回的那份已公布排行榜,专门打造的商业智能体达到 65.6,跑在该项目自家参考框架上的最强前沿模型落在 35.29 到 39.71 之间,而配上稍旧模型的朴素参考智能体是 2.94 到 14.70。

把这两行并起来读,设计就随之而来。用通用模型,大约三个仓库级 dbt 任务里只有一个能端到端完成,所以这个智能体是个绘图员,而你的闸门才是产品。这与补丁生成与测试驱动回路是同一种姿态,但有一处差别改变了一切:一个代码智能体可以自己跑测试、因而知道自己有没有成功。一个管道智能体做不到,因为能告诉它答案的那个东西,是一张它不被允许去建的表。

排行榜注意:Spider 2.0 其他设定下那些 90% 以上的条目,是厂商自行提交的定制系统,不是开箱即用地跑一个前沿模型;而该项目提示,随着它持续核对评测指标,分数「may change slightly over time」。请用参考框架那几行来回答「一个通用模型能替我做到什么」。

步骤 2给这个智能体一次延迟(deferred)构建,否则它什么都跑不起来。

第一个实际问题是:一个 dbt 模型离了它的上游就毫无意义,而智能体不可能为了测一处改动去重建一座 2,000 个模型的数仓。deferral 正是解决这件事的机制,也是最该放进智能体框架里的那一个参数。dbt 文档把它描述为让你能够「run a subset of models, tests, or functions in a sandbox environment without having to first build their upstream parents」,而那条解析规则值得原文照引,因为正是它让行为可预测:

# When --defer is enabled, dbt resolves ref() using the state
# manifest instead, but ONLY if:
#   1. the node isn't among the selected nodes, AND
#   2. it doesn't exist in the database (or --favor-state is used)

dbt build --select state:modified+ \
          --defer --state ./prod-artifacts

这条命令里有三处在发挥作用。用 dbt build 而不是 dbt run,因为 build 会按 DAG 顺序「will: run models, test tests, snapshot snapshots, seed seeds, build user-defined functions」——一道闸门而不是四道。用 state:modified+,其中尾部的 +「includes the resource itself and all its descendants」,于是智能体被迫把自己这处改动的全部下游都建出来,而不是只建它动过的那个文件。以及把 --state 指向一份来自此前生产调用的 manifest,因为 deferral「requires both --defer and --state to be set」。

有两种失效模式,要在框架里提前堵住、而不是留到评审。第一,文档自己的告警:用了 deferral 之后「you may be selecting from production datasets, development datasets, or a mix of both」,而如果你「apply environment-specific limits in development but not in production, you may select more data than expected」——于是「做过抽样的开发环境 + 一个延迟解析的父节点」就是跨着两个人群在做比较。第二,绝不要把 --state 指向 target/:dbt 在解析期间会覆写 target/manifest.json,于是在变更检测去读它之前,先前的状态已被抹掉,而智能体会拿到一句自信的「没有模型被改动」。在可用的地方,dbt clone 是替代方案——它创建真实对象,在 Snowflake、Databricks 与 BigQuery 上是零拷贝,这让你能在 dbt 之外测试下游消费方——代价是 deferral 那条路径不必花的算力。

步骤 3状态比较是不完整的,而 dbt 把这件事写在了文档里。

一个相信 state:modified 能枚举出自身改动影响半径的智能体,一定会漏掉一些情形,而厂商把漏掉哪些都记录了下来。这对智能体比对人更要紧,因为人类评审者会注意到「CI 只建了两个模型,而我预期是九个」;智能体读到「2 of 2 OK」就当成功了。

  • 那些子选择器告诉你完整检查覆盖了什么:state:modified.body、.configs、.relation、.persisted_descriptions、.macros 与 .contract。作为「这个面有多大」的文档很有用;state:modified 包含它们全部,外加若干按资源类型而定的判据。
  • 变量会切断血缘。引那页注意事项:「If a model uses a var or env_var in its definition, dbt is unable to identify that lineage in such a way that it can include the model in state:modified」。一个改了某变量取值的智能体,改的是变更检测看不见的行为。
  • 元数据是被刻意排除的。tags 与 meta 的改动不触发 state:modified,「because these fields don't affect how dbt materializes the resource」。这是对的;而如果你的编排是以 tag 为键的,这就是个意外。
  • 误报有一个专门的开关。把 state_modified_compare_more_unrendered_values 设为 true,以「reduce false positives during state:modified selection due to env-aware logic」——之后还要用 dbt 1.9 或更高版本重建那个 state 目录,否则比较会继续产生误报。
  • 改宏的波及面很宽。「dbt will mark modified any resource that depends on a changed macro, or on a macro that depends on a changed macro.」一个重构了共享宏的智能体,等于选中了项目的大半——这既是对的,也是一次失控的构建,如果你没给它设上限。

那一页以一句值得摆在「想要无人值守管道智能体」的人面前的坦白收尾:「State comparison is complex. We hope to reach eventual consistency between all configuration options」。请把选择结果当作对影响半径的一份尽力而为的提示,而不是它的证明。

步骤 4闸门是一次行级 diff,而多数人伸手去拿的那个开源工具已经归档了。

整个论点一句话讲完:智能体给出的 diff 是代码 diff,而你的闸门必须是输出 diff。两个模型可以只差一个 LEFT JOIN,却产出完全相同的行数、而其中 3% 的值变了;或者值完全相同、却掉了 8% 的行——而只有对已建成关系的比较才区分得出这两者。

在围着工具做设计之前,先核一下它的状态。data-diff——至今多数搜索结果仍指向的那个——已于 2024 年 5 月 17 日归档;它 README 的第一行写着「As of May 17, 2024, Datafold is no longer actively supporting or developing open source data-diff」,而它最后一次 PyPI 发版就在同一天。截至 2026 年 11 月,当前可用的是:

  • dbt-audit-helper(包名 audit_helper,0.4.0)——在数仓内跑的宏,不需要额外服务。compare_and_classify_query_results 生成「a row-by-row comparison of two queries, as well as summary stats of added, removed, identical and modified records」,返回取值为 identical、modified 或 added 的 dbt_audit_row_status 并附计数。它要求 primary_key_columns,而这才是真正的前置条件:一个没有可靠主键的模型,任何工具都无法对它做行级 diff——那是一处建模缺陷,应该先让智能体去修。quick_are_queries_identical 是那道便宜的前置检查——「calculated relatively quickly compared to other macros in this package」——而 compare_which_query_columns_differ 把损伤定位到某一列。注意 compare_queries 与 compare_relations 现已被标为遗留,推荐改用那几个分类宏。
  • Recce(1.72.0,2026 年 11 月 11 日,Apache-2.0)——「Environment diff tool for dbt」,为 PR 评审而建,提供 Profile、Value、Top-K 与 Histogram 四种 diff,外加并排的查询 diff 与列级血缘。它需要两个已准备好的环境来做比较,这与 deferral 的前置条件相同。其托管层可以在检查被批准之前阻止 PR 合并,而那正是你想要的闸门形状。
# the merge gate, in the order it should run
quick_are_queries_identical()      # cheap: identical? merge.
compare_row_counts()               # rows moved? by how many?
compare_which_query_columns_differ()  # which column changed?
compare_and_classify_query_results()  # added/removed/modified, by key

# the agent must PREDICT this delta in the PR description.
# An unpredicted non-zero delta is the review. Not the diff.

最后那一行,是值得从笔记本与数据科学智能体那儿偷来的运营小花招:要求智能体在 diff 跑之前先说明,它预期会有多少行发生变动、以及为什么。预测准了,就是它理解了自己这处改动的有力证据。而任何量级的未被预测到的差值,才是人该去看的东西——它是一条比代码好得多的审阅队列。

步骤 5有两道闸门在数仓被碰到之前就会触发——两个都用上。

做 diff 既贵、又跑得晚。dbt 有两项功能能更早、更便宜地让智能体的改动失败,而且它们抓的是不同类别的错误。

模型契约(model contracts)把输出形状变成一份声明过的接口。设上 contract: enforced: true 之后,dbt 会有两处不同:它会跑「a 'preflight' check to ensure that the model's query will return a set of columns with names and data types matching the ones you have defined」,并且会把这些名字、类型与约束写进它提交的 DDL。对智能体而言要紧的后果是:删掉一列、或改掉某个已有列的类型,「is considered a breaking change, and will raise an error」——于是智能体最常尝试的那类破坏性重构,压根到不了数仓。有两条限制要知道。契约对所有列生效,所以要强制一列就得声明每一列;而在那些约束里,「most platforms only enforce not_null」。它们在 Python 模型、物化视图、ephemeral 模型、source、seed 与 snapshot 上也都不支持。

单元测试(dbt 1.8 及以后)是为逻辑设的闸门。文档把界线划得很准:data test「could only be executed after building a model」,而单元测试「allow you to validate your SQL modeling logic on a small set of static inputs before you materialize your full model in production」。这恰恰是智能体需要的那个回路——一个它能自己跑、几秒就有结果、不需要数仓的裁判。dbt 自己关于「什么时候它最划得来」的建议,读起来就像一份「智能体会错在哪」的清单:正则、日期运算、窗口函数、分支很多的 case when、截断,以及「prior to refactoring the transformation logic」。注意 dbt Labs 建议只在开发与 CI 中跑单元测试,因为输入是静态的,在生产里跑纯属白烧算力。

要求智能体先写单元测试、把 fixture 的行一一列明,并且在改动之前先展示它在旧模型上是失败的。一条事后针对新逻辑补写的单元测试,断言的是「代码做了代码所做的事」。而事先写出来的那条,是这条管道里唯一把意图编码进去的产物。

步骤 6Airflow 隔离的是编排器,从来不是副作用。

转换改对之后,智能体还得去改那个调度它的东西,而在这里,人们默认存在的那个沙箱并不存在。Airflow 3.4.0 在任何 tasks 子命令上都没有 --dry-run。airflow tasks test 真正承诺的东西很窄,而 CLI 自己的帮助文本是对它最清楚的陈述:「Test a task instance. This will run a task without checking for dependencies or recording its state in the database.」它跳过的是依赖检查与元数据库状态。算子的代码是真跑的,对着这个环境里握着的任何连接去跑——所以一个「在测试」某个会往某个桶里写、或会调某个 API 的任务的智能体,是真的往那个桶里写了、也真的调了那个 API。

dag.test() 在 DAG 层级做的是同一笔交易。文档说它「executes a real Dag run」,需要一个已初始化的元数据库、以及一个 Airflow 序列化得了的 DAG;而最佳实践那一页直言「that is an integration test… not a substitute for the unit tests」。它唯一的隔离旋钮是 mark_success_pattern,会把匹配某个 task_id 模式的任务自动判成成功——实际用途是跳过传感器与清理步骤。这意味着真正的隔离必须来自环境、而不是来自命令:给智能体一份只能触达草稿数据集的凭证,并把每一次任务调用都当成一次写入。这就是试运行与预览那个问题,只不过预览这一半缺席了;也正因如此,面向智能体的预发环境是前置条件,而不是锦上添花。

Airflow 3 有两处改动,改变了智能体能安全碰什么。Asset 取代了 dataset,而基于 asset 的调度现在是一等公民:任务通过 outlets 把某个 asset 标记为已更新,但「Airflow marks an asset as updated only if the task completes successfully」,而消费方 DAG 只有在它所列的全部 asset 都至少被更新过一次之后才运行。一个往 schedule 列表里加了个 asset 的智能体,加进去的是一个 AND 条件,而结果是一个此后永不触发的 DAG。还要注意 3.4.0 改了默认值:单 asset 的调度与 asset 的 OR 表达式「now create one Dag run per event instead of consuming all queued events in one run」,可以用 batch_asset_events=True 恢复——这是一处会无声地把运行次数、因而把成本成倍放大的行为变更。

DAG bundle 与版本化决定了「运行途中的一次改动」是否安全。bundle 让「a task using a specific version of the Dag bundle」能够「run the same code for the whole run, even if the Dag is updated mid-way through the run」——但只有部分 bundle 做版本化。Git bundle「does support versioning」;而 local、S3、GCS 与 Azure Blob 这几种 bundle 明确「do not support versioning of the bundle, meaning tasks always run using the latest code」。于是在 local 或对象存储的 bundle 上,一个在某次运行进行中合并了改动的智能体,是在那次运行脚下把它的代码换掉了。如果要允许智能体无人值守地合并 DAG 改动,那个 bundle 必须是 Git 的那种。

以上一切都假设这条管道的写入是可重复的。通常并不是:一次部分完成的运行已经装载了一批行,而重跑它会再装一遍。请在给出自主度之前先把幂等性落定——构造见幂等与重试,到了需要它的那天见修复智能体已经做下的事,而修复所要求的那次回填见批量与回填运行。相关阅读:模式那一侧见数据库迁移智能体,回路形状见CI 修复智能体,而这一切下游的消费方见数据分析智能体。