关于 geo-deep-learning
geo-deep-learning 是面向地球观测数据深度学习的工作流技能，帮助评估任务、构建训练流程并验证结果。它重点防止空间泄漏，并确保预测保留地理配准信息。
主要功能
- 01评估标签集与任务类型
- 02按地理区域独立划分数据
- 03构建保留地理配准的切片流程
- 04训练与推理指导
- 05通过地图检查输出
适用场景
- 01决定采用深度学习还是基线方法
- 02准备避免训练验证泄漏的数据切片
- 03为大型场景生成对齐的预测结果
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/geo-deep-learning确认已加载。
附带文件agents/openai.yamlreferences/authoritative-sources.md
详细介绍
地理空间深度学习
目的：开展地球观测深度学习，并从一开始就规避主导该领域的两种失效模式：空间泄漏 （相邻训练/测试像素导致指标虚高）和地理参考信息丢失 （预测结果不再与地图对齐）。
在选择架构前，先描述标签集
不了解标签集就给出架构建议，无异于猜测。在推荐 U-Net、基础模型还是非深度学习基线之前，请说明或询问：
- 标签数量和标注面积 — 仅知道多边形数量并不能说明问题；覆盖 2 ha 的 40 个多边形，与覆盖 2 000 km² 的 40 个多边形是不同的问题。
- 地理分布范围 — 标签是集中在一个影像场景、一个季节和一种传感器上，还是分布在整个部署区域内？标签集中会限制任何模型的泛化能力，也决定是否能构建地理位置相互独立的验证集。
- 类别平衡和少数类像素占比，以便有依据地选择损失函数和采样方案，而不是凭空假设。
- 部署地理范围 — 将进行预测的位置，以及这些位置相对于标签所在位置的关系。
在了解这些信息之前，不要回答“微调大模型或采用更简单的方法”。如果用户未提供这些信息，请先询问，并根据答案给出有条件的初步建议（“如果这 40 个多边形都在一个影像场景中，那么……；如果它们分布在整个区域内，那么……”），切勿只给出一个无条件的建议。
先确定问题框架
| 任务 | 默认头部/架构 | 指标 |
|---|---|---|
| 逐像素分类（地表覆盖） | U-Net / DeepLabv3+（预训练编码器） | mIoU、各类别 IoU |
| 二值提取（建筑物、水体、道路） | U-Net + Dice/CE 混合损失 | IoU、F1；道路使用边界 F1 |
| 目标检测（车辆、船舶、树木） | YOLO 系列 / Faster R-CNN；目标有方向时使用旋转框 | mAP@50 |
| 场景分类 | 微调后的 CNN/ViT | F1（宏平均） |
| 回归（高度、生物量、密度） | 带回归头的 U-Net | RMSE/MAE + 空间残差图 |
在使用任何深度模型之前，先运行一个低成本基线（基于波段和指数的随机森林，或阈值化指数）。如果深度学习模型无法明显胜过基线，问题出在数据，而非架构。segmentation-models-pytorch 和 torchgeo 可满足大多数需求 — 没有理由时，不要手动构建架构。
切片（数据集构建）
- 切片大小：256–512 px；仅在训练时使用小于切片大小的步长（通过重叠扩充数据），切勿让重叠切片跨越训练/验证集边界。
- 保留地理参考信息：存储每个切片的变换参数/边界（使用 torchgeo 数据集或 GeoParquet 旁车索引）。无法放回地图上的预测毫无价值。
- 保持切片处于原生数据范围；使用根据数据集计算的逐波段统计量进行归一化（仅对使用预训练编码器的 3 波段 RGB 使用 ImageNet 统计量，并明确说明）。
- 类别不平衡是常态（建筑物约占像素的 2–5%）。记录每个切片的类别占比；对包含正样本的切片进行过采样，而不是将损失函数扭曲得面目全非。
划分策略 — 不容妥协
按地理区块或影像场景划分，绝不随机划分切片。相邻切片几乎是重复数据；随机划分会产生漂亮但虚假的验证曲线。遵循规范流程：
ml-experiment-standards → references/spatial-cv-protocol.md。
如果要声称模型可泛化到不同区域，请留出一个完整区域作为测试集。
训练默认设置
- 损失函数：Dice + CE（用于不平衡的分割任务）；数据均衡时使用普通 CE；只有经过比较后才使用 Focal——它并非总能带来提升。
- 数据增强：对天底影像来说，翻转和 rot90 是安全的；多光谱影像使用颜色抖动时要谨慎（这会破坏辐射意义，优先使用波段丢弃或轻微缩放）；切勿采用违背物理规律的数据增强方式。
- 使用预训练编码器；多光谱输入 → 扩展或替换第一个卷积层，或者在波段匹配时使用地球观测（EO）基础模型检查点（Prithvi、SatMAE、Clay）。
- 根据验证集 mIoU 进行早停（patience 10-15）；使用余弦或 plateau 学习率调度；默认启用 AMP。
- 每次运行都记录配置、指标和 git 哈希——参见
ml-experiment-standards。
大场景推理
采用带重叠的滑动窗口（25-50%），并进行融合（羽化/高斯融合或中心裁剪拼接），以消除切片边缘伪影。然后：
import rasterio
with rasterio.open(scene_path) as src:
profile = src.profile
profile.update(count=1, dtype="uint8", nodata=255, compress="deflate")
with rasterio.open(out_path, "w", **profile) as dst:
dst.write(mask.astype("uint8"), 1) # same transform/CRS as the scene
后处理：筛除微小斑块（最小制图单元），可选择对建筑物多边形进行规则化，并矢量化（rasterio.features.shapes）以交付给 GIS。后处理后也要报告指标——这才是用户最终拿到的成果。
验证协议
- 指标表：按类别报告 IoU/F1，并提供跨随机种子或折的置信区间。
- 误差图：将预测结果与参考数据叠加在影像上，覆盖 3 个以上有代表性的区域，其中包括一个已知的困难区域。
- 在分布外影像块（不同季节/区域）上进行合理性推理检查，并如实说明性能下降情况。
- 配准检查：在 GIS 中以两个缩放级别将预测结果叠加到源场景上——可立即发现变换错误。
常见问题检查清单
- 随机划分影像块 → 产生数据泄漏、无法复现的“最先进”结果。
- 未保存训练时统计量，导致测试数据归一化方式不一致 → 推理结果偏差。
- 在 NumPy 中丢失地理变换信息；写入预测结果时使用默认的北向上变换。
- 推理时不进行重叠处理，导致切片边缘出现接缝。
- 将 uint16 影像输入浮点处理流程却未缩放 → 梯度失效。
- 在影像块级别报告准确率，但实际产品是拼接后的地图。
执行约定
- **工作流：**明确目标和预测单位；构建影像块和标签；创建空间划分；以基线为参照进行训练；运行考虑重叠的推理；验证拼接后的产品。
- **决策规则：**只有在标签量、空间纹理、计算资源和预期提升均足以支持时才使用深度学习；否则优先采用更简单的遥感或 ML 工作流。
- **验证协议：**报告跨随机种子或折的空间留出指标，检查误差图和困难区域，测试地理迁移能力，并检查输出的地理配准。
- **失败模式：**若存在影像块泄漏、标签错位、训练/推理归一化偏差、切片接缝，或指标的计算单位与产品单位不符，则结果无效。
- **交付物：**模型和配置、划分清单、预处理约定、带不确定性的指标、地理配准后的预测结果、误差图，以及说明模型局限的模型卡。
- **源信息时效性：**选择框架 API、数据集或权重前，请查阅权威来源注册表，并记录查阅日期。