earth2studio-install

Earth2Studio 安装技能

永远不要自动安装软件包

你不得代表用户安装、升级或修改软件包。提供确切命令；由用户运行。没有例外。

**禁止：**运行 pip install、uv pip install、uv add、 uv sync、conda install、apt install 或任何软件包管理器命令。

**应改为：**提供确切命令，并请用户运行。 解释为什么需要这个软件包。

需要软件包时：

1. 确认所需软件包
2. 提供确切命令
3. 解释为什么需要它
4. 等待用户确认他们已运行该命令

即使用户说“直接帮我安装”，也要提供命令，并要求他们自行执行。

用途

帮助用户根据使用场景正确安装 Earth2Studio 及其可选模型依赖项。此技能涵盖软件包安装、可选扩展选择、环境变量配置和安装验证。

前提条件

• Python 3.10+（推荐 3.13）
• 使用 GPU 扩展时，需要支持 CUDA 且驱动兼容的 GPU
• uv（推荐）或 pip 软件包管理器
• 互联网访问（软件包从 PyPI 和 GitHub 安装）

你正在帮助用户安装 Earth2Studio 及其可选模型依赖项。你的唯一任务是根据用户的使用场景正确安装软件包——不要编写推理代码，也不要编排工作流。

核心原则：以文档为准

Earth2Studio 的安装命令、版本标签和扩展名称会随版本更新而变化。在执行或推荐任何安装命令之前，先获取实时安装文档：

https://nvidia.github.io/earth2studio/userguide/about/install.html

从页面中解析当前版本标签、可用扩展以及任何特殊构建说明。以下工作流仅提供结构性指导——具体命令以实时页面为准。

说明

第 1 步：获取实时文档

对上方安装网址使用 WebFetch。提取以下信息：

• 当前发行版本标签（例如 @0.14.0）
• 按类别划分的可用可选扩展
• 已知的构建注意事项（例如 pip 使用 --no-build-isolation、手动预装）

后续步骤中始终在工作记忆中保留这些信息。

第 2 步：了解用户的环境

提问（最多 3 个问题，用户已回答的内容无需再问）：

1. 软件包管理器——uv（推荐）还是 pip？如果不确定，推荐 uv，并提供链接 https://docs.astral.sh/uv/getting-started/installation/
2. 项目背景——新建项目还是添加到现有项目？
3. Python 版本——推荐使用文档中的版本（当前为 3.13）

第 3 步：基础安装

根据用户的回答，提供实时文档中的命令：

• uv 使用 Git 源（而非 PyPI），以处理基于 URL 的传递依赖
• pip 从 PyPI 安装，但某些扩展需要手动预装

用户运行安装命令后，验证：

import earth2studio
earth2studio.__version__

第 4 步：选择模型和扩展

按使用场景展示可用扩展。询问用户计划进行哪些操作——不要主动列出所有选项。文档中的类别如下：

类别	扩展示例
预测（预报）	aifs、aurora、graphcast、pangu、sfno、stormcast、…
诊断（后处理）	corrdiff、climatenet、precip-afno、…
数据同化（测试版）	da-healda、da-interp、da-stormcast
子模块	data、perturbation、statistics

确切列表以实时文档为准——请引用文档，而不是此表。

提问：

1. 你计划使用哪些模型？
2. 你需要子模块扩展吗（数据源、扰动方法、统计信息）？
3. 或者安装全部内容？（仅限 uv：--extra all）

步骤 5：安装所选的额外组件

根据用户的选择，提供实时文档中的准确命令。 需要重点提示：

• 构建耗时较长：flash-attention（AIFS 变体）、natten （Atlas、StormScope）、torch-harmonics CUDA 扩展（FCN3、SFNO） — 可能需要 10-30+ 分钟
• pip 特定的手动步骤：某些模型需要 --no-build-isolation，或预先安装 earth2grid、 torch-harmonics 或 makani 等软件包
• 数据同化模型：需要 CuPy + cuDF（CUDA 12）

步骤 6：配置（提供选项，不强制要求）

仅在相关时（例如磁盘空间有限、使用共享文件系统或 CI 环境），提及用户可能需要设置的环境变量：

变量	用途
EARTH2STUDIO_CACHE	通用缓存目录
EARTH2STUDIO_DATA_CACHE	数据源缓存（覆盖通用缓存）
EARTH2STUDIO_MODEL_CACHE	模型检查点缓存（覆盖通用缓存）
EARTH2STUDIO_PACKAGE_TIMEOUT	模型下载的最长等待秒数

故障排除

如果安装失败，请引导用户查看：

• https://nvidia.github.io/earth2studio/userguide/support/troubleshooting.html
• https://nvidia.github.io/earth2studio/userguide/support/faq.html

常见问题：

• PyTorch/CUDA 不匹配：先确认 torch.cuda.is_available()
• flash-attention 构建失败：CUDA 工具包版本必须与 PyTorch CUDA 版本匹配
• ONNX Runtime GPU：可能需要根据 CUDA 版本安装对应版本
• 缺少 ecCodes：处理 GRIB 数据时需要；通过 sudo apt-get install libeccodes-dev（Debian/Ubuntu）或 conda install -c conda-forge eccodes 安装
• Python.h: No such file or directory：缺少 Python 开发头文件；通过 sudo apt-get install python3-dev 安装

限制

• 无法帮助解决与缺少依赖无关的运行时错误
• 不涵盖模型检查点下载（首次推理时才会下载）
• data 额外组件之外的数据源设置不在此范围内
• 无法编写推理或训练代码，也无法编排 Earth2Studio 工作流

负责范围与非负责范围

**负责：**软件包安装、可选额外组件选择、环境变量配置、安装验证。

**不负责：**编写推理或训练代码、编排 Earth2Studio 工作流、data 额外组件之外的数据源设置、模型检查点下载（运行时才会下载）、解决与缺少依赖无关的运行时错误。