Xinference 部署 Z-Image-Turbo文生图/图生图模型启动、默认配置与 GGUF 量化实战【免费下载链接】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 内置模型文档 Z-Image-Turbo 展开讲清这一文生图/图生图模型在 Xinference 中的启动方式、内置模型规格默认推理配置、量化选项、模型来源并结合 model_spec.json 与 stable_diffusion/core.py 源码说明--gguf_quantization、--cpu_offload等启动参数在推理链路中的实际作用帮助读者可复制、可验证地完成部署。模型概览Z-Image-Turbo 的能力定位Z-Image-Turbo 是 Tongyi-MAI 发布的 Turbo 版文生图模型在 Xinference 中被注册为内置模型。按照官方文档给出的模型卡片其核心信息如下属性值Model NameZ-Image-TurboModel Familystable_diffusionAbilitiestext2image文生图、image2image图生图Available ControlNetNone不支持 ControlNet 控制Model IDTongyi-MAI/Z-Image-TurboGGUF Model IDunsloth/Z-Image-Turbo-GGUF几个要点归属 stable_diffusion 模型家族这意味着它走的是 Xinference 的 diffusers 加载链路而不是独立推理引擎双能力同时提供文生图与图生图从源码结构看Xinference 会以文生图 pipeline 形式加载再按需转换为 image2image 变体见下文 stable_diffusion/core.py 的初始化注释不支持 ControlNet文档明确标注 Available ControlNet 为 None因此启动时传入--controlnet会被 image 模型创建入口 中的校验逻辑拒绝对空 controlnet 列表的模型会抛出Model ... has empty controlnet list错误。完整的内置图像模型清单可以在 image 模型索引 中查看同家族的普通版 Z-Image 是它的非 Turbo 变体仅支持标准加载方式无 GGUF 量化选项。启动模型标准命令与 GGUF 量化命令标准启动xinference launch --model-name Z-Image-Turbo --model-type image这条命令会触发 image 模块的模型创建流程create_image_model首先通过match_diffusion匹配到 Z-Image-Turbo 的模型规格然后把model_spec.default_model_config与用户传入的kwargs合并L294-296最终通过ImageCacheManager缓存模型权重并实例化模型类。使用 GGUF 量化权重启动xinference launch --model-name Z-Image-Turbo --model-type image --gguf_quantization ${gguf_quantization} --cpu_offload True其中${gguf_quantization}替换为以下 16 种量化档位之一与 model_spec.json 中声明的gguf_quantizations完全一致BF16、F16、Q2_K、Q3_K_L、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量化档位的选择逻辑是典型的“显存—质量”权衡BF16/F16 保留完整精度适合显存充裕的显卡Q8_0 到 Q4_K_M 这类 K-quant 档位是精度与显存占用相对均衡的常见选择Q2_K/Q3_K 系列则面向显存极度受限的环境具体以实际硬件与画质要求为准。参数在源码中的真实链路当命令带有--gguf_quantization时create_image_model 会调用cache_manager.cache_gguf(gguf_quantization)下载并缓存对应的 GGUF 文件——文件名由规格中的模板z-image-turbo-{quantization}.gguf决定即unsloth/Z-Image-Turbo-GGUF仓库下的具体文件——然后把gguf_model_path透传给模型类。在 stable_diffusion/core.py 中gguf_model_path存在时加载路径会切换到_quantize_transformer_gguf()。源码解析GGUF 量化到底改变了什么Transformer 用 GGUF 单文件加载_quantize_transformer_gguf()的实现位于 stable_diffusion/core.pydef _quantize_transformer_gguf(self): from diffusers import GGUFQuantizationConfig # GGUF transformer torch_dtype self._torch_dtype logger.debug(Quantize transformer with gguf file %s, self._gguf_model_path) self._kwargs[transformer] self._get_layer_cls( transformer ).from_single_file( self._gguf_model_path, quantization_configGGUFQuantizationConfig(compute_dtypetorch_dtype), torch_dtypetorch_dtype, configos.path.join(self._model_path, transformer), )从这段实现可以看到三个关键点只量化 DiT transformer 主干GGUF 文件通过from_single_file载入结构配置仍来自原始模型仓库的transformer子目录也就是说 GGUF 仅替换权重、不改变模型结构计算精度由GGUFQuantizationConfig(compute_dtypetorch_dtype)控制反量化后的计算精度跟随模型的torch_dtype文本编码器保持原样_quantize_text_encoder 在检测到gguf_model_path时直接跳过注释写明 “skip quantization when gguf applied to transformer”因此 GGUF 模式下 text encoder 不做量化。--cpu_offload True的作用与显存不足时把部分权重卸载到内存有关配合低比特量化如 Q4_K_M可在消费级显卡上完成部署这是文档中给出的推荐组合具体卸载行为由 diffusers 加载链路实现。Z-Image 的专用加载分支Z-Image 系列还有一个值得注意的细节。在 stable_diffusion/core.py 中elif z-image in model_name_lower or zimage in model_name_lower: # TODO: remove this branch when auto pipeline supports Z-Image from diffusers import DiffusionPipeline self._model DiffusionPipeline.from_pretrained( self._model_path, **self._kwargs )主加载路径优先使用AutoPipelineModel.from_pretrained而当自动 pipeline 尚不能覆盖 Z-Image 时会回退到显式指定DiffusionPipeline的分支源码 TODO 注明待 auto pipeline 支持 Z-Image 后可移除该分支。另外当机器检测到多块 GPU 且未显式指定device_map时Xinference 会强制设置device_mapbalanced做权重分片core.py L422-430这对 Z-Image-Turbo 这类大尺寸文生图模型在多卡环境下的部署是自动生效的。内置规格详解默认配置、模型来源与运行环境model_spec.json 中 Z-Image-Turbo 的完整规格featured: true即官方精选模型包含以下几组对使用者有直接意义的信息默认模型加载配置default_model_config: { torch_dtype: bfloat16, low_cpu_mem_usage: false }torch_dtype 默认为 bfloat16在 BF16 硬件上可获得更高效的推理这也是 GGUF 分支中compute_dtype的取值来源low_cpu_mem_usage 默认 false不启用“边加载边卸载”的省内存模式加载过程更直接如果你需要覆盖这些默认值create_image_model会用 kwargs 更新默认配置L294-296因此启动参数优先级高于规格默认值。默认生成配置default_generate_config: { num_inference_steps: 9, guidance_scale: 0 }这两个值是 Turbo 蒸馏模型的典型特征9 步去噪、guidance_scale 为 0即不使用 CFG 引导。调用文生图接口时若未显式指定就会套用这套默认值——这也是“Turbo”命名的由来之一少步数即可出图。模型来源model_src: { huggingface: { model_id: Tongyi-MAI/Z-Image-Turbo, model_revision: 013496ad041be2e9ded1c291c00d8cc4054a6422 }, modelscope: { model_id: Tongyi-MAI/Z-Image-Turbo, model_revision: master } }Xinference 同时支持从 Hugging Face 与 ModelScope 下载权重其中 HF 侧锁定了具体的 revision 以保证可复现GGUF 权重则来自unsloth/Z-Image-Turbo-GGUF文件名模板为z-image-turbo-{quantization}.gguf。按引擎隔离的虚拟环境依赖规格中的virtualenv.packages声明了不同推理引擎对应的依赖集no_build_isolation: true体现了 Xinference 的模型虚拟环境机制引擎关键依赖diffusers默认#diffusers_dependencies#、transformers4.51.0、系统 torch/numpySGLangsglang[diffusion]vLLMvllm-omni0.24.*与同版本vllm0.24.*、transformers4.51.0这与 后端指南 的说明互相印证vLLM 与 SGLang 都可以作为 Z-Image-Turbo 这类文生图模型的推理引擎限 Linux NVIDIA GPU前提分别是安装 vLLM-Omni 附加组件与 vLLM 保持相同 major.minor 版本和安装带 diffusion 扩展的 SGLang。若不指定--model-enginecreate_image_model 会回落到 diffusers 引擎这也是xinference launch --model-name Z-Image-Turbo --model-type image不带引擎参数时的行为。常见问题排查GGUF 文件下载失败确认量化档位名拼写正确区分大小写如Q4_K_M文件按z-image-turbo-{quantization}.gguf模板从unsloth/Z-Image-Turbo-GGUF获取显存不足降低量化档位Q8_0 → Q4_K_M并保持文档给出的--cpu_offload True组合多卡机器可依赖自动device_mapbalanced分片意外传入 ControlNet该模型无可用 ControlNet--controlnet参数会在模型创建阶段被拒绝想指定其他后端参考 backends.rst 中 vLLM / SGLang 章节的环境要求通过--model-engine切换并按上表确认对应引擎依赖已安装。小结Z-Image-Turbo 在 Xinference 中是一条完整的内置文生图/图生图模型链路一条xinference launch命令即可拉起标准 BF16 版本加--gguf_quantization与--cpu_offload后走 GGUF 量化链路Transformer 单文件量化、文本编码器保留原精度。结合 model_spec.json 的默认配置9 步推理、guidance_scale 0与 stable_diffusion/core.py 的加载分支可以清晰判断每次启动实际执行的加载路径也为低显存部署、多卡部署和引擎切换提供了明确的排查依据。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考