截至目前GeoAI版本更新内容-夜雨聆风

截至目前GeoAI版本更新内容

版本信息

• 当前版本: v0.37.2
• 发布时间: 2026-04-10
• 主要变化: 新增 RF-DETR 目标检测支持、多种高级损失函数、模型微调功能、多类别标签支持等

主要更新概览

🔥 核心更新

功能	版本	描述	相关文件
RF-DETR 目标检测	v0.37.0+	新增 RF-DETR 模型支持，用于地理空间影像目标检测	geoai/rfdetr.py
高级损失函数	v0.37.0+	新增 DiceLoss、TverskyLoss、UnifiedFocalLoss	geoai/landcover_train.py
模型微调支持	v0.37.2+	支持冻结编码器、恢复训练、检查点加载	geoai/train.py
多类别标签支持	v0.37.1+	ObjectDetectionDataset 支持多类别实例分割	geoai/train.py
滑动窗口推理优化	v0.37.2+	边缘瓦片填充修复	geoai/
CLI Agent 集成	v0.37.2+	新增 GeoAI Agent 功能	geoai/cli.py

📊 损失函数更新

1. DiceLoss – 基于区域重叠的损失函数
2. TverskyLoss – 广义 Dice 损失，支持不对称 FP/FN 加权
3. UnifiedFocalLoss – 复合损失，结合 focal CE 和 focal Tversky
4. FocalLoss – 已有的焦点损失函数

🎯 模型与训练更新

1. RF-DETR 模型支持 – 5 种检测模型 + 6 种分割模型
2. 多类别实例分割 – 支持在目录格式中进行多类别目标检测
3. 模型微调 – freeze_encoder、checkpoint_path、resume_training 参数
4. 优化器状态恢复 – 支持从中断处恢复训练

新增功能详解

1. RF-DETR 目标检测

功能描述：新增 RF-DETR 模型支持，专门为地理空间影像目标检测设计。

支持模型：

• 检测模型：5 种
• 分割模型：6 种

核心特性：

• 滑动窗口推理
• 跨瓦片 NMS（非极大值抑制）
• 自动坐标变换
• 批量处理支持
• HuggingFace Hub 推拉功能

2. 高级损失函数

DiceLoss

classDiceLoss(nn.Module):
"""Dice 损失函数，用于语义分割

    计算预测和目标之间的 Sørensen–Dice 系数，
    衡量区域重叠度，对类别不平衡数据集特别有效。
    """

参数：

• smooth: 平滑常数，避免除零
• ignore_index: 忽略的目标值
• reduction: 应用于输出的归约方式
• weight: 类别权重张量

TverskyLoss

classTverskyLoss(nn.Module):
"""Tversky 损失函数，广义 Dice 损失

    通过允许不对称地加权假阳性和假阴性来推广 Dice 损失。
    设置 alpha=beta=0.5 可恢复标准 Dice 损失。
    """

参数：

• alpha: 假阳性权重
• beta: 假阴性权重
• smooth: 平滑常数
• ignore_index: 忽略的目标值
• reduction: 归约方式
• weight: 类别权重

UnifiedFocalLoss

classUnifiedFocalLoss(nn.Module):
"""统一焦损失，结合分布和区域损失

    将 focal cross-entropy（分布基础）和 focal Tversky（区域基础）
    损失统一到单个复合损失中，对严重类别不平衡的语义分割特别有效。
    """

参数：

• lambda_: 分布和区域组件之间的平衡
• gamma: 聚焦参数
• delta: Tversky 假阴性权重
• smooth: 平滑常数
• ignore_index: 忽略的目标值
• weight: 分布组件的类别权重
• region_weight: 区域组件的类别权重
• use_log_cosh: 应用 log(cosh(loss)) 进行梯度平滑

3. 模型微调支持

新增参数：

# train_segmentation_model 新增参数
checkpoint_path: str = None# 检查点路径，用于微调
resume_training: bool = False# 是否恢复训练
freeze_encoder: bool = False# 是否冻结编码器

# train_timm_segmentation_model 新增参数
freeze_encoder: bool = False# 冻结编码器权重

4. 多类别标签支持

功能描述：ObjectDetectionDataset 现在支持多类别实例分割。

改进点：

• 之前：所有实例标签硬编码为 1
• 现在：读取每个实例的真实类别 ID
• 支持按类别运行连通组件分析

新增参数：

multiclass: bool = False# 是否支持多类别

API 变更说明

train_segmentation_model

deftrain_segmentation_model(
    images_dir: str,
    labels_dir: str,
    output_dir: str,
    input_format: str = "directory",
    num_classes: int = 2,
    batch_size: int = 4,
    num_epochs: int = 10,
    learning_rate: float = 0.001,
    weight_decay: float = 1e-4,
    num_workers: int = 4,
    val_split: float = 0.2,
    seed: int = 42,
    checkpoint_path: Optional[str] = None,  # 新增
    resume_training: bool = False,  # 新增
    freeze_encoder: bool = False,  # 新增
    loss_fn: Optional[nn.Module] = None,  # 新增
    class_weights: Optional[List[float]] = None,  # 新增
    ignore_index: int = 255,  # 新增
    monitor_metric: str = "val_loss",
    mode: str = "min",
    patience: int = 10,
    save_top_k: int = 1,
    verbose: bool = True,
    device: Optional[str] = None,
) -> nn.Module:

