GeoAI 入门与实践：用 Python 统一完成遥感影像 AI 分析的开源工具包

GeoAI（geoai-py）是一个面向地理空间数据的人工智能 Python 工具包，目标是用统一的高层 API 打通"数据获取 → 数据集准备 → 模型训练 → 推理预测 → 交互可视化 → QGIS 桌面端使用"的完整链路，让研究者与开发者以尽量少的代码完成建筑物提取、地表覆盖分类、变化检测、目标检测等典型任务。读完本文，你将掌握 GeoAI 的六大核心能力、pip/conda 安装与 GPU 配置方法、分割/分类/检测等模块的关键 API 与参数语义，以及如何通过 YAML/JSON 管道配置和 CLI 命令把端到端工作流跑起来。

一、项目定位：为什么需要 GeoAI

遥感影像 + 深度学习虽然已是环境监测、城市规划、灾害响应与气候研究中的标配技术，但落地时始终存在两个痛点：一是数据预处理复杂（投影、波段、切块、标注组织），二是模型生态碎片化（通用深度学习库与专业地理空间库割裂）。GeoAI 的定位正是提供一个统一的、用户友好的高层接口，把 PyTorch、Hugging Face Transformers、PyTorch Segmentation Models（SMP）以及 torchchange 等框架与 GDAL/rasterio 类地理空间处理流程整合在一起，面向三类用户降低门槛：

• 地理空间研究者：不需要深入掌握机器学习细节即可获得可用的 AI 工作流；
• AI 工程师：希望直接拿到领域相关的数据集与地理预处理工具；
• 教育工作者：需要可复现、可教学的完整示例。

项目在 README（README.md）中明确列出了六大核心能力：

1. 遥感影像与地理空间数据的交互式 / 程序化检索下载；
2. 基于影像切片（image chips）与标签生成的自动化数据集准备；
3. 面向分类、检测、分割任务的模型训练；
4. 面向新数据的推理管线（inference pipelines）；
5. 与 Leafmap、MapLibre 集成的交互式可视化；
6. 基于专用 QGIS 插件的桌面端免代码工作流。

从源码结构看（geoai/ 目录），这些能力分别由 download.py、extract.py（数据准备与建筑物/车辆/船舶/光伏板等专项提取）、train.py（分割/检测/实例分割训练与推理）、inference.py（大影像推理）、pipeline.py（可配置工作流）、map_widgets.py 与 geoai.py（Leafmap 地图）等模块承载，另有 qgis_plugin/ 目录实现桌面端集成。

二、安装与 GPU 配置

2.1 四种安装方式

官方 README 与安装指南（docs/installation.md）均支持以下方式，要求 Python 3.10 及以上：

# pip（最简方式）
pip install geoai-py

# 安装全部可选依赖
pip install "geoai-py[all]"

# uv（更快的 pip 替代）
uv pip install geoai-py

# conda（conda-forge 渠道，可更优雅地解决 GDAL 依赖）
conda install -c conda-forge geoai

# mamba（推荐用于大型包，依赖解析更快）
conda create -n geo python=3.12
conda activate geo
conda install -c conda-forge mamba
mamba install -c conda-forge geoai

2.2 GPU 加速

如需 NVIDIA GPU 加速，安装时需指定带 CUDA 的 PyTorch 构建：

mamba install -c conda-forge geoai "pytorch=*=cuda*"

若在 JupyterLab 中使用交互式绘图，可一并安装 ipympl；若遇到 sqlite 相关问题，可执行 mamba update -c conda-forge sqlite 更新。Windows 用户使用 mamba 安装后可能拿到旧版 torchgeo，导致导入报错，建议补一条 pip install -U torchgeo。

2.3 验证安装

import geoai
print(geoai.__version__)

值得说明的是，import geoai 非常轻量：包顶层（geoai/init.py）实现了 PEP 562 的模块级 __getattr__ 懒加载机制，_LAZY_SYMBOL_MAP 中登记了上百个符号，torch、geopandas、leafmap 等重型依赖只在首次访问具体 API 时才被真正导入。这也意味着：即使当前环境没有装齐 torch 全家桶，import geoai 本身也不会失败，便于在轻量环境中做元信息操作。

三、六大核心能力逐一拆解

3.1 遥感数据检索与下载

GeoAI 的数据下载模块（geoai/download.py）覆盖多类公开数据源，典型入口包括：

