如何接入自己的气象模型:Earth2Studio自定义Prognostic模型扩展开发完整教程

原创2026-10-13 22:34:491,444 阅读
文章标签:人工智能大模型模型推理服务科学计算深度学习

如何接入自己的气象模型:Earth2Studio自定义Prognostic模型扩展开发完整教程

Earth2Studio(Earth2Studio 自定义 Prognostic 模型扩展开发)是 NVIDIA 开源的深度学习气象/气候 AI 工作流框架,它内置了 FourCastNet、Aurora、GraphCast 等主流 AI 天气模型。但真正让它在科研和生产中脱颖而出的,是扩展优先(Extension First)的设计理念——你可以用自己的深度学习模型替换掉框架中的任意一环。本教程将以最少的代码,手把手教你接入你自己的模型,实现一个自定义 Prognostic(预报)模型,并直接跑进 Earth2Studio 的标准工作流。

🎯 学完本文你将掌握:Prognostic 模型的 5 个必备接口、坐标系统(CoordSystem)的约定、create_iterator 时间积分迭代器,以及如何零改动地把自定义模型塞进 run.deterministic 工作流。


一、什么是 Prognostic 模型?为什么自定义它

在 Earth2Studio 中,模型按功能分为三类组件:

组件类型 目录 职责 典型用途
Prognostic(预报模型) earth2studio/models/px/ 时间积分:给定当前大气状态,自回归预测未来状态 中短期天气预报
Diagnostic(诊断模型) earth2studio/models/dx/ 从预报场推导衍生变量(降水、风速等) 降尺度、后处理
Data Assimilation(同化模型) earth2studio/models/da/ 融合观测更新初值 数值同化

Prognostic 模型是工作流的心脏:给定某一时刻的大气场(如 10 米风),它自动向前滚动(rollout)预测下一个时间步,通常一步推进 1~6 小时。如果你训练了一个自己的 AI 天气模型(无论 CNN、Transformer 还是 U-Net),只要把它封装成 Earth2Studio 的 Prognostic 接口,就能直接复用框架里的数据源、IO 后端、批量推理、检查点恢复等全部能力。

官方接口定义在 earth2studio/models/px/base.py,完整的组件说明可参考用户指南 docs/userguide/components/prognostic.md。


二、快速开始:接入你自己的模型只需 5 个方法

好消息是:Prognostic 接口非常简洁。一个合格的自定义模型只需要提供以下 5 个 API(无需强制继承基类,它是一个 Protocol):

方法 作用 一句话说明
input_coords() 声明输入坐标系统 告诉框架"我吃什么":变量、经纬度网格、时间步长
output_coords(input_coords) 计算输出坐标系统 告诉框架"我吐什么",同时校验输入合法性
__call__(x, coords) 单步前向预测 执行一次模型推理,返回 (新tensor, 新coords)
create_iterator(x, coords) 创建时间积分迭代器 用生成器(yield)逐步产出时间序列,可维护内部状态
to(device) 移动设备 通常继承 torch.nn.Module 即自动获得

其中 input_coords / output_coords 返回的都是 CoordSystem——一个有序字典(OrderedDict),键的顺序就是 tensor 维度的顺序,典型顺序为 batch → lead_time → variable → lat → lon。


三、动手实践:一个最小可用的自定义 Prognostic

官方扩展示例 examples/08_extend/01_custom_prognostic.py 实现了一个"每步给风场加噪声"的演示模型。下面按 3 个关键步骤拆解核心写法(代码已精简)。

3.1 第一步:定义坐标系统,声明模型契约

class CustomPrognostic(torch.nn.Module):
    def input_coords(self) -> CoordSystem:
        return OrderedDict({
            "batch": np.empty(0),
            "lead_time": np.array([np.timedelta64(0, "h")]),
            "variable": np.array(["u10m", "v10m"]),
            "lat": np.linspace(90, -90, 721),
            "lon": np.linspace(0, 360, 1440, endpoint=False),
        })

这是自定义 Prognostic 模型最容易出错的地方:坐标描述必须和你的训练数据完全一致(分辨率、变量名、网格范围)。output_coords 则负责把 lead_time 推进一个时间步,并校验输入坐标是否合法:

@batch_coords()
def output_coords(self, input_coords):
    # 用 handshake 工具校验输入,再构造推进 1 小时的输出坐标
    for key, value in self.input_coords().items():
        handshake_dim(input_coords, key, i)
        handshake_coords(input_coords, self.input_coords(), key)
    output_coords["lead_time"] = output_coords["lead_time"] + input_coords["lead_time"]
    return output_coords

💡 坐标系统的详细约定见 docs/userguide/about/overview.md 中的 "Data Movement" 一节。

