# 凌晨 2 点一次重试，可能让 AI 助手的数据翻倍

> Airflow 要求任务无论运行多少次结果都相同，这条四任务 ELT 管道按此设计。

原文: https://fdetimes.net/zh/guides/idempotent-nightly-airflow-pipeline-ai-assistant/

Airflow 的最佳实践文档里有一句话，值得打印出来贴在屏幕旁：任务失败时 Airflow 可能会重试，因此无论运行多少次，任务都必须产生**相同的结果**。这听起来理所当然，却决定了下面整条管道的设计方式。

设想这样一个场景：客户有一个 AI 助手，基于工单和产品文档回答客服人员的问题。

数据需要每晚刷新。假设 load 任务在凌晨 2 点重试，把 1,000 条工单变成了 2,000 条。第二天早上，助手引用重复内容、数错数量，用户对它的信任随之下降。

本指南将演示如何搭建这条管道，让它可以安全地重跑任意次数。AI 助手只能根据提供给它的数据作答。想成为前线部署工程师（FDE），这项技能值得在去客户现场之前先练熟。

## 要搭建什么？

Airflow 是一个用于构建和运行工作流的平台。每个工作流表示为一个有向无环图（DAG），由多个任务（Task）组成。DAG 定义任务之间的依赖关系，依赖关系又决定任务的执行顺序。

本指南中的 DAG 包含四个依次执行的任务。`extract` 拉取恰好一天的工单，`load` 把原始数据推送到远程存储，`transform` 对数据做规范化，`refresh_index` 刷新助手读取的知识源。先加载原始数据、再做转换，这就是 ELT：原始数据先落到中心存储，之后再规范化。

动手之前，需要一个可用的本地 Airflow 环境、基础的 Python 能力，以及一个 S3 类的远程存储。下面的代码是用于说明设计思路的**简化版本**。除 `schedule` 外，导入路径、Operator 名称和参数在不同版本间有差异，请对照已安装 Airflow 版本的文档核实。

## 第 1 步：为什么 DAG 文件必须轻量？

Airflow 的调度器既要按计划触发工作流，又要把任务交给执行器。为此，它必须读取（解析）DAG 文件。Airflow 文档说得很明确：DAG 文件的顶层不得访问数据库、不得做繁重计算，也不得发起网络调用。

```python
# 错误：调度器每次解析文件时都会执行这条查询，而不是在任务运行时执行
rows = source_db.query("SELECT * FROM tickets")

# 正确：所有 I/O 都放在函数内部，只在任务执行时运行
def extract(run_date: str):
    ...
```

**检查：**打开 DAG 文件，从头读到尾。除了 import、常量声明和函数定义，不应有任何一行访问数据库或 API。

## 第 2 步：只拉取一天的数据

Astronomer 的文档建议，尽可能把管道拆成增量抽取和增量加载。这样出错时，只需重新处理受影响的数据。对每晚同步来说，最自然的单位就是一天。

```python
# sync_utils.py：纯 Python 逻辑，无需 Airflow 即可测试
def extract_window(run_date: str) -> tuple[str, str]:
    return f"{run_date} 00:00:00", f"{run_date} 23:59:59"

def raw_path(run_date: str) -> str:
    # "acme-raw" 这个 bucket 只是示例
    return f"s3://acme-raw/tickets/dt={run_date}/part.jsonl"
```

关键在于，数据窗口按**本次运行的日期**计算，而不是按“现在”计算。今天重跑 10 月 7 日的任务，拉取的仍然恰好是 10 月 7 日的工单，不会混入 10 月 8 日的数据。

**检查：**在两个不同时间分别调用 `extract_window("2026-10-07")`，结果必须完全一致。

## 第 3 步：替换写入，而不是追加

回到 1,000 条工单变成 2,000 条的例子。如果 `load` 往一张共享表里追加数据，每次重试都会多出一份副本。如果 `load` 整体替换恰好 `dt=2026-10-07` 这个分区，那么无论任务运行一次还是三次，该分区都是 1,000 行。

```python
def load(run_date: str, rows: list[dict]):
    # storage 是一个假想的远程存储客户端（S3 或同类服务）
    storage.put(raw_path(run_date), rows, overwrite=True)
```

