免责声明

Apache Hamilton 是 Apache 软件基金会（ASF）孵化中的一个项目，由 Apache 孵化器 PMC 赞助。

所有新接受的项目都必须经过孵化期，直到进一步评估表明其基础设施、沟通机制和决策流程已稳定下来，达到与其他成功 ASF 项目一致的标准。

虽然孵化状态并不一定反映代码的完整性和稳定性，但它确实意味着该项目尚未得到 ASF 的完全认可。

Apache Hamilton（孵化中）是一个轻量级的 Python 库，用于构建数据转换的有向无环图（DAG）。您的 DAG 具有可移植性，无论是在脚本、笔记本、Airflow 流水线、FastAPI 服务器等任何可以运行 Python 的环境中，它都能正常运行。同时，Apache Hamilton 的 DAG 具有表达力，提供了丰富的功能来定义和修改 DAG 的执行过程（例如，数据验证、实验跟踪、远程执行等）。

要创建一个 DAG，只需编写普通的 Python 函数，并通过函数参数指定它们之间的依赖关系。如下所示，这样生成的代码既易于阅读，又始终可以可视化。Apache Hamilton 会加载这些定义并自动为您构建 DAG！

Apache Hamilton 为任何涉及数据流动的 Python 应用程序带来了模块化和结构化：ETL 流水线、机器学习工作流、大型语言模型应用、RAG 系统、BI 仪表盘等。而 Apache Hamilton UI 则允许您自动可视化、编目并监控 DAG 的执行情况。

Apache Hamilton 非常适合处理 DAG，但如果您需要循环或条件逻辑来构建大型语言模型代理或进行模拟，不妨看看我们的姊妹库 Burr 🤖 .

安装

Apache Hamilton 支持 Python 3.8 及以上版本。我们包含了可选的 visualization 依赖项，用于显示 Apache Hamilton DAG。对于可视化功能，您需要在系统上单独安装 Graphviz。

pip install "sf-hamilton[visualization]"

若要使用 Apache Hamilton UI，还需安装 ui 和 sdk 依赖项。

pip install "sf-hamilton[ui,sdk]"

如需在浏览器中试用 Apache Hamilton，请访问 www.tryhamilton.dev

为什么使用 Apache Hamilton？

数据团队编写代码以实现业务价值，但很少有资源来标准化实践并提供质量保证。无论团队规模大小，从概念验证过渡到生产环境以及跨职能协作（例如数据科学、工程和运维）仍然是挑战。Apache Hamilton 旨在在整个项目生命周期中提供帮助：

• 关注点分离。Apache Hamilton 将 DAG 的“定义”与“执行”分离，使数据科学家能够专注于解决问题，而工程师则负责管理生产管道。

• 高效协作。Apache Hamilton UI 提供一个共享界面，供团队在整个开发周期内检查结果并调试故障。

• 低摩擦的开发到生产。使用 @config.when() 在不同执行环境中修改 DAG，而不是依赖容易出错的 if/else 功能标志。Notebook 扩展可以避免将代码从 Notebook 迁移到 Python 模块时的麻烦。

• 可移植的转换。您的 DAG 独立于基础设施或编排系统，这意味着您可以在本地开发和调试，并在不同上下文中重用代码（本地、Airflow、FastAPI 等）。

• 可维护的 DAG 定义。Apache Hamilton 可以从一行代码自动构建 DAG，无论其包含 10 个节点还是 1000 个节点。它还可以将多个 Python 模块组装成一个管道，从而鼓励模块化设计。

• 表达性强的 DAG。函数修饰器是一项独特功能，可帮助您保持代码的 DRY 原则，并降低维护大型 DAG 的复杂性。其他框架往往会导致代码冗余或函数臃肿。

• 内置编码风格。Apache Hamilton DAG 是通过 Python 函数定义的，这有助于编写模块化、易读、自文档化且易于单元测试的代码。

• 数据和模式验证。使用 @check_output 装饰函数以验证输出属性，并触发警告或异常。添加 SchemaValidator() 适配器，即可自动检查类似 DataFrame 的对象（pandas、polars、Ibis 等），从而跟踪和验证其模式。

• 为插件而生。Apache Hamilton 专为与各种工具良好兼容而设计，并提供了适当的抽象层，以便您根据自身技术栈创建自定义集成。我们活跃的社区将帮助您构建所需的功能！

Apache Hamilton UI

您可以在 Apache Hamilton UI 中跟踪 Apache Hamilton DAG 的执行情况。它会自动填充包含血缘关系和追踪信息的数据目录，并提供执行可观测性，以便检查结果和调试错误。您可以将其作为 本地服务器 或使用 Docker 部署的 自托管应用 来运行。

DAG 目录、自动数据集分析和执行追踪

开始使用 Apache Hamilton UI

1. 要使用 Apache Hamilton UI，您需要安装依赖项（参见“安装”部分），然后通过以下命令启动服务器：

   hamilton ui
   

