README.md

---
library_name: pytorch
tags:
  - scene-graph-generation
  - sgg
  - remote-sensing
  - pretrained-weights
---

# SGGLab 模型权重

本仓库用于集中存放 **SGGLab 的模型组件预训练权重**与**完成训练的模型权重**。仓库仅提供权重文件；模型结构、配置、数据预处理和推理代码由对应的 SGGLab 项目版本提供。

## 权重类型

- `pretrained/`：可被不同模型复用的组件预训练权重，例如 PPG 等辅助模块。
- `models/`：完成训练、可用于评估或继续训练的模型权重。

## 当前文件

| 文件 | 类型 | 边界框表示 | 说明 |
| --- | --- | --- | --- |
| `pretrained/PPG/PPG_HBB_model.pth` | PPG 组件权重 | HBB | 用于水平边界框任务 |
| `pretrained/PPG/PPG_OBB_model.pth` | PPG 组件权重 | OBB | 用于旋转边界框任务 |

其中：

- **HBB**：Horizontal Bounding Box，水平边界框。
- **OBB**：Oriented Bounding Box，旋转边界框。
- **PPG**：作为场景图生成流程中的预训练组件使用，不能脱离对应模型代码直接完成推理。

## 目录约定

```text
.
├── pretrained/
│   └── <component>/
│       └── <component>_<variant>_model.pth
└── models/
    └── <model>/
        └── <dataset>/
            └── <box_type>/
                └── <task>.pth
```

推荐使用以下取值：

- `<component>`：组件名称，例如 `PPG`。
- `<model>`：模型或方法名称，例如 `RPCM`。
- `<dataset>`：训练使用的数据集名称。
- `<box_type>`：`HBB` 或 `OBB`。
- `<task>`：`PredCls`、`SGCls` 或 `SGDet`。

新增权重时，请同时在“权重清单”中记录其训练配置、适用代码版本和评估结果，避免仅凭文件名判断兼容性。

## 下载

安装 Hugging Face Hub 客户端：

```bash
uv add huggingface-hub
```

下载单个文件：

```python
from huggingface_hub import hf_hub_download

checkpoint_path = hf_hub_download(
    repo_id="<namespace>/<repository>",
    filename="pretrained/PPG/PPG_HBB_model.pth",
)
```

下载整个仓库：

```python
from huggingface_hub import snapshot_download

repository_path = snapshot_download(repo_id="<namespace>/<repository>")
```

请将示例中的 `<namespace>/<repository>` 替换为本仓库在 Hugging Face Hub 上的实际 ID。

## 加载

权重必须由与其结构匹配的 PyTorch 模块加载：

```python
import torch

checkpoint = torch.load(
    "pretrained/PPG/PPG_HBB_model.pth",
    map_location="cpu",
    weights_only=True,
)
model.load_state_dict(checkpoint)
```

不同权重可能保存为纯 `state_dict`，也可能包含 `state_dict`、优化器状态和训练轮次等字段。加载前应先确认对应训练代码的保存格式。不要将 HBB 与 OBB 权重混用，也不要假设不同提交或不同配置生成的同名模块必然兼容。

## 权重清单

发布完整模型时，建议按下表补充信息：

| 模型 | 数据集 | 任务 | 边界框 | 文件 | 代码版本 | 指标 |
| --- | --- | --- | --- | --- | --- | --- |
| 待发布 | — | — | — | — | — | — |

每个权重至少应记录：

1. 模型与配置名称；
2. 数据集及其版本或划分；
3. `PredCls`、`SGCls` 或 `SGDet` 任务；
4. HBB 或 OBB 边界框表示；
5. 对应代码仓库与提交版本；
6. 主要评估指标；
7. 权重来源、许可证及使用限制。

## 兼容性与安全

- `.pth` 文件与模型定义和代码版本强相关，请优先使用权重条目中标注的版本。
- PyTorch 权重可能包含可执行的序列化对象。只加载可信来源的文件，并在格式允许时使用 `weights_only=True`。
- 本仓库中的权重不自动继承训练代码或数据集的许可证。使用前请分别确认代码、数据集和权重的授权条件。
- 若权重由第三方项目转换或派生，请在对应条目中保留原始来源和许可证说明。

## 引用

如在研究中使用本仓库中的权重，请同时引用对应模型、数据集和原始论文。具体引用信息应随每个模型权重条目一并提供。