train_timm_segmentation_model

deftrain_timm_segmentation_model(
    images_dir: str,
    labels_dir: str,
    output_dir: str,
    input_format: str = "directory",
    encoder_name: str = "resnet50",
    architecture: str = "unet",
    encoder_weights: str = "imagenet",
    num_channels: int = 3,
    num_classes: int = 2,
    batch_size: int = 8,
    num_epochs: int = 50,
    learning_rate: float = 0.001,
    weight_decay: float = 1e-4,
    val_split: float = 0.2,
    seed: int = 42,
    num_workers: int = 4,
    freeze_encoder: bool = False,  # 新增
    class_weights: Optional[List[float]] = None,
    loss_fn: Optional[nn.Module] = None,  # 新增
    monitor_metric: str = "val_iou",
    mode: str = "max",
    patience: int = 10,
    save_top_k: int = 1,
    verbose: bool = True,
    device: Optional[str] = None,
    use_timm_model: bool = False,
    timm_model_name: Optional[str] = None,
    train_transforms: Optional[Callable] = None,
    val_transforms: Optional[Callable] = None,
) -> torch.nn.Module:

调用示例

示例 1：使用 RF-DETR 进行目标检测

import geoai

# 使用 RF-DETR 进行目标检测
detections = geoai.rfdetr_detect(
    input_path="satellite_image.tif",
    output_path="detections.gpkg",
    model_name="rfdetr",
    window_size=640,
    overlap=128,
    batch_size=4,
    conf_threshold=0.5,
    iou_threshold=0.5
)

print(f"检测到 {len(detections)} 个目标")

示例 2：使用 RF-DETR 进行批量目标检测

import geoai

# 批量处理多个影像
results = geoai.rfdetr_detect_batch(
    input_dir="path/to/images",
    output_dir="path/to/output",
    model_name="rfdetr",
    window_size=640,
    overlap=128,
    batch_size=4
)

print(f"处理完成 {len(results)} 个影像")

示例 3：使用高级损失函数训练语义分割模型

import geoai
import torch

# 使用 DiceLoss 训练语义分割模型
loss_fn = geoai.DiceLoss(
    smooth=1.0,
    ignore_index=255,
    reduction="mean",
    weight=None
)

model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    batch_size=8,
    num_epochs=50,
    loss_fn=loss_fn
)

print("模型训练完成")

示例 4：使用 TverskyLoss 训练模型

import geoai

# 使用 TverskyLoss 训练模型，适合类别不平衡数据集
loss_fn = geoai.TverskyLoss(
    alpha=0.3,   # 假阳性权重
    beta=0.7,    # 假阴性权重（提高召回率）
    smooth=1.0,
    ignore_index=255,
    reduction="mean",
    weight=None
)

model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=3,
    batch_size=8,
    num_epochs=50,
    loss_fn=loss_fn
)

示例 5：使用 UnifiedFocalLoss 训练模型

import geoai

# 使用 UnifiedFocalLoss 训练模型，处理严重类别不平衡
loss_fn = geoai.UnifiedFocalLoss(
    lambda_=0.5,      # 分布和区域组件之间的平衡
    gamma=0.75,       # 聚焦参数
    delta=0.6,        # Tversky 假阴性权重
    smooth=1.0,
    ignore_index=255,
    weight=None,
    region_weight=None,
    use_log_cosh=True# 使用梯度平滑
)

model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=10,  # 多类别分类
    batch_size=8,
    num_epochs=50,
    loss_fn=loss_fn
)

示例 6：使用自定义损失函数工厂

import geoai

# 使用内置工厂函数创建损失函数
loss_fn = geoai.get_landcover_loss_function(
    loss_type="dice",  # 可选: "cross_entropy", "dice", "tversky", "unified_focal"
    num_classes=5,
    ignore_index=255,
    class_weights=[1.0, 2.0, 1.5, 1.0, 1.0]  # 类别权重
)

model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    loss_fn=loss_fn
)

示例 7：微调预训练分割模型

import geoai

# 加载预训练检查点并微调
model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    batch_size=8,
    num_epochs=50,
    checkpoint_path="path/to/pretrained_model.pth",  # 预训练模型路径
    freeze_encoder=True,  # 冻结编码器，只微调解码器
    resume_training=False
)

print("模型微调完成")

示例 8：恢复中断的训练

import geoai

