BentoML TorchScript 模型管理指南:save_model、load_model 与 get 全解析

原创2026-09-24 10:25:521,404 阅读
文章标签:人工智能模型推理服务MLOpsLLMOps后端云原生API网关

BentoML TorchScript 模型管理指南:save_model、load_model 与 get 全解析

本指南以 BentoML 仓库中 docs/source/reference/bentoml/frameworks/torchscript.rst 文档为主体,系统讲解 bentoml.torchscript 模块提供的三个核心 API:save_model、load_model 与 get。读完本文,你将掌握如何在 BentoML modelstore 中保存 TorchScript 模型、按 tag 加载模型并将模型接入 Bento 服务,同时理解背后的源码实现与测试验证方式,可直接用于 PyTorch 模型的部署实战。

概述:BentoML 中的 TorchScript 支持

TorchScript 是 PyTorch 提供的模型序列化与部署格式,允许把训练好的 torch.nn.Module 编译为可独立执行的 ScriptModule,从而脱离 Python 解释器依赖运行推理。BentoML 通过 bentoml.torchscript 模块将其纳入统一的模型管理流程:模型被保存进本地 modelstore,以 name:version 形式的 tag 唯一标识,之后可被加载并接入 API 服务。

从源码结构看,TorchScript 的保存与加载逻辑实现在 src/bentoml/_internal/frameworks/torchscript.py 中,并作为 bentoml.torchscript 暴露在公开 API 层(见 src/bentoml/init.py 中的 lazy loader 注册)。该模块的核心常量包括:

  • MODEL_FILENAME = "saved_model.pt":模型权重在 modelstore 中的文件名;
  • API_VERSION = "v1":模型元数据 API 版本;
  • MODULE_NAME = "bentoml.torchscript":模型归属模块标识,用于加载时的模块校验。

save_model:将 TorchScript 模型写入 BentoML modelstore

bentoml.torchscript.save_model 接受一个 torch.ScriptModule 实例,将其保存为 BentoML Model,返回的 Model 对象携带 name:version 格式的 tag。

函数签名与参数说明

bentoml.torchscript.save_model(
    name,                       # 模型名称,需通过 Python 标识符检查
    model,                      # torch.ScriptModule 实例
    *,
    signatures=None,            # 方法名到签名配置的字典
    labels=None,                # 用户自定义标签,如 team=nlp, stage=dev
    custom_objects=None,        # 附加 Python 对象,如 tokenizer、预处理函数、配置 json
    external_modules=None,      # 附加 Python 模块,如 tokenizer 模块、预处理模块
    metadata=None,              # 模型自定义元数据
) -> bentoml.Model

类型校验

save_model 首先校验传入模型是否为 torch.ScriptModule 或 torch.jit.ScriptModule,否则抛出 TypeError。这意味着 save_model 只接受已通过 torch.jit.trace 或 torch.jit.script 编译的模型,而不是普通 torch.nn.Module。相关校验逻辑见 src/bentoml/_internal/frameworks/torchscript.py:

if not isinstance(model, (torch.ScriptModule, torch.jit.ScriptModule)):
    raise TypeError(f"Given model ({model}) is not a torch.ScriptModule.")

版本信息记录

保存时,模块会记录框架版本信息并写入模型上下文(ModelContext):普通 TorchScript 模型记录 torch 版本;当 _framework_name == "pytorch_lightning"(即被 bentoml.pytorch_lightning 复用)时,额外记录 pytorch_lightning 版本。版本号通过 get_pkg_version("torch") 获取,见 src/bentoml/_internal/frameworks/torchscript.py。

默认签名

若未显式传入 signatures,模块会自动采用默认签名 {"__call__": {"batchable": False}} 并打印日志,见 src/bentoml/_internal/frameworks/torchscript.py。这一点对后续服务化很重要:签名决定了 Runner 中可调用的方法以及是否启用批处理。

底层保存流程

