sgglab

SGGLab 模型权重

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

权重类型

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

当前文件

其中：

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

目录约定

.
├── 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 客户端：

uv add huggingface-hub

下载单个文件：

from huggingface_hub import hf_hub_download

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

下载整个仓库：

from huggingface_hub import snapshot_download

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

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

加载

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

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。
• 本仓库中的权重不自动继承训练代码或数据集的许可证。使用前请分别确认代码、数据集和权重的授权条件。
• 若权重由第三方项目转换或派生，请在对应条目中保留原始来源和许可证说明。

引用

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