Xinference 图像模型指南：使用 stable_diffusion 家族 sd3.5-medium 运行文生图、图生图与局部重绘-平芜编程栈

Xinference 图像模型指南：使用 stable_diffusion 家族 sd3.5-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.5-medium（模型家族stable_diffusion）展开，说明其能力边界、标准启动命令、GGUF 量化加载方式，并结合仓库源码剖析其默认配置、引擎选型与底层实现。读完本文，你将掌握如何用一条xinference launch命令在本地或服务器上拉起该模型，并在需要时通过 GGUF 量化与 CPU offload 在低显存环境运行。

模型规格速览

依据 Xinference 官方内置模型文档 sd3.5-medium.rst，该模型的基本规格如下：

Model Name（模型名）：sd3.5-medium
Model Family（模型家族）：stable_diffusion
Abilities（能力）：text2image（文生图）、image2image（图生图）、inpainting（局部重绘）
Available ControlNet：None（该模型暂不提供内置 ControlNet）

规格明细（Specifications）：

Model ID（HuggingFace 模型 ID）：stabilityai/stable-diffusion-3.5-medium
GGUF Model ID：city96/stable-diffusion-3.5-medium-gguf
GGUF Quantizations（GGUF 量化档位）：F16、Q3_K_M、Q3_K_S、Q4_0、Q4_1、Q4_K_M、Q4_K_S、Q5_0、Q5_1、Q5_K_M、Q5_K_S、Q6_K、Q8_0，共 13 个档位

上述能力与量化信息在模型注册表 model_spec.json 中有一一对应的结构化声明：model_ability为["text2image", "image2image", "inpainting"]，gguf_quantizations列表与文档完全一致，是 Xinference 在启动时校验参数、生成下载文件名的依据。

一行命令启动模型

在 Xinference 中启动sd3.5-medium非常简单，执行：

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

--model-name指定模型注册名sd3.5-medium；
--model-type指定模型类型为image。

执行后 Xinference 会依据内置模型规格自动完成以下工作：根据 model_spec.json 中的model_src确定下载源（HuggingFace 优先，ModelScope 作为国内镜像替代），下载权重文件，创建隔离的 Python 虚拟环境并安装依赖，最后以默认引擎（diffusers）加载模型并对外暴露统一的图像生成 RESTful API。

该命令默认会启用模型规格中声明的默认配置（见下文“默认配置”小节）。如果你希望指定后端引擎（例如改用 vLLM-Omni 引擎），可以在命令中追加--engine参数，例如--engine vLLM；具体引擎差异请参考下文“引擎选型”小节。

使用 GGUF 量化降低显存占用

对于显存有限的场景，Xinference 支持直接加载社区预量化的 GGUF 格式权重，命令如下：

xinference launch --model-name sd3.5-medium --model-type image \ --gguf_quantization ${gguf_quantization} --cpu_offload True

其中：

${gguf_quantization}为上文列出的 13 个档位之一，例如Q4_K_M、Q5_K_M或Q8_0；
--cpu_offload True启用模型的 CPU offload，将部分权重驻留在 CPU 内存、按需搬运到 GPU，进一步压低显存峰值。

GGUF 加载的底层实现

从源码看，GGUF 加载由 diffusers 引擎在 stable_diffusion/core.py 中实现：

引擎调用_quantize_transformer_gguf()，使用diffusers.GGUFQuantizationConfig(compute_dtype=torch_dtype)构造量化配置；
通过 transformer 层类的from_single_file()直接加载 GGUF 权重文件，并复用原始模型目录下transformer子目录中的配置文件；
加载路径self._gguf_model_path由--gguf_quantization参数解析得到：Xinference 依据 model_spec.json 中的文件名模板sd3.5_medium-{quantization}.gguf，将量化档位代入模板并从gguf_model_id（HuggingFacecity96/stable-diffusion-3.5-medium-gguf，ModelScope 镜像Xorbits/stable-diffusion-3.5-medium-gguf）仓库中下载对应文件。

CPU offload 的实现

