如何接入自己的气象模型:Earth2Studio自定义Prognostic模型扩展开发完整教程
如何接入自己的气象模型: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) 自动可用 |
想对照完整实现逐行学习,推荐按顺序阅读这三个文件:
- 官方扩展示例:examples/08_extend/01_custom_prognostic.py(本教程的原型)
- 接口协议定义:earth2studio/models/px/base.py
- 对照一个生产级内置模型: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,把噪声替换成你自己的网络吧!🚀