
名称	earth2studio-data-fetch
版本	0.16.0
开源协议	Apache-2.0 metadata:
作者	NVIDIA Earth-2 Team tags: - earth2studio - earth2 - python - data-fetch - weather-data - xarray
描述	> 通过Earth2Studio数据源获取特定变量和时间的天气/气候数据。不要用于推理流水线、模型发现或安装。

Earth2Studio 数据获取技能

目的

引导用户通过Earth2Studio数据源API下载天气/气候数据。通过检查词汇表识别兼容的数据源，验证变量支持，并生成输出xarray DataArray的可运行获取脚本。

先决条件

已安装 Earth2Studio（uv pip install earth2studio 或同等方式）
可访问远程数据存储（GCS、S3、CDS API 等）的网络
对于基于CDS的数据源：已配置有效的CDS API密钥（~/.cdsapirc）
Python 3.10+

说明

你正在帮助用户使用Earth2Studio的数据源API下载特定的天气/气候数据。你的工作是确定哪个（些）数据源能够提供所请求的变量，通过词汇表系统验证兼容性，并生成可用的获取脚本。

核心原则：实时文档和词汇表是真相来源

不同版本之间，数据源API、可用变量和词汇表会发生变化。在推荐数据源或编写获取脚本之前：

获取相关数据源文档页面，确认API签名和构造参数。
检查词汇表，验证请求的变量是否被该数据源支持。

实时文档参考（仅获取用户请求所需的内容）：

分析数据源： https://nvidia.github.io/earth2studio/modules/datasources_analysis.html
预报数据源： https://nvidia.github.io/earth2studio/modules/datasources_forecast.html
DataFrame数据源： https://nvidia.github.io/earth2studio/modules/datasources_dataframe.html
词汇表基础： https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/base.py
各数据源词汇表： https://github.com/NVIDIA/earth2studio/tree/main/earth2studio/lexicon

交互协议

第1步：理解用户请求

从用户所述内容中提取（如有需要可追问，最多3个问题）：

变量 — 他们想要什么？使用Earth2Studio变量名（例如 t2m、u500、z850、tp、msl）。如果用户使用通俗语言（“500 hPa位势高度”），通过检查实时 base.py 的 E2STUDIO_VOCAB 映射到E2Studio名称。
时间 — 什么日期/时间范围？单个时间戳、范围或多个离散时间？
数据类型 — 分析/再分析（历史状态）还是预报（基于提前时间）？
提前时间（仅预报）— 预测多远？哪个初始化时间？
区域 — 全球区域还是区域（例如HRRR的北美）？
输出格式 — xarray DataArray（默认）、保存到文件（NetCDF/Zarr）？

第2步：识别候选数据源

根据请求类型缩小候选范围：

分析/再分析（特定时间的历史状态）：

使用分析数据源页面识别选项
常见选择：GFS（业务运行，近期）、HRRR（北美，逐小时）、IFS/IFS_ENS（ECMWF）、ARCO/CDS/WB2ERA5/NCAR_ERA5（ERA5再分析）、GOES/MRMS/JPSS（观测）

预报（从初始化时间开始的预测，包含提前时间）：

使用预报数据源页面识别选项
常见选择：GFS_FX、GEFS_FX、HRRR_FX、IFS_FX、IFS_ENS_FX、AIFS_FX、CFS_FX

需要突出的关键差异：

时间覆盖 — 业务运行来源（GFS、HRRR）历史有限；再分析（通过ARCO/CDS/WB2的ERA5）可追溯到几十年前
空间分辨率 — HRRR是仅覆盖北美的3公里分辨率；GFS是0.25°全球；WB2ERA5_32x64是5.625°全球
更新频率 — 有些是实时的，有些有多天延迟

第3步：通过词汇表验证变量支持

这很关键。每个数据源都有一个词汇表文件，定义它能提供哪些E2Studio变量。

验证方法：