• download_naip(bbox, output_dir, year, max_items, preview)：按 bbox 下载 NAIP 航空影像；
• download_overture_buildings(bbox, output, overture_type) / get_overture_data(...)：拉取 Overture Maps 开放数据（如建筑物）用于训练或验证；
• pc_collection_list、pc_stac_search、pc_stac_download、read_pc_item_asset 等：一组基于 Microsoft Planetary Computer STAC API 的检索、下载与预览工具，支持 bbox、time_range、query 过滤条件与多线程并行下载；
• download_file、download_model_from_hf：通用文件下载与从 Hugging Face Hub 下载模型权重（utils 层）。

配合 CLI 可以直接按经纬度范围拉数据：

geoai download naip --bbox -122.5,37.5,-122.4,37.6 --output ./naip.tif --year 2023

CLI 的 download 子命令要求 bbox 为 minx,miny,maxx,maxy 的 EPSG:4326 四元组（见 geoai/cli.py）。

3.2 自动化数据集准备（切片与标签）

训练 AI 模型前，GeoAI 提供"切片 + 标签"的自动化流程，核心在 geoai/utils/training.py：

• export_geotiff_tiles(in_raster, out_folder, in_class_data, tile_size, stride, class_value_field, metadata_format, apply_augmentation, ...)：将大幅 GeoTIFF 切成训练切片，支持栅格/矢量标签数据，可输出 PASCAL_VOC、COCO、YOLO 等元数据格式，并能配合 apply_augmentation 与 augmentation_count 做数据增强；
• export_training_data(...)：经典接口，支持 image_chip_format（如 GEOTIFF）、tile_size_x/y、stride_x/y、output_nofeature_tiles、blacken_around_feature、rotation_angle 等参数；
• export_geotiff_tiles_batch(...)：对影像-掩膜文件夹批量切片，可按文件名匹配影像与掩膜；
• get_default_augmentation_transforms(...) / flipnslide_augmentation(...)：面向地理空间影像的增强工具（翻转 + 滑动）。

配套的栅格-矢量互转工具在 geoai/utils/raster.py：raster_to_vector（含 threshold、min_area、simplify_tolerance、output_format 等参数）、vector_to_raster、mosaic_geotiffs、stack_bands（支持输出 COG、压缩方式可配）等，覆盖 AI 工作流中最常见的格式转换需求。

3.3 模型训练：分割、分类、检测

训练能力集中在 geoai/train.py 与 geoai/classify.py：

• 语义分割：train_segmentation_model(images_dir, labels_dir, output_dir, architecture="unet", encoder_name="resnet34", num_channels, num_classes, ...)，底层基于 SMP（PyTorch Segmentation Models）构建模型（get_smp_model），支持 UNet、DeepLabV3 等架构与 resnet34/resnet50 等编码器，并内置 f1_score、iou_coefficient、precision_score、recall_score 等评估函数；
• 实例分割与目标检测：train_instance_segmentation_model、train_MaskRCNN_model、get_detection_model（默认 fasterrcnn_resnet50_fpn_v2）、get_instance_segmentation_model，支持 COCO/YOLO 标注解析（parse_coco_annotations、parse_yolo_annotations）与自定义数据集类 COCODetectionDataset；
• 图像分类：train_classifier(image_root, label_root, output_dir, in_channels=4, num_classes=14, epochs, img_size, model="unet", backbone="resnet50", loss="ce", class_weights, freeze_backbone, ...) 支持多光谱输入、类别权重与骨干冻结的迁移学习；另有基于 timm 生态的 train_timm_classifier、train_timm_segmentation、train_pixel_regressor（像素回归，见 geoai/timm_train.py、geoai/timm_segment.py、geoai/timm_regress.py）；
• 地表覆盖专项：train_segmentation_landcover（geoai/landcover_train.py）提供 DiceLoss、FocalLoss、TverskyLoss、UnifiedFocalLoss 等多种损失与 compute_class_weights 类别权重计算，支持 ignore_index、边界加权 IoU 等面向类别不平衡场景的配置。

训练完成后，推理侧提供 semantic_segmentation(input_path, output_path, model_path, architecture, encoder_name, num_channels, num_classes, window_size=512, overlap=256, batch_size, device)、object_detection、instance_segmentation 及对应的 _batch 版本，对大影像采用窗口滑推 + 重叠区拼接策略。模型可以推送到 Hugging Face Hub 并在任意环境直接调用（如 push_timm_model_to_hub、predict_detector_from_hub）。