3.2 第二步:实现 __call__ 单步预测

@batch_func()
def __call__(self, x, coords):
    out_coords = self.output_coords(coords)   # ① 先校验输入
    out = self.model_forward(x)               # ② 你的网络前向推理
    return out, out_coords                    # ③ 返回 (tensor, 新坐标)

两个装饰器来自 earth2studio/models/batch.py,是内置模型的标准配置:

  • @batch_func():自动把外部 batch(比如多个预报起报时间)压缩进模型自身的 batch 维,再拆回原形状——让你的模型天然支持批量推理;
  • @batch_coords():让坐标系统函数也能处理带 batch 维的输入。

3.3 第三步:create_iterator 生成时间序列

Prognostic 模型产出的是时间序列,这靠 Python 生成器实现。注意两点:第一个 yield 必须是初值(第 0 步);模型可以在迭代器内维护自己的内部状态(如编码器缓存),完全独立于工作流:

def _default_generator(self, x, coords):
    yield x, coords                       # 第 0 步:返回初值
    while True:                            # 自回归模型可无限滚动
        coords = self.output_coords(coords)
        x = self.model_forward(x)
        yield x, coords

def create_iterator(self, x, coords):
    yield from self._default_generator(x, coords)

⚠️ 提醒:校验输入合法性是模型自己的责任,推荐用 earth2studio/utils/coords.py 中的 handshake_coords / handshake_dim 工具函数来快速比对维度与坐标值。


四、运行你的自定义模型:零改动接入标准工作流

接口满足了?那么工作流对你完全无感——它不知道也不关心模型是内置的还是你写的。以确定性预报为例(完整示例见 examples/08_extend/01_custom_prognostic.py):

from earth2studio.data import GFS
from earth2studio.io import ZarrBackend
import earth2studio.run as run

model = CustomPrognostic(noise_amplitude=10.0)  # 你的模型
data = GFS()                                     # 数据源:GFS 再分析
io = ZarrBackend()                               # 输出后端:Zarr

# 一键跑 24 步预报
io = run.deterministic(["2024-01-01"], 24, model, data, io)
print(io.root.tree())

一个 run.deterministic 调用的背后,框架自动完成了:拉取 GFS 初始场 → 张量转换 → 迭代 24 步时间积分 → 结果写入 Zarr。数据源可换成 earth2studio/data/ 里的 ERA5(WB2)、CFS 季预报等任意组件,模型与数据完全解耦。

如果还需要自动下载缓存预训练权重,让你的模型继承 AutoModel(参考 docs/userguide/advanced/auto.md),就能用 PrognosticModel.load_default_package() 一行代码加载;而 PrognosticMixin 则提供迭代器钩子,用于更细粒度的时间序列控制——这两者都是内置模型的常用组合,非必需但强烈推荐。


五、避坑清单:自定义模型开发的 4 个高频问题

问题 正确做法
❌ 坐标写错导致 handshake 报错 lat 从 90 递减到 -90,lon 常用 [0, 360) 区间;维度顺序必须与 OrderedDict 键顺序一致
❌ create_iterator 第一步返回了预测值 第 0 步必须 yield 输入的初值,工作流依赖这个约定做初值对齐
❌ 推理速度上不去 用 @batch_func() 把多起报时间并入模型 batch 维,GPU 利用率显著提升
❌ 模型无法在 GPU 上运行 继承 torch.nn.Module,to(device) 自动可用

想对照完整实现逐行学习,推荐按顺序阅读这三个文件:

  1. 官方扩展示例:examples/08_extend/01_custom_prognostic.py(本教程的原型)
  2. 接口协议定义:earth2studio/models/px/base.py
  3. 对照一个生产级内置模型:earth2studio/models/px/fcn.py(FourCastNet 实现)

更多可运行案例集中在 examples/08_extend/(自定义模型三件套:Prognostic / Diagnostic / DataSource)和快速入门的 examples/01_getting_started/,开发者贡献规范见 CONTRIBUTING.md——如果你想把自己的模型提交进 Earth2Studio,只需满足上述接口并按贡献指南提供可下载的权重即可。


总结

接入你自己的模型到 Earth2Studio 其实非常直接:声明 input_coords / output_coords 契约 → 实现 __call__ 单步推理 → 用 create_iterator 生成时间序列,即可无缝跑进 run.deterministic 等标准工作流。框架的模块化设计意味着你只替换模型这一个零件,数据获取、批量推理、结果存储、检查点恢复全部免费获得。现在,就打开 examples/08_extend/01_custom_prognostic.py,把噪声替换成你自己的网络吧!🚀

登录后查看全文
earth2studio