BentoML Transformers 框架 API 详解：save_model、load_model 与 get 实战指南

模型推理服务人工智能后端大模型MLOpsLLMOps【免费下载链接】BentoMLThe easiest way to serve AI apps and models - Build Model Inference APIs, Job queues, LLM apps, Multi-model pipelines, and more!项目地址https://gitcode.com/gh_mirrors/be/BentoML点击查看免费下载本篇是 BentoML 官方 API 参考文档docs/source/reference/bentoml/frameworks/transformers.rst的深度展开版围绕bentoml.transformers模块的三个核心函数 ——save_model、load_model与get—— 结合仓库源码src/bentoml/_internal/frameworks/transformers.py与其集成测试tests/integration/frameworks/test_transformers_unit.py逐一拆解参数语义、底层实现与最佳实践。读完本文你将掌握如何在 BentoML Model Store 中完整保存、加载和管理 Transformers 的 Pipeline、预训练模型与自定义 Pipeline并理解 BentoML 内部如何对 Pipeline 与 PreTrained 对象采用两种不同的序列化协议。一、bentoml.transformers模块概览在 BentoML 中bentoml.transformers是面向 Hugging Face Transformers 框架的官方模型管理接口负责打通 Transformers 生态与 BentoML Model Store本地模型仓库默认位于~/bentoml/models/。模块对外暴露的公开 API 见源码中的__all__定义__all__ [load_model, import_model, save_model, get_runnable, get]其中由官方 API 参考文档收录的核心函数为save_model、load_model、get另有一个与 Hub 同步能力密切相关的import_model本文一并展开。从源码结构看该模块通过_LazyLoader挂载到bentoml.transformers命名空间见 src/bentoml/init.py模块主体定义在 src/bentoml/_internal/frameworks/transformers.py引入时会校验transformers依赖是否已安装try: import transformers except ImportError: raise MissingDependencyException( transformers is required in order to use module bentoml.transformers. Install transformers with pip install transformers. )模块内部定义了常量MODULE_NAME bentoml.transformers与API_VERSION v2并据此派生出两条序列化文件命名约定PIPELINE_PICKLE_NAME pipeline.v2.pkl保存 Pipeline 对象时仅 pickle 其类权重通过save_pretrained落盘PRETRAINED_PROTOCOL_NAME pretrained.v2.pkl保存 PreTrained 对象时pickle 其类以支持from_pretrained重建。此外模块会根据transformers版本判断是否支持PIPELINE_REGISTRYHAS_PIPELINE_REGISTRY TRANSFORMERS_VERSION (4, 21, 0)这决定了自定义 Pipeline 的注册方式详见后文。二、save_model把 Pipeline 或预训练模型写入 Model Store2.1 函数签名与参数全解源码中save_model的定义位于 src/bentoml/_internal/frameworks/transformers.py签名如下def save_model( name: Tag | str, pretrained_or_pipeline: TransformersPreTrained | transformers.Pipeline | None None, pipeline: transformers.Pipeline | None None, task_name: str | None None, task_definition: dict[str, t.Any] | TaskDefinition | None None, *, signatures: ModelSignaturesType | None None, labels: dict[str, str] | None None, custom_objects: dict[str, t.Any] | None None, external_modules: t.List[ModuleType] | None None, metadata: dict[str, t.Any] | None None, **save_kwargs: t.Any, ) - bentoml.Model各参数含义与注意事项如下参数类型说明nameTag/str模型在 Model Store 中的名称必须通过 Python 标识符检查例如text-generation-pipelinepretrained_or_pipelinePipeline 或任意 Transformers 支持的 PreTrained 对象要保存的对象。该对象必须同时具备save_pretrained与from_pretrained两个方法即 Transformers 定义的协议传入 Pipeline 或 PreTrainedModel / Tokenizer / Processor / FeatureExtractor 均可pipelinePipeline已弃用参数。旧版本通过pipeline传入 Pipeline源码中会发出DeprecationWarning并自动将其赋值给pretrained_or_pipeline建议直接使用后者task_namestrPipeline 任务名。若不提供则从pipeline.task自动推导仅当保存自定义 Pipeline时需要显式传入task_definitiondict自定义 Pipeline 的任务定义见 4.2 节。源码明确指出task_name与task_definition两个参数必须成对出现才能保存自定义 PipelinesignaturesModelSignaturesType暴露给 Runner 的推理方法签名例如{__call__: {batchable: False}}。不传时由make_default_signatures依据对象类型自动推断labelsdict[str, str]管理标签如{team: nlp, stage: dev}custom_objectsdict[str, t.Any]随模型一起保存的自定义对象如 tokenizer、normalizer使用 cloudpickle 序列化external_moduleslist[ModuleType]需要随模型一同打包的用户自定义 Python 模块如 tokenizer 模块、预处理模块对自定义 Pipeline 的加载尤为重要metadatadict[str, t.Any]模型元数据所有值必须是str/int等原始类型用于模型管理界面展示save_kwargs关键字参数透传给save_pretrained的额外参数例如save_formattf、max_shard_size等2.2 官方示例保存文本生成 PipelineAPI 参考文档与源码 docstring 给出的典型用法如下import bentoml from transformers import pipeline, AutoTokenizer, AutoModelForCausalLM tokenizer AutoTokenizer.from_pretrained(distilgpt2) model AutoModelForCausalLM.from_pretrained(distilgpt2) generator pipeline(tasktext-generation, modelmodel, tokenizertokenizer) bento_model bentoml.transformers.save_model(text-generation-pipeline, generator)返回值为bentoml.Model实例其tag形如name:version其中version是 BentoML 自动生成或由Tag指定的版本号。保存预处理对象如仅保存 tokenizer也是合法的因为其同样实现了save_pretrained/from_pretrained协议。集成测试 tests/integration/frameworks/models/transformers.py 中甚至以gpt2_tokenizer与vit_processorAutoImageProcessor为对象分别执行了保存与加载验证。2.3 源码级实现Pipeline 与 PreTrained 两条分支save_model内部通过LazyType(transformers.Pipeline).isinstance(pretrained_or_pipeline)判断对象类型从而走两条不同的落盘路径见源码 L1052-L1167分支 A保存 Pipeline。先通过check_task(pipeline_.task)推导任务定义然后with bentoml.models._create(name, moduleMODULE_NAME, api_versionAPI_VERSION, optionsModelOptions.from_task(*options_args), ...) as bento_model: pipeline_.save_pretrained(bento_model.path, **save_kwargs) # 权重已落盘此处仅 pickle 类保证 TensorFlow / Flax Pipeline 也能工作 with open(bento_model.path_of(PIPELINE_PICKLE_NAME), wb) as f: cloudpickle.dump(pipeline_.__class__, f)注意pipeline 的save_pretrained会递归把内部的 model、tokenizer、feature extractor 等全部写入bento_model.path目录。分支 B保存 PreTrained 对象。校验对象具有save_pretrained/from_pretrained后写入PRETRAINED_PROTOCOL_NAMEmetadata.update({_pretrained_class: pretrained.__class__.__name__}) if hasattr(pretrained, framework): metadata[_framework] pretrained.framework # pt / tf / flax ... pretrained.save_pretrained(bento_model.path, **save_kwargs) with open(bento_model.path_of(PRETRAINED_PROTOCOL_NAME), wb) as f: cloudpickle.dump(pretrained.__class__, f)写入的_pretrained_class与_framework元数据会在load_model与 Runner 初始化阶段被读取用于决定from_pretrained的调用方式以及 CPU/GPU 放置策略。2.4ModelOptions模型的落盘配置保存时使用的ModelOptions定义于源码 L172-L263会把任务信息结构化记录下来其字段包括taskPipeline 任务名如text-generationtf/pt该任务支持的 TensorFlow / PyTorch AutoModel 类名元组如(AutoModelForSeq2SeqLM,)用于自定义 Pipeline 的注册与重建default任务默认模型映射如{model: {pt: t5-base, tf: t5-base}}typePipeline 类型取值为text/audio/image/multimodalkwargs透传给transformers.pipeline(...)的附加关键字参数。这些字段会序列化进模型的model.yaml供load_model与get_runnable读取。三、load_model从 Model Store 还原模型3.1 函数签名def load_model(bento_model: str | Tag | Model, *args: t.Any, **kwargs: t.Any) - t.Any参数说明见源码 docstring位于 L371-L393bento_model可以是 Model Store 中的模型 tag如my_model:latest也可以是已获取的bentoml.Model实例args仅当保存对象是 PreTrained 协议对象时使用会被透传给from_pretrained当保存对象是 Pipeline 时禁止使用位置参数源码中有显式断言kwargs透传给transformers.pipeline(...)或from_pretrained(...)的关键字参数例如use_fastTrue、device0。官方示例import bentoml pipeline bentoml.transformers.load_model(my_model:latest)3.2 底层加载逻辑load_model首先通过get()校验模型模块归属必须是bentoml.transformers保存的模型然后读取api_version与taskv1 兼容分支旧版本保存的模型读取pipeline.v1.pkl给出升级建议日志并走transformers.pipeline(tasktask, modelbento_model.path, **kwargs)路径v2 分支当前 API 版本先检查元数据中是否存在_pretrained_classif _pretrained_class in bento_model.info.metadata: # 保存的是 PreTrained 对象反序列化类后调用 from_pretrained protocol cloudpickle.load(open(bento_model.path_of(PRETRAINED_PROTOCOL_NAME), rb)) return protocol.from_pretrained(bento_model.path, *args, **kwargs) else: # 保存的是 Pipeline反序列化类后按 task 重建 pipeline_class cloudpickle.load(open(bento_model.path_of(PIPELINE_PICKLE_NAME), rb)) kwargs.setdefault(pipeline_class, pipeline_class) return transformers.pipeline(tasktask, modelbento_model.path, **kwargs)若task不在 Transformers 支持的任务列表中说明是自定义 Pipeline此时会自动调用register_pipeline把pipeline_class与ModelOptions中记录的pt/tf/default/type重新注册进 Transformers 的 Pipeline 注册表并自动开启trust_remote_codeTrue以兼容远程代码。源码中同时给出了一个实用提示当自定义 Pipeline 尚未发布到 Hugging Face Hub 时建议用external_modules显式携带其定义模块例如import importlib bentoml.transformers.save_model(..., external_modules[importlib.import_module(pipeline_instance.__module__)])四、get与import_model检索与从 Hub 导入4.1get按 tag 获取模型对象def get(tag_like: str | Tag) - Model从 Model Store 中按 tag 取出bentoml.Model实例并校验该模型确实由bentoml.transformers模块保存否则抛出NotFound异常。官方示例import bentoml # target model must be from the BentoML model store model bentoml.transformers.get(my_pipeline:latest)get也是load_model内部的第一个步骤当传入的是字符串 tag 时先get再加载。测试用例 tests/integration/frameworks/test_transformers_unit.py 展示了典型的取模型 → 转 Runner → 本地初始化 → 运行推理链路bento_model bentoml.transformers.get(my_classification_model) runner bento_model.to_runner() runner.init_local() assert runner.run(I hate you, second_textI love you) expected_output4.2import_model不加载权重直接从 Hub 入库当模型体积巨大、不想在导入时占用内存时可用import_model直接从 Hugging Face Hub 将模型文件拷入 Model Store定义于源码 L615-L919。其关键参数参数默认值说明name—在 Model Store 中的名称需为合法Tagmodel_name_or_path—HF 仓库 ID如CompVis/ldm-text2im-large-256或本地权重目录proxiesNone代理配置如{http: foo.bar:3128}revisionmain分支名、tag 名或 commit idforce_downloadFalse是否强制重新下载覆盖缓存resume_downloadFalse断点续传trust_remote_codeFalse是否允许执行 Hub 上的自定义建模代码仅在可信仓库置Trueclone_repositoryFalse是否下载仓库全部文件快照默认只下载所需文件sync_with_hub_versionFalse是否用 HF 的 commit hash 覆盖模型版本号本地目录导入时不可用signatures自动推断默认{__call__: {batchable: False}}labels/custom_objects/metadata—同save_modelextra_hf_hub_kwargs—透传 HF 下载选项如from_tfTrue下载tf_model.h5、from_flaxTrue下载flax_model.msgpack、use_safetensorsTrue下载model.safetensors默认目标是pytorch_model.bin其实现要点是借助仓库内 vendored 的init_empty_weights上下文src/bentoml/_internal/frameworks/utils/transformers.py源自 accelerate在 meta device 上初始化空权重模型以解析架构避免把全部权重读入内存随后通过shutil.copytree把权重目录整体复制进 Model Store并 pickle 预训练类到pretrained.v2.pkl。测试test_import_model_has_required_files验证了导入后目录中应包含config.json、pytorch_model.bin、pretrained.v2.pkl与model.yaml四个关键文件。官方示例import bentoml bentoml.transformers.import_model( my_t5_model, t5-base, signatures{__call__: {batchable: False}}, )五、自定义 Pipelinetask_nametask_definition的完整保存方案保存自定义 Pipeline 时task_name与task_definition必须同时提供且task_definition需包含以下键见源码 L946-L967 的说明与示例implPipeline 实现类type[transformers.Pipeline]必须与传入的 pipeline 实例类型一致pt/tfPyTorch / TensorFlow 的 AutoModel 类元组二者至少提供一个default默认模型、tokenizer 等映射如{model: {pt: t5-base, tf: t5-base}}typePipeline 类型text/audio/image/multimodal。完整的自定义 Pipeline 保存示例节选自源码 docstringtask_definition { impl: Text2TextGenerationPipeline, tf: (TFAutoModelForSeq2SeqLM,) if is_tf_available() else (), pt: (AutoModelForSeq2SeqLM,) if is_torch_available() else (), default: {model: {pt: t5-base, tf: t5-base}}, type: text, }保存时源码会做三道一致性校验均有对应测试覆盖task_name必须与pipeline_.task一致否则抛BentoMLException见test_raise_does_not_match_task_nametask_definition必须包含impl键pipeline_必须是impl的实例否则抛BentoMLException见test_raise_does_not_match_impl_field。若task_name尚未注册save_model会自动调用模块级的register_pipeline(task_name, **task_definition)将其写入 Transformers 的PIPELINE_REGISTRYtransformers 4.21或SUPPORTED_TASKS旧版本对应地也可用delete_pipeline(task)移除。集成测试中定义了一个接收second_text参数的自定义PairClassificationPipelinetests/integration/frameworks/models/transformers.py并以保存 →load_model重建 → Runner 推理三步验证了自定义 Pipeline 的完整闭环由于自定义类不在 Hub 上测试通过external_modules[importlib.import_module(., tests.integration.frameworks.models)]携带定义模块。六、推理签名与 Runner 集成6.1 默认签名推断make_default_signatures不显式传signatures时BentoML 会根据对象类型自动推断可暴露的推理方法源码 L534-L612推断规则如下对象类型默认签名方法PreTrainedTokenizerBasetokenizer__call__、tokenize、encode、encode_plus、batch_encode_plus、pad、decode、batch_decode等 16 个方法PreTrainedModelPyTorch 模型__call__、forward、generate、sample、beam_search、greedy_search等TFPreTrainedModelTensorFlow 模型__call__、predict、call、generate、beam_search等FlaxPreTrainedModelFlax 模型__call__、generateBaseImageProcessor__call__、preprocessSequenceFeatureExtractorpadProcessorMixin子类__call__、batch_decode、decode并提示额外函数需手动指定签名所有默认签名均为batchableFalse若想启用批处理需显式传入签名例如集成测试batched_pipeline的做法save_kwargs{signatures: {__call__: {batchable: True}}}另外注意transformers 版本低于 4.17 时签名推断被禁用源码会输出 warning 并要求手动指定因为推断依赖较新的内部结构。6.2 Runnerget_runnable与资源分配get_runnable源码 L1170-L1260构建的TransformersRunnable声明SUPPORTED_RESOURCES (nvidia.com/gpu, cpu)并支持 CPU 多线程。其初始化逻辑根据CUDA_VISIBLE_DEVICES与元数据中的_framework决定设备策略Pipeline直接以devicegpu_id加载到 GPUPyTorch 模型.to(torch.device(cuda if gpu else cpu))TensorFlow 模型包在tf.device(/device:GPU:id 或 /device:CPU:0)中Flax 模型先通过tf.config.experimental.set_visible_devices([], GPU)隐藏 GPU避免 TensorFlow 抢占显存再加载。随后遍历bento_model.info.signatures用TransformersRunnable.add_method(...)把每个签名方法batchable、batch_dim、input_spec、output_spec均来自ModelSignature注册为 Runner 的可调用方法。这也是bento_model.to_runner()能够直接runner.run(...)的原因。七、模型的最终消费服务化与部署保存到 Model Store 的 Transformers 模型可以立即用于bentoml.service定义推理服务这是 BentoML 将模型交付为在线 API 的标准路径。更通用的模型保存/加载/管理背景可参考 docs/source/build-with-bentoml/model-loading-and-management.rst其中也展示了不借助框架 API、直接用bentoml.models.create()配合pipeline.save_pretrained(model_ref.path)的底层保存方式以及BentoModel/HuggingFaceModel在服务类作用域中的声明式用法。入门级的完整示例见 docs/source/get-started/hello-world.rst框架总览见 docs/source/reference/bentoml/frameworks/index.rst。八、小结围绕docs/source/reference/bentoml/frameworks/transformers.rst收录的save_model/load_model/get三个 API本文结合源码补充了import_model、register_pipeline、默认签名推断与 Runner 资源分配等完整链路。核心要点回顾保存save_model对 Pipeline 与 PreTrained 对象分别采用pipeline.v2.pkl与pretrained.v2.pkl两种协议权重统一经save_pretrained落盘加载load_model依据_pretrained_class元数据区分两条重建路径自定义 Pipeline 会自动注册回 Transformers 注册表检索get负责按 tag 校验并取出bentoml.Model是load_model与to_runner()的前置步骤自定义 Pipeline必须成对提供task_name与task_definition并用external_modules携带定义模块模型消费经to_runner()获得的 Runner 可直接集成进 BentoML Service实现从模型文件到在线推理 API 的全流程交付。所有结论均可在当前仓库的 src/bentoml/_internal/frameworks/transformers.py、tests/integration/frameworks/test_transformers_unit.py 与 tests/integration/frameworks/models/transformers.py 中逐一核对。赞分享模型推理服务人工智能后端大模型MLOpsLLMOps【免费下载链接】BentoMLThe easiest way to serve AI apps and models - Build Model Inference APIs, Job queues, LLM apps, Multi-model pipelines, and more!项目地址https://gitcode.com/gh_mirrors/be/BentoML点击查看免费下载相关推荐MLflow ONNX 模型接入实战save_model / log_model / load_model 全流程指南MLflow ONNX 模型接入实战save_model / log_model / load_model 全流程指南 mlflow.onnx 是 MLfloMLOpsLLMOps人工智能大模型模型评测LLM 网关可观测性ATX自动化测试框架API详解与实战指南ATX自动化测试框架API详解与实战指南 概述 ATX是一款强大的自动化测试框架主要用于移动设备 Android/iOS 的UI自动化测试。本文将全面介绍ATSimpleImage 框架详解与实战指南SimpleImage 框架详解与实战指南 1. 项目介绍 SimpleImage 是一个由阿里巴巴开发的轻量级图像处理库它提供了一系列简单的API用于在P上一篇VirtualAPK性能优化启动优化专项实践与效果下一篇LiveViewJS核心架构解析如何实现WebSocket驱动的实时DOM更新创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考