3.4 大影像推理管线

针对大幅 GeoTIFF，geoai/inference.py 提供了专门的推理函数：

• predict_geotiff(model, input_raster, output_raster, tile_size=256, overlap=64, batch_size=4, input_bands, num_classes, output_dtype, blend_mode="spline", blend_power=2, tta, preprocess_fn, postprocess_fn, device, compress="lzw")；
• 关键参数包括切片尺寸 tile_size、相邻切片重叠 overlap、拼接权重模式 blend_mode（spline 样条权重融合）、tta（D4 旋转测试时增强，底层由 d4_forward/d4_inverse/d4_tta_forward 实现）、输入波段选择 input_bands 与自定义前后处理回调；
• 另提供 predict_geotiff_superres 支持超分任务的输出放大。

create_weight_mask(tile_size, overlap, mode, power) 负责生成切片融合权重，保证重叠区域平滑过渡、无明显接缝。

3.5 交互式可视化

可视化能力建立在 Leafmap 与 MapLibre 之上，核心入口是 geoai/geoai.py 中的 LeafMap / Map 类，以及 geoai/map_tools.py 的地图工具集：

• 本地或云端栅格/矢量多图层叠加：add_raster、add_vector、add_cog_layer（COG 云优化栅格）、add_wms_layer、add_vector_tile；
• 样式定制：add_colorbar、add_legend、set_paint_property、set_layout_property、set_color、set_opacity、set_visibility；
• 时间序列可视化：add_nlcd、add_mapillary（街景影像）、add_overture_3d_buildings（Overture 3D 建筑）；
• 地图导出：save_map(output="map.html", title, width, height)。

utils 层还有 view_raster、view_vector、view_vector_interactive、create_split_map（左右对比图）、plot_batch、plot_prediction_comparison 等便捷函数（geoai/utils/visualization.py），用于快速检查切片与预测结果。

3.6 QGIS 桌面端集成

仓库内附完整 QGIS 插件实现（qgis_plugin/），插件在 QGIS 内提供分割（segmentation 面板）、SAM/GroundingSAM（samgeo 面板）、水体分割（water_segmentation）、Moondream 视觉问答（moondream 面板）、实例分割、DeepForest 树冠检测等对话框与对应的异步 worker（qgis_plugin/workers/），并通过环境/虚拟环境管理（qgis_plugin/core/venv_manager.py、uv_manager.py）隔离依赖。这意味着不写代码的用户也可以在 QGIS 桌面环境内直接调用 GeoAI 的 AI 工作流。

四、遥感基础模型目录与加载

README 强调的核心特性之一是内置20 个遥感基础模型（foundation models）的策展目录，实现在 geoai/foundation_models.py 中：

• list_foundation_models(category=None, modality=None, task=None, terratorch_only=False, huggingface_only=False, as_dataframe=True)：返回 pandas DataFrame，可按类别、模态、任务过滤。合法的 category 为 vision、vision-language、generative、vision-location、agents；合法的 modality 为 optical、sar、multispectral、hyperspectral、multimodal、timeseries、lidar，非法取值会抛出 ValueError；
• get_foundation_model_info(name)：返回某个模型（如 "prithvi-eo-2.0-300m"）的完整元数据，包括论文、代码、HuggingFace ID、许可证；
• load_foundation_model(name, pretrained=True, **kwargs)：通过 TerraTorch 骨干注册表加载支持的基础模型（如 Prithvi-EO-2.0、Clay、DOFA、SatlasPretrain 等 terratorch_supported=True 的模型），返回 torch.nn.Module 供推理或微调；需要 pip install geoai-py[terratorch] 安装 TerraTorch，pretrained=False 可得到随机初始化的同架构骨干；
• check_terratorch_available()：检测当前环境是否可导入 TerraTorch。

import geoai

# 查看全部基础模型
df = geoai.list_foundation_models()

# 过滤：vision 类别 + multispectral 模态 + 分割任务
df = geoai.list_foundation_models(category="vision", modality="multispectral", task="segmentation")

# 仅列出 TerraTorch 可直接加载的模型
df = geoai.list_foundation_models(terratorch_only=True)

