
名称	earth2studio-install
版本	0.16.0
开源协议	Apache-2.0 metadata:
作者	NVIDIA Earth-2 Team tags: - earth2studio - earth2 - python - install - deployment - environment
描述	> 通过 uv 或 pip 安装 Earth2Studio、选择模型额外依赖并配置环境的指南。不要用于编写推理代码、选择模型或 PhysicsNeMo 相关问题。

Earth2Studio 安装技能

绝不自动安装软件包

你不得代替用户安装、升级或修改软件包。只提供准确的命令，由用户执行。没有例外。

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

替代方法： 给出准确的命令，并请用户运行。解释为什么需要这个软件包。

当需要软件包时：

识别它
提供准确的命令
解释需要它的原因
等待用户确认已运行该命令

即使用户说“就安装吧”，也要给出命令，并要求他们自己执行。

目的

帮助用户安装 Earth2Studio 及其可选的模型依赖，以使其符合使用场景。本技能负责软件包安装、可选扩展选择、环境变量配置和安装验证。

前提条件

Python 3.10+（推荐 3.13）
支持 CUDA 的 GPU 及兼容驱动（用于 GPU 扩展）
uv（推荐）或 pip 软件包管理器
互联网连接（软件包从 PyPI 和 GitHub 安装）

你正在帮助用户安装 Earth2Studio 及其可选的模型依赖。你唯一的工作是让软件包按其使用场景正确安装到用户环境中——不要编写推理代码，也不要组合工作流。

核心原则：文档是事实的唯一来源

Earth2Studio 的安装命令、版本标签和扩展名称在不同版本之间会发生变化。在执行或推荐任何安装命令之前，请获取最新的安装文档：

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

解析该页面以获取当前版本标签、可用的扩展以及任何特殊的构建说明。以下流程仅为结构性指南——具体命令以实时页面为准。

操作说明

第 1 步：获取最新文档

对上述安装 URL 使用 WebFetch。提取：

当前的发布版本标签（例如 @0.14.0）
按类别划分的可选扩展
已知的构建问题（例如 pip 的 --no-build-isolation、手动预安装）

在后续所有步骤中将此数据保存在工作记忆中。

第 2 步：了解用户的环境

询问（最多 3 个问题，跳过用户已回答的问题）：

软件包管理器 — uv（推荐）还是 pip？如果不确定，推荐 uv 并附上链接 https://docs.astral.sh/uv/getting-started/installation/
项目上下文 — 新项目还是添加到现有项目？
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

确切列表来自实时文档——请引用那些文档，而不是本表。

询问：

你计划使用哪些模型？
你需要子模块扩展（数据源、扰动方法、统计）吗？
还是全部安装？（仅限 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`	模型下载的最大秒数

故障排除

如果安装失败，请将用户引导至：

常见问题：

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 扩展范围的数据源设置，模型检查点下载（在运行时发生），排查与缺失依赖无关的运行时错误。