从 https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/<source>.py（例如 gfs.py、hrrr.py、cds.py、arco.py、wb2.py）获取数据源的词汇表文件
检查请求的变量是否出现在该数据源 VOCAB 字典的键中
如果变量不在数据源的词汇表中，该数据源无法提供它 — 尝试其他数据源

词汇表VOCAB将Earth2Studio变量名映射到数据源特定的标识符。如果变量键存在于VOCAB中，则该数据源支持它。

清晰呈现结果：“GFS支持 t2m、u500、z850。HRRR也支持这些变量，但仅限于北美。ARCO（ERA5）支持所有三个变量，并且数据可追溯到1959年。”

第4步：与用户确认数据源选择

展示可行选项及其权衡：

数据源	变量	覆盖范围	分辨率	时间范围
…	…	…	…	…

让用户选择。如果存在一个明显选择，推荐它并请求确认。

第5步：生成获取脚本

编写一个Python脚本，使用所选数据源获取请求的数据。脚本结构取决于它是分析数据源还是预报数据源。

分析数据源模式：

import datetime
from earth2studio.data import <SourceClass>

# 初始化数据源
ds = <SourceClass>()

# 获取数据
# 分析数据源使用：ds(time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # 或时间数组
variable = ["var1", "var2"]  # E2Studio变量名

data = ds(time, variable)

预报数据源模式：

import datetime
from earth2studio.data import <SourceClass>

# 初始化数据源
ds = <SourceClass>()

# 预报数据源使用：ds(time, lead_time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # 初始化时间
lead_time = [datetime.timedelta(hours=H)]   # 或提前时间数组
variable = ["var1", "var2"]

data = ds(time, lead_time, variable)

编写脚本前务必获取特定数据源的API文档页面，确认确切的构造参数和调用签名 — 它们各不相同（有些需要认证令牌、缓存路径、特定参数）。

在脚本中包含：

适当的导入
清晰注释每一步
如何检查结果（print(data)、data.shape、data.coords）
可选：如果用户要求则保存到文件

第6步：提供后续步骤

交付脚本后，提及：

如何在不重写整个脚本的情况下修改变量/时间
如果他们可能想将其输入模型，请指向发现技能
缓存行为（首次获取后数据通过 EARTH2STUDIO_CACHE 在本地缓存）

所有权和范围外

拥有： 识别满足用户变量/时间请求的数据源、通过词汇表验证变量支持、生成数据获取脚本、解释分析与预报数据源之间的差异。

不拥有： 安装（earth2studio-install）、模型选择（earth2studio-discover）、推理流水线、自定义数据源创建（指向扩展示例）、超出文档描述的数据源认证设置。

示例

典型调用：

“我需要ERA5的500 hPa位势高度和2米温度，时间为2020年1月1日00时。”

该技能将：

将通俗语言映射到 z500、t2m
检查ARCO/CDS/WB2ERA5词汇表是否支持
推荐ARCO（免费，无需API密钥）或CDS（官方，需要密钥）
使用所选数据源生成获取脚本

限制

需要网络 — 所有数据源都从远程存储获取（GCS、S3、CDS API）
不支持本地文件加载 — 对于本地NetCDF/Zarr，请直接使用 DataArrayFile/DataSetFile
每个脚本仅支持一种数据类型 — 不能在单个调用中混合分析与预报数据源
变量可用性各不相同 — 并非所有数据源都提供所有变量；务必通过词汇表验证
速率限制 — CDS API有基于队列的节流；GCS/S3源通常更快

故障排查

错误	原因	解决方案
`KeyError: '<var>'`	不在词汇表中	检查词汇表；尝试其他数据源
`FileNotFoundError` / 404	时间不可用	验证时间覆盖范围
`CDS API timeout`	队列拥塞	重试或使用ARCO获取ERA5
`ModuleNotFoundError`	未安装	`uv pip install earth2studio`
空DataArray	时间/变量不匹配	检查日期时间和变量名称