Xinference 内置 gemma-4 模型完整部署指南16 种模型规格、四大推理引擎与源码级解析【免费下载链接】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 仓库中内置模型的 gemma-4 规格文档doc/source/models/builtin/llm/gemma-4.rst系统讲解 Gemma 4 系列模型在 Xinference 中的完整部署方案包括 16 种「格式 × 参数量 × 量化」组合规格、对应的xinference launch命令、各引擎vLLM / Transformers / llama.cpp / MLX的适用边界并进一步结合仓库源码剖析 Gemma-4 的架构匹配、投机解码默认值、工具调用解析等底层实现细节。读完本文你可以直接复现任意一种 gemma-4 的启动命令并理解 Xinference 如何在引擎与模型之间做匹配、校验与批量调度。一、模型概览gemma-4 的定位与能力Gemma 是 Google DeepMind 出品的开源模型家族。Xinference 中注册的 gemma-4 条目定义如下与 模型家族注册表 中gemma-4字段一致上下文长度Context Length262144256K tokens模型名称Model Namegemma-4支持语言en英语、zh中文模型能力Abilitiesgenerate/chat文本生成与对话reasoning推理模式混合思考tools函数调用Tool Callingaudio音频输入官方描述明确为「小尺寸模型支持音频」vision图像输入hybrid支持开启/关闭思考的混合推理描述Gemma 4 是多模态模型可处理文本与图像输入小模型还支持音频输出文本。从源码结构看gemma-4 的架构标识为Gemma4ForConditionalGeneration与Gemma4UnifiedForConditionalGeneration两种见 llm_family.json 中architectures字段其中 12B 版本走「Unified」统一多模态路径后文会专门展开。二、16 种模型规格全览与启动命令gemma-4 文档共列出16 个 Model Spec按「模型格式 × 参数量」组织覆盖 4 种格式、5 个参数量档位2B / 4B / 12B / 26B / 31B。完整清单如下2.1 pytorch 格式5 个规格引擎vLLM / TransformersSpec参数量Model ID量化12Bgoogle/gemma-4-E2B-itnone24Bgoogle/gemma-4-E4B-itnone312Bgoogle/gemma-4-12B-itnone431Bgoogle/gemma-4-31B-itnone626B-A4Bgoogle/gemma-4-26B-A4B-itnonepytorch 格式均无量化选项quantization为none适用于 GPU 服务器上以 FP16/BF16 精度直接加载。26B-A4B 从命名看是 MoE 结构总参数 26B、激活参数 4B这类规格通常能以更低的激活开销换取较大的总参数容量。启动命令将${engine}替换为vllm或Transformers${quantization}为nonexinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 2 --model-format pytorch --quantization none xinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 4 --model-format pytorch --quantization none xinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 12 --model-format pytorch --quantization none xinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 31 --model-format pytorch --quantization none xinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 26 --model-format pytorch --quantization none2.2 fp4 格式1 个规格引擎vLLM / TransformersSpec参数量Model ID量化531Bnvidia/Gemma-4-31B-IT-NVFP4ModelScope 侧为nv-community/Gemma-4-31B-IT-NVFP4FP4这是 NVIDIA 官方的 NVFP4 量化版本用 4-bit 浮点权重大幅压缩 31B 模型的显存占用适合显存不足以容纳 BF16 权重、但仍希望走 vLLM 高吞吐路径的部署场景。注意 fp4 格式仅在 31B 档位提供。xinference launch --model-engine ${engine} --model-name gemma-4 --size-in-billions 31 --model-format fp4 --quantization FP42.3 ggufv2 格式5 个规格引擎llama.cppSpec参数量Model ID量化选项数72Bunsloth/gemma-4-E2B-it-GGUF21 种含 BF1684Bunsloth/gemma-4-E4B-it-GGUF21 种含 BF16912Bunsloth/gemma-4-12b-it-GGUF21 种含 BF161031Bunsloth/gemma-4-31B-it-GGUF20 种无 BF1631B 的 BF16 体积过大1126B-A4Bunsloth/gemma-4-26B-A4B-it-GGUF20 种MoE 专用量化集含 MXFP4_MOE各规格量化列表以 2B 为例4B / 12B 相同BF16, IQ4_NL, IQ4_XS, Q3_K_M, Q3_K_S, Q4_0, Q4_1, Q4_K_M, Q4_K_S, Q5_K_M, Q5_K_S, Q6_K, Q8_0, UD-IQ2_M, UD-IQ3_XXS, UD-Q2_K_XL, UD-Q3_K_XL, UD-Q4_K_XL, UD-Q5_K_XL, UD-Q6_K_XL, UD-Q8_K_XL。 31B 规格与上述相同但去掉BF1626B-A4B 规格为MXFP4_MOE, Q8_0, UD-IQ2_M, UD-IQ3_S, UD-IQ3_XXS, UD-IQ4_NL, UD-IQ4_XS, UD-Q2_K_XL, UD-Q3_K_M, UD-Q3_K_S, UD-Q3_K_XL, UD-Q4_K_M, UD-Q4_K_S, UD-Q4_K_XL, UD-Q5_K_M, UD-Q5_K_S, UD-Q5_K_XL, UD-Q6_K, UD-Q6_K_XL, UD-Q8_K_XL。llama.cpp 路线面向 CPU / 混合算力 / 边缘设备部署通过量化档位灵活匹配内存预算典型选择如Q4_K_M精度与体积的平衡点、Q8_0近无损。xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 2 --model-format ggufv2 --quantization Q4_K_M # 其余档位同理替换 --size-in-billions 与 --quantization xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 4 --model-format ggufv2 --quantization ${quantization} xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 12 --model-format ggufv2 --quantization ${quantization} xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 31 --model-format ggufv2 --quantization ${quantization} xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 26 --model-format ggufv2 --quantization ${quantization}2.4 mlx 格式5 个规格引擎MLXSpec参数量Model ID{quantization}为占位符122Bmlx-community/gemma-4-e2b-it-{quantization}134Bmlx-community/gemma-4-e4b-it-{quantization}1412Bmlx-community/gemma-4-12B-it-{quantization}1531Bmlx-community/gemma-4-31b-it-{quantization}1626B-A4Bmlx-community/gemma-4-26b-a4b-it-{quantization}mlx 格式的 Model ID 本身带{quantization}占位符即同一仓库按量化分目录发布。全部 5 个规格支持相同量化集bf16, 8bit, 6bit, 5bit, 4bit, mxfp8, mxfp4, nvfp4。该路线面向 Apple SiliconM 系列芯片设备是 Mac 上运行 gemma-4 的指定引擎。xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 2 --model-format mlx --quantization 4bit # 其余档位同理 xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 4 --model-format mlx --quantization ${quantization} xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 12 --model-format mlx --quantization ${quantization} xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 31 --model-format mlx --quantization ${quantization} xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 26 --model-format mlx --quantization ${quantization}上述所有 Model ID 均可从 Hugging Face 与 ModelScope 两个模型源下载Xinference 的--download-hub参数控制来源。三、规格数据背后的注册表llm_family.json 中的 gemma-4 条目上面文档中的每一项规格其机器可读来源都是 llm_family.json 中model_name为gemma-4的条目。相比文档注册表还包含若干对实际运行行为有影响的关键字段context_length: 262144与文档一致的 256K 上下文is_built_in: true、featured: truegemma-4 是内置且被标记为 featured 的模型会出现在 Xinference 的内置模型列表中stop_token_ids: [1, 106, 50]与stop: [eos, turn|, |tool_response]定义了 Gemma-4 的终止词元与终止字符串推理引擎以此判断生成结束reasoning_start_tag: |channelthought\n、reasoning_end_tag: channel|这是 Gemma-4 思考链thought channel的起止标记reasoning能力与hybrid能力的实现就依赖这对标签从输出中切分思考内容与正式回答tool_parser: gemma指定使用gemma工具调用解析器见第五节每个规格的draft_model_id所有规格均注册了草稿模型draft model例如 2B 的草稿模型是google/gemma-4-E2B-it-assistantGGUF 格式还给出了草稿文件模板MTP/mtp-gemma-4-…-{draft_quantization}.gguf与草稿量化集BF16 / F16 / Q8_0mlx 为bf16这是投机解码Speculative Decoding的支撑见第六节。注册表中的virtualenv字段则定义了各引擎的依赖环境Xinference 可为每个模型引擎创建隔离虚拟环境Transformerstransformers5.10.0、accelerate0.28.0vLLMvllm0.22.0、transformers5.8.0并附带qwen_omni_utils、audioread音频输入相关等依赖llama.cppxllamacpp2026.6.9713MLXmlx-vlm0.6.1sglang固定sglang0.5.13.post1、transformers5.8.1等一整套依赖这也解释了文档中「Engines」一列的实际含义pytorch / fp4 规格由 vLLM 与 Transformers 承接ggufv2 由 llama.cpp 承接mlx 由 MLX 承接——引擎与格式之间的匹配逻辑由 llm_family.py 中的check_engine_by_spec_parameters等函数完成。四、Transformers 引擎的 Gemma-4 专属实现对于--model-engine Transformers路径Xinference 为 Gemma-4 提供了专门的模型类Gemma4ChatModel位于 transformers/gemma4.py。几个值得注意的实现细节1. 版本门槛check_libGEMMA4_MIN_TRANSFORMERS_VERSION 5.5.0 GEMMA4_UNIFIED_MIN_TRANSFORMERS_VERSION 5.10.0加载普通规格需要transformers5.5.0而 12B 的「unified」架构Gemma4UnifiedForConditionalGeneration要求transformers5.10.0否则在_ensure_model_spec_transformers_version中抛出ImportError。判断依据是 model ID 中是否含gemma-4-12b见_is_unified_model_spec与统一多模态架构恰好对应 12B 档位的事实一致。2. 双加载路径_load_model中根据是否为 unified 规格选择不同的自动类unified 走AutoModelForMultimodalLM其余走AutoModelForCausalLM同时AutoProcessor以padding_sideleft加载tokenizer 缺失 pad token 时回退使用 EOS token 作为 pad token。3. 批量多模态支持Gemma4ChatModel通过register_batching_multimodal_models(gemma-4)注册为可参与连续批处理的多模态模型。build_prefill_kwargs实现了对左 padding 批次的预处理逐条依据attention_mask计算真实长度、padding_len并回填prompt_tokens再由build_prefill_position_ids生成与 padding 对齐的position_ids。对应的单测 test_gemma4.py 中test_gemma4_prefill_uses_attention_mask_for_left_padding验证了[1,2,3,4]与[0,0,5,6]两条输入在 padding 后position_ids分别为[0,1,2,3]与[0,0,0,1]。4. 工具与思考开关透传到 Chat Template_get_processor_chat_template_kwargs会把generate_config中的tools与chat_template_kwargs如enable_thinking传入processor.apply_chat_template批量调度器还会按「模板参数兼容性键」get_batching_prefill_compatibility_key即tools与chat_template_kwargs的序列化结果把不兼容的请求拆入不同批次——测试test_gemma4_scheduler_separates_incompatible_template_kwargs验证了enable_thinking: True的请求不会被与False的请求同批处理。这一机制保证了混合推理开关不会在并发批次里串线。5. 默认生成参数build_generate_kwargs中max_tokens缺省为 512、temperature缺省为 1流式输出经TextIteratorStreamer超时 60s、跳过 prompt 与特殊 token驱动。五、工具调用Gemma 专属解析器gemma-4 的tools能力由注册名为gemma的解析器实现位于 tool_parsers/gemma_tool_parser.py。Gemma-4 的工具调用不使用常规 JSON而是自有 token 标记格式例如|tool_callcall:get_weather{location:||Shanghai||}tool_call|GemmaToolParser围绕三个标记工作起始|tool_call、结束tool_call|、字符串定界符||。解析时先把参数块按||切分为交替的结构段与字符串段奇偶下标区分再对裸键自动补引号、对字符串内容做 JSON 重编码——这样即使字符串本身含双引号、反斜杠或换行也能还原成合法 JSON。结合注册表中stop列表里的|tool_response可以看出完整链路请求侧把工具定义写入 chat templatetools参数响应侧由解析器把标记块翻译为 OpenAI 风格的tool_calls。六、投机解码gemma-4 的默认草稿深度注册表中每个规格都携带draft_model_id…-it-assistant草稿模型Xinference 针对 gemma-4 在 llm/core.py 中内置了按参数量区分的投机解码默认值GEMMA_4_NUM_SPECULATIVE_TOKENS_BY_SIZE { 2: 2, 4: 4, 12: 4, 26: 4, 31: 4, }即启动 2B 档位时默认投机深度为 24B / 12B / 26B / 31B 默认为 4用户未显式设置时由get_model_speculative_tokens_default查表显式设置的值则必须经parse_num_speculative_tokens校验为正整数Web UI 以字符串提交参数零值或负值会直接报ValueError而非被静默替换。各引擎vLLM / llama.cpp / sglang的投机配置解析测试中均包含 gemma-4 的用例如 vllm/tests/test_speculative_config.py、llama_cpp/tests/test_speculative_config.py。GGUF 与 mlx 规格的草稿模型量化集BF16/F16/Q8_0、bf16等也与草稿文件命名模板一一对应供引擎定位草稿权重。七、实战速查按硬件选型与启动结合上述规格与引擎信息常见的选型路径可以归纳为硬件场景推荐规格启动示例单/多 GPU 服务器追求吞吐pytorch 2B~31B 或 fp4 31BvLLM 引擎xinference launch --model-engine vllm --model-name gemma-4 --size-in-billions 12 --model-format pytorch --quantization none显存紧张需压 31Bfp4NVFP431BvLLM 引擎xinference launch --model-engine vllm --model-name gemma-4 --size-in-billions 31 --model-format fp4 --quantization FP4轻量验证 / 不想装 CUDA 栈pytorch 小规格Transformers 引擎xinference launch --model-engine Transformers --model-name gemma-4 --size-in-billions 2 --model-format pytorch --quantization noneCPU / 边缘设备ggufv2 Q4_K_M 等量化llama.cpp 引擎xinference launch --model-engine llama.cpp --model-name gemma-4 --size-in-billions 4 --model-format ggufv2 --quantization Q4_K_MApple Siliconmlx 4bit/8bit 等MLX 引擎xinference launch --model-engine MLX --model-name gemma-4 --size-in-billions 12 --model-format mlx --quantization 4bit几点适用前提--model-engine的取值必须与所选格式匹配pytorch/fp4 用 vllm 或 Transformersggufv2 用 llama.cppmlx 用 MLX不匹配会在match_llm/ 引擎校验阶段报错走 Transformers 引擎时环境中的 transformers 版本需满足 5.5.012B unified 为 5.10.0门槛启用 Xinference 虚拟环境enable_virtual_env时会自动按注册表安装transformers5.10.0等依赖31B 的 GGUF 不提供 BF16 档位26B-A4B 的 GGUF 量化集为 MoE 专用含MXFP4_MOE选型时以注册表量化列表为准音频输入仅在「小尺寸模型」上可用官方描述部署音频链路时建议优先选择 2B / 4B 档位验证。八、小结gemma-4 在 Xinference 中的完整形态是「一份规格文档 一份注册表 多个引擎适配」的组合规格文档 面向使用者列出 16 种可启动组合llm_family.json 以机器可读方式固化了架构、停止词元、推理标签、工具解析器、草稿模型与各引擎虚拟环境依赖而 gemma4.py、gemma_tool_parser.py 与 core.py 等源码则分别实现了 Transformers 路径的多模态批量调度、Gemma 风格工具调用解析与按规格区分的投机解码默认值。理解这三层的关系就能在任意硬件上正确、高效地把 Gemma 4 接入统一的 OpenAI 兼容推理 API。【免费下载链接】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），仅供参考