Skip to content

GeoAdapter_Verification_Guide.md

Latest commit

 

History

History
187 lines (137 loc) · 7.3 KB

GeoAdapter_Verification_Guide.md

File metadata and controls

187 lines (137 loc) · 7.3 KB
Raw

GeoAdapter 系统完整验证指南

自动化测试结果（已通过）

以下测试已由 Claude 在本地执行并全部通过，你无需重复运行：

测试项 结果 详情
37 个单元测试 PASS (11.67s) adapters/prithvi/heads/trainer/datasets
GeoAdapter 适配器 (5 种输入通道) PASS 2ch/3ch/4ch/5ch/10ch → 6ch 全部正确
ZeroPad 通道保持 PASS 前 N 通道保留，后续补零
Prithvi-100M 真实权重加载 PASS 86,237,184 参数，12 层，全冻结
Prithvi 多尺寸输入 PASS 64x64 / 128x128 / 224x224 均输出 [B,768]
完整训练管线 (GeoAdapter+Prithvi+Head) PASS loss=2.41, predict 正常
5 种 PEFT 参数量 PASS LoRA=147K, BitFit=103K, Houlsby=1.19M, GeoAdapter=147, LinearProbe=0
真实 ZY3 数据 → GeoAdapter → Prithvi PASS 4 波段 uint16 → 归一化 → 6ch → 768 维特征
ae_backend 集成 PASS PrithviAlphaEarthEncoder 使用 geoadapter 内部模块
Benchmark dry-run PASS 75 实验组合正确列出

前端页面手动验证指南

前端有 3 个主页面，共 12 个交互功能点。以下按操作顺序逐一说明。

前置条件

  1. PostgreSQL 数据库可连接（119.3.175.198，配置在 .env）
  2. 启动后端服务：
cd D:\adk\AlphaEarth-System\ae_backend
set PYTHONPATH=D:\adk\AlphaEarth-System
D:\adk\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8085 --reload
  1. 浏览器打开 http://localhost:8085

如果启动失败（数据库连接错误），检查 .env 中的 POSTGRES_PASSWORD 是否正确。

页面一：数据源与预处理流水线

点击左侧边栏【数据源与预处理流水线】进入。

功能点 1：搜索行政区

  • 在"搜索行政区"输入框中输入关键词，如 和平 或 璧山
  • 预期：下拉列表显示匹配的乡镇级行政区（来自 PostGIS xiangzhen 表）
  • 点击选中一个区域，输入框显示完整名称（如 重庆市-璧山区-璧泉街道-和平村）
  • 验证点：如果数据库中没有 xiangzhen 表数据，下拉列表为空——这是正常的，说明需要先导入行政区边界数据

功能点 2：刷新卫星列表

  • 点击【刷新卫星】按钮
  • 预期：表格显示可用的卫星数据源（来自外部 API 3d.img.net）
  • 如果网络不通，会显示错误提示——这不影响核心功能

功能点 3：勾选卫星 + 数据源适配性分析

  • 在卫星列表中勾选 1-3 个数据源（如 Sentinel-2、Sentinel-1）
  • 点击【分析数据源适配性】按钮
  • 预期：显示雷达图评分（光谱覆盖、空间分辨率、时间密度、模态丰富度、数据就绪度）
  • 验证点：评分逻辑在 ae_backend/app/api/pipeline.py 的 analyze 端点

功能点 4：启用内存直通模式

  • 勾选 启用内存直通(Zero-Copy)模式 复选框
  • 这控制数据融合管线是写磁盘还是存内存
  • 验证点：勾选后，后续生成的切片会存在 IN_MEMORY_DATASETS 字典中

功能点 5：生成训练切片

  • 确保已选择区域 + 至少 1 个数据源
  • 点击【生成训练切片任务】
  • 预期：
    • 进度条从 0% 推进到 100%
    • 日志区域显示处理步骤（提取边界 → 下载/裁切 → 归一化 → 切片）
    • 完成后显示生成的 patch 数量和吞吐量
  • 可能的问题：
    • GEE 下载超时（需要 Google Earth Engine 认证 + 网络通畅）
    • 如果没有 GEE 认证，只能处理本地 raw_samples/ 目录下的 ZY3 数据
    • 数据库中没有对应行政区的边界数据时，会使用默认回退边界

