【避坑指南】在学校无网服务器(HPC)上部署Grounded-Segment-Anything (GroundingDINO) 的完整踩坑记录
前言
最近在复现 Grounded-Segment-Anything (GroundingDINO + SAM) 进行图像分割任务时，在学校的高性能计算平台（HPC）上遇到了一系列环境配置问题。由于服务器无法连接外网（HuggingFace 连不上），且 CUDA 环境比较隐蔽，导致安装过程异常痛苦。
经过一晚上的折腾，终于解决了从 NumPy 版本冲突、离线模型加载 到 CUDA 算子编译 的所有 BUG。特此记录，希望能帮到同样使用 A40/A100 服务器做科研的同学。
0. 环境背景
-
硬件：NVIDIA A40 GPU
-
系统：Linux (Ubuntu/CentOS)
-
环境：Anaconda / Python 3.9
-
PyTorch 版本：2.1.0 + CUDA 11.8 (这是关键，编译器的版本必须和它对应)
坑一：NumPy 2.0 版本冲突
报错现象：
A module that was compiled using NumPy 1.x cannot be run in NumPy 2.0.2...
UserWarning: Failed to initialize NumPy: _ARRAY_API not found
原因分析：
NumPy 最近发布了 2.0 大版本，底层的二进制接口改了，而 PyTorch 和很多旧库是基于 NumPy 1.x 编译的。
解决方案：
强制降级 NumPy：
pip install "numpy<2.0"
# 或者
pip install numpy==1.24.4
坑二：服务器无网，无法连接 HuggingFace
报错现象：
OSError: We couldn't connect to 'https://huggingface.co' to load this file...
Network is unreachable
解决方案：
-
手动下载：在有网的电脑上下载
bert-base-uncased模型文件（包含config.json,pytorch_model.bin,vocab.txt等），上传到服务器指定目录（例如/home/user/models/bert-base-uncased）。 -
修改代码强制离线读取：
虽然修改配置文件 config.py 可以解决部分问题，但 GroundingDINO 的源码中有硬编码。建议直接修改 GroundingDINO/groundingdino/util/get_tokenlizer.py。
修改
get_tokenlizer函数和get_pretrained_language_model函数：# 在文件开头定义你的本地路径 LOCAL_BERT_PATH = "/你的/绝对/路径/models/bert-base-uncased" def get_tokenlizer(text_encoder_type): if text_encoder_type == "bert-base-uncased": print(f"强制加载本地 Tokenizer: {LOCAL_BERT_PATH}") return AutoTokenizer.from_pretrained(LOCAL_BERT_PATH) # ... 其他代码保持不变 def get_pretrained_language_model(text_encoder_type): if text_encoder_type == "bert-base-uncased": print(f"强制加载本地 BERT Model: {LOCAL_BERT_PATH}") return BertModel.from_pretrained(LOCAL_BERT_PATH) # ... 其他代码保持不变
坑三：GroundingDINO 编译失败 (核心难点)
报错现象：
运行 demo 时出现：
UserWarning: Failed to load custom C++ ops. Running on CPU mode Only!
NameError: name '_C' is not defined
或者编译时报错：
fatal error: cuda_runtime_api.h: No such file or directory
fatal error: cusparse.h: No such file or directory
RuntimeError: The detected CUDA version (12.4) mismatches PyTorch (11.8)
原因分析：
-
GroundingDINO 依赖
MultiScaleDeformableAttention算子，必须用nvcc编译。 -
学校服务器的 CUDA 路径经常没配好，或者版本不对。
-
Conda 安装的
cuda-nvcc默认缺少头文件 (.h)。 -
pip安装时启用了隔离构建 (build isolation)，导致版本不匹配。
终极解决方案 (按顺序执行)：
1. 确认 PyTorch 的 CUDA 版本
python -c "import torch; print(torch.version.cuda)"
# 输出: 11.8 (以你的实际输出为准)
2. 安装匹配的编译器和头文件 (在 Conda 环境内)
不要依赖服务器自带的 CUDA，直接在 Conda 里装一套独立的。注意版本必须和上面查到的一致！
# 安装编译器
conda install -c nvidia cuda-nvcc=11.8 -y
# 安装所有必要的开发库头文件 (解决 fatal error: cusparse.h 等问题)
conda install -c nvidia cuda-libraries-dev=11.8 -y
# 如果上一条找不到，尝试：conda install -c nvidia libcusparse-dev=11.8 libcublas-dev=11.8 -y
3. 设置环境变量
这一步至关重要，否则编译器找不到头文件。
# 将 Conda 环境路径设为 CUDA_HOME
export CUDA_HOME=$CONDA_PREFIX
# 告诉编译器去哪里找头文件 (解决 .h not found)
export CPATH=$CONDA_PREFIX/include:$CPATH
export CPATH=$CONDA_PREFIX/targets/x86_64-linux/include:$CPATH
# 开启编译开关
export BUILD_WITH_CUDA=True
4. 清理缓存并重新编译
使用 --no-build-isolation 参数，防止 pip 偷偷下载不兼容的新版 PyTorch。
cd GroundingDINO
# 1. 必须清理旧文件！
rm -rf build/ dist/ groundingdino.egg-info/
# 2. 开始编译安装 (加上 -v 查看详细日志)
pip install --no-build-isolation -v .
验证结果
编译完成后，运行以下 Python 代码验证：
import groundingdino.models.GroundingDINO.ms_deform_attn as ops
print("Success! CUDA ops loaded.")
如果不再报 UserWarning: Failed to load custom C++ ops，说明 GPU 加速已成功开启！
总结
在 HPC 上配置环境，核心在于**“版本对齐”和“路径明确”**。不要相信系统的默认环境，自己用 Conda 搭建一套完整的闭环（PyTorch + NVCC + Dev Headers）是最稳妥的方案。
希望这篇笔记能帮大家少踩几个坑，专心搞科研！