--cpu_offload True对应源码中的两种路径（stable_diffusion/core.py）：

cpu_offload=True：调用model.enable_model_cpu_offload()，模型整体按层卸载到 CPU；
sequential_cpu_offload=True：调用model.enable_sequential_cpu_offload()，实现更细粒度的顺序卸载，显存占用更低但推理更慢。

需要说明的是：默认规格中该模型的quantize默认值为true（见下文），源码中 GGUF 与内置量化存在互斥处理（stable_diffusion/core.py 在 GGUF 生效时跳过普通量化路径），因此使用 GGUF 时无需再手动叠加其他量化参数。

引擎选型：diffusers 与 vLLM 的能力差异

sd3.5-medium在 Xinference 中可由 diffusers 与 vLLM 两套引擎加载，但能力并不完全相同，这从引擎实现注释中可以清晰确认（vllm/core.py）：

VLLM_SUPPORTED_IMAGE_MODELS中明确包含"sd3.5-medium"，即 vLLM-Omni 引擎已验证支持该模型；
但VLLM_SUPPORTED_ABILITIES仅包含("text2image",)，vLLM 引擎只实现文生图能力；文档声明的image2image与inpainting仅由 diffusers 引擎提供；
在 vllm/core.py 中，gguf_model_path、lightning_model_path、lora_model、controlnet任一参数传入时都会抛出ValueError并提示"请改用 diffusers 引擎"。

因此选型建议：

需求	推荐引擎
文生图，追求 vLLM 引擎的吞吐能力	`vLLM`（仅支持`text2image`）
图生图 / 局部重绘	`diffusers`（默认引擎）
GGUF 量化加载 / CPU offload	`diffusers`（vLLM 引擎明确不支持 GGUF）
LoRA / ControlNet	`diffusers`

模型来源与默认配置

在模型注册表 model_spec.json 中，sd3.5-medium还携带了文档之外的工程化细节：

默认模型配置（default_model_config）：

{ "quantize": true, "quantize_text_encoder": "text_encoder_3", "torch_dtype": "bfloat16" }

quantize: true：默认启用 8bit 量化以降低显存占用；
quantize_text_encoder: "text_encoder_3"：对第三个文本编码器执行量化。SD 3.5 架构包含多个文本编码器，源码中该参数支持逗号分隔多个名称（stable_diffusion/core.py），可按需对text_encoder、text_encoder_2等分别指定；
torch_dtype: "bfloat16"：默认以 bfloat16 精度加载。

模型来源（model_src）：

平台	Model ID	固定 Revision
HuggingFace	`stabilityai/stable-diffusion-3.5-medium`	`94b13ccbe959c51e8159d91f562c58f29fac971a`
ModelScope	`AI-ModelScope/stable-diffusion-3.5-medium`	`master`

HuggingFace 源固定了可复现的 commit revision，ModelScope 源则面向国内网络环境提供镜像加速。两条来源均声明了相同的 GGUF 量化档位与文件名模板。

虚拟环境依赖（virtualenv.packages）：该模型在 diffusers 引擎下依赖#diffusers_dependencies#、transformers>=4.51.0及系统级 torch/numpy；若指定#engine# == "vLLM"，则会安装vllm-omni==0.24.*与vllm==0.24.*。Xinference 会在启动时自动为模型创建隔离虚拟环境，避免不同模型间的依赖冲突。

小结

sd3.5-medium是 Xinference 内置的 stable_diffusion 家族图像模型，覆盖文生图、图生图与局部重绘三类能力。生产实践中建议遵循以下要点：

默认一行命令xinference launch --model-name sd3.5-medium --model-type image即可启动；
显存受限时，从 13 个 GGUF 档位中选择合适的量化（如Q4_K_M），配合--cpu_offload True运行；
需要image2image/inpainting/ GGUF 时务必使用默认的 diffusers 引擎，vLLM 引擎仅支持text2image且不接受 GGUF、LoRA 与 ControlNet 参数；
模型默认启用text_encoder_3量化与 bfloat16 精度，无需手动调整即可获得较好的显存与精度平衡。