[特殊字符] Diffusers 混合推理（Hybrid Inference）实战指南：远程 VAE 编解码与本地 AI 构建
Diffusers 混合推理Hybrid Inference实战指南远程 VAE 编解码与本地 AI 构建【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers混合推理Hybrid Inference是 Diffusers 提供的实验性能力它将 VAE 编码、解码这类内存密集的生成环节卸载到远端推理端点让本地设备只运行文本编码器与 UNet/Transformer 主干从而在普通显卡甚至无 GPU 环境下也能跑高质量生成工作流。读完本文你将掌握remote_encode/remote_decode的完整调用方式、各模型对应的缩放系数与端点配置、分块tiled内存优化思路以及如何在 img2img 等真实管线中落地这套方案。为什么使用混合推理混合推理提供了一种快速、简单的方式来卸载本地生成需求它的核心价值可以概括为降低要求无需昂贵硬件即可访问强大模型。VAE 的编解码往往占据显著显存把它放到远端后本地只需承载扩散主干无妥协在不牺牲性能的前提下实现最高质量输出解码结果与本地 VAE 产出保持同一水平成本效益高当前该实验性服务免费开放是低成本接入高性能 VAE 的途径多样化用例与 Diffusers 生态及更广泛的社区完全兼容可作为独立工具使用也可嵌入现有管线开发者友好接口简单——一次 HTTP 请求、快速响应配合diffusers提供的辅助函数即可调用。从实现看这一功能由 src/diffusers/utils/remote_utils.py 提供核心是remote_encode与remote_decode两个函数它们将张量/图像序列化后通过requests.post发送到远端端点再把返回的二进制流还原为torch.Tensor、PIL.Image.Image或视频字节。[!TIP] 混合推理属于实验性功能接口与端点可能随版本调整建议从main分支安装使用pip install githttps://github.com/huggingface/diffusersmain。可用模型与端点混合推理目前覆盖以下能力端点在 src/diffusers/utils/constants.py 中以DECODE_ENDPOINT_*/ENCODE_ENDPOINT_*常量形式预置能力说明VAE 解码 ️快速将潜在表示latents解码为高质量图像不影响性能或工作流速度VAE 编码 高效将图像编码为潜在表示用于生成和训练图像到图像、图像到视频等场景文本编码器 即将推出快速准确计算提示词的文本嵌入保障流畅高质量的工作流对应不同模型家族的可用端点与模型如下模型端点Encode端点Decode后端模型Stable Diffusion v1https://qc6479g0aac6qwy9.us-east-1.aws.endpoints.huggingface.cloud/https://q1bj3bpq6kzilnsu.us-east-1.aws.endpoints.huggingface.cloud/stabilityai/sd-vae-ft-mseStable Diffusion XLhttps://xjqqhmyn62rog84g.us-east-1.aws.endpoints.huggingface.cloud/https://x2dmsqunjd6k9prw.us-east-1.aws.endpoints.huggingface.cloud/madebyollin/sdxl-vae-fp16-fixFluxhttps://ptccx55jz97f9zgo.us-east-1.aws.endpoints.huggingface.cloud/https://whhx50ex1aryqvw6.us-east-1.aws.endpoints.huggingface.cloud/black-forest-labs/FLUX.1-schnellHunyuan Video解码—https://o7ywnmrahorts457.us-east-1.aws.endpoints.huggingface.cloud/—[!TIP] 需要更多模型支持时可在仓库的 Issue 模板remote-vae-pilot-feedback中提交请求。缩放系数与移位系数不同模型的 latent 需要乘以不同的缩放系数scaling_factor、加上移位系数shift_factor这些值定义在 VAE 的config中也直接写入了 remote_utils.py 的文档字符串模型scaling_factorshift_factorSD v10.18215—SD XL0.13025—Flux0.36110.1159语义上解码时服务端会执行latents / scaling_factor以及latents shift_factor后送入 VAE编码时则执行latents * scaling_factor以及latents - shift_factor。如果传入scaling_factorNone则要求调用方在本地完成缩放后再传参。快速上手remote_encode 与 remote_decode辅助方法简化了与混合推理的交互直接导入即可from diffusers.utils.remote_utils import remote_encode, remote_decode基本示例编码一张图像再解码下面的示例将一张宇航员图片远程编码为潜在表示再远程解码回图像完整走一遍「编 → 解」闭环from diffusers.utils import load_image from diffusers.utils.remote_utils import remote_decode, remote_encode image load_image(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg?downloadtrue) latent remote_encode( endpointhttps://ptccx55jz97f9zgo.us-east-1.aws.endpoints.huggingface.cloud/, imageimage, scaling_factor0.3611, shift_factor0.1159, ) decoded remote_decode( endpointhttps://whhx50ex1aryqvw6.us-east-1.aws.endpoints.huggingface.cloud/, tensorlatent, scaling_factor0.3611, shift_factor0.1159, )remote_encode接受PIL.Image.Image或torch.Tensor输入返回torch.Tensorremote_decode接受潜在张量默认返回PIL.Image.Image。二者的完整签名与返回类型由 remote_utils.py 中的 docstring 详细说明。生成示例img2img 全流程更贴近实战的场景是把混合推理接入真实管线——先用远端编码得到初始 latent本地只跑 UNet 去噪输出 latent最后再远程解码成图import torch from diffusers import StableDiffusionImg2ImgPipeline from diffusers.utils import load_image from diffusers.utils.remote_utils import remote_decode, remote_encode pipe StableDiffusionImg2ImgPipeline.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, dtypetorch.float16, variantfp16, vaeNone, # 关键本地不加载 VAE交给远端 ).to(cuda) init_image load_image( https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg ) init_image init_image.resize((768, 512)) init_latent remote_encode( endpointhttps://qc6479g0aac6qwy9.us-east-1.aws.endpoints.huggingface.cloud/, imageinit_image, scaling_factor0.18215, ) prompt A fantasy landscape, trending on artstation latent pipe( promptprompt, imageinit_latent, strength0.75, output_typelatent, # 让管线直接返回 latent ).images image remote_decode( endpointhttps://q1bj3bpq6kzilnsu.us-east-1.aws.endpoints.huggingface.cloud/, tensorlatent, scaling_factor0.18215, ) image.save(fantasy_landscape.jpg)注意其中的两个关键设计from_pretrained(..., vaeNone)让本地不加载 VAE 权重这是显存节省的主要来源管线以output_typelatent输出绕开本地解码最后统一走remote_decode。API 参数详解remote_decode/remote_encode的参数覆盖了输入输出格式、缩放、后处理等多个维度以下结合源码逐一说明remote_decode 参数参数类型 / 默认值说明endpointstr远端解码端点 URLtensortorch.Tensor待解码的潜在张量processorVaeImageProcessor/VideoProcessor可选与return_typept或视频模型的return_typepil配合使用do_scalingbool默认True已弃用请改传scaling_factor/shift_factor设为False表示输入已完成缩放scaling_factorfloat可选服务端执行latents / scaling_factorSD v1 为0.18215SD XL 为0.13025Flux 为0.3611shift_factorfloat可选服务端执行latents shift_factorFlux 为0.1159output_typemp4/pil/pt默认pil端点返回类型。图像模型pil返回image_format指定的图像字节视频模型mp4返回视频字节、pil返回部分后处理的张量需传processor占位pt返回torch.Tensor配合partial_postprocessTrue时为uint8图像张量return_typemp4/pil/pt默认pil函数返回类型。pil返回PIL.Image.Imagept返回torch.Tensorpartial_postprocessFalse时为float16/bfloat16未反归一化True时为反归一化的uint8image_formatpng/jpg默认jpg与output_typepil配合指定端点返回的图像格式partial_postprocessbool默认False与output_typept配合是否做部分后处理input_tensor_type/output_tensor_typebinary默认张量传输格式base64已弃用height/widthint可选packed latents如 Flux 的[1, 4096, 64]形状必须提供用于还原空间维度源码中的check_inputs_decoderemote_utils.py会对参数做前置校验3 维张量且未提供height/width时抛出ValueErroroutput_typept且return_typepil但未传processor时同样报错。传输协议上prepare_decode会把张量序列化为二进制Content-Type: tensor/binary并以Accept: image/jpeg/image/png/tensor/binary声明期望的返回格式。官方推荐组合ptpartial_postprocessTrue全质量下传输量最小ptpartial_postprocessFalse与第三方代码兼容性最好pilimage_formatjpg整体传输量最小。remote_encode 参数参数类型说明endpointstr远端编码端点 URLimagetorch.Tensor/PIL.Image.Image待编码的图像PIL输入会在本地转成 PNG 字节发送scaling_factorfloat可选服务端执行latents * scaling_factorshift_factorfloat可选服务端执行latents - shift_factor返回torch.Tensor形状为[1, channels, height//8, width//8]8 为 VAE 下采样倍率。内存分析混合推理帮你省下多少显存混合推理最大的价值在显存。以VAE 编码为例docs/source/zh/hybrid_inference/vae_encode.md 给出了不同 GPU 上 SD v1.5 与 SDXL 的实测数据下表为该文档的原始测量。内存占比决定了一个事实对于大多数 GPU要腾出空间承载其他模型文本编码器、UNet/Transformer要么卸载其他组件要么使用分块编码tiled——分块会略微增加时间并影响质量。SD v1.5 VAE 编码内存/耗时GPU分辨率时间秒内存%分块时间秒分块内存%NVIDIA GeForce RTX 4090512x5120.0153.519010.0153.51901NVIDIA GeForce RTX 4090256x2560.0041.31540.0051.3154NVIDIA GeForce RTX 40902048x20480.40247.18520.4963.51901NVIDIA GeForce RTX 40901024x10240.07812.26580.0943.51901NVIDIA GeForce RTX 4080 SUPER512x5120.0235.301050.0235.30105NVIDIA GeForce RTX 4080 SUPER256x2560.0061.981520.0061.98152NVIDIA GeForce RTX 4080 SUPER2048x20480.57471.080.6565.30105NVIDIA GeForce RTX 4080 SUPER1024x10240.11118.47720.145.30105NVIDIA GeForce RTX 3090512x5120.0323.527820.0323.52782NVIDIA GeForce RTX 3090256x2560.011.318690.0091.31869NVIDIA GeForce RTX 30902048x20480.74247.30330.9543.52782NVIDIA GeForce RTX 30901024x10240.13612.29650.2073.52782NVIDIA GeForce RTX 3080512x5120.0368.517610.0368.51761NVIDIA GeForce RTX 3080256x2560.013.183870.013.18387NVIDIA GeForce RTX 30802048x20480.86386.74241.1918.51761NVIDIA GeForce RTX 30801024x10240.15729.68880.2278.51761NVIDIA GeForce RTX 3070512x5120.05110.69410.05110.6941NVIDIA GeForce RTX 3070256x2560.0153.997430.0153.99743NVIDIA GeForce RTX 30702048x20481.21796.0541.48210.6941NVIDIA GeForce RTX 30701024x10240.22337.27510.32710.6941SDXL VAE 编码内存/耗时GPU分辨率时间秒内存%分块时间秒分块内存%NVIDIA GeForce RTX 4090512x5120.0294.957070.0294.95707NVIDIA GeForce RTX 4090256x2560.0072.296660.0072.29666NVIDIA GeForce RTX 40902048x20480.87366.34520.86315.5649NVIDIA GeForce RTX 40901024x10240.14215.54790.14315.5479NVIDIA GeForce RTX 4080 SUPER512x5120.0447.467350.0447.46735NVIDIA GeForce RTX 4080 SUPER256x2560.013.45970.013.4597NVIDIA GeForce RTX 4080 SUPER2048x20481.31787.16151.29123.447NVIDIA GeForce RTX 4080 SUPER1024x10240.21323.42150.21423.4215NVIDIA GeForce RTX 3090512x5120.0585.656380.0585.65638NVIDIA GeForce RTX 3090256x2560.0162.450810.0162.45081NVIDIA GeForce RTX 30902048x20481.75577.82391.61418.4193NVIDIA GeForce RTX 30901024x10240.26518.40230.26518.4023NVIDIA GeForce RTX 3080512x5120.06413.65680.06413.6568NVIDIA GeForce RTX 3080256x2560.0185.917280.0185.91728NVIDIA GeForce RTX 30802048x2048内存不足 (OOM)内存不足 (OOM)1.86644.4717NVIDIA GeForce RTX 30801024x10240.30244.43080.30244.4308NVIDIA GeForce RTX 3070512x5120.09317.14650.09317.1465NVIDIA GeForce RTX 3070256x2560.0257.429310.0267.42931NVIDIA GeForce RTX 30702048x2048内存不足 (OOM)内存不足 (OOM)2.67455.8355NVIDIA GeForce RTX 30701024x10240.44355.78410.44355.7841从上表可以提炼出几条关键结论分辨率是显存瓶颈2048x2048 下 SDXL 编码在 RTX 3080/3070 上直接 OOM而分块后可以流畅运行内存占比从 85% 降至约 44%~56%分块换取稳定分块对低分辨率几乎无开销时间基本持平高分辨率下增加少量时间如 SDXL 在 RTX 3090 上 1.755s → 1.614s但显存骤降混合推理的价值把编码/解码放到远端后本地 GPU 的这些内存开销整体消失表中所占用的显存可以完全让给扩散主干或其他组件。源码视角一次远程调用发生了什么从 src/diffusers/utils/remote_utils.py 的实现看remote_decode的执行链路分为三步校验check_inputs_decode检查 packed latent 是否提供height/width、output_type与processor的搭配是否合法序列化与请求prepare_decoderequests.post把张量通过safetensors.torch._to_ndarray转为二进制将shape、dtype、scaling_factor、shift_factor、image_format、output_type等元信息放入请求参数Content-Type: tensor/binary发送到端点反序列化postprocess_decode从响应头解析shape与dtype支持float16/float32/bfloat16/uint8见DTYPE_MAP用torch.frombuffer重建张量再按output_type/return_type组合输出PIL.Image.Image、张量或视频字节。remote_encode走类似链路prepare_encode→requests.post→postprocess_encode区别在于输入是PIL.Image时会在本地转成 PNG 字节后发送。测试用例佐证仓库在 tests/remote/test_remote_decode.py 与 tests/remote/test_remote_encode.py 中提供了覆盖 SD v1、SD XL、Flux含 packed latent、Hunyuan Video 的端到端测试验证了output_type与return_type的全部组合pil/pt/mp4及其返回类型、尺寸正确性partial_postprocess对张量 dtypefloat16/bfloat16vsuint8与反归一化的影响image_formatpng时output.format pngdo_scaling、input_tensor_typebase64、output_tensor_typebase64的弃用告警多分辨率320 至 2048的编解码一致性测试中编码输出形状恒为[1, channels, h//8, w//8]。这些测试是理解各参数语义的最佳参考例如测试中的TestRemoteAutoencoderKLFluxPacked使用shape(1, 4096, 64)的 packed latent 并显式传入height1024, width1024正是height/width参数存在的意义。[!NOTE] 需要说明的是ENCODE_ENDPOINT_*端点曾在测试中被标记为未部署状态返回 404因此编码端点的可用性以当前实际部署为准DECODE_ENDPOINT_*则持续在慢速测试slow由RUN_SLOW环境变量门控中被调用验证。集成生态混合推理已经得到社区工具链的直接支持SD.Next一体化 UI内置混合推理支持ComfyUI-HFRemoteVae面向 ComfyUI 的混合推理节点可在节点图中直接调用远程 VAE。更新日志2025 年 3 月 10 日新增 VAE 编码能力2025 年 3 月 2 日初始发布包含 VAE 解码。继续深入混合推理的文档分为三部分本文已覆盖其核心内容VAE 编码使用混合推理进行 VAE 编码的基础知识见 docs/source/zh/hybrid_inference/vae_encode.mdVAE 解码使用混合推理进行 VAE 解码的基础知识API 参考任务特定设置与参数的完整签名见 docs/source/zh/hybrid_inference/api_reference.md其中remote_decode/remote_encode的完整文档字符串可直接在 src/diffusers/utils/remote_utils.py 中查阅。如果你正受限于本地显存、又希望不降级地使用高质量 VAE混合推理是目前最简单直接的接入方式一条导入语句、一次请求即可把最重的编解码环节交给远端让本地算力专注于生成本身。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考