企业官网建设流程全解析

Xinference 图像模型实战：用 diffusers 引擎启动与使用 sd3-medium（Stable Diffusion 3 Medium）

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference

本指南以 Xinference 内置的 sd3-medium 图像模型为核心，讲解如何通过一条xinference launch命令将其加载为可对外服务的推理实例，并覆盖 text2image、image2image、inpainting 三种能力的用法、diffusers 引擎的底层实现、文本编码器量化等显存优化手段，以及宽高必须为 16 倍数等关键使用约束。读完本文，你将掌握 sd3-medium 在 Xinference 中的完整启动、调用与调优方法。

sd3-medium 是什么：模型家族与能力总览

sd3-medium 是 Xinference 内置镜像库中的一款 Stable Diffusion 3 Medium 图像生成模型，归属于stable_diffusion模型家族。根据 sd3-medium.rst 的官方规格说明，其核心属性如下：

• Model Name：sd3-medium
• Model Family：stable_diffusion
• Abilities：text2image（文生图）、image2image（图生图）、inpainting（局部重绘）
• Available ControlNet：None（该模型不提供可附加的 ControlNet 组件）
• Model ID：stabilityai/stable-diffusion-3-medium-diffusers

这份能力清单与仓库中的模型注册表完全一致。在 model_spec.json 中，sd3-medium条目明确声明了model_ability: ["text2image", "image2image", "inpainting"]三种能力，且model_family为stable_diffusion。也就是说，同一个模型权重在加载后可以同时对外提供三类图像服务，无需分别部署三个实例。

模型来源与版本锁定

在 model_spec.json 中，sd3-medium 同时注册了 Hugging Face 与 ModelScope 两个镜像源，便于不同网络环境下的下载：

• Hugging Face：stabilityai/stable-diffusion-3-medium-diffusers，固定 revision 为ea42f8cef0f178587cf766dc8129abd379c90671；
• ModelScope：AI-ModelScope/stable-diffusion-3-medium-diffusers，revision 为master。

值得注意的是，模型 ID 后缀为-diffusers，表明该权重是以 diffusers 格式发布的，这决定了它必须走 Xinference 的diffusers 引擎进行加载（详见下文「底层实现」一节）。版本锁定的 revision 保证了同一模型在不同时间、不同节点上拉取的权重一致，便于生产环境的可复现部署。

一条命令启动 sd3-medium

按官方文档，启动命令非常简单：

xinference launch --model-name sd3-medium --model-type image

执行后，Xinference 会依据模型规格自动完成以下工作：

1. 根据model_src从 Hugging Face（或配置的 ModelScope 镜像）拉取stable-diffusion-3-medium-diffusers权重，并默认使用锁定 revision；
2. 按照virtualenv配置为模型创建/复用独立虚拟环境，并安装依赖（详见下文「环境依赖」一节）；
3. 通过 diffusers 引擎将模型加载到可用 GPU 设备上；
4. 返回一个可用的model_uid，随后即可通过统一的推理 API 进行调用。

扩展启动参数

--model-type image表明这是一类图像模型；此外，Xinference 的launch命令还支持在命令行直接覆盖模型默认配置，例如指定设备、model_uid等。与 sd3-medium 密切相关的两个配置项来自 model_spec.json 中的default_model_config：

• quantize: true：默认启用量化流程；
• quantize_text_encoder: "text_encoder_3"：默认对第三个文本编码器（SD3 三编码器架构中的核心文本编码器）做量化以降低显存占用。

模型虚拟环境隔离

从 model_spec.json 可以看到 sd3-medium 的虚拟环境依赖为：

• #diffusers_dependencies#（diffusers 引擎所需依赖，仅当引擎为 diffusers 时安装）；
• transformers>=4.51.0（加载 SD3 多文本编码器所需的 transformers 版本下限）；
• #system_torch#、#system_numpy#（复用系统已安装的 torch 与 numpy）。

#engine# == "diffusers"这类条件标记说明依赖是随引擎选择动态解析的，Xinference 通过虚拟环境机制把图像模型的依赖与主服务隔离，避免包版本冲突。

底层实现：diffusers 引擎与按能力切换 Pipeline

sd3-medium 的加载与推理由 stable_diffusion/core.py 中的DiffusionModel类实现，所属引擎注册在 engine.py 中：SUPPORTED_ENGINES["diffusers"]将DiffusersImageModel与 diffusers 引擎绑定，required_libs = ("diffusers",)，即模型格式为diffusers。

三种能力对应三种 Pipeline

从源码结构看，DiffusionModel会根据当前请求的能力动态选择 diffusers 的 AutoPipeline 子类（core.py）：

• text2image：AutoPipelineForText2Image
• image2image：AutoPipelineForImage2Image
• inpainting：AutoPipelineForInpainting

