mistral.rs GGUF 兼容性完全指南支持架构、存储格式与功能边界【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsGGUF 是当前开源生态中最主流的模型量化分发格式本指南以 mistral.rs 的 GGUF 兼容性参考 为骨架系统梳理该推理引擎支持的文本与多模态模型家族、可接受的存储量化类型以及 LoRA、ISQ、离线加载等功能的兼容边界。读完本文你将能对照general.architecture元数据判断任意 GGUF 文件是否可加载、需要哪些配套资产投影器、tokenizer、原模型配置并理解 mistral.rs 在源码层是如何完成架构识别、格式校验与功能约束的。GGUF 兼容性参考的定位mistral.rs 将 GGUF 支持拆成两份文档一份是本文讲解的兼容性参考回答“哪些模型能跑、什么存储格式能读、哪些功能可用”另一份是 Run GGUF models 指南回答“怎么跑起来”——包括-f精确文件加载、--quant工件选择、投影器发现与资产覆盖等命令级工作流。两者配合使用遇到“Unknown or unsupported GGUF architecture”或“IQ GGUF 无法加载”等报错时排查依据就是本参考页中的三张核心表格。从源码结构看GGUF 支持横跨 mistralrs-core/src/gguf/ 目录下的 20 个模块normal_registry.rs负责文本架构注册表multimodal_vision_registry.rs与各*_bindings.rs负责多模态投影器绑定gguf_tokenizer.rs负责从tokenizer.ggml.*元数据重建 tokenizercontent.rs负责多分片文件与存储类型的解析校验。下文将沿着这些模块逐一印证参考页的每一条结论。文本模型家族general.architecture决定一切参考页明确GGUF architecture列就是文件general.architecture元数据中存储的值同家族内的微调版本与不同尺寸共用同一入口。这一机制在源码中得到严格印证content.rs 在读取时遍历所有分片、强制要求存在general.architecture键否则直接报错GGUF files must specify general.architecture。参考页支持的文本家族完整清单如下模型家族GGUF architectureLlama、Mistral、MixtralllamaMistral 3 文本权重mistral3GemmagemmaGemma 2gemma2Gemma 3 文本权重gemma3Phi-2phi2Phi-3 与 Phi-3.5phi3Phi-3.5 MoEphimoeQwen2 与 Qwen2.5qwen2Qwen3qwen3Qwen3 MoEqwen3moeQwen3-Next 与 Qwen3-Coder-Nextqwen3nextQwen3.5 与 Qwen3.6 denseqwen35Qwen3.5 与 Qwen3.6 MoEqwen35moeStarCoder2starcoder2DeepSeek-V2、DeepSeek-V3、DeepSeek-R1非蒸馏、GLM-4 MoE Litedeepseek2GLM-4 denseglm4GLM-4 MoEglm4moeSmolLM3smollm3Granite densegraniteGranite MoEgranitemoeGranite hybridgranitehybridGPT-OSSgpt-ossHunyuan densehunyuan-denseHunyuan MoEhunyuan-moeLFM2 与 LFM2.5 denselfm2LFM2 与 LFM2.5 MoElfm2moe这份清单与源码中的CanonicalGgufArchitecture枚举一一对应normal_registry.rs 定义了 26 种规范架构FromStr实现normal_registry.rs将字符串形式的general.architecture大小写不敏感地解析为枚举未命中即返回UnknownArchitecture错误。一架构多家族的歧义消解参考页特别提醒部分 GGUF 架构覆盖不止一个模型家族。例如llama同时承载 Llama、Mistral、Mixtral、Idefics3、SmolVLM 等deepseek2覆盖 DeepSeek-V2/V3/R1 与 GLM-4 MoE Lite。mistral.rs 的做法是“仓库文件 GGUF 元数据联合判定”normal_registry.rs 中的GgufDescriptor除架构外还收集全部元数据键与张量名通过has_metadata、has_tensor做模式匹配并记录ResolutionReason单候选、显式覆盖、专家清单、模型身份、张量清单等来决定最终 loadergeneral.name与general.basename也参与身份判定with_model_identity。对无法无歧义识别的独立文件参考页给出的补救手段是随原模型一起传入--tok-model-id用原模型的配置、tokenizer、processor 资产补足缺失信息。对应到 Python/Rust 侧则是GgufModelBuilder::with_tok_model_idmistralrs/src/gguf.rs。GLM 多模态 GGUF 的限制参考页明确指出为多模态输入配置的 GLM GGUF 不能作为纯文本模型加载。这是双向互斥约束——GLM 的多模态 GGUF 依赖其配套投影器与配置缺少这些组件时加载器不会降级为文本模式。多模态模型家族投影器projector是硬性依赖多模态 GGUF 必须搭配兼容的配套投影器部分家族加载时还需要原始配置或 processor 资产。仓库加载会在“仓库与 GGUF 元数据能无歧义识别”的前提下自动选取支撑文件直接本地简写-f /path/model.gguf也会自动选择存放在模型旁边的唯一投影器。支持的多模态家族清单如下模型家族GGUF architectureGemma 3gemma3Gemma 3ngemma3nGemma 4 dense 与 MoEgemma4Idefics3 与 SmolVLMllamaMistral 3 与 Pixtralmistral3Llama 4llama4LFM2-VL 与 LFM2.5-VLlfm2Muse Glimmermuse-glimmerQwen2-VL 与 Qwen2.5-VLqwen2vlQwen3-VLqwen3vlQwen3-VL MoEqwen3vlmoeQwen3.5 与 Qwen3.6 多模态 denseqwen35Qwen3.5 与 Qwen3.6 多模态 MoEqwen35moe源码层面对投影器的识别有专门逻辑multimodal_binding_utils.rs 定义了clip.projector_type与clip.vision.projector_type两个元数据键projector_type()负责从档案中读取投影器类型multimodal_vision_registry.rs 中的require_architecture会校验“投影器要求的架构”与“主 GGUF 的架构”必须一致跨家族配对比如给qwen2vl主模型塞一个 Gemma 投影器会被直接拒绝相关测试用例覆盖了rejects_cross_family_projector_pair场景。输入模态取决于具体模型参考页强调家族列表中列出的架构不代表每个 checkpoint 都接受图像、音频和视频。具体约束如下多模态 Qwen3.5/Qwen3.6 接受图像与视频输入不接受音频Gemma 4 在模型配置与投影器文件包含对应组件时可接受图像/视频和音频Muse Glimmer 的 GGUF 需要配套muse-glimmer投影器当前已发布的 GGUF 仓库因缺少足够的基础模型配置元数据还必须传入--tok-model-id meta-models/Muse-Glimmer-30B才能独立加载。图像输入受支持视频输入被拒绝原因是 llama.cpp 的转换在投影器中不可逆地把每对时间维 patch 权重做了求和。判断某个 checkpoint 具体支持哪些请求类型应查阅模型卡与多模态输入指南。始终需要投影器的架构参考页给出了一条精确规则gemma3n、gemma4、llama4、qwen2vl、qwen3vl、qwen3vlmoe这六个架构永远需要投影器而同时出现在两张表中的架构——gemma3、llama、mistral3、lfm2、qwen35、qwen35moe——在未提供投影器时按文本模型加载。这也解释了 run-gguf 指南中的 Troubleshooting 项“An architecture is supported only as a multimodal model”为什么会要求你补传投影器。在多模态场景下显式指定投影器的方法是--mmproj file.gguf多个投影器组件用分号分隔对应 Python/Rust SDK 则是Which.GGUF(..., mmproj_filename...)与GgufModelBuilder::with_mmproj_filesmistralrs/src/gguf.rs。CLI 参数层面对--mmproj有强校验它要求格式必须是 GGUF见 mistralrs-cli/src/args/model.rs 的mmproj_rejects_an_explicit_non_gguf_format约束且允许分号分隔的多个文件名。存储格式支持的类型与明确的禁区mistral.rs 接受以下 GGUF 存储类型单个文件可混用多种类型常见的_K_M与_K_S产物即是如此类别支持的存储类型浮点F32、F16、BF16传统块量化Q4_0、Q4_1、Q5_0、Q5_1、Q8_0、Q8_1K-quantsQ2_K、Q3_K、Q4_K、Q5_K、Q6_K、Q8_KGPT-OSSGPT-OSS 的 MXFP4 表示这张表的可信度可以从源码直接验证content.rs 维护了一份与 Candle 保持同步的KNOWN_DTYPES常量数组逐项对应上述浮点、传统块量化与 K-quants 类型当分片解析报错信息包含 “unknown dtype for tensor” 时加载器会打印该数组拼出的支持清单并终止加载content.rs。同时多分片文件还受split.count元数据的一致性校验分片数必须与split.count一致且不同分片的split.count值不允许冲突content.rs。明确不支持的类型参考页划出了三条硬边界IQ 存储类型IQ1、IQ2、IQ3、IQ4 各变体暂不支持需改用上表中的 Q/K 工件上表未列出的其他存储类型同样不支持大端序big-endianGGUF 文件不支持。这些限制在故障排查表中都有对应处理建议遇到 IQ GGUF 时报错“IQ GGUF formats are not supported yet”直接换用仓库中的 Q/K 量化版本即可。功能兼容性一张表看清边界参考页最后给出功能级兼容矩阵能力GGUF 支持情况本地精确文件加载支持使用-fHugging Face 精确文件加载支持使用-m与-f自动工件选择支持使用-m与--quantTokenizer 与聊天模板发现来自内嵌 GGUF 元数据或提供的模型资产多模态投影器发现来自无歧义的 GGUF 仓库或直接本地-f简写时模型旁的投影器Serving、工具调用与 Agent与其他加载方式走相同运行时路径checkpoint 与聊天模板支持仍适用动态 LoRA仅限兼容旋转位置编码布局的语言模型适配器相邻 RoPE 布局被拒绝多模态 LoRA仅限语言模型适配器投影器、视觉与音频适配器不支持传统静态 LoRA仅限phi3架构的文本 GGUF不支持多模态 GGUFX-LoRA仅限phi3架构的文本 GGUF不支持多模态 GGUFISQ 重量化支持针对-f选定的兼容权重离线加载支持前提是所有必需文件均为本地或已缓存值得展开的是动态 LoRA 的相邻 RoPE 拒绝规则。参考页列出当前被拒绝的原生 GGUF 架构llama、mistral3、deepseek2、glm4、smollm3、granite、granitemoe、granitehybrid、llama4、muse-glimmer。这些架构将 Q/K 特征存储在相邻旋转顺序adjacent rotary order中与规范 LoRA 适配器权重的特征顺序不匹配若强行加载会导致特征错序。该限制同样波及经由这些架构路由的多模态模型Idefics3、Mistral 3/Pixtral、Llama 4、Muse Glimmer但基础模型加载不受影响。从源码看RopePairing枚举Adjacent与HalfSplit正是这张表的实现依据normal_registry.rs 为每个GgufSchema记录旋转配对方式只有HalfSplit布局才与规范 LoRA 权重兼容。参考页的措辞“会被拒绝”在实现层表现为加载前的显式校验而非运行时的静默错误。另外两点边界需要留意其一GGUF 支持覆盖文本生成与上表所列多模态家族不是embedding、语音、扩散或图像生成管线的加载格式其二GGUF 只改变权重与配套资产的加载方式一旦加载完成推理表面Chat Completions、Responses、结构化输出、工具调用、CLI Agent与非 GGUF 加载完全一致——工具调用能力仍取决于 checkpoint 行为与兼容的聊天模板。从参考到实战加载命令与资产覆盖速查将参考页与 run-gguf 指南 结合可得到如下实战对照目标命令运行精确本地文件mistralrs run -f /path/model-Q4_K_M.gguf运行精确 Hub 文件mistralrs run -m owner/repo -f model-Q4_K_M.gguf选择已发布位宽mistralrs run -m owner/repo --quant 4从本地目录选择mistralrs run -m /path/to/gguf-dir --quant 4多分片 GGUF-f model-00001-of-00002.gguf;model-00002-of-00002.gguf其中--quant 4是选择已发布工件优先Q4_K_M而--isq q4k是加载时重量化——两者是完全不同的操作。分片文件本地提供且不带-m时所有分片必须位于同一目录。资产覆盖选项与使用场景对应如下选项适用场景-f file.gguf需要精确模型文件而非自动量化选择--mmproj file.gguf需要精确投影器或投影器不在所选本地模型旁--tok-model-id model-id-or-path原配置/tokenizer/processor 资产无法自动识别-t tokenizer.json直接提供 tokenizer 文件-c template覆盖聊天模板Rust SDK 侧GgufModelBuilder::new(model_id, files)会应用若干默认值token 来源为 HF 缓存、最大并发序列 32、前缀缓存 16 条序列、自动设备映射mistralrs/src/gguf.rs。在线加载时若 GGUF 能识别原模型--tok-model-id可省略离线场景HF_HUB_OFFLINE1下独立文本 GGUF 可依赖内嵌 tokenizer 与模板而多模态模型还需本地投影器与原配置——可把投影器放在主 GGUF 旁并将支撑资产放入缓存或直接--tok-model-id指向本地资产目录。结语mistral.rs 的 GGUF 支持在架构识别、存储校验与功能约束三个层面都有清晰的源码实现26 种规范架构枚举与元数据/张量模式匹配负责“认模型”KNOWN_DTYPES白名单与分片校验负责“读文件”RopePairing与投影器家族校验负责“划边界”。对照本参考页的表格你可以快速判定一个 GGUF 文件的可加载性、所需的配套资产以及动态 LoRA、ISQ、离线加载等高级能力是否可用。遇到具体加载问题配合 run-gguf 指南 的故障排查表即可完成从诊断到修复的闭环。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考