保存过程通过 bentoml.models._create(...) 创建模型目录(含标签、签名、custom objects、external modules、元数据等),随后调用 torch.jit.save(model, bento_model.path_of(MODEL_FILENAME)) 将模型权重写入 saved_model.pt,见 src/bentoml/_internal/frameworks/torchscript.py。

此外,save_model 还支持一个内部参数 _extra_files:当传入时,其文件名列表会被写入 metadata["_extra_files"],并在 torch.jit.save 时透传给 PyTorch,用于保存模型附带的自定义资源文件。

完整保存示例

import bentoml
import torch

# 1. 定义一个可脚本化的模块
class NNLinearModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = torch.nn.Linear(5, 1, bias=False)
        torch.nn.init.ones_(self.linear.weight)

    def forward(self, x: torch.Tensor):
        return self.linear(x)

nn_model = NNLinearModel()

# 2. 通过 tracing 或 scripting 生成 ScriptModule
traced_model = torch.jit.trace(nn_model, torch.ones(5))
# 或 scripted_model = torch.jit.script(nn_model)

# 3. 保存到 BentoML modelstore
tag = bentoml.torchscript.save_model(
    "my_torchscript_model",
    traced_model,
    labels={"team": "ml", "stage": "dev"},
    metadata={"description": "linear regression demo"},
    custom_objects={"preprocessor": lambda x: x.float()},
)
print(tag)  # 例如 my_torchscript_model:20240101...

load_model:按 tag 从 modelstore 加载模型

bentoml.torchscript.load_model 从 BentoML 本地 modelstore 按名称加载已保存的 TorchScript 模型,返回 torch.ScriptModule 实例。

函数签名与参数说明

bentoml.torchscript.load_model(
    bentoml_model,     # str | Tag | Model,modelstore 中已保存模型的 tag
    device_id="cpu",   # 模型放置的设备,如 "cpu"、"cuda:0"
    *,
    _extra_files=None, # 字典,键为文件名、值为空字符串,透传给 torch.jit.load
) -> torch.ScriptModule
  • bentoml_model:可以传 tag 字符串(如 'lit_classifier:latest')、Tag 对象或 Model 对象;字符串与 Tag 会先经 get() 解析。
  • device_id:默认 "cpu",用于 torch.jit.load 的 map_location 参数,可将模型加载到指定设备。
  • _extra_files:PyTorch torch.jit.load 的附加文件参数,用于加载保存时附带的自定义资源。

加载流程与模块校验

加载的核心逻辑见 src/bentoml/_internal/frameworks/torchscript.py:先解析 tag 得到 Model,再校验 bentoml_model.info.module 是否为 bentoml.torchscript,若不是则抛出 NotFound,防止跨框架误加载;随后定位 saved_model.pt 权重文件,调用 torch.jit.load(weight_file, map_location=device_id, _extra_files=_extra_files) 完成加载。

加载示例

import bentoml

# 按 tag 加载,latest 表示最新版本
model = bentoml.torchscript.load_model('lit_classifier:latest', device_id="cuda:0")

# 也可以传入 Model 对象
model = bentoml.torchscript.load_model(saved_model_obj)

get:获取 modelstore 中的模型对象

bentoml.torchscript.get 用于从 modelstore 中取出指定 tag 对应的 bentoml.Model 对象(不加载模型权重)。它同样会校验模型的 info.module 是否为 bentoml.torchscript,不匹配时抛出 NotFound,见 src/bentoml/_internal/frameworks/torchscript.py:

def get(tag_like: str | Tag) -> Model:
    model = bentoml.models.get(tag_like)
    if model.info.module not in (MODULE_NAME, __name__):
        raise NotFound(
            f"Model {model.tag} was saved with module {model.info.module}, not loading with {MODULE_NAME}."
        )
    return model

典型用途包括:查看模型元数据、获取模型路径以便手动访问 saved_model.pt、或将 Model 对象直接传给 load_model。

将 TorchScript 模型接入 BentoML 服务(Runner 机制)