# 查询单个模型元数据
info = geoai.get_foundation_model_info("prithvi-eo-2.0-300m")
print(info["description"])

# 加载骨干（需 terratorch）
if geoai.check_terratorch_available():
    model = geoai.load_foundation_model("prithvi-eo-2.0-300m")
    print(f"Parameters: {sum(p.numel() for p in model.parameters()):,}")

模型目录数据来源于公开的 Awesome Remote Sensing Foundation Models 列表，仓库内每个条目都记录了 publication、year、backbone、license 等字段，便于按需检索与引用。

五、额外能力：变化检测、目标检测与地理配准

README 的 "Additional Capabilities" 还列出三类能力：

• 变化检测：模块 geoai/change_detection.py 提供基于 ChangeStar 模型的 changestar_detect(image1_path, image2_path, model_name, output_change, output_t1_semantic, output_t2_semantic, output_vector, tile_size=1024, overlap=64, threshold=0.5)，一次推理可同时输出变化图、T1/T2 语义分割图与变化矢量；另有 SAM 驱动的 ChangeStarDetection 类支持 detect_changes 与自动阈值（set_hyperparameters）；
• 目标检测：multiclass_detection、batch_multiclass_detection（geoai/object_detect.py）支持 NWPU VHR-10 数据集一键下载（download_nwpu_vhr10）、多类别检测训练（train_multiclass_detector）、检测结果转 GeoDataFrame（detections_to_geodataframe）；geoai.rfdetr 模块还提供基于 RF-DETR 的 rfdetr_detect / rfdetr_segment / rfdetr_train；
• 地理配准工具：如 geoai/utils/conversion.py 中的 coords_to_xy、rowcol_to_xy、bbox_to_xy，以及 geoai/moondream.py 中视觉语言模型检测结果的 _georef_detections/_georef_points，把像素级 AI 输出（框、点、掩膜）反算到地理坐标，进而导出矢量。

此外，README 中提到的分割成果可导出 GeoJSON / Shapefile / GeoPackage / GeoParquet 等标准格式，主要由 raster_to_vector、masks_to_vector、boxes_to_vector 与 save_vector（geoai/auto.py、geoai/onnx.py 中均有实现）完成。

六、用管道（Pipeline）串起端到端工作流

6.1 管道模型

geoai/pipeline.py 实现了可声明式配置的处理管道：

• Pipeline：由若干 PipelineStep 组成的执行器，支持顺序（_run_sequential）与并行（_run_parallel，按 max_workers/executor_type）执行，支持 on_error（skip 等策略）与断点续跑（CheckpointManager 记录每个 item 的完成状态）；
• 内置步骤：GlobStep（按扩展名收集输入文件）、SemanticSegmentationStep（分割推理）、RasterToVectorStep（掩膜转矢量），并可通过 register_step 注册自定义步骤；
• load_pipeline(config_path, **overrides)：从 YAML 或 JSON 加载管道配置；
• PipelineResult 汇总每个 item 的每个步骤结果，to_json / to_yaml 可导出配置。

仓库提供了可直接参考的示例配置（docs/examples/pipelines/）。以下是语义分割管道 YAML（semantic_segmentation.yaml）：

# Semantic Segmentation Pipeline
# 对输入目录中所有 GeoTIFF 执行 UNet 语义分割，再把掩膜转成 GeoJSON
name: semantic_segmentation
max_workers: 1
executor_type: thread
on_error: skip

steps:
  - type: GlobStep
    name: find_images
    extensions:
      - ".tif"
      - ".tiff"

  - type: SemanticSegmentationStep
    name: segment
    model_path: "path/to/model.pth"
    architecture: unet
    encoder_name: resnet34
    num_channels: 3
    num_classes: 2
    window_size: 512
    overlap: 256
    batch_size: 4
    suffix: "_mask"

  - type: RasterToVectorStep
    name: vectorize
    output_format: ".geojson"
    input_key: output_path
    output_key: vector_path

建筑物提取管道（building_extraction.yaml）与之类似，只是输出换成 GeoPackage 并加了 simplify_tolerance: 1.0 几何简化；JSON 格式的纯矢量批处理管道（batch_vectorize.json）与仅收集文件的管道（glob_only.json）也一并提供。

6.2 CLI 运行

GeoAI 提供 click 实现的命令行工具（geoai/cli.py），核心子命令：

