BentoML TorchScript 模型管理指南:save_model、load_model 与 get 全解析
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:PyTorchtorch.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的兼容性。
相关文档与后续阅读
- 更多 TorchScript 实战示例可参考仓库 examples 目录;
- BentoML 各框架 API 索引见 docs/source/reference/bentoml/frameworks/index.rst;
- 服务化相关可阅读 docs/source/reference/bentoml/sdk.rst 与 docs/source/reference/bentoml/batch.rst;
- Runner 与运行时的机制实现位于 src/bentoml/_internal/runner/。