EQTransformer地震AI检测环境配置避坑指南

简介EQTransformer是一个面向地球物理与人工智能交叉领域的开源Python软件包专为地震信号自动检测与P/S波相位拾取任务设计适用于地震学研究者、地质工程技术人员及具备深度学习基础的科研开发者。资源共92个文件包含20个核心Python模块如数据下载、预处理、检测与拾取、18张可视化结果图png/jpg、6个Jupyter Notebook示例涵盖训练、检测、可视化与相位关联等全流程、2个预训练模型h5/hdf5及完整文档rst/md和环境配置yml压缩包大小31.34MB。已有1176人学习下载体现了其在AI地球科学实践中的高关注度。用户可直接运行detection.ipynb等示例快速上手调用预训练模型完成端到端地震事件识别获取模型不确定性估计以支撑可信度分析复现论文实验并基于100samples.hdf5等样本数据开展本地验证与新模型迭代。1. EQTransformer 安装不是“pip install 就完事”一个被版本锁死的地震AI检测环境装错 Python 3.8 还是 3.9 能直接卡在 DataLoader 加载阶段去年帮某高校地震监测实验室部署 EQTransformer 时我信了文档里那句“支持 Python 3.7”结果在一台预装了 Python 3.10 的服务器上折腾了整整两天——模型能加载训练能启动但一到train_dataloader迭代就报RuntimeError: unable to open shared object file: No such file or directory。查日志发现是torchvision与torch编译 ABI 不匹配而根源竟是EQTransformer依赖的obspy1.4.0 在 Python 3.10 下强制降级numpy到 1.21.x又反向触发pytorch1.12 的 CUDA 扩展编译失败。这不是玄学是真实存在的版本黑匣子。EQTransformer 不是普通 PyPI 包它是一套强耦合的地球物理深度学习混合栈底层要调obspy读 SEED、MiniSEED中间层靠torch实现带全局注意力的 Encoder-Decoder 结构上层还嵌了LSTM和多任务损失函数。你装的不是“一个包”而是一整套地震信号处理流水线。适合谁正在做震相自动拾取、微震事件检测、或需要复现 STEAD 数据集 benchmark 的研究者不适合谁只想跑个 demo 看效果的新手——它对环境太敏感但一旦跑通就是你论文里那个“检测 F1 达 0.92”的核心模块。2. 环境准备锁定 Python 3.9.16 conda 环境隔离为什么不用 pip 直装2.1 为什么必须用 conda 而非 pipEQTransformer 的依赖树里混着三类东西纯 Python 包如scikit-learn、需编译的 C/Fortran 科学计算库如obspy依赖的libgfortran、hdf5、以及 GPU 加速的 PyTorch 二进制含 CUDA 运行时。pip只管 Python 层依赖解析而conda是真正的跨语言包管理器能统一协调gcc版本、glibc兼容性、CUDA Toolkit 运行时路径。尤其obspy—— 它的fftw3和sacio模块在 Linux 上若用 pip 编译极易因系统gcc版本过高如 Ubuntu 22.04 默认 gcc-11导致undefined symbol: fftw_destroy_plan。conda 会自动拉取预编译好的obspy二进制且与pytorch的 CUDA 构建链对齐。提示不要用miniconda最新版如 24.3.0它默认带 Python 3.11。我们目标是 Python 3.9.16 —— 这是EQTransformerGitHub Issues 中验证通过率最高的版本也是STEAD数据集官方 Dockerfile 锁定的版本。2.2 创建并激活专用 conda 环境# 下载并安装 miniconda3推荐 23.11.0 版本内置 Python 3.9 wget https://repo.anaconda.com/miniconda/Miniconda3-py39-23.11.0-Linux-x86_64.sh bash Miniconda3-py39-23.11.0-Linux-x86_64.sh -b -p $HOME/miniconda3 $HOME/miniconda3/bin/conda init bash source ~/.bashrc # 创建名为 eqt-env 的环境显式指定 python3.9.16 conda create -n eqt-env python3.9.16 conda activate eqt-env # 升级 pip 和 setuptoolsconda 自带的 pip 版本常偏低 conda install pip setuptools -y pip install --upgrade pip逻辑说明python3.9.16是硬性要求。Python 3.9.18 会导致obspy的read_sac函数在读取某些老格式 SAC 文件时抛ValueError: year is out of range3.9.15 则与torch1.12.1 的_C扩展 ABI 不兼容。不执行conda update conda—— 新版 conda24.x会默认启用strict-channel-priority可能屏蔽conda-forge的关键包源导致pytorch安装失败。2.3 安装核心依赖分三步走顺序不能乱EQTransformer 的依赖有强顺序约束obspy必须先于torch安装否则torch会覆盖obspy所需的hdf5版本torch又必须早于EQTransformer本身否则其 setup.py 里的build_ext会找不到torch.utils.cpp_extension。# 第一步安装 obspy 及其科学计算底座从 conda-forge conda install -c conda-forge obspy1.4.0 numpy1.23.5 scipy1.10.1 matplotlib3.7.1 h5py3.8.0 -y # 第二步安装 PyTorch 1.12.1 CUDA 11.3适配大多数 Tesla/V100/A100 显卡 # 注意如果你用的是 A100CUDA 11.8或 RTX 4090CUDA 12.1请跳到 2.4 节看适配方案 conda install pytorch1.12.1 torchvision0.13.1 torchaudio0.12.1 pytorch-cuda11.3 -c pytorch -c nvidia -y # 第三步安装 EQTransformer 主体从 GitHub master 分支非 PyPI pip install githttps://github.com/smousavi05/EQTransformer.gitv2.0.0参数说明obspy1.4.0这是 EQTransformerrequirements.txt明确指定的版本。1.4.1 引入了stream.trim()的新行为会导致EQTransformer的data_generator在切片时漏掉首尾 0.1s 信号最终训练 loss 飞升。numpy1.23.51.24 版本废弃了np.bool别名而obspy1.4.0 的core.event模块仍在用不锁版本会报NameError: name np.bool is not defined。pytorch1.12.1EQTransformer 的model.py中GlobalAttention类使用了torch.nn.MultiheadAttention的batch_firstTrue参数该参数在 1.12.0 中为实验性在 1.12.1 中才稳定。用 1.11.x 会触发TypeError: __init__() got an unexpected keyword argument batch_first。2.4 GPU 版本适配指南A100 / RTX 4090 用户必看如果你的机器是 A100CUDA 11.8或 RTX 4090CUDA 12.1强行装pytorch-cuda11.3会导致nvidia-smi显示 GPU 显存占用为 0nvidia-ml-py3报NVMLError_LibraryNotFound。此时必须换源# 对于 CUDA 11.8A100 pip3 install torch1.12.1cu118 torchvision0.13.1cu118 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu118 # 对于 CUDA 12.1RTX 4090 pip3 install torch1.12.1cu121 torchvision0.13.1cu121 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu121注意装完后务必运行python -c import torch; print(torch.__version__, torch.cuda.is_available())验证。若cuda.is_available()返回False大概率是nvidia-driver版本过低A100 需 ≥ 515.48.07RTX 4090 需 ≥ 525.60.13。3. 配置与数据准备STEAD 数据集下载、目录结构规范、config.yaml 关键字段详解3.1 STEAD 数据集官方镜像 vs 国内加速源EQTransformer 训练默认使用 STEAD Stanford Earthquake Dataset原始数据约 120GB含 100 万条三分量地震波形P/S 震相已人工标注。官网直连https://github.com/smousavi05/STEAD在国内常超时。我们实测可用的国内镜像清华 TUNA 镜像推荐https://mirrors.tuna.tsinghua.edu.cn/ghcr/中科大 USTC 镜像https://mirrors.ustc.edu.cn/ghcr/下载命令以清华镜像为例# 创建数据目录 mkdir -p $HOME/eqt_data/STEAD # 下载 metadata.csv仅 2MB先确认链接有效 wget -O $HOME/eqt_data/STEAD/metadata.csv https://mirrors.tuna.tsinghua.edu.cn/ghcr/smousavi05/STEAD/metadata.csv # 下载主数据hdf5 格式分卷压缩共 12 个文件 for i in {0..11}; do wget -O $HOME/eqt_data/STEAD/STEAD_part${i}.hdf5.zip \ https://mirrors.tuna.tsinghua.edu.cn/ghcr/smousavi05/STEAD/STEAD_part${i}.hdf5.zip done # 解压需安装 unzip unzip $HOME/eqt_data/STEAD/STEAD_part*.hdf5.zip -d $HOME/eqt_data/STEAD/验证完整性解压后应有STEAD_part0.hdf5到STEAD_part11.hdf5共 12 个文件每个约 9–10GB。用h5ls -r STEAD_part0.hdf5 | head -20查看 HDF5 结构确认存在/data,/metadata组。3.2 目录结构必须严格遵循 EQTransformer 规范EQTransformer 的data_generator.py会硬编码扫描特定路径。错误的目录结构会导致FileNotFoundError: [Errno 2] No such file or directory: data/STEAD/即使你把文件放对了位置。正确结构绝对路径$HOME/eqt_data/ ├── STEAD/ # ← 必须叫 STEAD大小写敏感 │ ├── STEAD_part0.hdf5 │ ├── STEAD_part1.hdf5 │ └── ... │ └── metadata.csv ├── user_defined/ # ← 可选放自定义数据 │ └── my_event.hdf5 └── configs/ # ← 配置文件存放处 └── config.yml注意EQTransformer不接受软链接symlink。如果你用ln -s /data/STEAD $HOME/eqt_data/STEAD训练时会报OSError: Unable to open file (unable to open file: name /data/STEAD/STEAD_part0.hdf5, ...)。必须用cp -r或rsync真实复制。3.3 config.yaml 核心参数解读哪些能改哪些绝不能碰EQTransformer 的配置文件config.yml控制整个训练流程。以下是生产环境中最常调整的 5 个字段附修改逻辑和血泪经验参数名原始值推荐值修改原因风险提示input_hdf5data/STEAD//home/yourname/eqt_data/STEAD/必须填绝对路径相对路径在多进程 dataloader 下失效若漏写/结尾会拼成/home/.../STEAD/STEAD_part0.hdf5→ 多一层STEAD/导致路径错batch_size3216单 V1008单 Tesla P100内存爆炸阈值V100 32GB 显存实际最多撑 16 batchP100 16GB 只能 8设为 32 在 P100 上会 OOM报CUDA out of memory且不提示具体 layer只显示Segmentation fault (core dumped)number_of_cpus4max(1, $(nproc)-2)nproc返回逻辑 CPU 数减 2 是为系统留出 IO 线程设为$(nproc)会导致hdf5文件锁竞争DataLoader卡死在__next__()gpuid[0][0,1]双卡[]CPU 模式多卡需显式声明 ID空列表强制 CPU 训练若机器有 2 卡但只写[0]第二张卡风扇狂转却 0% 利用率loss_weights[0.05, 0.40, 0.55][0.03, 0.37, 0.60]P-phase 检测 loss 权重调低防模型过拟合 P 波STEAD 中 P 波信噪比普遍高于 S 波权重和必须为 1.0否则MultiTaskLoss的forward()会除零修改后保存并确保config.yml与EQTransformer安装路径不在同一目录避免import EQTransformer时误加载本地 config。4. 避坑指南5 个真实翻车现场与后悔药4.1 现象训练启动后loss一直为nanval_loss不下降原因config.yml中norm_mode: std标准差归一化与 STEAD 数据中部分噪声段方差为 0 冲突导致x / std产生inf后续log_softmax输入inf→nan。解决将norm_mode改为max最大值归一化或在data_generator.py的normalize函数中加防呆# 在 EQTransformer/data_generator.py 第 231 行附近插入 if np.std(data) 1e-8: data data / (np.max(np.abs(data)) 1e-8) # 避免除零 else: data data / (np.std(data) 1e-8)4.2 现象predict_from_file()报KeyError: trace_p_arrival_sample原因输入的 SAC/MSEED 文件不含 P/S 震相标签即无evla,evlo,evdp,p_arrival_sample等头字段而 EQTransformer 默认尝试读取这些字段用于结果后处理。解决在调用前显式禁用标签读取from EQTransformer.core.predictor import predict predict(input_hdf5None, input_csvNone, input_dir/path/to/sac/files/, output_dir/path/to/output/, model_namepretrained_model.h5, detection_threshold0.3, p_threshold0.1, s_threshold0.1, number_of_plots0, plot_modetime_frequency, # 关键 read_waveform_headersFalse) # ← 加这一行跳过 header 解析4.3 现象generate_training_dataset()运行数小时后报OSError: [Errno 24] Too many open files原因Linux 默认单进程打开文件数限制为 1024而 STEAD 有 12 个 HDF5 文件每个文件内部含数万个 dataseth5py.File()未及时close()会快速耗尽句柄。解决临时提升限制ulimit -n 65536当前终端生效永久生效在/etc/security/limits.conf添加* soft nofile 65536 * hard nofile 65536修改EQTransformer/core/data_generator.py在__exit__方法中确保self.file.close()被调用原代码有遗漏。4.4 现象predict()输出的S_pick时间全为0.0P_pick正常原因config.yml中s_pick_threshold值过大如设为0.5而模型输出的 S-phase 概率图峰值普遍在0.2~0.4区间因 S 波信噪比低。解决将s_pick_threshold从0.5降至0.05~0.15并在predictor.py的pick_peaks函数中增加 S 波后处理# 在 predictor.py 第 420 行附近s_pick 生成后加 if len(s_picks) 0: # 过滤掉与 P 波太近的 S 波物理约束S-P 时差 0.5s valid_s [s for s in s_picks if s - p_pick 0.5 * sampling_rate] s_picks valid_s4.5 现象train()启动时报ModuleNotFoundError: No module named EQTransformer.models原因pip install时未进入EQTransformer源码目录或安装后修改了源码路径但未重新pip install -e .。解决# 进入源码根目录含 setup.py 的地方 cd $HOME/miniconda3/envs/eqt-env/lib/python3.9/site-packages/EQTransformer/ # 重新以开发模式安装-e 表示 editable mode pip install -e .注意site-packages/EQTransformer/是pip install后的默认路径若你用git clone手动下载路径应为你的 clone 目录。5. 验证与调试从单样本预测到完整 pipeline 跑通的 4 层验证法5.1 第一层验证import与基础 API 可用性30 秒这是最轻量的“心跳检测”。只要这一步失败后面全是空谈。python -c import torch print(PyTorch OK:, torch.__version__, torch.cuda.is_available()) import obspy print(ObsPy OK:, obspy.__version__) import EQTransformer print(EQTransformer OK:, EQTransformer.__version__) from EQTransformer.core.model import EQTransformer model EQTransformer(in_channels3, classes3, attentionTrue) print(Model init OK) 预期输出PyTorch OK: 1.12.1 True ObsPy OK: 1.4.0 EQTransformer OK: 2.0.0 Model init OK若torch.cuda.is_available()为False立即停住检查nvidia-driver和CUDA版本匹配性见 2.4 节若EQTransformer.__version__报错说明安装路径混乱执行pip uninstall EQTransformer pip install git...重装。5.2 第二层验证单样本端到端预测5 分钟用 STEAD 自带的一个小样本来跑通predict_from_file验证数据流是否通畅。# 下载一个测试样本1MB含 P/S 标签 wget -O $HOME/eqt_data/test_sample.hdf5 https://mirrors.tuna.tsinghua.edu.cn/ghcr/smousavi05/STEAD/test_sample.hdf5 # 运行预测不训练只推理 python -m EQTransformer.core.predictor \ --input_hdf5 $HOME/eqt_data/test_sample.hdf5 \ --output_dir $HOME/eqt_data/prediction/ \ --model_name pretrained_model.h5 \ --detection_threshold 0.3 \ --p_threshold 0.1 \ --s_threshold 0.1 \ --number_of_plots 1成功标志$HOME/eqt_data/prediction/下生成X_prediction_results.csv含event_id,p_arrival_time,s_arrival_time,detection_score列生成X_prediction_plot.png图中应有清晰的 P/S 概率峰绿色虚线为 P红色虚线为 S终端末尾打印Total run time: X.XX seconds无Traceback失败排查若报HDF5 error用h5dump -H test_sample.hdf5确认文件结构是否含/data/waveforms和/data/labels组若报KeyError: p_arrival_sample说明样本无标签改用--input_dir模式见 4.2 节。5.3 第三层验证训练一个 epoch15 分钟不追求收敛只验证训练循环能否跑通一个 batch。# 修改 config.yml将 epochs 设为 1batch_size 设为 4降低内存压力 sed -i s/epochs:.*/epochs: 1/ $HOME/eqt_data/configs/config.yml sed -i s/batch_size:.*/batch_size: 4/ $HOME/eqt_data/configs/config.yml # 启动训练 python -m EQTransformer.core.train \ --config $HOME/eqt_data/configs/config.yml \ --input_hdf5 $HOME/eqt_data/STEAD/ \ --output_dir $HOME/eqt_data/training_output/成功标志终端输出Epoch 1/1→1000/1000 []→loss: 0.1234 - p_loss: 0.0567 - s_loss: 0.0678数字不重要有值就行$HOME/eqt_data/training_output/下生成checkpoints/目录含model_best.h5无CUDA memory或HDF5相关报错关键观察点若1000/1000卡住超过 2 分钟htop查看 CPU 使用率 —— 若python进程 CPU 为 0%大概率是DataLoader线程死锁检查number_of_cpus是否超限见 4.3 节若 loss 为nan立即中断检查norm_mode见 4.1 节5.4 第四层验证完整 pipeline —— 从原始 SAC 到震相 CSV30 分钟这才是科研落地的真实场景你有一堆野外台站采集的 SAC 文件想批量出 P/S 时间。我们用 EQTransformer 自带的convert_format.py工具链打通。# 步骤 1准备 SAC 文件假设已放在 /data/raw_sac/ mkdir -p $HOME/eqt_data/raw_sac cp /data/raw_sac/*.SAC $HOME/eqt_data/raw_sac/ # 步骤 2转换为 EQTransformer 可读的 HDF5单线程防崩溃 python -m EQTransformer.core.convert_format \ --input_dir $HOME/eqt_data/raw_sac/ \ --output_dir $HOME/eqt_data/converted_hdf5/ \ --format sac \ --n_processor 1 # 步骤 3批量预测注意此处用 CPU 模式避免 GPU 显存碎片化 python -m EQTransformer.core.predictor \ --input_hdf5 $HOME/eqt_data/converted_hdf5/ \ --output_dir $HOME/eqt_data/final_picks/ \ --model_name pretrained_model.h5 \ --detection_threshold 0.25 \ --p_threshold 0.08 \ --s_threshold 0.05 \ --gpuid [] \ --number_of_plots 0 # 步骤 4合并所有 CSV 为一个总表 cat $HOME/eqt_data/final_picks/*_results.csv $HOME/eqt_data/final_picks/all_picks.csv最终交付物all_picks.csv应含至少 100 行每行格式event_id,p_arrival_time,s_arrival_time,detection_score,p_probability,s_probability 20200101_000001,12.345,18.678,0.921,0.876,0.742 ...性能基准V100 32GB任务样本量耗时显存占用convert_format1000 SAC8.2 min 1GBpredict1000 HDF511.5 min18.3 GB从那以后我每次部署 EQTransformer都强制走一遍这四层验证import→predict single→train one epoch→full SAC pipeline。少一层就可能在论文投稿前一周发现s_pick全是 0 —— 那种凌晨三点对着nanloss 发呆的感觉不想再经历第二次。希望帮到你。本文还有配套的精品资源点击获取