SeisBench 模型 API

安装 SeisBench

推荐的安装方式是通过 pip 安装。只需运行：

pip install seisbench

概述

SeisBench 提供了抽象基类 WaveformModel，所有 SeisBench 模型均应继承该类。此类提供了两个核心方法：annotate 和 classify。这两个方法均基于具体模型中实现的配置与子方法自动构建。

SeisBenchModel 在 PyTorch 模型接口与地震学中常用的 ObsPy 接口之间架起桥梁。它能自动将 ObsPy Stream 组装为 PyTorch 张量，并将计算结果重新组装为 Stream；同时自动处理批处理（batching）。只需将模型移至 GPU，即可在 GPU 上执行计算。

annotate 方法接收一个 ObsPy Stream 对象作为输入，并返回同样为 Stream 对象的标注结果。例如，对于拾取（picking）类模型，输出即为其特征函数（characteristic functions），即随时间变化的拾取概率。

stream = obspy.read("my_waveforms.mseed")
annotations = model.annotate(stream)  # 返回带标注信息的 ObsPy Stream 对象

classify 方法同样以 ObsPy Stream 为输入，但与 annotate 不同，其返回离散化结果。这些结果的具体结构可能因模型而异：例如，纯拾取模型将返回拾取点（picks）列表，而兼具拾取与检测功能的模型则可能同时返回拾取点列表和事件检测（detections）列表。

stream = obspy.read("my_waveforms.mseed")
outputs = model.classify(stream)  # 返回拾取点列表
print(outputs)

annotate 与 classify 均支持一次性传入来自多个台站的波形数据，并自动完成迹线（traces）的正确分组。如需了解如何基于 SeisBench 构建自定义模型，请参阅 WaveformModel 的文档；如需了解模型应用方法，请参阅 Examples（示例）部分。

加载预训练模型

若要对波形进行有意义的标注，必须使用已训练好的模型权重。SeisBench 通过统一接口提供一系列预训练模型权重。模型权重将在首次使用时自动下载，并在本地缓存。部分模型提供多个版本的权重，有关如何访问不同版本的详细说明，请参阅 from_pretrained 文档。

import seisbench.models as sbm

sbm.PhaseNet.list_pretrained()                  # 获取可用模型列表
model = sbm.PhaseNet.from_pretrained("original")  # 加载 PhaseNet 原作者发布的原始模型权重

预训练模型不仅可用于波形标注，亦可作为迁移学习（transfer learning）的理想起点。

加速模型推理

在大规模数据集上应用模型时，运行时间往往是关键瓶颈。以下是一些提升模型推理速度的实用建议：

• 在 GPU 上运行。 GPU 推理通常更快，尽管不同模型的实际加速比存在差异。但需注意，GPU 并非总是最具成本效益的选择——例如，在云环境中，租用若干台 CPU 服务器并行标注大规模数据集，其成本可能低于租用一台 GPU 服务器，且总耗时相近。

• 增大 batch_size。 该参数可作为可选参数传入所有模型。尤其在 GPU 上，更大的 batch size 通常带来更快的标注速度。只要 batch 能完整装入（GPU）显存，就值得尝试增大 batch size。

• 编译模型（PyTorch 2.0+）。 若使用 PyTorch 2.0 或更高版本，建议对模型进行编译，仅需执行 model = torch.compile(model) 即可。编译过程会消耗一定时间，但若需标注大量波形数据，则收益将迅速显现。请注意，torch.compile 提供多种编译选项，其选择将显著影响性能增益。

• 使用 asyncio 接口。 利用异步 I/O 接口，在模型推理的同时并行加载数据，即调用 annotate_asyncio 和 classify_asyncio。该方式通常大幅提速，因为数据加载属于 I/O 密集型任务，而实际标注则属于计算密集型任务。

• 手动重采样。 尽管 SeisBench 支持自动重采样，但预先手动完成重采样往往更高效。SeisBench 内部使用 ObsPy 的重采样例程（截至 2023 年尚未并行化）。可通过 model.sampling_rate 查询模型所需采样率。其他替代方案（如 Pyrocko 库中的重采样函数）亦可供选用。

已集成至 SeisBench 的模型

若您无需从零构建模型，SeisBench 已为您集成了如下文献中具有代表性的模型。这些深度学习模型均继承自 SeisBench 统一模型接口，底层均基于 PyTorch 实现；在条件允许的情况下，原始训练权重已被导入并开放使用，您可通过 from_pretrained 方法便捷获取。

当前集成的模型可完成地震事件检测与初至波（P/S 波）拾取、波形去噪、震源深度估计、低频地震事件拾取等任务。此外，借助 SeisBench，您还可构建机器学习模型，执行震级与震源参数估计、震中定位等通用地震学任务。

最佳实践

• 若波形数据幅值极小（<=1e-10），可能存在数值不稳定风险。此时可先将数据整体放大（例如乘以 1e10），再进行归一化或送入模型。

• 尽管 SeisBench 模型 API 会自动对波形执行归一化，但仍强烈建议您自行完成归一化操作。因为 SeisBench 默认采用带 epsilon 的归一化公式：(waveform - mean(waveform)) / (std(waveform) + epsilon)；当波形幅值极小时（如 <=1e-10），该归一化操作可能严重破坏原始信号特征。

• SeisBench 模型 API 可直接处理任意长度的波形 Stream，因此无需手动切分数据。此外，请勿假设单个波形 Stream 中仅包含一个 P 波与一个 S 波；最合理的做法是将其视为连续观测数据流（continuous data stream）本身。