BentoML Diffusers API 完整指南：import_model / 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 仓库中bentoml.diffusers模块的 API 参考指南覆盖该模块对外暴露的四个核心函数import_model、save_model、load_model与get。通过本文你将掌握如何把 Hugging Face 上的 Diffusion 模型如 Stable Diffusion 系列导入 BentoML 模型库、如何将内存中的DiffusionPipeline持久化保存、如何按标签重新加载为可推理的 Pipeline并理解调度器替换、LoRA/Textual Inversion 注入、CPU offload 与 torch.compile 等高级加载选项的底层行为。文中所有结论均以本仓库源码 diffusers.py 及其测试为事实依据。bentoml.diffusers模块概览bentoml.diffusers是 BentoML 对 Hugging Face Diffusers 框架的适配层负责把 diffusers 的扩散模型 Pipeline 纳入 BentoML 的模型管理体系中模型以标准 BentoML Model 的形式存入本地模型库model store并可通过统一的bentoml.modelsAPI 进行版本管理、打包进 Bento 并部署为推理服务。在源码中该模块位于 src/bentoml/_internal/frameworks/diffusers.py模块名常量定义为MODULE_NAME bentoml.diffusers内部使用一个固定目录diffusion_model/存放模型权重并以model_index.json作为校验是否为合法 Diffusion 模型的标志文件源码 L42-L44。所有模型在库中都以ModelContext(framework_namediffusers, framework_versions{diffusers: diffusers.__version__})记录框架版本信息。使用前提与依赖该模块在导入时会强制检查diffusers、torch依赖若缺失会抛出MissingDependencyException并提示安装命令源码 L28-L39pip install --upgrade diffusers transformers accelerate此外bentoml.diffusers自 v1.4 起已被标记为弃用见 src/bentoml/init.py 中的_LazyLoader加载警告官方建议在新代码中改用bentoml.diffusers_simple.stable_diffusion/stable_diffusion_xl或直接在 Service 中使用HuggingFaceModel加载后者可参考 sdxl-turbo 示例。尽管如此import_model/save_model/load_model/get仍是理解 BentoML 与 Diffusers 集成原理的最佳入口且内部实现被diffusers_simple路径复用。import_model把 Diffusion 模型导入 BentoML 模型库import_model是bentoml.diffusers中最常用的入口函数源码 diffusers.py#L377-L557用于把 Hugging Face 仓库中的预训练 Pipeline 或本地权重目录导入到 BentoML 模型库。import bentoml bentoml.diffusers.import_model( my_sd15_model, runwayml/stable-diffusion-v1-5, signatures{ __call__: {batchable: False}, } )参数详解参数类型说明nameTag \| str模型在 BentoML 模型库中的名称必须是合法的bentoml.Tag名称可带:version后缀model_name_or_pathstr \| os.PathLikeHugging Face 仓库 id如CompVis/ldm-text2im-large-256或包含save_pretrained产物含model_index.json的本地目录proxiesdict[str, str] \| None按协议/端点指定的代理服务器字典如{http: foo.bar:3128}用于下载请求revisionstr默认main指定 Hugging Face 上模型的具体版本可以是分支名、标签名或 commit idvariantstr \| None模型变体如fp16/fp32例如DeepFloyd/IF-I-XL-v1.0提供这两种变体可节省下载带宽与磁盘空间pipeline_classstr \| type[DiffusionPipeline] \| None指定用于下载与解析模型的 Pipeline 类传字符串时会被解析为类对象见下文_str2clssync_with_hub_versionbool默认False为True时模型版本将自动与 Hugging Face 仓库的 commit hash 同步signaturesdict推理方法签名默认{__call__: {batchable: False}}labels/custom_objects/external_modules/metadata杂项管理标签、自定义对象cloudpickle 序列化、外部模块与元数据须为str/int等原始类型版本同步机制sync_with_hub_version当sync_with_hub_versionTrue时导入完成后会从下载目录中解析出 commit hash 作为模型版本号如果同时指定了variant版本号会追加-variant后缀源码 L511-L534version extract_commit_hash(src_dir, REGEX_COMMIT_HASH) if version is not None: if variant is not None: version version - variant tag.version version两个注意点源码中均有实现逻辑若用户显式传入name:version日志会警告该版本可能被 Hub commit hash 覆盖当model_name_or_path指向本地目录时sync_with_hub_versionTrue会直接抛出BentoMLExceptionCannot sync version with huggingface hub when importing a local model。这一点由测试 test_diffusers_unit.py 明确验证sync_with_hub_versionTrue时bento_model.tag.version等于传入的revisioncommit hash不开启时保留用户显式指定的版本如asdf。三种导入路径源码根据model_name_or_path的性质选择下载方式本地目录直接使用该目录作为源目录源码 L499-L504指定了pipeline_class调用pipeline_class.download(...)精确下载对应 Pipeline 组件源码 L506-L509适用于需要按 Pipeline 结构组织权重的场景未指定 Pipeline 类回退到huggingface_hub.snapshot_download全量快照下载源码 L520-L527。无论走哪条路径最终都会校验源目录中是否存在model_index.json不存在则抛出BentoMLException(fartifact {src_dir} is not a Diffusion model)源码 L551-L553随后把整个目录忽略.git复制进模型库的diffusion_model/目录。pipeline_class字符串解析_str2clspipeline_class支持直接传类对象或类名字符串。字符串解析逻辑位于 diffusers.py#L154-L168先按最后一个.切分模块名与类名若未提供模块名则默认从diffusers导入最终通过importlib.import_modulegetattr得到类。因此你既可以写diffusers.StableDiffusionPipeline也可以直接写StableDiffusionPipeline。save_model保存内存中的 Pipeline如果你已经在内存中构造好了一个diffusers.DiffusionPipeline例如微调或组合过组件之后可以调用save_model直接写入模型库源码 diffusers.py#L560-L638import diffusers import bentoml pipeline diffusers.StableDiffusionPipeline.from_pretrained(runwayml/stable-diffusion-v1-5) bentoml.diffusers.save_model(my_sd15_model, pipeline)关键行为参数pipeline必须是diffusers.DiffusionPipeline实例否则抛出BentoMLException未传signatures时默认同样为{__call__: {batchable: False}}底层调用pipeline.save_pretrained(diffusion_model_dir)把完整 Pipeline含model_index.json与各组件权重序列化进模型库的diffusion_model/目录。注意save_model与import_model的一个差异save_model不记录options源码 L629 传入optionsNone因此通过save_model保存的模型不具备pipeline_class、variant等持久化选项加载时的行为完全由load_model的参数决定。load_model从模型库加载为可推理 Pipelineload_model是运行时最核心的函数源码 diffusers.py#L197-L374它把模型库中的 Diffusion 模型还原为 diffusers Pipelineimport bentoml pipeline bentoml.diffusers.load_model(my_diffusers_model:latest) images pipeline(prompt)bento_model参数既可以是Tag/str内部先经get校验模块归属也可以是现成的bentoml.Model实例。若模型的info.module不是bentoml.diffusers会抛出NotFound。主要加载参数参数类型 / 默认说明device_idstr \| torch.device \| None把 Pipeline 放到指定设备参考 PyTorch device 属性pipeline_class默认diffusers.DiffusionPipeline用于加载保存模型的 Pipeline 类支持字符串形式经_str2cls解析device_mapNone \| str \| dict[str, int \| str \| torch.device]指定每个子模块放置的设备映射透传给from_pretrainedcustom_pipelinestr \| None社区自定义 Pipeline 标识托管于 GitHub 的 community pipelinesscheduler_classtype[SchedulerMixin] \| None加载后替换 Pipeline 使用的调度器torch_dtypestr \| torch.dtype \| None覆盖默认 dtype 加载模型权重low_cpu_mem_usagebool \| None不初始化权重、只加载预训练权重以加速加载enable_xformersbool默认False启用 xformers 内存高效注意力enable_attention_slicingint \| str \| None启用注意力切片可传 slice sizeenable_model_cpu_offload/enable_sequential_cpu_offloadbool \| None两种 CPU offload 策略enable_torch_compilebool \| None对 UNet 执行torch.compilevariantstr \| None加载指定变体权重文件如pytorch_model.variant.binlora_weightsLoraOptionType \| list[...] \| None加载 LoRA 权重见下文textual_inversionsTextualInversionOptionType \| list[...] \| None加载 Textual Inversion 权重load_pretrained_extra_kwargsdict[str, Any] \| None透传给 Pipelinefrom_pretrained的额外 kwargs加载流程的源码级细节low_cpu_mem_usage的自动判定为None时若 torch ≥ 1.9.0 且accelerate可用则自动置True否则False源码 L305-L309Pipeline 实例化调用pipeline_class.from_pretrained(diffusion_model_dir, torch_dtype..., low_cpu_mem_usage..., device_map..., custom_pipeline..., variant..., **load_pretrained_extra_kwargs)源码 L312-L320调度器替换若传入scheduler_class用scheduler_class.from_config(pipeline.scheduler.config)重建并替换pipeline.scheduler源码 L322-L326设备迁移的防冲突逻辑当目标设备是cuda且同时启用了device_map、sequential_cpu_offload或model_cpu_offload时跳过pipeline.to(device_id)避免与 offload/分片机制冲突源码 L328-L343注释引用了 diffusers 的 issue #2782优化开关顺序执行enable_xformers→sequential_cpu_offload→model_cpu_offload→attention_slicing→torch_compile对pipeline.unet以modereduce-overhead, fullgraphTrue编译源码 L357-L361。LoRA 与 Textual Inversion 的加载LoraOptionType可以是str或dict[str, str]字符串形式_prepare_lora_args源码 L77-L119先按“本地权重文件路径”解析——绝对路径存在则直接用否则拼接lora_dir默认当前工作目录支持~展开再判断相对路径。路径解析成功则返回(model_name, {weight_name: 文件名})。若两者都不命中则把字符串当作 Hugging Face 仓库 id 处理格式须为org/repo/weightfile形式至少两个/否则抛出ValueError。字典形式必须包含model_name键指向 Hub 仓库或本地目录可含weight_name键及其他透传给pipeline.load_lora_weights的 kwargs。加载时若传入多个 LoRA 权重源码会记录警告“Currently diffusers only support single lora weight loading”并只加载第一个源码 L130-L137。此外load_model在加载 LoRA 前会校验pipeline_class是否是LoraLoaderMixin的子类Textual Inversion 同理校验TextualInversionLoaderMixin不满足直接抛NotImplementedError源码 L291-L301。get从模型库获取 Model 对象get是最轻量的 API源码 diffusers.py#L171-L194import bentoml model bentoml.diffusers.get(my_stable_diffusion_model)它接收str | Tag返回bentoml.Model。与通用bentoml.models.get的区别在于它会校验模型的info.module是否为bentoml.diffusers若不是则抛出NotFound从而避免用 diffusers 加载器误读其他框架保存的模型。拿到 Model 实例后可以继续调用model.with_options(...)或model.to_runnable()完成服务化装配。服务化Runnable 与运行时行为bentoml.diffusers通过私有接口get_runnable(bento_model)源码 diffusers.py#L641-L868把模型转换为 BentoML 的Runnable建议通过bentoml.Model.to_runnable使用。该 Runnable 的行为可以从bentoml.models._create时持久化的ModelOptions推导ModelOptions定义在 diffusers.py#L53-L74覆盖pipeline_class、scheduler_class、torch_dtype、device_map、各类 offload/优化开关、variant、lora_dir、lora_weights、textual_inversions等。Runnable 的运行时特性均有源码依据资源声明SUPPORTED_RESOURCES (nvidia.com/gpu, cpu)SUPPORTS_CPU_MULTI_THREADING Truedtype 默认策略CUDA 可用且未显式指定torch_dtype时自动使用torch.float16CUDA 可用且未显式指定enable_xformers时若环境安装了 xformers 则自动启用动态 LoRA若 Pipeline 类支持 LoRARunnable 会注册_load_lora_weights/_unload_lora_weights私有方法调用推理方法时可通过 kwargs 传入lora_weights在推理前后自动加载/卸载并在finally中执行torch.cuda.empty_cache()释放显存源码 L816-L828调度器热替换注册了_replace_scheduler(scheduler_txt)方法按类名字符串解析新调度器若与当前调度器类型相同则直接返回{success: True}若兼容则替换否则返回失败原因cannot import scheduler class/scheduler class is incompatible to this pipeline见 tests/integration/frameworks/models/diffusers.py 中对_replace_scheduler的四组用例断言输出归一化推理结果若是diffusers.utils.BaseOutputdiffusers 新版输出容器统一to_tuple()转成可序列化元组源码 L831-L833。简化入口stable_diffusion / stable_diffusion_xl对于 Stable Diffusion 与 SDXL 这类最常见的模型仓库在 diffusers_simple.py 提供了开箱即用的 Runner 工厂stable_diffusion.create_runner(...)与stable_diffusion_xl.create_runner(...)实现位于 stable_diffusion.py 与 stable_diffusion_xl.py。它们内部复用了import_modelsync_with_hub_versionTrue的导入链路get_model_or_downloadutils.py会先用bentoml.diffusers.get查本地模型库存在且与 Hub 最新 commit 一致则直接复用否则自动导入并把 Hub commit hash 作为版本号模型名由backend-model_id规范化生成/转--、_转-。两个工厂分别预设了默认模型与 Pipeline 映射stable_diffusion默认stabilityai/stable-diffusion-2-1支持text2img/img2img默认输出尺寸768×768stable_diffusion_xl默认stabilityai/stable-diffusion-xl-base-1.0支持text2img/img2img默认输出尺寸1024×1024。create_runner的参数与load_model高度对齐pipeline_class、scheduler_class、torch_dtype、各类 offload 与优化开关、lora_weights、textual_inversions等最终通过model.with_options(**options).to_runner()产出 Runner。测试验证与事实来源仓库的集成测试确认了上述行为tests/integration/frameworks/models/diffusers.py使用hf-internal-testing/tiny-stable-diffusion-torch构造测试模型验证__call__输出形状为(256, 256, 3)并覆盖_replace_scheduler的成功/导入失败/不兼容三种分支tests/integration/frameworks/test_diffusers_unit.py验证sync_with_hub_version对模型版本号的影响Hub commit hash 覆盖用户版本、本地导入禁用同步等。小结bentoml.diffusers的四个 API 构成了一条完整的模型生命周期链路import_model入库→get查询→load_model加载推理→save_model保存自定义 Pipeline配合ModelOptions与 Runnable 机制即可将 Diffusion 模型无缝接入 BentoML 的 Bento 打包与部署流程。若你的目标只是快速服务 Stable Diffusion 系模型可直接使用bentoml.diffusers_simple.stable_diffusion/stable_diffusion_xl工厂而理解本文的底层 API将帮助你更精细地控制调度器、dtype、LoRA 注入与显存优化策略。赞分享模型推理服务人工智能后端大模型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 Transformers 框架 API 详解save_model、load_model 与 get 实战指南BentoML Transformers 框架 API 详解save_model、load_model 与 get 实战指南 本篇是 BentoML 官方 A模型推理服务人工智能后端大模型MLOpsLLMOpsBentoML ONNX 框架 API 参考save_model / load_model / get 完整指南BentoML ONNX 框架 API 参考save_model / load_model / get 完整指南 本篇以 BentoML 官方 API 参考文模型推理服务人工智能后端大模型MLOpsLLMOpsHyperswitch 架构深度解析Router、Scheduler、数据库与可观测性体系Hyperswitch 架构深度解析Router、Scheduler、数据库与可观测性体系 本篇技术指南以 Hyperswitch 官方 架构文档 https模型推理服务人工智能后端大模型MLOpsLLMOps上一篇突破嵌入式开发瓶颈Kotlin/Native物联网应用实战指南下一篇医疗资源优化Parlant智能医疗资源分配创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考