2. 首次连接时，请创建一个用户名并新建一个项目（project_id 应设置为 1）。

3. 通过使用您的用户名和项目 ID 创建一个 HamiltonTracker 对象，并将其添加到 Builder 中，即可跟踪您的 Apache Hamilton DAG。现在，您的 DAG 将显示在 UI 的目录中，所有执行操作都会被记录下来！

   from hamilton import driver
   from hamilton_sdk.adapters import HamiltonTracker
   import my_dag
   
   # 使用您的用户名和项目 ID
   tracker = HamiltonTracker(
      username="my_username",
      project_id=1,
      dag_name="hello_world",
   )
   
   # 将跟踪器添加到 Builder 中，DAG 就会被加入目录
   dr = (
      driver.Builder()
      .with_modules(my_dag)
      .with_adapters(tracker)  # 在此处添加您的跟踪器
      .build()
   )
   
   # 执行 Driver 将会记录结果
   dr.execute(["C"])
   

文档与学习资源

• 📚 请参阅 官方文档，了解 Apache Hamilton 的核心概念。

• 👨‍🏫 可以查阅 GitHub 上的示例，学习特定功能或与其他框架的集成方法。

• 📰 DAGWorks 博客 包含有关如何构建数据平台的指南和叙事式教程。

• 📺 您可以在 DAGWorks YouTube 频道 上找到视频教程。

• 📣 如需帮助或故障排除，请通过 Apache Hamilton Slack 社区 联系我们。

Apache Hamilton 与 X 相比如何？

Apache Hamilton 既不是编排工具（你可能并不需要一个），也不是特征存储库（不过你可以用它来构建一个！）。它的主要用途是帮助你组织和管理数据转换逻辑。如果你熟悉 dbt，那么 Apache Hamilton 对 Python 的作用就类似于 dbt 对 SQL 的作用。

另一种理解方式是从数据栈的不同层次来考虑。Apache Hamilton 处于资产层。它可以帮助你将数据转换代码（即表达式层）组织起来，管理变更，并对数据进行验证和测试。

更多信息请参阅我们的页面 为什么使用 Apache Hamilton？ 以及框架间的代码比较。

📑 许可证

Apache Hamilton 根据 Apache 2.0 许可证发布。详细信息请参阅 LICENSE。

🌎 社区

👨‍💻 贡献

我们非常欢迎新贡献者提出的各种大小改动！在提交拉取请求之前，请务必通过创建议题或在现有议题上留言来讨论潜在的更改。不错的首次贡献包括创建示例或与你喜欢的 Python 库集成！

如需贡献，请查看我们的贡献指南、开发者设置指南，以及我们的行为准则。

😎 使用情况

Apache Hamilton 最初是在 Stitch Fix 开发的，后来由其原作者创立了 DAGWorks Inc！该库经过实战检验，自 2019 年以来一直支持生产环境中的各类用例。

更多关于起源故事的信息。

• Stitch Fix — 时间序列预测
• 英国政府数字服务 — 全国反馈流水线（处理与分析）
• IBM — 内部搜索与机器学习流水线
• Opendoor — 管理 PySpark 流水线
• Lexis Nexis — 特征处理与血缘关系追踪
• Adobe — 提示工程研究
• WrenAI — 异步文本转 SQL 工作流
• British Cycling — 遥测数据分析
• Oak Ridge 和 PNNL — Naturf 项目
• ORNL
• 联邦储备委员会
• Joby Aviation — 飞行数据处理
• Two
• Transfix — 在线特征提取与预测
• Railofy — 编排 pandas 代码
• Habitat Energy — 时间序列特征工程
• KI-Insurance — 特征工程
• Ascena Retail — 特征工程
• NaroHQ
• EquipmentShare
• Everstream.ai
• Flectere
• F33.ai
• Kora Money
• Capitec Bank
• Best Egg
• RTV Euro AGD
• Wealth.com
• wren.ai

🤝 代码贡献者

🙌 特别感谢 & 🦟 漏洞猎人

感谢我们出色的社区及其对 Apache Hamilton 库的积极参与。

Nils Olsson、Michał Siedlaczek、Alaa Abedrabbo、Shreya Datar、Baldo Faieta、Anwar Brini、Gourav Kumar、Amos Aikman、Ankush Kundaliya、David Weselowski、Peter Robinson、Seth Stokes、Louis Maddox、Stephen Bias、Anup Joseph、Jan Hurst、Flavia Santos、Nicolas Huray、Manabu Niseki、Kyle Pounder、Alex Bustos、Andy Day、Alexander Cai、Nils Müller-Wendt、Paul Larsen、 Kemal Eren、Jernej Frank、Noah Ridge

🎓 引用

如果您使用了 Apache Hamilton，请通过以下任一方式引用我们：

