复现项目需要的步骤
指南涵盖了环境搭建、数据集准备、模型推理和训练的流程：
1. 克隆项目代码
首先从官方仓库克隆代码：
git clone https://github.com/ai4ce/MSG.git
cd MSG
2. 配置运行环境
项目提供了两种方式来设置运行环境，推荐使用 environment.yml 方法，以确保完整的环境依赖。
方法 1：使用 requirements.txt
如果想搭建最小依赖环境：
conda create --name msg python=3.11.8
conda activate msg
pip install -r requirements.txt
方法 2：使用 environment.yml
如果想完全复现官方环境：
conda env create -f environment.yml
conda activate msg
提示：第二种方法可以避免遗漏依赖项，推荐使用。
3. 数据集准备
官方数据集基于 Apple 的 ARKitScenes 转换而来，需要从 Huggingface 下载：
下载和解压数据
- 下载数据：
- 数据链接在 Huggingface Dataset Hub 中。
- 下载以下压缩包：
Training_aa.zip至Training_aj.zipValidation.zipTest.zipmini-val.zip
这个脚本是一个非常好的选择，直接利用 huggingface_hub 库自动批量下载 Huggingface 上的数据集文件。以下是确保脚本正确运行的操作步骤：
操作步骤
1. 安装 huggingface_hub
在运行脚本之前，确保安装了 huggingface_hub 库。运行以下命令：
pip install huggingface_hub
2. 准备脚本
将您提供的脚本保存为一个 Python 文件，例如 download_msg.py：
from huggingface_hub import hf_hub_downloadfiles = ["Test.zip","Training_aa.zip","Training_ab.zip","Training_ac.zip","Training_ad.zip","Training_ae.zip","Training_af.zip","Training_ag.zip","Training_ah.zip","Training_ai.zip","Training_aj.zip","Validation.zip","mini-val.zip"
]for file in files:hf_hub_download(repo_id="ai4ce/MSG", filename=f"data/{file}", repo_type="dataset", local_dir="./data/msg")
3. 运行脚本
运行以下命令启动脚本：
python download_msg.py
下载文件说明
-
hf_hub_download参数：repo_id: 数据集的 ID，这里是"ai4ce/MSG"。filename: 文件的路径，这里以data/为前缀。repo_type: 数据类型，这里是dataset。local_dir: 下载到的本地目录，这里是./data/msg。
-
存储路径：
下载完成后，文件会存储到./data/msg目录，形成如下结构：./data/msg/ ├── Test.zip ├── Training_aa.zip ├── Training_ab.zip ├── ... ├── Validation.zip ├── mini-val.zip
后台运行（可选）
如果文件较大，下载可能需要较长时间。为了避免 SSH 会话中断影响下载任务，可以用以下方式让脚本在后台运行：
使用 nohup 后台运行：
nohup python download_msg.py > download.log 2>&1 &
> download.log: 将下载进度记录到download.log文件。&: 将任务放到后台。
查看日志：
tail -f download.log
验证文件完整性
下载完成后，建议检查文件大小与 Huggingface 页面显示是否一致。可以运行以下命令：
ls -lh ./data/msg/
优势
- 自动化：无需手动操作，脚本会自动逐一下载。
- 重用性：如有文件下载失败，可以重新运行脚本，
hf_hub_download会自动跳过已存在的文件。
检测数据是否完整
解压后的目录应如下：
./data/msg/
├── Training/
├── Validation/
├── Test/
├── mini-val/
4. 预训练模型准备
-
下载预训练模型：
- 预训练的 AoMSG 模型可从 Huggingface 数据库下载。
- 将模型下载到
./exp-results/aomsg目录下：mkdir -p ./exp-results/aomsg # 将预训练模型文件移动到此目录
-
检查路径：
确保模型的路径如下：./exp-results/aomsg/ └── [预训练模型文件，如 29-step22470+.pth]
5. 推理（Inference）
使用预训练模型进行推理：
python inference.py --experiment inference
配置文件说明
默认配置文件为 ./configs/experiments/inference.yaml，以下参数可以覆盖 YAML 文件中的配置：
- 数据集路径：
--dataset_path - 模型权重路径：
--eval_output_dir - 使用的 checkpoint 文件：
--eval_chkpt
示例：
python inference.py --experiment inference \
--dataset_path ./data/msg \
--eval_output_dir ./exp-results/aomsg \
--eval_chkpt 29-step22470+.pth
6. 训练
训练 AoMSG 模型
运行以下命令：
python train.py --experiment aomsg
- 配置文件：
./configs/experiments/aomsg.yaml
训练 SepMSG 基线模型
运行以下命令：
python train.py --experiment sepmsg
- 配置文件：
./configs/experiments/sepmsg.yaml
从 checkpoint 恢复训练
在 YAML 文件中设置以下参数：
resume: true
resume_path: ./exp-results/aomsg/[checkpoint_file.pth]
7. 评估
评估训练好的模型性能：
- 评估 AoMSG：
python eval.py --experiment aomsg - 评估 SepMSG：
python eval.py --experiment sepmsg - 评估直接使用冻结特征的模型：
python eval.py --experiment direct
8. 注意事项
-
目标检测依赖：
- 当前版本未包含对象检测的代码。您需要单独运行目标检测，并将检测结果存储到指定路径。
- GroundingDINO 结果文件已在数据集中提供，可直接使用。
- 在
./configs/experiments/aomsg_gdino.yaml中，指定目标检测结果路径。
-
在线检测：
- 当前版本不支持在线检测，后续版本可能会支持。
9. 数据处理（可选）
如果想要自定义数据转换，可参考 data_preprocess 中的代码来复现从 3D 注释到 2D 数据的转换过程。
10. 结果可视化
推理结果和可视化会保存在指定的 eval_output_dir 下，您可以在本地查看结果文件（如 JSON 文件或图片）。
服务器上可以使用的下载方法
在服务器上可以使用以下方法，让下载任务在后台运行，同时确保任务不会因为会话断开而停止：
方法 1：使用 nohup
nohup 命令允许进程在后台运行，即使你断开 SSH 会话，任务也会继续执行。
-
运行后台下载任务：
nohup wget -i file_list.txt > download.log 2>&1 &wget -i file_list.txt: 批量下载文件。> download.log: 将输出记录到download.log文件中，便于查看进度。2>&1: 将标准错误重定向到日志文件中。&: 将任务放入后台运行。
-
检查运行状态：
- 查看后台任务：
jobs - 如果需要重新连接任务，使用：
fg %1
- 查看后台任务：
-
查看下载日志：
- 你可以通过以下命令查看日志：
tail -f download.log
- 你可以通过以下命令查看日志：
方法 2：使用 screen
screen 是一个多窗口管理工具，允许你在断开连接后重新连接到任务。
-
启动一个新会话：
screen -S download -
运行下载任务：
在新窗口中运行下载命令：wget -i file_list.txt -
分离会话：
按下Ctrl + A，然后按D键，可以将会话分离到后台。 -
重新连接会话：
当你重新登录服务器时，使用以下命令重新连接：screen -r download
方法 3：使用 tmux
tmux 是类似于 screen 的工具，可以管理多个终端会话。
-
启动
tmux会话：tmux new -s download -
运行下载任务：
在会话中运行下载命令：wget -i file_list.txt -
分离会话：
按下Ctrl + B，然后按D，将会话分离到后台。 -
重新连接会话：
当需要重新连接时，运行：tmux attach -t download
方法 4：使用 & 和 disown
-
运行下载任务：
wget -i file_list.txt > download.log 2>&1 & -
断开任务与当前会话的关系：
disown
方法对比
| 方法 | 优点 | 缺点 |
|---|---|---|
nohup |
简单易用，适合短期任务 | 不支持任务管理，需手动查看日志 |
screen |
可重连会话，支持多个任务管理 | 初次使用需要记住快捷键 |
tmux |
功能强大，支持分屏、重连 | 配置稍复杂，初次使用需学习 |
& + disown |
命令简单，适合小任务 | 无法重连任务，需谨慎使用 |
推荐方法
- 如果任务较多且复杂，推荐使用
screen或tmux。 - 如果是简单的批量下载，推荐使用
nohup。
对于你描述的这种批量下载多个大文件的场景（Huggingface 数据集），建议使用 nohup 或 tmux，具体选择取决于以下因素：
推荐 1：nohup（简单高效，适合一次性下载）
如果你只需要运行一个简单的批量下载任务，不需要频繁监控或重新进入任务，那么 nohup 是最合适的选择。
优点：
- 简单易用，无需额外学习或配置。
- 下载完成后可以查看日志文件，检查是否有错误。
- 适合这种短时间的批量下载任务（只下载一组文件）。
操作步骤：
-
运行命令：
nohup wget -i file_list.txt > download.log 2>&1 &wget会读取file_list.txt中的链接依次下载。- 下载日志会保存在
download.log文件中。
-
查看进度：
tail -f download.log -
任务完成后：
- 如果你重新登录服务器，可以通过查看
download.log确认任务是否成功。
- 如果你重新登录服务器，可以通过查看
推荐 2：tmux（需要灵活监控的任务）
如果你希望在下载过程中能够实时监控任务进度，甚至在网络中断后重新连接到任务，tmux 是更适合的选择。
优点：
- 支持重连，适合长时间运行的任务。
- 支持在同一会话中运行多个任务（如同时解压文件、检查文件完整性）。
- 使用灵活，支持实时切换任务窗口。
操作步骤：
-
启动
tmux会话：tmux new -s download -
运行下载命令：
wget -i file_list.txt -
分离会话：
按下Ctrl + B，然后按D，将会话分离。 -
重新连接：
如果你断开连接，可以重新连接到任务：tmux attach -t download -
查看文件下载进度：
wget本身会显示每个文件的下载进度（包括百分比、下载速度等）。
选择依据
- 任务简单、一次性完成： 使用
nohup，非常简单，运行后就不用管了。 - 需要实时监控、可能断网： 使用
tmux，方便断网后重连并继续监控任务。
不推荐的方案
screen：- 功能类似于
tmux，但快捷键不如tmux直观，扩展性稍差。
- 功能类似于
- 直接运行任务（不后台运行）：
- 如果没有
nohup或tmux，会话断开任务也会中断，不安全。
- 如果没有
推荐方案：nohup 示例
对于你的场景，直接运行以下命令即可：
nohup wget -i file_list.txt > download.log 2>&1 &
后台运行下载任务，避免因为网络断开导致任务中断。
额外建议：验证文件完整性
下载完成后，使用以下方式检查文件完整性：
-
检查文件大小：
确认每个文件的大小是否与 Huggingface 页面显示一致：ls -lh -
解压测试：
在解压前测试文件完整性（以 ZIP 为例）：unzip -t Training_aa.zip
如果你的任务时间较长或者网络环境不稳定，我更推荐 tmux。如果不想复杂操作，nohup 也能很好地解决问题。根据你的偏好选择即可！
