xuannv_embdding_api

# 玄女 Embedding API 资产库 这个 ModelScope 数据集用于存放 `go-bananas-wwj/embedding-api` 项目的部署资产，包括模型权重、嵌入结果、下游任务头、预测结果、可视化结果和复现实验所需的数据归档。 当前已经发布的版本： - **海淀区 V1 版本**：底座模型为 xuannv P2A embedding 模型，覆盖时间范围为 **2025 年 12 月到 2026 年 5 月**。 - **哈尔滨新区 V1/V2 版本**：底座模型为 xuannv_show，覆盖时间范围为 **2025 年 4 月到 2026 年 5 月**。 ## 当前可用版本 | 区域 | API 版本 | 模型 | 时间范围 | ModelScope 路径 | 状态 | |---|---|---|---|---|---| | 海淀区 | `v1` | xuannv P2A | 2025-12 到 2026-05 | `haidian/v1` | 可用 | | 哈尔滨新区 | `v1` / `v2` | xuannv_show | 2025-04 到 2026-05 | `harbin/v1` | 可用 | ## 海淀区 V1 包含哪些内容 ```text haidian/v1/ README.md manifest.json checksums.sha256 api_ready/ data/haidian/ patches_meta_v1.json embeddings/v1/{月份}/{patch_id}.npy embeddings/v1/{月份}/{patch_id}.png embeddings/v1/{月份}/{patch_id}.json tasks/{任务}/v1/predictions/{patch_id}.npy tasks/{任务}/v1/results/tiles/{patch_id}.png tasks/{任务}/v1/labels/{patch_id}.npy models/haidian/v1/ embedding/best.pt embedding/config.yaml task_heads/{任务}/{下游头}/best.pt task_heads/{任务}/{下游头}/metrics.json archive/ raw_training_data/haidian_202512_202605/ processed_training_data/haidian_202512_202605.tar training_output/ downstream_osm_eval/ benchmark_eval/ training_data_summary.json ``` 其中： - `api_ready/`：部署 API 时真正需要下载的内容。 - `archive/`：训练数据、训练输出、测评输出等归档内容，主要用于复现和审计。 - `manifest.json`：资产包的基本信息，例如区域、版本、月份、任务数量等。 - `checksums.sha256`：文件校验表，用于检查文件是否完整。 ## 哈尔滨新区 V1/V2 包含哪些内容 由于哈尔滨新区静态资产文件数量超过 15 万个，超出了 ModelScope 单目录文件数限制，因此 `harbin/v1/api_ready` 采用 **tar 归档**方式存放。每个归档解压后都会恢复为与本地项目一致的目录结构。 ```text harbin/v1/ README.md manifest.json checksums.sha256 api_ready/ data_harbin.tar # data/harbin：embedding、任务结果/预测/标签、patches_meta models_harbin.tar # models/harbin：哈尔滨系统模型 checkpoint models_sam3.tar # models/sam3：SAM3 交互式分割权重 raw_harbin.tar # /workspace/raw/harbin：mosaic 大图使用的 S2/S1/Landsat 原始 TIFF raw_harbin_scenes.tar # /workspace/raw/harbin_scenes：SAM3/embedding 使用的多时相 S2 场景 ``` 哈尔滨新区支持的接口/任务： - `GET /regions/harbin/patches/{patch_id}/embedding`：v1 / v2 embedding 查询。 - `POST /models/{model_id}/infer`：支持自定义模型和系统预训练模型： - `land_cover_classification`（土地覆盖分类） - `water_extraction`（水体提取） - `building_extraction`（建筑物提取） - 专题任务结果： - `change_detection`（变化检测） - `building_extraction`（建筑物提取，映射原 construction 任务） - `land_use_classification`（土地利用分类，映射原 farmland/land_conversion 任务） ## 容量说明 下面是当前资产的大致大小，实际显示会因为文件系统和压缩方式略有差异： ### 海淀区 V1 | 内容 | 路径 | 大小 | |---|---|---:| | 完整海淀区 V1 包 | `haidian/v1/` | 约 95G | | API 部署必需内容 | `haidian/v1/api_ready/` | 约 9.5G | | API 数据部分 | `haidian/v1/api_ready/data/haidian/` | 约 7.8G | | 6 个月 embedding 总量 | `haidian/v1/api_ready/data/haidian/embeddings/` | 约 7.6G | | 每个月 embedding | `haidian/v1/api_ready/data/haidian/embeddings/v1/{月份}/` | 约 1.3G/月 | | 下游任务预测和可视化总量 | `haidian/v1/api_ready/data/haidian/tasks/` | 约 117M | | 建筑物提取结果 | `haidian/v1/api_ready/data/haidian/tasks/building_extraction/` | 约 33M | | 道路提取结果 | `haidian/v1/api_ready/data/haidian/tasks/road_extraction/` | 约 33M | | 施工变化检测结果 | `haidian/v1/api_ready/data/haidian/tasks/construction/` | 约 26M | | 联合施工变化检测结果 | `haidian/v1/api_ready/data/haidian/tasks/construction_joint/` | 约 27M | | API 模型权重 | `haidian/v1/api_ready/models/haidian/` | 约 1.8G | | 复现归档总量 | `haidian/v1/archive/` | 约 86G | | 原始训练数据 | `haidian/v1/archive/raw_training_data/` | 约 64G | | 预处理训练数据归档 | `haidian/v1/archive/processed_training_data/` | 约 15G | | P2A 训练输出 | `haidian/v1/archive/training_output/` | 约 7.2G | | OSM 下游测评输出 | `haidian/v1/archive/downstream_osm_eval/` | 约 134M | | 变化检测基准测评输出 | `haidian/v1/archive/benchmark_eval/` | 约 42M | 如果只是部署 API，通常只需要下载 `haidian/v1/api_ready/`，大约 `9.5G`；不需要下载 `archive/`。 ### 哈尔滨新区 V1/V2 | 内容 | 路径 / 归档 | 大小 | |---|---|---:| | 完整哈尔滨 V1/V2 包 | `harbin/v1/` | 约 31.14G | | API 数据与任务结果 | `harbin/v1/api_ready/data_harbin.tar` | 约 12.59G | | 哈尔滨系统模型权重 | `harbin/v1/api_ready/models_harbin.tar` | 约 422.42MB | | SAM3 分割模型权重 | `harbin/v1/api_ready/models_sam3.tar` | 约 3.22G | | mosaic 原始 TIFF（S2/S1/Landsat） | `harbin/v1/api_ready/raw_harbin.tar` | 约 2.80G | | 多时相 S2 场景 | `harbin/v1/api_ready/raw_harbin_scenes.tar` | 约 12.12G | 如果只是部署 embedding 推理和普通专题任务接口，通常只需要下载 `data_harbin.tar` 和 `models_harbin.tar`，大约 `13G`；如果需要 SAM3 交互式分割，再额外下载 `models_sam3.tar`；如果需要整区域 mosaic 大图，再下载 `raw_harbin.tar` 和 `raw_harbin_scenes.tar`。 ## 覆盖月份 ### 海淀区 V1 海淀区 V1 包含以下 6 个月份的 embedding： - `202512` - `202601` - `202602` - `202603` - `202604` - `202605` ### 哈尔滨新区 V1/V2 哈尔滨新区 V2 包含以下月份的 embedding（V1 为其中较早的子集）： - `2025-04`、`2025-06`、`2025-08`、`2025-09`、`2025-10` - `2026-01`、`2026-02`、`2026-03`、`2026-04`、`2026-05` ## 支持的下游任务 ### 海淀区 V1 | 任务名 | 说明 | |---|---| | `building_extraction` | 建筑物提取，标签主要来自 OSM 派生结果 | | `road_extraction` | 道路/路网提取，标签主要来自 OSM 派生结果 | | `construction` | 海淀区施工变化检测 | | `construction_joint` | 联合施工变化检测基准中的海淀区子集 | 每个任务都包含： - `.npy` 概率图：用于程序读取和后续分析。 - `.png` 可视化图：红色表示预测前景，白色表示背景，方便人工查看。 - 下游任务头权重：保存在 `models/haidian/v1/task_heads/` 下。 ### 哈尔滨新区 | 任务名 | 说明 | |---|---| | `change_detection` | 基于两期 embedding 差分的变化检测 | | `building_extraction` | 建筑物提取与建筑工地监测 | | `land_use_classification` | 土地利用分类与转换监测 | | `land_cover_classification` | 土地覆盖分类（系统预训练模型） | | `water_extraction` | 水体提取（系统预训练模型） | ## 快速部署方式 先克隆 API 项目： ```bash git clone [e-mail]:go-bananas-wwj/embedding-api.git cd embedding-api ``` 安装 ModelScope 命令行工具： ```bash pip install modelscope ``` ### 海淀区 V1 下载海淀区 V1 的 API 部署资产： ```bash export MODELSCOPE_TOKEN="你的 ModelScope Token" # 如果数据集是公开的，可以不设置 python pipelines/haidian/download_modelscope_assets.py \ --repo WeijieWu/xuannv_embdding_api \ --prefix haidian/v1/api_ready \ --target . ``` ### 哈尔滨新区 V1/V2 下载哈尔滨新区完整资产（约 31 GB）： ```bash export MODELSCOPE_TOKEN="你的 ModelScope Token" python pipelines/harbin/download_modelscope_assets.py \ --repo WeijieWu/xuannv_embdding_api \ --prefix harbin/v1/api_ready \ --target . \ --verify-checksums ``` 下载完成后，项目根目录下会出现： ```text data/haidian/... data/harbin/... models/haidian/... models/harbin/... models/sam3/... ``` 同时 `/workspace/raw/harbin` 和 `/workspace/raw/harbin_scenes` 会被解压到绝对路径。 然后启动 API： ```bash DOCS_URL=/docs uvicorn app.main:app --host 0.0.0.0 --port 9061 ``` 启动后打开： ```text http://localhost:9061/docs ``` ## 快速检查 API 是否可用 可以用下面几条命令做最小化检查： ```bash # 区域列表 curl -s "http://localhost:9061/regions" | python -m json.tool # 海淀区 curl -s "http://localhost:9061/regions/haidian/patches?page=1&page_size=2" | python -m json.tool curl -s "http://localhost:9061/regions/haidian/patches/patch_000000/embedding?format=json&version=v1&month=202512" | python -m json.tool curl -s "http://localhost:9061/regions/haidian/patches/patch_000000/tasks/road_extraction/result?format=png&version=v1" -o /tmp/haidian_road.png # 哈尔滨新区 curl -s "http://localhost:9061/regions/harbin/patches/patch_000000/embedding?format=json&version=v2&month=2025-04" | python -m json.tool curl -s "http://localhost:9061/regions/harbin/patches/patch_000000/embedding?format=png&version=v2&month=2025-04" -o /tmp/harbin_emb.png ``` 如果这些接口能正常返回，就说明对应区域的资产已经部署成功。 ## 直接使用 ModelScope CLI 下载 ### 海淀区 V1 如果不使用项目里的下载脚本，也可以直接下载 `api_ready` 部分： ```bash modelscope download \ --dataset WeijieWu/xuannv_embdding_api \ --include "haidian/v1/api_ready/**" "haidian/v1/manifest.json" "haidian/v1/README.md" \ --local_dir ./modelscope_cache ``` 然后把下面这个目录里的内容复制到 `embedding-api` 项目根目录： ```text modelscope_cache/haidian/v1/api_ready/ ``` ### 哈尔滨新区 V1/V2 ```bash modelscope download \ --dataset WeijieWu/xuannv_embdding_api \ --include "harbin/v1/api_ready/**" "harbin/v1/manifest.json" "harbin/v1/README.md" \ --local_dir ./modelscope_cache ``` 然后使用 `pipelines/harbin/download_modelscope_assets.py` 或手动解压各个 tar 归档到对应位置。 ## 文件格式说明 - Embedding 文件：`.npy`，形状为 `[C, H, W]`。 - Embedding 预览图：`.png`，由 PCA 降到 RGB 后生成。 - 任务预测结果：`.npy`，表示每个像素属于目标类别的概率。 - 任务可视化图：`.png`，红色为预测前景，白色为背景。 - 标签文件：`.npy`，uint8 mask。 - 模型权重：`.pt`，PyTorch checkpoint。 ## 普通部署只需要哪些内容 如果只是部署 API，只需要下载： ```text haidian/v1/api_ready/ harbin/v1/api_ready/ ``` `archive/` 目录很大，里面主要是原始训练数据、预处理数据、训练日志和测评结果，普通部署不需要下载。