# 恢复中断的训练
model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    batch_size=8,
    num_epochs=100,  # 继续训练
    checkpoint_path="path/to/checkpoint_epoch_50.pth",  # 检查点路径
    resume_training=True,  # 恢复训练，包括优化器状态
    freeze_encoder=False
)

print("训练恢复完成")

示例 9：使用多类别实例分割

import geoai

# 使用多类别实例分割
model = geoai.train_instance_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,  # 5 个类别 + 背景
    batch_size=4,
    num_epochs=50,
    multiclass=True# 启用多类别支持
)

print("多类别实例分割模型训练完成")

示例 10：组合使用多种损失函数

import geoai
import torch.nn as nn

# 组合使用交叉熵损失和 Dice 损失
classCombinedLoss(nn.Module):
def__init__(self, ce_weight=0.5, dice_weight=0.5):
super().__init__()
self.ce_weight = ce_weight
self.dice_weight = dice_weight
self.ce_loss = nn.CrossEntropyLoss()
self.dice_loss = geoai.DiceLoss()

defforward(self, inputs, targets):
        ce = self.ce_loss(inputs, targets)
        dice = self.dice_loss(inputs, targets)
returnself.ce_weight * ce + self.dice_weight * dice

# 使用组合损失训练
loss_fn = CombinedLoss(ce_weight=0.5, dice_weight=0.5)

model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    loss_fn=loss_fn
)

示例 11：RF-DETR 训练工作流

import geoai

# 准备 NWPU-VHR-10 数据集
images_dir, labels_dir = geoai.prepare_nwpu_vhr10(
    output_dir="path/to/nwpu_data"
)

# 训练 RF-DETR 模型
model = geoai.rfdetr_train(
    images_dir=images_dir,
    labels_dir=labels_dir,
    output_dir="path/to/output",
    model_name="rfdetr",
    num_epochs=50,
    batch_size=4,
    learning_rate=0.001
)

print("RF-DETR 模型训练完成")

示例 12：使用滑动窗口推理

import geoai

# 使用滑动窗口进行语义分割推理
geoai.timm_semantic_segmentation(
    input_path="large_satellite_image.tif",
    output_path="segmentation_result.tif",
    model_path="path/to/model.pth",
    encoder_name="resnet50",
    architecture="unet",
    num_classes=5,
    num_channels=3,
    window_size=512,      # 滑动窗口大小
    overlap=128,           # 窗口重叠度
    batch_size=4,
    probability_path="path/to/probability.tif",  # 保存概率图
    save_class_probabilities=True# 保存每个类别的概率
)

print("滑动窗口推理完成")

升级指南

从 v0.35.0 升级到 v0.37.2

1. 依赖更新

# 更新 geoai
pip install geoai==0.37.2

# 如果使用可选依赖
pip install geoai[extra]       # 额外功能
pip install geoai[building]     # 建筑物相关
pip install geoai[agents]       # Agent 功能
pip install geoai[onnx]         # ONNX 推理
pip install geoai[geodeep]      # GeoDeep
pip install geoai[rfdetr]       # RF-DETR

2. 代码迁移

损失函数

旧代码：

# v0.35.0 - 只支持 CrossEntropyLoss
model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5
)

新代码：

# v0.37.2 - 支持多种损失函数
loss_fn = geoai.DiceLoss()
model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    loss_fn=loss_fn
)

模型微调

旧代码：

# v0.35.0 - 不支持微调
model = geoai.train_segmentation_model(...)

新代码：

# v0.37.2 - 支持微调
model = geoai.train_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    checkpoint_path="path/to/pretrained.pth",
    freeze_encoder=True
)

多类别实例分割

旧代码：

# v0.35.0 - 多类别硬编码为 1
model = geoai.train_instance_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5# 被忽略，所有实例标签为 1
)

新代码：

# v0.37.2 - 支持真实多类别
model = geoai.train_instance_segmentation_model(
    images_dir="path/to/images",
    labels_dir="path/to/labels",
    output_dir="path/to/output",
    num_classes=5,
    multiclass=True# 启用多类别支持
)

3. 新增使用场景

目标检测

# v0.37.2 - 新增 RF-DETR 支持
detections = geoai.rfdetr_detect(
    input_path="satellite.tif",
    output_path="detections.gpkg",
    model_name="rfdetr"
)

Agent 功能

# v0.37.2 - 新增 CLI Agent
# 通过命令行使用
# geoai agent "分析这张遥感影像中的建筑物"

GeoAI v0.37.2 带来了多项重要更新，主要包括：

1. RF-DETR 目标检测 – 专门为地理空间影像设计的检测模型
2. 高级损失函数 – DiceLoss、TverskyLoss、UnifiedFocalLoss 处理类别不平衡
3. 模型微调 – 支持冻结编码器和恢复训练
4. 多类别支持 – ObjectDetectionDataset 支持真实多类别
5. 性能优化 – 滑动窗口推理边缘处理优化

这些更新使得 GeoAI 在遥感影像分析方面更加强大和灵活，能够更好地支持各种深度学习任务。