Segearth-R2理解01

这个工程是 CVPR 2026 Highlight：SegEarth-R2，面向遥感图像的语言引导分割模型 ，代码已在 2026-05-24 发布，数据集 LaSeRS 在 2026-05-23 发布。仓库主目录包括 docs、scripts、segearth_r2，核心语言是 Python/CUDA/Shell。(GitHub1)

一、先按这个顺序学

第1步：先读文档，不读代码

阅读顺序：

1. docs/Preparation.md：看数据和预训练权重怎么放。数据目录包括 train/annotations/train_ann.json、train/images、test/annotations、test/images；预训练权重包括 Mipha-3B、CLIP/siglip-so400m-patch14-384、Mask2Former。(GitHub2)
2. docs/Installation.md：配置环境。它要求 Linux、Python ≥3.10、PyTorch ≥2.0，并需要编译 MSDeformAttn 的 CUDA kernel。(GitHub3)
3. docs/Training.md：理解训练入口。训练通过 deepspeed segearth_r2/train/train.py 启动，核心参数包括大语言模型、视觉编码器、Mask2Former、数据路径、LoRA、DeepSpeed 配置等。(GitHub4)
4. docs/Evaluation.md：理解测试入口。评估通过 deepspeed segearth_r2/eval/eval.py 启动。(GitHub5)

二、工程目录怎么理解

SegEarth-R2/
├── docs/                 # 官方使用说明
├── scripts/              # 训练、测试、LoRA合并、DeepSpeed配置脚本
├── segearth_r2/
│   ├── datasets/          # 数据读取、样本构造、图文/掩膜标注处理
│   ├── eval/              # 推理与评估入口
│   ├── model/             # 模型主体：多模态大模型 + 视觉编码器 + 分割解码器
│   ├── train/             # 训练入口、参数解析、LoRA保存/合并
│   └── utils/             # 通用工具函数
├── README.md
└── requirements.txt

三、这个工程的主线逻辑

它不是普通语义分割，而是：

遥感图像 + 文本描述 → 多模态大模型理解语言 → 视觉编码器提取图像特征 → Mask2Former 类分割解码器生成 mask → 输出语言引导的分割结果。

可以理解为三层：

第一层：语言理解层

使用类似 Mipha-3B 的多模态大模型，负责理解输入文本，例如"segment the airport runway"或遥感目标描述。

第二层：视觉表征层

使用 CLIP/SigLIP 作为视觉塔，提取遥感图像的全局/局部语义特征。

第三层：分割解码层

使用 Mask2Former 相关结构，把语言条件和视觉特征转成像素级 mask。

四、核心文件学习路线

1. scripts/train.sh

这是最重要的入口脚本。里面这类参数要重点看：

deepspeed --master_port=29500 --include localhost:4 segearth_r2/train/train.py

含义：用 DeepSpeed 启动分布式训练，真正执行的是 segearth_r2/train/train.py。

--model_name_or_path "pretrained_model/mllm/Mipha-3B"

指定多模态大语言模型。

--vision_tower "pretrained_model/CLIP/siglip-so400m-patch14-384"

指定视觉编码器。

--vision_tower_mask "pretrained_model/mask2former/model_final_54b88a.pkl"

指定分割解码相关预训练权重。

--base_data_path 'your_data_path'

指定数据集根目录。

--lora_r 4

表示用 LoRA 微调，秩为 4。

--deepspeed scripts/zero3.json

使用 DeepSpeed ZeRO-3 节省显存。官方文档也说明显存不足时可选择 zero3.json 或 zero2.json。(GitHub4)

2. segearth_r2/datasets/dataset.py

这一类文件通常负责：

读取 train_ann.json
读取图像
读取文本问题 description
读取答案 answer
读取或构造 mask
图像预处理
文本 token 化
返回训练样本 dict

你读这个文件时重点看：

__init__()

一般用于初始化数据路径、读取标注文件、设置 tokenizer 和图像 transform。

__len__()

返回数据集大小。

__getitem__(idx)

最关键。它决定一个样本如何从"原始图像+文本+标注"变成模型可训练的 tensor。

3. segearth_r2/train/train.py

这是训练主入口。通常要按以下顺序读：

参数解析
加载 tokenizer
加载模型
加载视觉塔
加载 mask decoder
加载数据集
构造 DataLoader
设置 LoRA
设置 DeepSpeed / Trainer
开始训练
保存权重

你要重点看三类对象：

ModelArguments
DataArguments
TrainingArguments

它们决定了模型路径、数据路径、训练超参数。