功能点 6：查看已生成的数据集

  • 切片完成后，数据集会出现在训练监控页面的下拉菜单中
  • 带 [内存直通] 标志的数据集表示存在内存中

页面二：训练监控驾驶舱

点击左侧边栏【训练监控驾驶舱】进入。

功能点 7：选择数据集

  • 顶部下拉菜单显示所有已生成的数据集
  • 选择一个数据集（如果没有，需要先在"数据源"页面生成）

功能点 8：开始训练

  • 点击橙色【开始训练】按钮
  • 预期：
    • 按钮变为【停止训练】
    • 终端日志区域开始滚动显示训练日志
    • 左侧 ECharts 图表实时更新 Loss 曲线（重构损失 + 均匀性损失）
    • 右侧散点图显示 PCA 降维后的 64 维特征分布
    • 顶部指标卡片更新：当前 Epoch、Loss 值、GPU 显存、预估剩余时间
  • 训练完成后：
    • 日志显示"训练完成！本地模型权重已安全保存"
    • 如果配置了华为云 OBS，会自动上传权重
    • 模型自动注册到数据库

功能点 9：观察 Loss 收敛

  • 训练过程中，观察 Loss 曲线是否下降
  • 重构损失（蓝线）应该持续下降
  • 均匀性损失（橙线）应该趋于稳定
  • 验证点：如果 Loss 不下降或出现 NaN，说明数据预处理有问题

功能点 10：观察特征空间演化

  • 右侧 PCA 散点图每个 Epoch 更新一次
  • 早期（Epoch 1-5）：点聚成一团
  • 中期（Epoch 20-30）：开始分离出簇
  • 后期（Epoch 50）：形成清晰的聚类结构
  • 验证点：这是论文 Fig.6 的数据来源

页面三：模型资产库

点击左侧边栏【模型资产库】进入。

功能点 11：查看 + 评测模型

  • 点击【刷新模型列表】
  • 预期：显示所有已训练完成的模型卡片（名称、评分、OBS 路径、创建时间）
  • 点击某个模型的【评测】按钮
  • 预期：
    • 系统加载模型权重，对训练数据做推理
    • 计算 KMeans 聚类 + Silhouette Score
    • 返回评测结果（重构损失、轮廓系数、下游精度估计、特征维度）
  • 验证点：评测结果中 silhouette_score 应该 > 0（正值表示特征有区分度）

功能点 12：激活默认模型

  • 点击某个模型的【设为默认预测模型】按钮
  • 预期：该模型标记为 Active，其他模型取消激活
  • 验证点：刷新后只有一个模型显示为激活状态

端到端完整流程验证

如果以上 12 个功能点都要走一遍，推荐按以下顺序操作：

1. 启动后端 (uvicorn)
2. 打开浏览器 http://localhost:8085
3. 进入【数据源与预处理流水线】
   3.1 搜索行政区 → 选择一个区域
   3.2 刷新卫星 → 勾选数据源
   3.3 分析适配性 → 查看雷达图
   3.4 勾选内存直通模式
   3.5 生成训练切片 → 等待完成
4. 进入【训练监控驾驶舱】
   4.1 选择刚生成的数据集
   4.2 开始训练 → 观察 Loss 曲线和 PCA 散点图
   4.3 等待 50 Epoch 完成
5. 进入【模型资产库】
   5.1 刷新列表 → 看到新模型
   5.2 评测模型 → 查看 Silhouette Score
   5.3 激活模型

已知限制

限制 影响 解决方案
GEE 认证 无法下载 Sentinel 公开数据 只用本地 ZY3 数据测试，或配置 GEE 认证
数据库行政区数据 搜索行政区可能无结果 需要 xiangzhen 表有数据，或使用外部 API
华为云 OBS 权重无法上传云端 不影响本地训练和评测，权重保存在本地
无 GPU 训练速度慢 CPU 上 50 Epoch 约 2-5 分钟（取决于切片数量）
前端 CDN 依赖 需要网络加载 Vue/ECharts/Tailwind 离线环境需要本地化这些 CDN 资源