当一个模型具备多种能力时，模型会以 text2image Pipeline 为基础加载，并在首次发起 image2image / inpainting 请求时按需转换为对应 Pipeline（通过_ability_to_models缓存）。这正是 sd3-medium 能一个实例提供三种能力的关键：能力的判定来自model_ability，若请求的能力不在列表中，会抛出RuntimeError（例如"does not support image2image"）。

面向 SD3 的两处关键适配

源码中有两条与 SD3 模型直接相关的注释，揭示了 diffusers 引擎为兼容 sd3-medium 所做的特殊处理：

1. 噪声缩放修复（core.py）：在准备 latent 时，如果 scheduler 没有add_noise方法，则改用scale_noise处理，注释明确写道 "Fix for SD3 img2img and inpainting"——这是 SD3 的 FlowMatch 调度器与经典调度器的差异导致的兼容性修正。
2. 尺寸约束与宽高参数（core.py）：SD3 的 image2image / inpainting 要求输入图片宽高为 16 的倍数。源码通过padding_image_to_multiple参数支持自动 padding 到 16 的倍数，并记录原始尺寸（origin_size）以便还原；同时，SD3 的 image2image Pipeline 不接受width/height参数，引擎会通过model_accept_param检查签名后再决定是否传入尺寸。

可用的采样方法

引擎内置的采样方法列表（core.py）同样适用于 sd3-medium，包括Euler、Euler a、Heun、DPM++ 2M、DPM++ 2M SDE、LMS及其 Karras 变体等 16 种，调用时可通过采样器相关参数选择。

三种能力的调用方式

启动成功后，sd3-medium 即通过 Xinference 的统一推理 API 对外服务，按其能力可发起三类请求：

1. text2image：传入文本 prompt 与期望尺寸（如1024*1024），返回生成的图像 URL 或 Base64。
2. image2image：在 prompt 之外再上传一张参考图，模型基于参考图构图生成新图。需注意上传图片的宽高应满足 16 倍数约束（或利用引擎的 padding 能力）；且从源码看，该能力不接受额外的宽高参数，输出尺寸沿用输入图。
3. inpainting：同时上传原始图片与 mask 图片，模型只重绘 mask 覆盖的区域；同样受 16 倍数约束，引擎还支持mask_blur参数对 mask 做模糊处理（core.py）。

这类模型默认以1024*1024尺寸发起 inpainting 请求（方法签名中的size默认值），text2image 的默认尺寸则视 Pipeline 而定。

显存优化：文本编码器量化

sd3-medium 采用 SD3 的三文本编码器架构，其中text_encoder_3是参数量最大的核心编码器，也是显存占用的大头。Xinference 的默认配置quantize: true+quantize_text_encoder: "text_encoder_3"即针对这一点做了优化。

从 core.py 的_quantize_text_encoder实现可以看到：

• 默认量化方法为 bitsandbytes（text_encoder_quantize_method="bnb"），默认量化位数为 8-bit（text_encoder_quantization="8-bit"）；
• 支持通过逗号分隔传入多个编码器名（如text_encoder_3,text_encoder）批量量化；
• 量化后的编码器以self._kwargs[text_encoder_name]形式直接注入 Pipeline 构建参数；
• 若已使用 GGUF 量化 transformer，则跳过文本编码器量化（防止双重量化冲突）；
• 量化流程执行后，若未指定device_map，会自动设置为balanced以在多设备间均衡分布权重（core.py）。

在启动时可覆盖这些默认值，例如改用 4-bit NF4 或对 transformer 单独量化，从而在低显存 GPU 上运行 sd3-medium。

环境依赖与引擎要求

• 依赖库：diffusers 引擎要求安装diffusers；sd3-medium 额外要求transformers>=4.51.0（支撑多文本编码器与新版模型代码）。
• 设备要求：推理依赖 torch 与 GPU（代码中使用get_available_device/gpu_count/move_model_to_available_device等设备工具进行调度）。
• 可用性说明：当前仓库未为 sd3-medium 配置 GGUF 量化文件路径与 ControlNet 组件，因此该模型在仓库内以标准 diffusers 权重形式加载，且不附带 ControlNet 能力，这与文档中 "Available ControlNet: None" 的说明一致。如需更高量化自由度，可关注同一家族中已注册 GGUF 支持的 sd3.5 系列（model_spec.json），但两者是不同模型，配置不可混用。

小结

• sd3-medium 是 Xinference 内置的 Stable Diffusion 3 Medium 图像模型，一个实例同时支持 text2image、image2image、inpainting 三种能力；
• 通过xinference launch --model-name sd3-medium --model-type image即可启动，权重来自 Hugging Face（固定 revision）或 ModelScope 镜像；
• 底层由 diffusers 引擎的DiffusionModel实现，按能力动态切换 AutoPipeline 子类，并对 SD3 的噪声缩放与 16 倍数尺寸约束做了专门适配；
• 默认对text_encoder_3做 8-bit bitsandbytes 量化以降低显存，可按需覆盖量化参数。

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference