mistral.rs Topology 逐层量化控制实战用 Rust API 与 YAML 配置为每一层指定 ISQ 类型【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本指南围绕 mistral.rs 的 Topology 机制展开讲解如何打破整个模型一套量化的限制为 Transformer 的每一层甚至每个正则匹配的权重单独指定 ISQ 量化类型与计算设备。读完本文你将掌握Topology的核心 API 结构、with_topology/with_topology_from_path两种接入方式、YAML 拓扑文件的完整语法以及它在 ISQ 加载管线中的底层执行原理可直接上手复现仓库中的topology示例并改造为自己的混合量化方案。为什么需要逐层量化控制mistral.rs 常规的 ISQIn-Situ Quantization就地量化通过ModelBuilder::with_auto_isq或with_isq为整个模型选择一种量化类型如Q4K、Q8_0。但真实模型的不同层对量化的敏感度并不一致靠近输入的低层往往对精度更敏感而深层或 FFN 层可以承受更激进的压缩。Topology 正是为此设计——它允许按**层区间layer range或权重名正则regex**声明差异化的isq与device配置从而实现浅层用高精度、深层用低比特这类混合量化策略也可以把不同层分配到不同设备上。在 API 层面topology 的优先级高于全局 ISQmistralrs/src/builder_macros.rs中with_topology与with_topology_from_path的文档明确写着If there is an overlap, the topology type is used over the ISQ type存在重叠时topology 指定的类型优先于 ISQ 类型。因此with_auto_isq仍然可以保留用于兜底未被 topology 覆盖的层。Topology 核心数据结构剖析Topology与LayerTopology定义在 mistralrs-core/src/topology/mod.rs并在 mistralrs/src/lib.rs 中被重新导出因此用户代码可直接use mistralrs::{Topology, LayerTopology}。两个核心类型#[derive(Clone, Debug)] pub struct LayerTopology { pub isq: OptionIsqType, // 该层使用的量化类型None 表示不覆盖 pub device: OptionDevice, // 该层放置的设备None 表示不覆盖 } #[derive(Clone, Debug)] pub struct Topology { pub layers: VecOptionLayerTopology, // 按层索引存储 pub patterns: Vec(Regex, LayerTopology), // 按权重名正则存储 }LayerTopology的两个字段都是Option只关心量化就填isq、device留None只关心设备放置就反过来。Topology内部用VecOptionLayerTopology保存按索引命中的层用(Regex, LayerTopology)列表保存名字模式匹配。从源码看device字段的存在使 Topology 同时具备逐层设备映射能力——is_dummy_device_map方法正是用来判断拓扑是否不包含任何设备指定。Topology提供的主要构造与查询方法方法作用Topology::empty()创建空拓扑无层、无模式Topology::with_capacity(cap)预分配cap个None槽位Topology::with_range(range, layer)为range区间内的每一层设置LayerTopology必要时自动扩展layers长度Topology::from_str(s)从 YAML 字符串解析支持区间、单层、正则三种选择器Topology::from_path(p)/from_reader(r)/from_option_path从文件 / 读取器 / 可选路径加载layer_for(layer)查询某层索引对应的LayerTopologymatch_for_name(name)/pattern_overrides()按权重名匹配正则拓扑后者返回逆序声明列表immediate_overrides()将拓扑编译为 ISQ 管线可直接消费的ImmediateIsqOverride列表完整示例为 Gemma 4 E4B 配置四段量化仓库中的topology示例位于 mistralrs/examples/quantization/topology/main.rs对应的文档页为 docs/src/content/docs/examples/rust/quantization/topology.md。运行命令cargo run --release --example topology -p mistralrs完整源码如下未做任何删减//! Per-layer quantization control using a Topology. //! //! Run with: cargo run --release --example topology -p mistralrs use anyhow::Result; use mistralrs::{ IsqBits, IsqType, LayerTopology, ModelBuilder, PagedAttentionMetaBuilder, TextMessageRole, TextMessages, Topology, }; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(google/gemma-4-E4B-it) .with_auto_isq(IsqBits::Eight) .with_topology( Topology::empty() .with_range( 0..8, LayerTopology { isq: Some(IsqType::Q3K), device: None, }, ) .with_range( 8..16, LayerTopology { isq: Some(IsqType::Q4K), device: None, }, ) .with_range( 16..24, LayerTopology { isq: Some(IsqType::Q6K), device: None, }, ) .with_range( 24..32, LayerTopology { isq: Some(IsqType::Q8_0), device: None, }, ), ) .with_logging() .with_paged_attn(PagedAttentionMetaBuilder::default().build()?) .build() .await?; let messages TextMessages::new() .add_message( TextMessageRole::System, You are an AI agent with a specialty in programming., ) .add_message( TextMessageRole::User, Hello! How are you? Please write generic binary search function in Rust., ); let response model.send_chat_request(messages).await?; println!({}, response.choices[0].message.content.as_ref().unwrap()); dbg!( response.usage.avg_prompt_tok_per_sec, response.usage.avg_compl_tok_per_sec ); Ok(()) }示例逐段拆解模型与兜底量化ModelBuilder::new(google/gemma-4-E4B-it)加载 Gemma 4 E4B 指令模型with_auto_isq(IsqBits::Eight)声明全局 8-bit 自动量化作为兜底。拓扑区间with_range的区间是左闭右开的 RustRangeusize。示例把 32 层划分为四段形成前紧后松的渐进策略层区间量化类型说明0..8IsqType::Q3K最低比特最激进的压缩8..16IsqType::Q4K次低比特16..24IsqType::Q6K中等精度24..32IsqType::Q8_0接近无损保住深层精度这里展示的Q3K、Q4K、Q6K、Q8_0都是 mistral.rs 支持的IsqType枚举值除此之外IsqType还包含Q4_0、Q4_1、Q5_0、Q5_1、Q5K等类型见 mistralrs/src/lib.rs 的文档说明。叠加的 builder 配置with_logging()开启日志、with_paged_attn启用分页注意力PagedAttention二者与拓扑正交可自由组合。推理与性能观测示例构造了一组 System/User 消息并调用send_chat_request随后通过dbg!打印avg_prompt_tok_per_sec与avg_compl_tok_per_sec便于直观对比不同拓扑配置下的吞吐差异。用 YAML 文件定义 Topology除了代码内构造Topology 还支持从 YAML 加载。解析入口是Topology::from_str内部使用serde_saphyr反序列化选择器有三种形态见 mistralrs-core/src/topology/mod.rs区间START-END含起点、不含终点inclusive-exclusive如0-8表示层 0..7单层直接写数字索引如5等价于5-6正则以/开头和结尾的字符串如/ffn\.weight$/用于按权重名匹配。设备字段必须匹配正则^(cpu|cuda\[(\d)\]|metal\[(\d)\])$即合法值形如cpu、cuda[0]、metal[1]不带序号时默认落到 CPUDevice::Cpu。仓库自带了一个同时演示isq与device两个维度的拓扑文件 topologies/isq_and_device.yml完整内容如下0-8: isq: Q3K device: cuda[0] 8-16: isq: Q4K device: cpu 16-24: isq: Q6K # Skip 24-28 28-32: isq: Q8_0 device: cuda[0]这份配置展示了两个重要特性逐层设备放置层 0-8 与 28-32 放在cuda[0]层 8-16 放在cpu——device字段与isq字段相互独立可单独使用也可组合使用跳层跳过区间注释# Skip 24-28表明层 24-28 不声明拓扑这些层会回落到全局 ISQ 设置。这也从侧面印证了with_auto_isq兜底的必要性——topology 只覆盖它声明的层。对应的 YAML 解析规则有两点值得注意均有 mistralrs-core/src/topology/mod.rs 中的单元测试背书重叠区间按终点排序end更大的区间覆盖end更小的区间测试highest_end_range_overrides_lower_end相同终点时后声明者胜先声明的0-4与后声明的2-4重叠层 2-3 采用后者的配置测试later_range_with_same_end_wins正则匹配match_for_name对权重名如model.layers.2.ffn.weight逐条匹配声明在后的正则有更高优先级测试regex_overrides_respect_declaration_order。代码中加载 YAML 的推荐方式是Topology::from_path配合 builder 的with_topology_from_path使用let model ModelBuilder::new(google/gemma-4-E4B-it) .with_topology_from_path(topologies/isq_and_device.yml)? // ...与with_topology相比with_topology_from_path会额外记录拓扑文件路径从而支持 unload/reload见 mistralrs/src/builder_macros.rs。仓库的topologies/目录还提供 isq.yml 与 isq_regex.yml 两个配套示例文件分别演示纯 ISQ 区间与正则模式拓扑的写法。底层原理Topology 如何汇入 ISQ 加载管线Topology 本身只描述哪一层用什么真正生效要靠它被编译成 ISQ 管线可执行的覆盖指令。关键方法在 mistralrs-core/src/topology/mod.rs 的immediate_overrides()先按声明逆序处理所有正则模式保证后声明者优先生成带predicate正则的ImmediateIsqOverride再遍历layers数组为每个有isq或device指定的层生成layer_range: Some(index..index1)的单层覆盖项两层结果拼接成VecImmediateIsqOverride返回。这些覆盖项会进入 mistralrs-core/src/pipeline/isq_flow/plan.rs 的resolve_and_install_isq_plan作为IsqLoadPlan.topology_overrides参与 ISQ 加载计划的决策。各模型管线的加载入口都会把 topology 编译进计划例如文本模型mistralrs-core/src/pipeline/normal.rs多模态模型mistralrs-core/src/pipeline/multimodal.rsEmbedding 模型mistralrs-core/src/pipeline/embedding.rs从 plan.rs 的分支逻辑及测试命名如uqff_precedence_suppresses_isq_topology_overrides可以推断当从 UQFF 检查点加载时加载管线对 topology 的 ISQ 覆盖存在专门的处理/抑制逻辑即 UQFF 路径下 topology 覆盖的优先级可能与普通 ISQ 加载不同。若你的工作流涉及 UQFF需要留意这一交互。实战建议与注意事项先测敏感层再定区间混合量化的核心收益来自精度敏感层用高比特、冗余层用低比特。可以先用示例中的dbg!吞吐输出与生成质量做基准再逐步调整各区间边界与IsqType保留全局兜底建议始终同时调用with_auto_isq或with_isq确保未覆盖层如跳过的 24-28仍有一个明确类型避免意外行为区间务必合法YAML 中end start会直接报错Topology range end must be start设备字符串不合法也会被DEVICE_PATTERN校验拦截正则命名约定正则匹配的是权重张量名如model.layers.2.ffn.weight与具体模型架构的命名规范强相关换模型时需同步调整模式异构设备需谨慎把层跨设备放置如 YAML 示例中的 cpu/cuda 混排会增加数据传输开销适合显存受限或混合算力场景普通场景建议保持单一设备。总结Topology 是 mistral.rs 将量化控制粒度从模型级下沉到层级的机制代码内可用Topology::empty().with_range(...)链式构造文件内可用isq/device/ 正则选择器写出可复用的 YAML 拓扑底层则由immediate_overrides()编译成ImmediateIsqOverride汇入isq_flow加载计划。以仓库自带的topology示例为起点配合 topologies/isq_and_device.yml 这类真实配置即可快速构建属于自己的逐层混合量化方案。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mistral.rs Topology 逐层量化控制实战：用 Rust API 与 YAML 配置为每一层指定 ISQ 类型
mistral.rs Topology 逐层量化控制实战用 Rust API 与 YAML 配置为每一层指定 ISQ 类型【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本指南围绕 mistral.rs 的 Topology 机制展开讲解如何打破整个模型一套量化的限制为 Transformer 的每一层甚至每个正则匹配的权重单独指定 ISQ 量化类型与计算设备。读完本文你将掌握Topology的核心 API 结构、with_topology/with_topology_from_path两种接入方式、YAML 拓扑文件的完整语法以及它在 ISQ 加载管线中的底层执行原理可直接上手复现仓库中的topology示例并改造为自己的混合量化方案。为什么需要逐层量化控制mistral.rs 常规的 ISQIn-Situ Quantization就地量化通过ModelBuilder::with_auto_isq或with_isq为整个模型选择一种量化类型如Q4K、Q8_0。但真实模型的不同层对量化的敏感度并不一致靠近输入的低层往往对精度更敏感而深层或 FFN 层可以承受更激进的压缩。Topology 正是为此设计——它允许按**层区间layer range或权重名正则regex**声明差异化的isq与device配置从而实现浅层用高精度、深层用低比特这类混合量化策略也可以把不同层分配到不同设备上。在 API 层面topology 的优先级高于全局 ISQmistralrs/src/builder_macros.rs中with_topology与with_topology_from_path的文档明确写着If there is an overlap, the topology type is used over the ISQ type存在重叠时topology 指定的类型优先于 ISQ 类型。因此with_auto_isq仍然可以保留用于兜底未被 topology 覆盖的层。Topology 核心数据结构剖析Topology与LayerTopology定义在 mistralrs-core/src/topology/mod.rs并在 mistralrs/src/lib.rs 中被重新导出因此用户代码可直接use mistralrs::{Topology, LayerTopology}。两个核心类型#[derive(Clone, Debug)] pub struct LayerTopology { pub isq: OptionIsqType, // 该层使用的量化类型None 表示不覆盖 pub device: OptionDevice, // 该层放置的设备None 表示不覆盖 } #[derive(Clone, Debug)] pub struct Topology { pub layers: VecOptionLayerTopology, // 按层索引存储 pub patterns: Vec(Regex, LayerTopology), // 按权重名正则存储 }LayerTopology的两个字段都是Option只关心量化就填isq、device留None只关心设备放置就反过来。Topology内部用VecOptionLayerTopology保存按索引命中的层用(Regex, LayerTopology)列表保存名字模式匹配。从源码看device字段的存在使 Topology 同时具备逐层设备映射能力——is_dummy_device_map方法正是用来判断拓扑是否不包含任何设备指定。Topology提供的主要构造与查询方法方法作用Topology::empty()创建空拓扑无层、无模式Topology::with_capacity(cap)预分配cap个None槽位Topology::with_range(range, layer)为range区间内的每一层设置LayerTopology必要时自动扩展layers长度Topology::from_str(s)从 YAML 字符串解析支持区间、单层、正则三种选择器Topology::from_path(p)/from_reader(r)/from_option_path从文件 / 读取器 / 可选路径加载layer_for(layer)查询某层索引对应的LayerTopologymatch_for_name(name)/pattern_overrides()按权重名匹配正则拓扑后者返回逆序声明列表immediate_overrides()将拓扑编译为 ISQ 管线可直接消费的ImmediateIsqOverride列表完整示例为 Gemma 4 E4B 配置四段量化仓库中的topology示例位于 mistralrs/examples/quantization/topology/main.rs对应的文档页为 docs/src/content/docs/examples/rust/quantization/topology.md。运行命令cargo run --release --example topology -p mistralrs完整源码如下未做任何删减//! Per-layer quantization control using a Topology. //! //! Run with: cargo run --release --example topology -p mistralrs use anyhow::Result; use mistralrs::{ IsqBits, IsqType, LayerTopology, ModelBuilder, PagedAttentionMetaBuilder, TextMessageRole, TextMessages, Topology, }; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(google/gemma-4-E4B-it) .with_auto_isq(IsqBits::Eight) .with_topology( Topology::empty() .with_range( 0..8, LayerTopology { isq: Some(IsqType::Q3K), device: None, }, ) .with_range( 8..16, LayerTopology { isq: Some(IsqType::Q4K), device: None, }, ) .with_range( 16..24, LayerTopology { isq: Some(IsqType::Q6K), device: None, }, ) .with_range( 24..32, LayerTopology { isq: Some(IsqType::Q8_0), device: None, }, ), ) .with_logging() .with_paged_attn(PagedAttentionMetaBuilder::default().build()?) .build() .await?; let messages TextMessages::new() .add_message( TextMessageRole::System, You are an AI agent with a specialty in programming., ) .add_message( TextMessageRole::User, Hello! How are you? Please write generic binary search function in Rust., ); let response model.send_chat_request(messages).await?; println!({}, response.choices[0].message.content.as_ref().unwrap()); dbg!( response.usage.avg_prompt_tok_per_sec, response.usage.avg_compl_tok_per_sec ); Ok(()) }示例逐段拆解模型与兜底量化ModelBuilder::new(google/gemma-4-E4B-it)加载 Gemma 4 E4B 指令模型with_auto_isq(IsqBits::Eight)声明全局 8-bit 自动量化作为兜底。拓扑区间with_range的区间是左闭右开的 RustRangeusize。示例把 32 层划分为四段形成前紧后松的渐进策略层区间量化类型说明0..8IsqType::Q3K最低比特最激进的压缩8..16IsqType::Q4K次低比特16..24IsqType::Q6K中等精度24..32IsqType::Q8_0接近无损保住深层精度这里展示的Q3K、Q4K、Q6K、Q8_0都是 mistral.rs 支持的IsqType枚举值除此之外IsqType还包含Q4_0、Q4_1、Q5_0、Q5_1、Q5K等类型见 mistralrs/src/lib.rs 的文档说明。叠加的 builder 配置with_logging()开启日志、with_paged_attn启用分页注意力PagedAttention二者与拓扑正交可自由组合。推理与性能观测示例构造了一组 System/User 消息并调用send_chat_request随后通过dbg!打印avg_prompt_tok_per_sec与avg_compl_tok_per_sec便于直观对比不同拓扑配置下的吞吐差异。用 YAML 文件定义 Topology除了代码内构造Topology 还支持从 YAML 加载。解析入口是Topology::from_str内部使用serde_saphyr反序列化选择器有三种形态见 mistralrs-core/src/topology/mod.rs区间START-END含起点、不含终点inclusive-exclusive如0-8表示层 0..7单层直接写数字索引如5等价于5-6正则以/开头和结尾的字符串如/ffn\.weight$/用于按权重名匹配。设备字段必须匹配正则^(cpu|cuda\[(\d)\]|metal\[(\d)\])$即合法值形如cpu、cuda[0]、metal[1]不带序号时默认落到 CPUDevice::Cpu。仓库自带了一个同时演示isq与device两个维度的拓扑文件 topologies/isq_and_device.yml完整内容如下0-8: isq: Q3K device: cuda[0] 8-16: isq: Q4K device: cpu 16-24: isq: Q6K # Skip 24-28 28-32: isq: Q8_0 device: cuda[0]这份配置展示了两个重要特性逐层设备放置层 0-8 与 28-32 放在cuda[0]层 8-16 放在cpu——device字段与isq字段相互独立可单独使用也可组合使用跳层跳过区间注释# Skip 24-28表明层 24-28 不声明拓扑这些层会回落到全局 ISQ 设置。这也从侧面印证了with_auto_isq兜底的必要性——topology 只覆盖它声明的层。对应的 YAML 解析规则有两点值得注意均有 mistralrs-core/src/topology/mod.rs 中的单元测试背书重叠区间按终点排序end更大的区间覆盖end更小的区间测试highest_end_range_overrides_lower_end相同终点时后声明者胜先声明的0-4与后声明的2-4重叠层 2-3 采用后者的配置测试later_range_with_same_end_wins正则匹配match_for_name对权重名如model.layers.2.ffn.weight逐条匹配声明在后的正则有更高优先级测试regex_overrides_respect_declaration_order。代码中加载 YAML 的推荐方式是Topology::from_path配合 builder 的with_topology_from_path使用let model ModelBuilder::new(google/gemma-4-E4B-it) .with_topology_from_path(topologies/isq_and_device.yml)? // ...与with_topology相比with_topology_from_path会额外记录拓扑文件路径从而支持 unload/reload见 mistralrs/src/builder_macros.rs。仓库的topologies/目录还提供 isq.yml 与 isq_regex.yml 两个配套示例文件分别演示纯 ISQ 区间与正则模式拓扑的写法。底层原理Topology 如何汇入 ISQ 加载管线Topology 本身只描述哪一层用什么真正生效要靠它被编译成 ISQ 管线可执行的覆盖指令。关键方法在 mistralrs-core/src/topology/mod.rs 的immediate_overrides()先按声明逆序处理所有正则模式保证后声明者优先生成带predicate正则的ImmediateIsqOverride再遍历layers数组为每个有isq或device指定的层生成layer_range: Some(index..index1)的单层覆盖项两层结果拼接成VecImmediateIsqOverride返回。这些覆盖项会进入 mistralrs-core/src/pipeline/isq_flow/plan.rs 的resolve_and_install_isq_plan作为IsqLoadPlan.topology_overrides参与 ISQ 加载计划的决策。各模型管线的加载入口都会把 topology 编译进计划例如文本模型mistralrs-core/src/pipeline/normal.rs多模态模型mistralrs-core/src/pipeline/multimodal.rsEmbedding 模型mistralrs-core/src/pipeline/embedding.rs从 plan.rs 的分支逻辑及测试命名如uqff_precedence_suppresses_isq_topology_overrides可以推断当从 UQFF 检查点加载时加载管线对 topology 的 ISQ 覆盖存在专门的处理/抑制逻辑即 UQFF 路径下 topology 覆盖的优先级可能与普通 ISQ 加载不同。若你的工作流涉及 UQFF需要留意这一交互。实战建议与注意事项先测敏感层再定区间混合量化的核心收益来自精度敏感层用高比特、冗余层用低比特。可以先用示例中的dbg!吞吐输出与生成质量做基准再逐步调整各区间边界与IsqType保留全局兜底建议始终同时调用with_auto_isq或with_isq确保未覆盖层如跳过的 24-28仍有一个明确类型避免意外行为区间务必合法YAML 中end start会直接报错Topology range end must be start设备字符串不合法也会被DEVICE_PATTERN校验拦截正则命名约定正则匹配的是权重张量名如model.layers.2.ffn.weight与具体模型架构的命名规范强相关换模型时需同步调整模式异构设备需谨慎把层跨设备放置如 YAML 示例中的 cpu/cuda 混排会增加数据传输开销适合显存受限或混合算力场景普通场景建议保持单一设备。总结Topology 是 mistral.rs 将量化控制粒度从模型级下沉到层级的机制代码内可用Topology::empty().with_range(...)链式构造文件内可用isq/device/ 正则选择器写出可复用的 YAML 拓扑底层则由immediate_overrides()编译成ImmediateIsqOverride汇入isq_flow加载计划。以仓库自带的topology示例为起点配合 topologies/isq_and_device.yml 这类真实配置即可快速构建属于自己的逐层混合量化方案。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考