除了三个公开 API,模块内部还实现了 get_runnable(bento_model)(私有 API,官方建议使用 bentoml.Model.to_runnable 代替),它把已保存的 TorchScript 模型包装成 BentoML Runner,使模型能够在服务中运行,见 src/bentoml/_internal/frameworks/torchscript.py。其核心逻辑复用 src/bentoml/_internal/frameworks/common/pytorch.py 中的 PytorchModelRunnable:

  • 加载时根据 torch.cuda.is_available() 自动选择 "cuda" 或 "cpu",并在推理前调用 model.train(False) 关闭 dropout 与 batchnorm(见 src/bentoml/_internal/frameworks/common/pytorch.py);
  • 运行方法通过 make_pytorch_runnable_method 生成:推理期间将 numpy 数组、pandas DataFrame 等输入统一转换为 torch.Tensor 并搬运到目标设备,随后在 torch.inference_mode(PyTorch ≥ 1.9)或 torch.no_grad 上下文中执行模型前向,见 src/bentoml/_internal/frameworks/common/pytorch.py;
  • 每个签名(signature)会生成一个对应的可运行方法,并遵循其 batchable、batch_dim、input_spec、output_spec 配置。

因此,一个典型的服务化流程是:

import bentoml
import torch

# 保存阶段
class NNLinearModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = torch.nn.Linear(5, 1, bias=False)
        torch.nn.init.ones_(self.linear.weight)

    def forward(self, x):
        return self.linear(x)

traced = torch.jit.trace(NNLinearModel(), torch.ones(5))
bentoml.torchscript.save_model("linear_demo", traced)

# 服务中加载
runner = bentoml.torchscript.load_model("linear_demo:latest").to_runnable()
# 或以 runner = bentoml.torchscript.get_runnable(model) 的方式(私有 API,不推荐)

集成测试验证:tracing 与 scripting 双路径

仓库中的集成测试 tests/integration/frameworks/models/torchscript.py 验证了 TorchScript 模块的完整工作流:

  • 定义了一个 NNLinearModel(单层线性层,权重初始化为 1),并分别通过 torch.jit.trace 与 torch.jit.script 生成两种 ScriptModule,覆盖 TorchScript 的两大生产方式;
  • 测试输入覆盖 numpy 数组、pandas DataFrame、CPU 上的 torch.Tensor,并在 GPU 可用时追加 CUDA 张量;
  • 每个输入都断言模型输出等于 5(因为输入全 1、权重全 1,5 维输入求和为 5),以此验证 save_model → load_model → __call__ 整条链路在多种输入类型与设备下的正确性。

同时,backward_compatible = True 表明该框架模块保持向后兼容。这些测试同时印证了 PytorchModelRunnable 对 numpy/pandas/Tensor 三种输入类型的自动映射能力(见 src/bentoml/_internal/frameworks/common/pytorch.py)。

注意事项

  • 依赖要求:使用 bentoml.torchscript 需要安装 torch。若缺失,模块会在导入时报 MissingDependencyException,提示 pip install torch(见 src/bentoml/_internal/frameworks/common/pytorch.py)。
  • 弃用提示:在 src/bentoml/init.py 中,bentoml.torchscript 以 _LazyLoader 注册并带警告——bentoml.torchscript 自 v1.4 起已弃用,未来版本可能移除。当前仓库仍支持 bentoml.pytorch(保存 PyTorch 模型)与 bentoml.pytorch_lightning(保存 Lightning 模型)等新 API 路径;其中 bentoml.pytorch_lightning 内部正是复用 bentoml.torchscript 的保存实现(见 src/bentoml/_internal/frameworks/pytorch_lightning.py),先将 LightningModule 通过 to_torchscript() 转换后再走 TorchScript 保存管线。
  • 框架版本兼容性:模型保存时会记录 torch 版本;加载时通过模块名校验防止跨框架误用。建议在部署环境使用与训练环境一致的 torch 主版本,以确保 torch.jit.load 的兼容性。

相关文档与后续阅读

登录后查看全文
BentoML