mistral.rs UQFF 格式全解析从文件布局到分片加载的量化模型格式参考【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsUQFFUniversal Quantized File Format是 mistral.rs 原生的量化模型文件格式用于持久化预量化权重并实现免运行时转换的直接加载。本文以仓库 UQFF 格式参考文档 为主体结合mistralrs-quant与mistralrs-core中的读写实现完整讲解 UQFF 的目录结构、分片shard内部布局、混合量化类型的自描述机制、版本兼容规则与张量并行加载语义帮助你理解 UQFF 文件到底是什么、如何生成、如何校验以及加载器内部究竟做了什么。使用提示日常使用 UQFF 模型并不需要了解本文的底层布局——按 UQFF 使用指南 加载即可本文面向需要排查问题、二次开发或深度理解格式的读者。为什么需要 UQFF设计目标与定位UQFF 解决的核心问题是让量化一次、到处加载成为可能。普通的 safetensors 模型在每次启动时都要经历 ISQin-situ quantization原位量化的运行时转换既耗时又无法保证跨机器一致性而 UQFF 把量化结果直接落盘加载时跳过转换步骤。由此衍生的三个设计约束贯穿了 UQFF 的全部细节自描述self-describing每个量化层条目都携带格式标签与元数据加载器无需外部清单即可确定每个张量的反序列化方式——这也是单个文件内可以混合多种量化类型的前提推理专用inference-onlyUQFF 只保存前向推理所需的权重不包含优化器状态或训练元数据目录即分发单位UQFF 的导出结果是一个自包含目录单独的 shard 文件无法独立加载。从实现上看UQFF 的规范实现分处两端读路径reader 与张量编码位于 mistralrs-quant/src/uqffmod.rs、reader.rs、tensor.rs等写路径位于 mistralrs-core/src/pipeline/isq.rswrite_uqff_artifacts与write_uqff_type等函数。导出目录结构一份完整的 UQFF 资产包含什么一个 UQFF 导出结果是一个目录其中包含三类内容量化权重分片一个或多个stem-shard.uqff文件存放量化层权重例如q4k-0.uqff、q4k-1.uqff残差 safetensorsresidual.safetensors存放未量化张量典型代表是各类归一化层norm与稠密词嵌入dense embeddings模型资产副本从源仓库复制、使目录自包含的 JSON/模板文件包括config.json、tokenizer.json、tokenizer_config.json、generation_config.json以及存在时一并复制的modules.json、chat_template.jinja、processor_config.json、preprocessor_config.json。加载器from_uqff被指向一个或多个 shard 文件residual.safetensors与上述 JSON 资产通过**同级路径查找sibling-path lookup**自动拾取——也就是说加载器在 shard 文件所在目录内按约定文件名寻找配套文件这正是目录是分发单位的直接体现单独拷走一个 shard 而没有配套的 residual 与config.json是无法加载的。Shard 内部布局自描述层的字节级约定每个.uqffshard 都是标准 safetensors 文件其条目entry按命名约定组织。每一个量化层都通过一组相邻条目实现自描述条目名类型含义key.weight原始数据层数据本体GGML 家族的原始块数据raw blocks、AFQ/MXFP4/FP8 的打包张量packed tensors或未量化回退层中的原生 safetensors 张量key.weight.formatu8 标量量化家族标签加载器据此分发到对应的反序列化器deserializerkey.weight.dtype/key.weight.shapeu32GGML 类型的附加元数据块类型码 / 逻辑形状key.weight.scales/.bits/.group_size依类型而定AFQ 家族的附加元数据缩放、位宽、分组大小key.bias张量该层存在偏置时出现其中key即层的权重路径例如model.layers.0.self_attn.q_proj。源码 reader.rs 中的load_format读取key.weight.format的 u8 标量并转换为QuantizedSerdeType枚举Gguf、Unquant、Hqq、Fp8、Afq、F8Q8、Mxfp4等随后load_linear依据该枚举把反序列化分发到GgufMatMul、UnquantLinear、AfqLayer、FP8Linear、HQQLayer、MXFP4Layer等对应的deserialize_uqff实现。此外safetensors 的元数据中还包含信息性生产方字段uqff.producer、uqff.producer.mistralrs.version、uqff.producer.mistralrs.git_revision。这些字段仅用于溯源provenance加载器不校验其内容。MoE 专家层的三个规范键MoEMixture of Experts模型的专家层使用每个 block 三个规范键....experts.gate_proj....experts.up_proj....experts.down_proj三者各持一份堆叠权重形状为[num_experts, out, in]。源码 mod.rs 中的QuantizedExpertKeys::new正是按{experts_prefix}.gate_proj/.up_proj/.down_proj构造这三个键名。值得注意的是堆叠专家权重并非所有量化后端都支持reader 在加载时若发现三阶rank-3堆叠权重搭配 HQQ、FP8 或 F8Q8 格式会直接报错拒绝——这三种格式不支持堆叠专家 gather这一点有专门的单元测试uqff_rejects_stacked_backend_without_gather_on_load覆盖。版本标量条目每个 shard 集shard set的头部还会写入三个 u32 标量条目uqff.version.major、uqff.version.minor、uqff.version.patch。这三个条目由 mod.rs 中的uqff_version_tensors()生成当前仓库的版本常量为UQFF_VERSION_MAJOR 1、UQFF_VERSION_MINOR 2、UQFF_VERSION_PATCH 0见 mod.rs。混合量化一个文件里为什么可以同时存在多种类型因为每个层都自描述单个 UQFF 文件天然允许混合多种量化类型。三种典型来源如下Topology 固定的层由 topology 配置 显式指定类型的层会保持其固定类型例如在整体 Q4K 文件中把lm_head钉在q8_0敏感张量自动提精度模型声明的语言 token 嵌入与输出头output head使用 量化类型参考 中记录的更高精度默认值。例如afq4shard 集中这些张量以 AFQ6 存储q4kshard 集中则以 Q6K 存储。关键在于每个加载器都声明精确的路径因此仅仅名称相似如以embed_tokens、word_embeddings或lm_head结尾的视觉、音频等辅助张量不会被隐式提精度形状不支持的层按层回退形状无法满足目标类型的层会单独回退。例如输入维度不能被 AFQ 分组大小整除的 AFQ 层会以未量化形式存储。混合类型的打包因子pack factor计算在 reader 中有一套保守逻辑pack_factor会对所有层布局聚合取最小值而pack_factor_for则返回单个键的精确值。相关单元测试如mixed_uqff_uses_conservative_default_and_exact_per_key_factors验证了嵌入层以 AFQ6/AFQ8 存储时全局因子取嵌入层因子、单键因子精确到层的行为。分片规则10 GiB 软上限与按类型分片写路径writer把张量流切分为stem-0.uqff、stem-1.uqff、……每个 shard 的软上限为 10 GiB。若一次运行指定了多个 ISQ 类型则每种类型生成一套独立的 shard 集如q4k-0.uqff、afq4-0.uqff但共享同一个residual.safetensors与同一批模型资产。配套的 UQFF 使用指南 进一步说明约定命名的 shard 共享前缀且以-0、-1结尾如q4k-0.uqff与q4k-1.uqff只需选择其中一个加载器即可发现连续的 shard 集合。当uqff_report.json存在并声明了输出时其 shard 列表具有权威性允许使用自定义文件名。版本兼容机制major 严格、minor 向前兼容每个 shard 集携带的三个 u32 版本标量是加载时兼容性判定的依据。UqffReader::open见 reader.rs的执行逻辑如下major 不同 → 拒绝报错并提示用mistralrs quantize重新生成minor 新于当前构建支持 → 拒绝报错提示文件由更新版本的 mistral.rs 写出建议升级同 major 下 minor 更旧 → 接受向后兼容完全没有版本条目 → 拒绝判定为 pre-1.0 的旧文件。同时open还会做跨 shard 的键一致性校验validate_shard_tensor_keys版本标量在所有 shard 中必须一致任何重复张量键都会被拒绝并指出冲突文件。这些规则均有对应单元测试uqff_reader_rejects_conflicting_versions_across_shards、uqff_reader_rejects_malformed_version_copies、uqff_reader_rejects_duplicate_tensor_keys_across_shards。版本演进的两个里程碑UQFF 1.1引入内联的未量化线性条目weight.format Unquant。此前形状不支持量化的层权重需要挪进residual.safetensors1.1 之后这类层可以直接以未量化条目内联在 shard 中使混合文件保持完整。UQFF 1.2量化后的 token 嵌入改为常规层条目存储并从residual.safetensors中省略其原始稠密权重。读者仍然接受 token 嵌入留在 residual 文件中的 UQFF 1.1 文件向后兼容。兼容性红线UQFF 1.x 与 pre-1.0 版本产出的文件不兼容。旧文件加载时会直接报错请用mistralrs quantize重新生成。reader 中甚至专门检测所有键都形如数字的旧式文件并给出明确提示Pre-1.0 UQFF artifacts are no longer supported。张量并行下的加载语义切片还是复制UQFF shard 中存储的是完整张量在张量并行tensor parallelism场景下每个 rank 在加载时切出自己的那部分而非在文件中预分片。这一点从源码可以确认shard_rangemod.rs把Shard简单均分或显式偏移区间解析为(dim, start, len)三元组load_tensor_shardedreader.rs先在 CPU 上narrow出目标切片并contiguous()再搬运到目标设备确保设备只看到自己那份数据bias 的切分遵循bias_shard语义输入维被切分时偏置跳过归约后由调用方补加非输入维被切分时则嵌入匹配的偏置切片BiasShard::Narrow。切分打包packed输入维需要块对齐block alignment。典型模型维度满足此要求当对齐不成立时出现在部分专家层该 rank 会复制完整张量而非切片。块对齐量由shard_alignmentreader.rs按类型返回GGML 类型返回块大小、AFQ 返回 group size、MXFP4/F8Q8 返回 32、FP8 与未量化返回 1而HQQ 明确不支持分片加载。底层块数据的切片由slice_blocked_datamod.rs实现支持沿末维打包维要求 start/len 均为块的整数倍、外维与中间维切片并有slice_blocked_last_dim、slice_blocked_outer_dim、slice_blocked_3d_middle_dim等测试覆盖。从生成到校验UQFF 的完整工作流虽然布局参考文档聚焦于格式本身但配合 UQFF 使用指南 可以拼出完整工作流。生成 UQFF# 从 safetensors 模型源量化导出 mistralrs quantize \ -m google/gemma-4-E4B-it \ --isq q4k \ -o gemma-q4k.uqff # 从本地 GGUF 文件量化导出-f 推断 GGUF-m 可省略 mistralrs quantize \ -f /path/model-BF16.gguf \ --isq q4k \ -o model-q4k.uqff # 从 GGUF 仓库导出--quant 选输入产物--isq 选输出 UQFF 格式 mistralrs quantize \ -m gguf-repo \ --quant 8 \ --isq q4k \ -o output/要点--quant与-f互斥--isq可重复或逗号分隔以一次生成多个变体此时-o需传目录数字简写如--isq 4会同时写出afq4.uqff与q4k.uqfftopology 钉住的层在每一个输出变体中都会保留。从 GGUF 生成的 UQFF 会保留源文件的 Q/K rotary 布局若该布局为相邻adjacent形式转换后动态 LoRA 与 X-LoRA 仍不受支持。加载 UQFF# CLI-m 提供 tokenizer/基础模型解析--from-uqff 接受文件名或简写/类型名 mistralrs run -m repo --from-uqff q4k-0.uqff# Pythonfrom_uqff 接收 shard 文件名或列表 from mistralrs import Runner, Which runner Runner( whichWhich.Plain( model_idrepo, from_uqffq4k-0.uqff, ), )// RustUqffTextModelBuilder 接收基础仓库与首个 shard use mistralrs::UqffTextModelBuilder; let model UqffTextModelBuilder::new(repo, vec![q4k-0.uqff.into()]) .build() .await?;UQFF 模型在张量并行下同样可用每个 rank 只加载量化权重中属于自己的切片。元数据命令report / verify / inspectquantize还会在 UQFF 文件旁写出uqff_report.json记录生成的变体、shard 名、各层存储格式、生产方版本与回退层。加载器在其存在时会用它解析量化名称与 shard 集合含自定义文件名无 report 的约定命名 UQFF 仓库仍可正常加载。# 为现有产物扫描生成 report mistralrs uqff report -m gemma4_26b_a4b/ \ --write \ --base-model google/gemma-4-26B-A4B-it \ --repo-id mistralrs-community/gemma-4-26B-A4B-it # 对远程 HF 仓库生成 report--quant 选择分组 mistralrs uqff report -m mistralrs-community/gemma-4-26B-A4B-it --quant afq3 --json # 发布前校验结构 mistralrs uqff verify -m gemma4_26b_a4b/ # 交互式浏览张量 mistralrs uqff inspect -m mistralrs-community/gemma-4-26B-A4B-it --quant afq3uqff report、uqff verify、uqff inspect均为仅元数据操作对本地路径或已缓存的 Hugging Face 产物只做 seek-read 需要的字节区间对远程 HF 仓库则使用 HTTP 字节区间请求byte-range读取 safetensors 头部与小体积 UQFF 元数据张量不会下载完整模型权重。注意事项与边界推理专用UQFF 不包含优化器状态或训练元数据不可用于恢复训练目录即分发单位residual.safetensors与config.json是加载的必要配套单独的 shard 无法加载HQQ 的限制HQQ UQFF 产物不支持分片加载shard_alignment直接报错堆叠专家限制HQQ、FP8、F8Q8 格式不支持三阶堆叠专家权重的 gather加载时会被拒绝旧文件不兼容pre-1.0 文件无版本标签或旧式键名必须用mistralrs quantize重新生成存储扩张检查reader 会校验各层驻留字节数不超过其稠密估计否则提示使用等宽或更宽的模型 dtype 或显式设备映射对应测试uqff_rejects_storage_expansion_that_a_pack_factor_cannot_represent。延伸阅读UQFF 使用指南生成与加载的完整命令手册量化类型参考AFQ、Q*K、FP8、NVFP4、MXFP4、HQQ 各家族与敏感张量精度策略量化指南格式选型与 imatrix 背景Topology 指南逐层钉住量化类型参考实现mistralrs-quant/src/uqffreader 与张量编码、mistralrs-core/src/pipeline/isq.rswriter完整示例Rust 示例 uqff 与 multimodal uqff。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mistral.rs UQFF 格式全解析：从文件布局到分片加载的量化模型格式参考
mistral.rs UQFF 格式全解析从文件布局到分片加载的量化模型格式参考【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsUQFFUniversal Quantized File Format是 mistral.rs 原生的量化模型文件格式用于持久化预量化权重并实现免运行时转换的直接加载。本文以仓库 UQFF 格式参考文档 为主体结合mistralrs-quant与mistralrs-core中的读写实现完整讲解 UQFF 的目录结构、分片shard内部布局、混合量化类型的自描述机制、版本兼容规则与张量并行加载语义帮助你理解 UQFF 文件到底是什么、如何生成、如何校验以及加载器内部究竟做了什么。使用提示日常使用 UQFF 模型并不需要了解本文的底层布局——按 UQFF 使用指南 加载即可本文面向需要排查问题、二次开发或深度理解格式的读者。为什么需要 UQFF设计目标与定位UQFF 解决的核心问题是让量化一次、到处加载成为可能。普通的 safetensors 模型在每次启动时都要经历 ISQin-situ quantization原位量化的运行时转换既耗时又无法保证跨机器一致性而 UQFF 把量化结果直接落盘加载时跳过转换步骤。由此衍生的三个设计约束贯穿了 UQFF 的全部细节自描述self-describing每个量化层条目都携带格式标签与元数据加载器无需外部清单即可确定每个张量的反序列化方式——这也是单个文件内可以混合多种量化类型的前提推理专用inference-onlyUQFF 只保存前向推理所需的权重不包含优化器状态或训练元数据目录即分发单位UQFF 的导出结果是一个自包含目录单独的 shard 文件无法独立加载。从实现上看UQFF 的规范实现分处两端读路径reader 与张量编码位于 mistralrs-quant/src/uqffmod.rs、reader.rs、tensor.rs等写路径位于 mistralrs-core/src/pipeline/isq.rswrite_uqff_artifacts与write_uqff_type等函数。导出目录结构一份完整的 UQFF 资产包含什么一个 UQFF 导出结果是一个目录其中包含三类内容量化权重分片一个或多个stem-shard.uqff文件存放量化层权重例如q4k-0.uqff、q4k-1.uqff残差 safetensorsresidual.safetensors存放未量化张量典型代表是各类归一化层norm与稠密词嵌入dense embeddings模型资产副本从源仓库复制、使目录自包含的 JSON/模板文件包括config.json、tokenizer.json、tokenizer_config.json、generation_config.json以及存在时一并复制的modules.json、chat_template.jinja、processor_config.json、preprocessor_config.json。加载器from_uqff被指向一个或多个 shard 文件residual.safetensors与上述 JSON 资产通过**同级路径查找sibling-path lookup**自动拾取——也就是说加载器在 shard 文件所在目录内按约定文件名寻找配套文件这正是目录是分发单位的直接体现单独拷走一个 shard 而没有配套的 residual 与config.json是无法加载的。Shard 内部布局自描述层的字节级约定每个.uqffshard 都是标准 safetensors 文件其条目entry按命名约定组织。每一个量化层都通过一组相邻条目实现自描述条目名类型含义key.weight原始数据层数据本体GGML 家族的原始块数据raw blocks、AFQ/MXFP4/FP8 的打包张量packed tensors或未量化回退层中的原生 safetensors 张量key.weight.formatu8 标量量化家族标签加载器据此分发到对应的反序列化器deserializerkey.weight.dtype/key.weight.shapeu32GGML 类型的附加元数据块类型码 / 逻辑形状key.weight.scales/.bits/.group_size依类型而定AFQ 家族的附加元数据缩放、位宽、分组大小key.bias张量该层存在偏置时出现其中key即层的权重路径例如model.layers.0.self_attn.q_proj。源码 reader.rs 中的load_format读取key.weight.format的 u8 标量并转换为QuantizedSerdeType枚举Gguf、Unquant、Hqq、Fp8、Afq、F8Q8、Mxfp4等随后load_linear依据该枚举把反序列化分发到GgufMatMul、UnquantLinear、AfqLayer、FP8Linear、HQQLayer、MXFP4Layer等对应的deserialize_uqff实现。此外safetensors 的元数据中还包含信息性生产方字段uqff.producer、uqff.producer.mistralrs.version、uqff.producer.mistralrs.git_revision。这些字段仅用于溯源provenance加载器不校验其内容。MoE 专家层的三个规范键MoEMixture of Experts模型的专家层使用每个 block 三个规范键....experts.gate_proj....experts.up_proj....experts.down_proj三者各持一份堆叠权重形状为[num_experts, out, in]。源码 mod.rs 中的QuantizedExpertKeys::new正是按{experts_prefix}.gate_proj/.up_proj/.down_proj构造这三个键名。值得注意的是堆叠专家权重并非所有量化后端都支持reader 在加载时若发现三阶rank-3堆叠权重搭配 HQQ、FP8 或 F8Q8 格式会直接报错拒绝——这三种格式不支持堆叠专家 gather这一点有专门的单元测试uqff_rejects_stacked_backend_without_gather_on_load覆盖。版本标量条目每个 shard 集shard set的头部还会写入三个 u32 标量条目uqff.version.major、uqff.version.minor、uqff.version.patch。这三个条目由 mod.rs 中的uqff_version_tensors()生成当前仓库的版本常量为UQFF_VERSION_MAJOR 1、UQFF_VERSION_MINOR 2、UQFF_VERSION_PATCH 0见 mod.rs。混合量化一个文件里为什么可以同时存在多种类型因为每个层都自描述单个 UQFF 文件天然允许混合多种量化类型。三种典型来源如下Topology 固定的层由 topology 配置 显式指定类型的层会保持其固定类型例如在整体 Q4K 文件中把lm_head钉在q8_0敏感张量自动提精度模型声明的语言 token 嵌入与输出头output head使用 量化类型参考 中记录的更高精度默认值。例如afq4shard 集中这些张量以 AFQ6 存储q4kshard 集中则以 Q6K 存储。关键在于每个加载器都声明精确的路径因此仅仅名称相似如以embed_tokens、word_embeddings或lm_head结尾的视觉、音频等辅助张量不会被隐式提精度形状不支持的层按层回退形状无法满足目标类型的层会单独回退。例如输入维度不能被 AFQ 分组大小整除的 AFQ 层会以未量化形式存储。混合类型的打包因子pack factor计算在 reader 中有一套保守逻辑pack_factor会对所有层布局聚合取最小值而pack_factor_for则返回单个键的精确值。相关单元测试如mixed_uqff_uses_conservative_default_and_exact_per_key_factors验证了嵌入层以 AFQ6/AFQ8 存储时全局因子取嵌入层因子、单键因子精确到层的行为。分片规则10 GiB 软上限与按类型分片写路径writer把张量流切分为stem-0.uqff、stem-1.uqff、……每个 shard 的软上限为 10 GiB。若一次运行指定了多个 ISQ 类型则每种类型生成一套独立的 shard 集如q4k-0.uqff、afq4-0.uqff但共享同一个residual.safetensors与同一批模型资产。配套的 UQFF 使用指南 进一步说明约定命名的 shard 共享前缀且以-0、-1结尾如q4k-0.uqff与q4k-1.uqff只需选择其中一个加载器即可发现连续的 shard 集合。当uqff_report.json存在并声明了输出时其 shard 列表具有权威性允许使用自定义文件名。版本兼容机制major 严格、minor 向前兼容每个 shard 集携带的三个 u32 版本标量是加载时兼容性判定的依据。UqffReader::open见 reader.rs的执行逻辑如下major 不同 → 拒绝报错并提示用mistralrs quantize重新生成minor 新于当前构建支持 → 拒绝报错提示文件由更新版本的 mistral.rs 写出建议升级同 major 下 minor 更旧 → 接受向后兼容完全没有版本条目 → 拒绝判定为 pre-1.0 的旧文件。同时open还会做跨 shard 的键一致性校验validate_shard_tensor_keys版本标量在所有 shard 中必须一致任何重复张量键都会被拒绝并指出冲突文件。这些规则均有对应单元测试uqff_reader_rejects_conflicting_versions_across_shards、uqff_reader_rejects_malformed_version_copies、uqff_reader_rejects_duplicate_tensor_keys_across_shards。版本演进的两个里程碑UQFF 1.1引入内联的未量化线性条目weight.format Unquant。此前形状不支持量化的层权重需要挪进residual.safetensors1.1 之后这类层可以直接以未量化条目内联在 shard 中使混合文件保持完整。UQFF 1.2量化后的 token 嵌入改为常规层条目存储并从residual.safetensors中省略其原始稠密权重。读者仍然接受 token 嵌入留在 residual 文件中的 UQFF 1.1 文件向后兼容。兼容性红线UQFF 1.x 与 pre-1.0 版本产出的文件不兼容。旧文件加载时会直接报错请用mistralrs quantize重新生成。reader 中甚至专门检测所有键都形如数字的旧式文件并给出明确提示Pre-1.0 UQFF artifacts are no longer supported。张量并行下的加载语义切片还是复制UQFF shard 中存储的是完整张量在张量并行tensor parallelism场景下每个 rank 在加载时切出自己的那部分而非在文件中预分片。这一点从源码可以确认shard_rangemod.rs把Shard简单均分或显式偏移区间解析为(dim, start, len)三元组load_tensor_shardedreader.rs先在 CPU 上narrow出目标切片并contiguous()再搬运到目标设备确保设备只看到自己那份数据bias 的切分遵循bias_shard语义输入维被切分时偏置跳过归约后由调用方补加非输入维被切分时则嵌入匹配的偏置切片BiasShard::Narrow。切分打包packed输入维需要块对齐block alignment。典型模型维度满足此要求当对齐不成立时出现在部分专家层该 rank 会复制完整张量而非切片。块对齐量由shard_alignmentreader.rs按类型返回GGML 类型返回块大小、AFQ 返回 group size、MXFP4/F8Q8 返回 32、FP8 与未量化返回 1而HQQ 明确不支持分片加载。底层块数据的切片由slice_blocked_datamod.rs实现支持沿末维打包维要求 start/len 均为块的整数倍、外维与中间维切片并有slice_blocked_last_dim、slice_blocked_outer_dim、slice_blocked_3d_middle_dim等测试覆盖。从生成到校验UQFF 的完整工作流虽然布局参考文档聚焦于格式本身但配合 UQFF 使用指南 可以拼出完整工作流。生成 UQFF# 从 safetensors 模型源量化导出 mistralrs quantize \ -m google/gemma-4-E4B-it \ --isq q4k \ -o gemma-q4k.uqff # 从本地 GGUF 文件量化导出-f 推断 GGUF-m 可省略 mistralrs quantize \ -f /path/model-BF16.gguf \ --isq q4k \ -o model-q4k.uqff # 从 GGUF 仓库导出--quant 选输入产物--isq 选输出 UQFF 格式 mistralrs quantize \ -m gguf-repo \ --quant 8 \ --isq q4k \ -o output/要点--quant与-f互斥--isq可重复或逗号分隔以一次生成多个变体此时-o需传目录数字简写如--isq 4会同时写出afq4.uqff与q4k.uqfftopology 钉住的层在每一个输出变体中都会保留。从 GGUF 生成的 UQFF 会保留源文件的 Q/K rotary 布局若该布局为相邻adjacent形式转换后动态 LoRA 与 X-LoRA 仍不受支持。加载 UQFF# CLI-m 提供 tokenizer/基础模型解析--from-uqff 接受文件名或简写/类型名 mistralrs run -m repo --from-uqff q4k-0.uqff# Pythonfrom_uqff 接收 shard 文件名或列表 from mistralrs import Runner, Which runner Runner( whichWhich.Plain( model_idrepo, from_uqffq4k-0.uqff, ), )// RustUqffTextModelBuilder 接收基础仓库与首个 shard use mistralrs::UqffTextModelBuilder; let model UqffTextModelBuilder::new(repo, vec![q4k-0.uqff.into()]) .build() .await?;UQFF 模型在张量并行下同样可用每个 rank 只加载量化权重中属于自己的切片。元数据命令report / verify / inspectquantize还会在 UQFF 文件旁写出uqff_report.json记录生成的变体、shard 名、各层存储格式、生产方版本与回退层。加载器在其存在时会用它解析量化名称与 shard 集合含自定义文件名无 report 的约定命名 UQFF 仓库仍可正常加载。# 为现有产物扫描生成 report mistralrs uqff report -m gemma4_26b_a4b/ \ --write \ --base-model google/gemma-4-26B-A4B-it \ --repo-id mistralrs-community/gemma-4-26B-A4B-it # 对远程 HF 仓库生成 report--quant 选择分组 mistralrs uqff report -m mistralrs-community/gemma-4-26B-A4B-it --quant afq3 --json # 发布前校验结构 mistralrs uqff verify -m gemma4_26b_a4b/ # 交互式浏览张量 mistralrs uqff inspect -m mistralrs-community/gemma-4-26B-A4B-it --quant afq3uqff report、uqff verify、uqff inspect均为仅元数据操作对本地路径或已缓存的 Hugging Face 产物只做 seek-read 需要的字节区间对远程 HF 仓库则使用 HTTP 字节区间请求byte-range读取 safetensors 头部与小体积 UQFF 元数据张量不会下载完整模型权重。注意事项与边界推理专用UQFF 不包含优化器状态或训练元数据不可用于恢复训练目录即分发单位residual.safetensors与config.json是加载的必要配套单独的 shard 无法加载HQQ 的限制HQQ UQFF 产物不支持分片加载shard_alignment直接报错堆叠专家限制HQQ、FP8、F8Q8 格式不支持三阶堆叠专家权重的 gather加载时会被拒绝旧文件不兼容pre-1.0 文件无版本标签或旧式键名必须用mistralrs quantize重新生成存储扩张检查reader 会校验各层驻留字节数不超过其稠密估计否则提示使用等宽或更宽的模型 dtype 或显式设备映射对应测试uqff_rejects_storage_expansion_that_a_pack_factor_cannot_represent。延伸阅读UQFF 使用指南生成与加载的完整命令手册量化类型参考AFQ、Q*K、FP8、NVFP4、MXFP4、HQQ 各家族与敏感张量精度策略量化指南格式选型与 imatrix 背景Topology 指南逐层钉住量化类型参考实现mistralrs-quant/src/uqffreader 与张量编码、mistralrs-core/src/pipeline/isq.rswriter完整示例Rust 示例 uqff 与 multimodal uqff。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考