黏土基金会模型

一个用于地球的开源人工智能模型及界面。

许可证

黏土模型采用 Apache 许可证授权。这适用于源代码以及训练好的模型权重。

文档则采用 CC-BY-4.0 许可证授权。

快速入门

在以下平台启动 JupyterLab 环境：

Binder	SageMaker Studio Lab

安装

使用 pip 安装（推荐）

安装黏土基金会模型最简单的方式是通过 pip：

pip install git+https://github.com/Clay-foundation/model.git

这将安装 claymodel 包及其所有依赖项。随后您可以在 Python 代码中导入并使用它：

from claymodel.datamodule import ClayDataModule
from claymodel.module import ClayMAEModule

开发环境安装

若需进行开发或高级使用，您可以搭建完整的开发环境：

为协助开发，请先克隆此 repo-url：

git clone <repo-url>
cd model

然后我们建议使用 mamba 来安装依赖项。同时会创建一个包含 Python 和 JupyterLab 的虚拟环境。

mamba env create --file environment.yml

[!注意] 上述命令已在配备 CUDA 显卡的 Linux 设备上测试通过。

请先激活虚拟环境：

mamba activate claymodel

最后，请再次确认库是否已正确安装：

mamba list

使用

运行 Jupyter Lab

mamba activate claymodel
python -m ipykernel install --user --name claymodel  # 正确安装虚拟环境
jupyter kernelspec list --json                       # 检查内核是否已安装
jupyter lab &

运行模型

可通过 LightningCLI v2 运行神经网络模型。

[!注意] 如果您是通过 pip 安装的，则需要克隆仓库才能访问训练脚本和配置文件。

要查看可用选项及超参数配置，请运行：

python trainer.py --help

要在验证集的一个批次上快速测试模型：

python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml --trainer.fast_dev_run=True

要训练模型：

python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml

更多选项可通过 python trainer.py fit --help 或访问 LightningCLI 文档 获取。

贡献

编写文档

我们的文档使用 Jupyter Book 构建。

安装方法如下：

pip install -U jupyter-book

构建时执行：

jupyter-book build docs/

您也可以在本地预览站点：

python -m http.server --directory _build/html

GitHub 上有一个工作流 .github/workflows/deploy-docs.yml，会自动构建站点并推送到 GitHub Pages。

Clay Foundation Model 快速上手指南

Clay Foundation Model 是一个面向地球科学的开源 AI 模型及接口。本指南将帮助中国开发者快速完成环境配置、安装及基础运行。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：推荐 Linux（官方测试环境），Windows 或 macOS 可能需要额外配置。
• 硬件加速：推荐使用配备 CUDA 驱动的 NVIDIA GPU 以获得最佳训练和推理性能。
• 包管理器：推荐安装 Mamba（比 Conda 更快），用于管理依赖环境。
• Python 版本：通过 Mamba 自动安装（包含在 environment.yml 中）。

提示：国内用户若下载依赖较慢，可配置清华源或阿里源加速 pip 和 conda/mamba 通道。

安装步骤

您可以根据需求选择“快速使用”或“开发模式”进行安装。

方式一：Pip 快速安装（推荐仅使用者）

这是最简单的安装方式，适用于直接调用模型库进行开发。

pip install git+https://github.com/Clay-foundation/model.git

安装完成后，即可在 Python 代码中导入：

from claymodel.datamodule import ClayDataModule
from claymodel.module import ClayMAEModule

方式二：开发环境安装（推荐贡献者/进阶用户）

如果您需要修改源码、运行训练脚本或使用 JupyterLab 交互环境，请按以下步骤操作：

1. 克隆仓库

   git clone https://github.com/Clay-foundation/model.git
   cd model
   

2. 创建虚拟环境 使用 Mamba 根据配置文件一键安装所有依赖（含 PyTorch, JupyterLab 等）：

   mamba env create --file environment.yml
   

3. 激活环境

   mamba activate claymodel
   

4. 验证安装

   mamba list
   

基本使用

1. 启动 JupyterLab 交互环境

若采用方式二安装，建议先注册内核以便在 Jupyter 中使用：

mamba activate claymodel
python -m ipykernel install --user --name claymodel
jupyter kernelspec list --json  # 确认内核已注册
jupyter lab &

2. 运行模型训练与测试

模型运行基于 LightningCLI v2。

注意：若通过 Pip 安装，需先克隆仓库以获取 trainer.py 脚本和 configs 配置文件。

• 查看帮助与超参数配置

  python trainer.py --help
  

• 快速测试（单批次验证） 用于快速检查环境是否正常，仅在验证集上运行一个 batch：

  python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml --trainer.fast_dev_run=True
  

• 正式训练 使用默认配置开始训练模型：

  python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml
  

更多高级选项可通过 python trainer.py fit --help 查看，或参考 LightningCLI 官方文档。