4. segearth_r2/model/

这是研究价值最高的部分。建议重点关注：

语言模型如何接收图像 token
视觉特征如何接入 LLM
mask token 如何产生
mask decoder 如何根据隐藏状态生成分割结果
loss 如何计算

你博士阶段最该看的不是"每一行语法"，而是这些核心问题：

第一，文本和图像在哪里融合？

找 forward()，看输入里是否有 input_ids、images、masks、seg_token_mask。

第二，分割 token 怎么从语言模型 hidden states 中取出来？

通常会有类似 seg_token、mask_token、hidden_states 的变量。

第三，mask decoder 怎么用这些 token？

看模型是否把 LLM 输出的 embedding 传给 Mask2Former 或类似 decoder。

第四，loss 怎么组成？

通常包括语言建模 loss、mask BCE loss、Dice loss 或类似分割损失。

5. segearth_r2/eval/eval.py

测试入口一般做：

加载合并后的模型
读取测试集
输入图像和问题
生成文本答案或 mask
保存预测结果
计算评价指标

官方文档给出的评估命令包括 base_data_path、mask_config、model_path、output_dir、eval_batch_size。(GitHub5)

五、你作为博士应重点掌握的"代码主链路"

建议你画一条主线：

scripts/train.sh
        ↓
segearth_r2/train/train.py
        ↓
datasets/dataset.py
        ↓
model/模型构建
        ↓
vision_tower 提取图像特征
        ↓
LLM 融合语言和视觉
        ↓
mask_decoder 生成分割掩膜
        ↓
loss 计算
        ↓
LoRA / DeepSpeed 训练
        ↓
merge_lora_weights.sh
        ↓
eval/eval.py

六、逐行读代码的方法

你可以按这个模板做笔记：

文件名：
功能定位：
输入：
输出：
核心类：
核心函数：
关键变量：
与其他文件的关系：
我不懂的地方：
可改进点：

逐行解释时，建议先从这 4 个文件开始：

1. scripts/train.sh
2. segearth_r2/train/train.py
3. segearth_r2/datasets/dataset.py
4. segearth_r2/eval/eval.py

先不要一开始就读 model/mask_decoder 里的 CUDA、Detectron2、Mask2Former 细节，那部分依赖复杂，适合第二阶段读。

七、博士研究角度怎么切入

你可以把 SegEarth-R2 当成你"多模态融合驱动的遥感开放世界目标识别研究"的参考工程，重点吸收三点：

第一，多模态遥感图文对齐。

它把遥感图像和语言描述结合起来，适合支撑"语义级对齐"。

第二，语言引导分割。

相比封闭类别分割，它更接近开放词表、开放目标识别。

第三，大模型 + 分割解码器。

这是你后续做"开放世界目标识别""未知类别发现""多目标统一推理"的重要技术基础。

八、建议学习安排

第1天：跑通环境和 README
第2天：看 docs 和 scripts
第3天：逐行读 dataset.py
第4-5天：逐行读 train.py
第6-8天：读 model 主体 forward
第9-10天：读 mask decoder
第11天：跑一次小规模训练
第12天：跑 eval.py
第13天：总结输入输出链路图
第14天：结合自己课题写改进点

很好，接下来我们进入真正的源码阅读阶段。

系统架构
    ↓
数据流
    ↓
模型流
    ↓
训练流
    ↓
源码细节

第一章 SegEarth-R2整体架构解析

根据论文和代码结构，SegEarth-R2本质上是：

                ┌──────────────┐
                │   Text Prompt │
                └──────┬───────┘
                       │
                       ▼
              ┌─────────────────┐
              │    Mipha-3B     │
              │   多模态LLM      │
              └──────┬──────────┘
                     │
                     ▼
┌──────────┐   ┌──────────────┐
│ Remote   │→ │ Vision Tower │
│ Image    │   │   SigLIP     │
└──────────┘   └──────┬───────┘
                      │
                      ▼
             ┌────────────────┐
             │ Projector      │
             │ 特征映射模块     │
             └──────┬─────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ Segmentation Head │
           │   Mask2Former     │
           └──────┬───────────┘
                  │
                  ▼
              Segmentation
                   Mask

实际上就是：

SigLIP负责看图

Mipha负责理解语言

Mask2Former负责生成mask

SegEarth-R2负责连接三者

---

第二章 train.sh逐行阅读

这是整个工程入口。

你以后读任何大模型工程：

train.sh
↓
train.py
↓
model.py

永远是这条路线。

---

第一行

GPUS=8

意思：

使用8张GPU训练