数据必须写到远程存储，不能留在本地磁盘，因为在 Airflow 中，每个任务可能运行在不同的机器上。`extract` 在机器 A 上写进 `/tmp` 的文件，等 `transform` 在机器 B 上运行时根本不存在。Airflow 文档不建议把文件或配置存放在本地文件系统，并建议把大数据量放到 S3 这类存储中。

**要点:** 好的任务以运行日期为输入，只整体替换当天的那一个分区，因此重跑只会重现相同的结果。

**检查：**写一个测试，用同一个 `run_date` 调用两次 `load`，然后统计行数。如果行数翻倍，说明任务还不是幂等的。

## 第 4 步：转换数据并刷新助手的数据源

`transform` 从 `raw_path(run_date)` 读取数据，做清洗（去掉空字段、统一格式），再把结果写入同样按日期划分的“干净”分区。随后，`refresh_index` 按同一原则更新 AI 助手查询的知识源：替换当天的数据，而不是插入重复记录。

据 Astronomer 介绍，幂等的 DAG 和任务能缩短故障后的恢复时间，并防止数据丢失。在客户现场，好处很具体：数据源团队说刚修复了 10 月 5 日的问题，只需重跑那一天，而不必清空一切、从头重新同步。

## 第 5 步：把运行时间定在凌晨 2 点

调度通过 DAG 的 `schedule` 参数设置，可以是 cron 表达式、`timedelta` 或预设值。每到调度时间，Airflow 都会创建一个对应的 Dag Run，并保存在后端数据库中。

```python
# nightly_sync.py：简化骨架，请对照所用版本核实 import
with DAG(
    dag_id="nightly_assistant_sync",
    schedule="0 2 * * *",   # cron：每天凌晨 2 点
    start_date=datetime(2026, 10, 1),
) as dag:
    extract_task >> load_task >> transform_task >> refresh_index_task
```

第 2 步和第 3 步中的函数应从当前 Dag Run 获取 `run_date`，而不是读取系统时钟。任务读取 Dag Run 日期的方式因 Airflow 版本而异，请查阅已安装版本的文档。

所有幂等性都建立在这一选择之上：重跑某个 Dag Run，处理的恰好是该 Dag Run 的日期。

**检查：**第一晚运行后，打开 Airflow UI，确认出现了一个新的 Dag Run，且四个任务全部成功。然后手动重跑同一个 Dag Run，确认行数没有变化。

## 客户现场常见的三个错误

最常见的错误是用“当前时间”计算数据窗口，例如 `WHERE updated_at > now() - 1 day`。任务准时运行时没问题，可一旦在早上 9 点重试，窗口就已偏移，数据会丢失或重复，而且不会报任何错。

第二个错误是在顶层放重逻辑，通常是因为有人想“从数据库取出表清单，动态生成任务”。第三个错误是把中间文件写到本地磁盘：在笔记本上运行正常，一到客户的多 worker 环境就出问题。

## 从笔记本到客户现场

本指南中的管道只是数据工程的一小部分。IBM 对数据工程的定义是：设计和构建用于大规模收集、存储和分析数据的系统。

FDE 岗位描述里提到“数据管道”“Airflow”或“与客户系统集成”时，真正想问的是：你能否在客户的真实系统上交付这一部分。

所以简历上不要只写“用过 Airflow”。要写清楚：你设计了一条按日期分区的增量管道，可以重跑任意单日而不产生重复数据。这句话说明你理解客户真正担心的事：一个晚上出错，第二天早上用户就会看到助手给出错误答案。

第一天到客户那里，不要急着问“用哪个模型？”。先问：“如果今晚的任务失败了，明天早上怎么重跑？”

**本周动手试试:**

- 编写 raw_path(run_date) 函数，再写一个连续调用两次 load 的测试，确认行数保持不变
- 检查一个现有的 DAG 文件（自己的或团队的），划掉所有放在顶层的数据库访问和网络调用
- 在简历中加一行描述你的管道，按这个公式写：调度方式、如何拆出增量部分、失败后如何重跑

## 信源

- [Airflow Overview (Apache Airflow docs)](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/overview.html)

- [Cron and Time Intervals (Apache Airflow docs)](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html)

- [Best Practices (Apache Airflow docs)](https://airflow.apache.org/docs/apache-airflow/stable/best-practices.html)

- [DAG writing best practices (Astronomer Docs)](https://www.astronomer.io/docs/learn/dag-best-practices)

- [What is data engineering? (IBM Think)](https://www.ibm.com/think/topics/data-engineering)