@inproceedings{DBLP:conf/vldb/KrawczykI22,
  title     = {Hamilton: 一种模块化的开源声明式范式，用于数据流的高层次建模},
  author    = {Stefan Krawczyk 和 Elijah ben Izzy},
  editor    = {Satyanarayana R. Valluri 和 Mohamed Za{\"{\i}}t},
  booktitle = {第一届可组合数据管理系统国际研讨会，CDMS@VLDB 2022，澳大利亚悉尼，2022年9月9日},
  year      = {2022},
  url       = {https://cdmsworkshop.github.io/2022/Proceedings/ShortPapers/Paper6\_StefanKrawczyk.pdf},
  timestamp = {Wed, 19 Oct 2022 16:20:48 +0200},
  biburl    = {https://dblp.org/rec/conf/vldb/KrawczykI22.bib},
  bibsource = {dblp 计算机科学文献数据库，https://dblp.org}
}

@inproceedings{CEURWS:conf/vldb/KrawczykIQ22,
  title     = {Hamilton：通过广义数据流图实现数据转换中的软件工程最佳实践},
  author    = {Stefan Krawczyk、Elijah ben Izzy 和 Danielle Quinn},
  editor    = {Cinzia Cappiello、Sandra Geisler 和 Maria-Esther Vidal},
  booktitle = {与第48届非常大规模数据库国际会议（VLDB 2022）同期举办的首届数据生态系统国际研讨会},
  pages     = {41--50},
  url       = {https://ceur-ws.org/Vol-3306/paper5.pdf},
  year      = {2022}
}

📚 基于或为 Apache Hamilton 构建的库

• Hypster - 超参数管理
• DSP Decision Engine - 决策树
• NaturF - 用于天气预报的数据转换库
• WrenAI - RAG
• FlowerPower - Apache Hamilton 的调度器

Apache Hamilton 快速上手指南

Apache Hamilton 是一个轻量级的 Python 库，用于构建可移植且表达力强的数据转换有向无环图（DAG）。它通过普通的 Python 函数定义依赖关系，自动构建 DAG，适用于 ETL、机器学习工作流、LLM 应用及 BI 仪表盘等场景。

环境准备

• 操作系统：支持所有可运行 Python 的系统（Linux, macOS, Windows）。
• Python 版本：要求 Python 3.8 及以上（推荐 3.10 - 3.14）。
• 前置依赖：
  • 若需使用 DAG 可视化功能，需单独安装系统级工具 Graphviz。
  • 若需使用 Apache Hamilton UI 进行目录管理和执行监控，需额外安装相关依赖包。

安装步骤

建议使用国内镜像源（如清华源或阿里源）加速安装。

1. 基础安装（含可视化支持）

安装核心库及可视化可选依赖：

pip install "sf-hamilton[visualization]" -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：安装完成后，请确保系统已安装 graphviz 二进制文件，否则可视化功能无法使用。

2. 完整安装（含 UI 支持）

若需要使用 Apache Hamilton UI 进行项目追踪和调试：

pip install "sf-hamilton[ui,sdk]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Hamilton 的核心理念是：代码即 DAG。只需编写带有明确参数依赖的普通 Python 函数，Hamilton 会自动解析并构建执行图。

1. 定义 DAG (my_dag.py)

创建一个 Python 文件（例如 my_dag.py），定义数据转换逻辑。函数的参数名即为该节点所依赖的其他节点名称。

# my_dag.py

def A() -> int:
    """根节点，不依赖其他节点"""
    return 1

def B(A: int) -> int:
    """依赖节点 A"""
    return A + 1

def C(A: int, B: int) -> int:
    """依赖节点 A 和 B"""
    return A + B

2. 执行 DAG

使用 driver 加载模块并执行。你只需指定想要计算的最终输出节点名称，Hamilton 会自动解析依赖链并执行必要的函数。

from hamilton import driver
import my_dag

# 初始化 Driver，加载包含函数定义的模块
dr = driver.Builder().with_modules(my_dag).build()

# 执行 DAG，请求计算节点 "C"
# Hamilton 会自动先执行 A，然后 B，最后计算 C
result = dr.execute(["C"])

print(result)
# 输出示例：{'C': 3}

3. (可选) 可视化 DAG

如果已安装 Graphviz，可以生成 DAG 图像以检查依赖结构：

# 生成并显示 DAG 图像
dr.visualize_execution(
    ["C"],          # 目标输出节点
    {},             # 输入参数（本例无需外部输入）
    {"format": "png"} # 输出格式
)

4. (可选) 接入 Hamilton UI

若需追踪执行记录和查看数据血缘，可配置 HamiltonTracker：

from hamilton import driver
from hamilton_sdk.adapters import HamiltonTracker
import my_dag

# 配置追踪器（需先在 UI 中创建项目和用户）
tracker = HamiltonTracker(
    username="my_username",
    project_id=1,
    dag_name="hello_world",
)

# 将追踪器添加到 Builder
dr = (
    driver.Builder()
    .with_modules(my_dag)
    .with_adapters(tracker)
    .build()
)

# 执行后，结果将自动同步至 UI
dr.execute(["C"])

启动 UI 服务器命令：

hamilton ui