对应：

GPU0
GPU1
GPU2
GPU3
GPU4
GPU5
GPU6
GPU7

这是标准DeepSpeed训练方式。

---

第二行

export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

意思：

告诉PyTorch：

只能看到这8张GPU

如果改成：

CUDA_VISIBLE_DEVICES=0

就是单卡训练。

---

第三行

deepspeed \

启动：

DeepSpeed Engine

而不是：

python train.py

原因：

SegEarth-R2太大。

包含：

Mipha-3B
+
SigLIP
+
Mask2Former

单卡放不下。

所以：

模型切分
梯度切分
优化器切分

全部交给DeepSpeed。

---

master_port

--master_port 29500

作用：

GPU之间通信

例如：

GPU0
GPU1
GPU2
...

梯度同步时：

all_reduce()

要走这个端口。

---

include

--include localhost:0,1,2,3,4,5,6,7

意思：

使用本机8张卡

如果是服务器集群：

node1
node2

这里会写多个节点。

---

第三章 train.py开始阅读

真正入口：

segearth_r2/train/train.py

首先会看到：

from transformers import HfArgumentParser

作用：

读取命令行参数。

例如：

--learning_rate 2e-5

自动变成：

training_args.learning_rate

---

第四章 参数类

你会看到三个重要类：

ModelArguments
DataArguments
TrainingArguments

这是HuggingFace标准写法。

---

ModelArguments

控制模型。

例如：

vision_tower

对应：

--vision_tower siglip

作用：

决定使用哪个视觉编码器。

---

例如：

model_name_or_path

对应：

Mipha-3B

表示：

加载语言模型

---

DataArguments

控制数据。

例如：

base_data_path

对应：

LaSeRS数据集

---

例如：

image_size

控制：

Resize(1024)

类似操作。

---

TrainingArguments

控制训练。

例如：

batch_size

learning_rate

weight_decay

warmup_ratio

等。

---

第五章 train.py核心流程

真正重要的是：

main()

通常流程：

def main():

    读取参数

    加载Tokenizer

    加载模型

    加载数据

    Trainer初始化

    开始训练

---

第六章 Tokenizer加载

你会看到：

tokenizer = AutoTokenizer.from_pretrained()

作用：

把文字变数字。

例如：

输入：

segment the airport runway

变成：

[101, 2384, 5678, 9012]

因为神经网络只能处理数字。

---

第七章 Vision Tower加载

会看到：

build_vision_tower()

或者类似函数。

作用：

加载SigLIP

输入：

1024×1024遥感图像

输出：

Patch Features

例如：

256个patch

每个patch

1152维

得到：

[256,1152]

这样的特征矩阵。

---

第八章 为什么要Projector

很多博士第一次看不懂这里。

SigLIP输出：

1152维

Mipha输入：

3072维

维度不同。

所以需要：

mm_projector

本质：

Linear(1152,3072)

即：

视觉空间
↓
语言空间

映射。

---

第九章 最关键Forward

真正理解整个工程：

找到：

forward()

这里会出现：

input_ids
images
labels
masks

四大输入。

---

input_ids

来自：

文本Prompt

例如：

Locate all airplanes

---

images

来自：

遥感图像

---

labels

来自：

语言监督

用于：

CrossEntropyLoss

---

masks

来自：

像素级标注

用于：

DiceLoss

或者：

BCELoss

---

第十章 数据流真正长什么样

训练一个样本：

{
    "image":"001.jpg",
    "question":"segment all bridges",
    "answer":"bridge detected",
    "mask":"001.png"
}

经过dataset.py：

变成：

{
    "image_tensor",
    "input_ids",
    "attention_mask",
    "gt_mask"
}

然后送入：

forward()

最终：

loss

---

第十一章 SegEarth-R2最有价值的代码

如果你准备申博或者未来做论文，我建议重点研究：

segearth_r2/model/

尤其：

builder.py

language_model/

mask_decoder/

multimodal_encoder/

multimodal_projector/

因为创新几乎全部在这里。

真正的贡献不在：

dataset.py

而在：

语言特征
+
视觉特征
+
Mask2Former

如何融合。

---

下一步（最重要）

下一篇我建议直接开始：

《SegEarth-R2源码精读（二）：segearth_r2/model目录逐文件解析》

我会按照真实源码结构讲解：

builder.py
每一行作用

multimodal_encoder/
每个类作用

multimodal_projector/
为什么这样设计

language_model/
Mipha如何接收图像

mask_decoder/
Mask2Former如何生成分割结果

forward()
数据流全过程