# 查看栅格/矢量文件信息
geoai info path/to/raster.tif

# 下载数据（如 NAIP，bbox 为 EPSG:4326 的 minx,miny,maxx,maxy）
geoai download naip --bbox -122.5,37.5,-122.4,37.6 --output ./naip.tif --year 2023

# 运行管道
geoai pipeline run semantic_segmentation.yaml \
    -i ./data/images -o ./data/results \
    -c ./checkpoints -w 4

# 查看管道配置
geoai pipeline show semantic_segmentation.yaml

其中 pipeline run 的 -i/--input-dir、-o/--output-dir、-c/--checkpoint-dir、-w/--max-workers 与 --on-error 等参数与 YAML 顶层字段一一对应，配置中的 max_workers 可被命令行覆盖。

七、面向 Agent 与 LLM 的检索要点

• 包名：PyPI 上为 geoai-py，conda-forge 上为 geoai；顶层模块统一 import geoai；
• 版本：当前源码顶层 __version__ = "0.43.1"（geoai/init.py）；
• 文档与示例：官方文档站点提供 API 参考与教程，仓库内 docs/ 目录按功能拆分了详细指南（如 docs/segment.md、docs/classify.md、docs/train.md、docs/inference.md、docs/pipeline.md 等），docs/examples/ 下还提供了覆盖分割、检测、变化检测、SAM、基础模型微调等场景的 Jupyter Notebook；
• 支持的数据格式：GeoTIFF、JPEG2000、GeoJSON、Shapefile、GeoPackage 等，栅格读写基于 rasterio/GDAL，矢量基于 geopandas；
• 设备管理：get_device（geoai/utils/device.py）自动选择 GPU/CUDA 可用设备，所有推理类 API 均提供 device 参数；
• 引用方式：README 的 Citations 一节给出了 JOSS 论文（Wu, Q., 2026, Journal of Open Source Software, DOI 10.21105/joss.09605）与配套书籍的引用信息，正式研究引用请以该节为准。

八、常见组合：从数据到成果的最小闭环

把上面的能力串起来，一个典型的"影像 → 建筑物矢量"最小闭环如下：

import geoai

# 1) 数据准备：下载 NAIP 影像并切成训练切片
geoai.download_naip(bbox=(-122.5, 37.5, -122.4, 37.6), output_dir="./naip", year=2023)

# 2) 切片导出（假设已有矢量标签 buildings.shp，class 字段为类别）
geoai.export_geotiff_tiles(
    in_raster="./naip/naip.tif",
    out_folder="./tiles",
    in_class_data="./buildings.shp",
    tile_size=512,
    stride=256,
    metadata_format="PASCAL_VOC",
)

# 3) 训练语义分割模型（SMP UNet + resnet34 编码器）
model = geoai.train_segmentation_model(
    images_dir="./tiles/images",
    labels_dir="./tiles/labels",
    output_dir="./model_output",
    architecture="unet",
    encoder_name="resnet34",
    num_channels=3,
    num_classes=2,
    num_epochs=20,
)

# 4) 对整幅 GeoTIFF 做大影像推理
geoai.semantic_segmentation(
    input_path="./naip/naip.tif",
    output_path="./result_mask.tif",
    model_path="./model_output/best_model.pth",
    architecture="unet",
    encoder_name="resnet34",
    num_channels=3,
    num_classes=2,
    window_size=512,
    overlap=256,
)

# 5) 掩膜转矢量并查看
gdf = geoai.raster_to_vector(
    "./result_mask.tif",
    output_path="./buildings.geojson",
    threshold=0.5,
    min_area=10,
    simplify_tolerance=1.0,
)
print(gdf.head())

结语

GeoAI 的价值不在于重新发明某个模型，而在于把遥感 AI 工作流中重复、繁琐的环节（数据检索、切片标注、格式转换、大影像推理拼接、结果地理化）收敛为一套以 README.md 为入口、以 geoai 顶层 API 为统一面的简洁接口。无论是用 Python 做研究原型、用 CLI 批处理数据，还是借助管道配置把流程产品化，都可以在这个仓库中找到对应的实现与可直接运行示例。下一步建议按 docs/installation.md 完成环境搭建后，挑选一个与自身业务最贴近的 Notebook（如 docs/examples/ 下的分割或检测示例）跑通第一个端到端流程。