mistral.rs 自动设备映射Auto Device Mapping参数完全指南TextAutoMapParams 与 MultimodalAutoMapParams【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本指南围绕 mistral.rs 的自动设备映射automatic device mapping机制展开详细讲解 Python API 中TextAutoMapParams与MultimodalAutoMapParams两个参数类的每个字段、默认值与取值含义并结合源码剖析这些参数如何参与显存估算与层分配决策。读完本文你将掌握在单卡、多卡、统一内存等环境下通过这组非硬性上限参数精准控制模型切分策略的完整方法。什么是自动设备映射为什么需要这些参数当要加载的模型超过单块 GPU 显存时mistral.rs 支持自动把模型的各层layers分配到多块设备上甚至溢出到 CPU 内存这一过程称为自动设备映射automatic device mapping。核心实现位于 auto_device_map.rs 中的get_device_layers函数见 L199-L515。自动映射在真正加载权重之前需要估算运行期的内存开销——包括 KV Cache、激活值activations、不可映射子模型等。这些开销的大小取决于模型将处理多长的序列、多大的批量、多少张图片而模型本身不会告诉你这些信息。因此 mistral.rs 引入了一组用户可调的预估参数文档原话These affect automatic device mapping but are not a hard limit.即这些参数只影响自动映射时的内存预算计算并不是运行时的硬性限制。真实请求的序列长度、批量大小即使超过这些值模型依然可以运行只是超出部分的 KV Cache 与激活内存并未被计入映射预算可能在运行时产生额外压力。TextAutoMapParams纯文本模型的映射参数对应 Python 类定义见 which.rs L214-L235类型存根见 mistralrs.pyi L340-L348。FieldTypeDefaultmax_seq_lenint4 * 1024即 4096max_batch_sizeint1max_seq_len预期的最长 prompt 序列长度token 数。它直接参与 KV Cache 的元素数估算在非 PagedAttention 场景下每个 KV 头按max_batch_size × num_kv_heads × max_seq_len × head_dim计算 key/value 张量见 auto_device_map.rs L328-L342。序列越长预留的 KV 显存越大可用于放置模型层的空间就越小。max_batch_size预期同时处理的 prompt 批量大小。它同样线性放大 KV Cache 预算上述公式中的第一个维度以及激活值开销。两个字段均由 Python 构造函数提供默认值底层默认常量定义在 auto_device_map.rs L135-L140pub const DEFAULT_MAX_SEQ_LEN: usize 4 * 1024; pub const DEFAULT_MAX_BATCH_SIZE: usize 1;实战示例文本模型仓库提供了完整可运行的示例 text_auto_device_map.pyfrom mistralrs import Runner, Which, ChatCompletionRequest, TextAutoMapParams runner Runner( whichWhich.Plain( model_idmeta-llama/Llama-3.3-70B-Instruct, auto_map_paramsTextAutoMapParams(max_seq_len4096, max_batch_size2), ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ {role: user, content: Tell me a story about the Rust type system.} ], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.1, ) ) print(res.choices[0].message.content) print(res.usage)示例中为 70B 规模的 Llama 3.3 模型配置了max_seq_len4096、max_batch_size2即在估算时假定每次最多并发处理 2 个 4096 token 的请求。如果实际服务的请求更长或批量更大映射预算可能偏紧运行时需要通过 KV Cache 的动态分配来兜底。MultimodalAutoMapParams多模态模型的映射参数对应 Python 类定义见 which.rs L237-L269类型存根见 mistralrs.pyi L350-L359。FieldTypeDefaultmax_seq_lenint4 * 1024即 4096max_batch_sizeint1max_num_imagesint1max_image_lengthint1024前两个字段与文本版含义一致多模态模型额外多出两个字段max_num_images每个请求中预期的最大图片数量。它影响视觉编码器激活值与后续文本侧序列长度的估算。max_image_length预期图片的最大边长按正方形估算边长底层转换为(max_image_length, max_image_length)的图像形状见 lib.rs L1088-L1092。图像尺寸越大视觉编码器产生的 patch/embedding 越多激活内存开销越大。底层默认值同样定义于 auto_device_map.rs L135-L140pub const DEFAULT_MAX_NUM_IMAGES: usize 1; pub const DEFAULT_MAX_IMAGE_LENGTH: usize 1024;实战示例多模态模型仓库提供了完整示例 multimodal_auto_device_map.pyfrom mistralrs import ( Runner, Which, ChatCompletionRequest, MultimodalArchitecture, MultimodalAutoMapParams, ) # MODEL_ID meta-llama/Llama-3.2-11B-Vision-Instruct MODEL_ID lamm-mit/Cephalo-Llama-3.2-11B-Vision-Instruct-128k runner Runner( whichWhich.MultimodalPlain( model_idMODEL_ID, archMultimodalArchitecture.VLlama, auto_map_paramsMultimodalAutoMapParams( max_seq_len4096, max_batch_size2, max_num_images2, max_image_length512 ), ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ { type: image_url, image_url: { url: https://www.nhmagazine.com/content/uploads/2019/05/mtwashingtonFranconia-2-19-18-108-Edit-Edit.jpg }, }, { type: text, text: What is shown in this image? Write a detailed response analyzing the scene., }, ], } ], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.1, ) ) print(res.choices[0].message.content) print(res.usage)示例为视觉模型设置了单请求最多 2 张图、图片边长按 512 估算相比默认值1 张图、1024 边长显著降低了视觉激活内存预算适合在显存紧张的多卡/CPU 溢出场景下使用。参数在Which变体中的接入方式Python 侧的所有模型选择变体Which枚举都支持auto_map_params参数多模态相关变体还支持multimodal_auto_map_params。Runner内部会把 Python 参数统一转换为核心层的AutoDeviceMapParams枚举见 lib.rs L1048-L1132纯文本变体Plain、Lora、LoraGGUF、GGML、LoraGGML、XLora、XLoraGGUF、XLoraGGML→AutoDeviceMapParams::Text { max_seq_len, max_batch_size }MultimodalPlain→AutoDeviceMapParams::Multimodal其中max_image_shape (max_image_length, max_image_length)GGUF变体比较特殊当提供了mmproj_filename多模态投影文件时优先使用multimodal_auto_map_params否则回退到auto_map_params并把图像参数置为默认值见 lib.rs L1079-L1116Embedding、DiffusionPlain、Speech变体固定使用default_text()。另外有两条前置校验见 lib.rs L404-L409GGUF 同时传入auto_map_params与multimodal_auto_map_params会报错只能二选一传入multimodal_auto_map_params但未提供mmproj_filename会报错。最终num_device_layers未指定时映射策略被设为DeviceMapSetting::Auto(auto_map_params)见 lib.rs L1211核心层的AutoDeviceMapParams枚举定义在 auto_device_map.rs L54-L66并可通过maybe_promote_to_multimodal()在检测到多模态配置后把文本参数自动补全为多模态参数默认1024×1024图像形状、1 张图有对应单元测试覆盖见 auto_device_map.rs L517-L573。CLI 与 TOML 配置方式除 Python API 外相同的四个参数也可以通过命令行与 TOML 配置传入。命令行参数CLI 侧在 model_selected.rs L735-L750 定义默认值直接取自AutoDeviceMapParams常量参数默认值说明--max-seq-len4096预期最大 prompt 序列长度影响自动映射但非硬限制--max-batch-size1预期最大 prompt 批量影响自动映射但非硬限制--max-num-images1预期最大图片数量影响自动映射但非硬限制--max-image-length1024预期图片最大边长两边缘均按此值估算影响自动映射但非硬限制例如mistralrs serve --model-id meta-llama/Llama-3.3-70B-Instruct --max-seq-len 8192 --max-batch-size 4TOML 配置在 TOML 选择器中如 toml-selectors/plain.toml各模型段同样支持max_seq_len、max_batch_size多模态段还支持max_num_images、max_image_length通过#[serde(default default_max_seq_len)]等属性自动填充默认值见 toml_selector.rs L27-L41 与 L79-L88。示例[[models]] kind plain model_id meta-llama/Llama-3.3-70B-Instruct max_seq_len 8192 max_batch_size 2底层原理这些参数如何参与显存估算理解参数的真实影响需要看get_device_layers的核心流程auto_device_map.rs L199-L5151. 激活值预算。函数首先通过 loader 的mapped_max_act_size_elems与non_mapped_max_act_size_elems如 multimodal_loaders.rs L598-L615按max_seq_len × max_batch_size多模态再叠加max_num_images与图像形状估算映射层与不可映射子模型视觉/音频编码器的激活峰值乘以dtype字节数后作为激活内存开销。2. KV Cache 预算。启用 PagedAttention 时KV 预算由calculate_cache_config计算并传入max_seq_len * max_batch_size作为 token 容量基准auto_device_map.rs L308-L327未启用时直接按[max_batch_size, num_kv_heads, max_seq_len, head_dim]计算 key/value 形状的元素总数L328-L343。这就是max_seq_len与max_batch_size直接决定预留显存大小的位置。3. 逐设备贪心分配。之后对每块设备执行贪心放置先检查全部剩余内容能否放进当前设备整个模型 激活 KV放得下则全部放置否则按层大小列表从后往前逐个累加层权重与对应 KV 开销直到逼近设备容量上限L413-L475。当某设备一层都放不下时会打印警告Device {} can fit 0 layers. Consider reducing auto map params from current: {params} (ex. reducing max seq len or max num images)这正是调参的直接信号如果映射结果极端某个设备分到 0 层或报错model does not fit首要手段就是调小max_seq_len、max_batch_size、max_num_images、max_image_length来压缩估算预算。4. CPU 回退与统一内存。非统一内存系统会把 CPU 作为最后一个回退设备参与分配L366-L371统一内存iGPU系统则因为 GPU/CPU 共享物理 RAM 而不再追加 CPU 设备避免重复计费。调参实战建议保持默认即可起步默认值4096 序列、batch1对多数单请求场景是合理起点不必一上来就调整。服务长上下文时上调max_seq_len如果业务需要 32K 或 128K 长上下文务必把max_seq_len同步调大否则 KV Cache 预算会被严重低估运行时可能因动态扩容挤压模型层空间导致 OOM。并发服务时上调max_batch_sizeRunner采用连续批处理时把max_batch_size设为期望的并发请求数避免多请求挤占预算。显存不足时优先下调多卡映射失败或某设备分到 0 层时按警告提示依次调小四个参数——文本模型先动max_seq_len/max_batch_size多模态模型再动max_num_images/max_image_length。多模态图片尺寸要如实预估max_image_length按正方形边长估算如果真实图片更大如 2048 边长视觉编码器激活会超出预算应相应上调反之若只处理小图下调该值可以省出显存放更多层。牢记非硬限制语义这些参数只决定映射时的预估预算不是运行时上限超出后模型仍可运行但显存压力由运行时机制承担。追求绝对精确的分配时可改用num_device_layersDeviceMapSetting::Map手工指定每块设备的层数。小结TextAutoMapParams与MultimodalAutoMapParams是 mistral.rs 自动设备映射的预估输入通过max_seq_len、max_batch_size、max_num_images、max_image_length四个字段影响激活值与 KV Cache 的显存预算进而决定模型层在各设备间的贪心分配结果。理解其影响映射但不构成硬限制的本质并根据实际业务形态上下文长度、并发度、图片尺寸调整这四个参数是让超大模型在多卡甚至 CPU 溢出场景下稳定运行的关键技能。更多示例可参考 text_auto_device_map.py 与 multimodal_auto_device_map.py。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mistral.rs 自动设备映射（Auto Device Mapping）参数完全指南：TextAutoMapParams 与 MultimodalAutoMapParams
mistral.rs 自动设备映射Auto Device Mapping参数完全指南TextAutoMapParams 与 MultimodalAutoMapParams【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本指南围绕 mistral.rs 的自动设备映射automatic device mapping机制展开详细讲解 Python API 中TextAutoMapParams与MultimodalAutoMapParams两个参数类的每个字段、默认值与取值含义并结合源码剖析这些参数如何参与显存估算与层分配决策。读完本文你将掌握在单卡、多卡、统一内存等环境下通过这组非硬性上限参数精准控制模型切分策略的完整方法。什么是自动设备映射为什么需要这些参数当要加载的模型超过单块 GPU 显存时mistral.rs 支持自动把模型的各层layers分配到多块设备上甚至溢出到 CPU 内存这一过程称为自动设备映射automatic device mapping。核心实现位于 auto_device_map.rs 中的get_device_layers函数见 L199-L515。自动映射在真正加载权重之前需要估算运行期的内存开销——包括 KV Cache、激活值activations、不可映射子模型等。这些开销的大小取决于模型将处理多长的序列、多大的批量、多少张图片而模型本身不会告诉你这些信息。因此 mistral.rs 引入了一组用户可调的预估参数文档原话These affect automatic device mapping but are not a hard limit.即这些参数只影响自动映射时的内存预算计算并不是运行时的硬性限制。真实请求的序列长度、批量大小即使超过这些值模型依然可以运行只是超出部分的 KV Cache 与激活内存并未被计入映射预算可能在运行时产生额外压力。TextAutoMapParams纯文本模型的映射参数对应 Python 类定义见 which.rs L214-L235类型存根见 mistralrs.pyi L340-L348。FieldTypeDefaultmax_seq_lenint4 * 1024即 4096max_batch_sizeint1max_seq_len预期的最长 prompt 序列长度token 数。它直接参与 KV Cache 的元素数估算在非 PagedAttention 场景下每个 KV 头按max_batch_size × num_kv_heads × max_seq_len × head_dim计算 key/value 张量见 auto_device_map.rs L328-L342。序列越长预留的 KV 显存越大可用于放置模型层的空间就越小。max_batch_size预期同时处理的 prompt 批量大小。它同样线性放大 KV Cache 预算上述公式中的第一个维度以及激活值开销。两个字段均由 Python 构造函数提供默认值底层默认常量定义在 auto_device_map.rs L135-L140pub const DEFAULT_MAX_SEQ_LEN: usize 4 * 1024; pub const DEFAULT_MAX_BATCH_SIZE: usize 1;实战示例文本模型仓库提供了完整可运行的示例 text_auto_device_map.pyfrom mistralrs import Runner, Which, ChatCompletionRequest, TextAutoMapParams runner Runner( whichWhich.Plain( model_idmeta-llama/Llama-3.3-70B-Instruct, auto_map_paramsTextAutoMapParams(max_seq_len4096, max_batch_size2), ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ {role: user, content: Tell me a story about the Rust type system.} ], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.1, ) ) print(res.choices[0].message.content) print(res.usage)示例中为 70B 规模的 Llama 3.3 模型配置了max_seq_len4096、max_batch_size2即在估算时假定每次最多并发处理 2 个 4096 token 的请求。如果实际服务的请求更长或批量更大映射预算可能偏紧运行时需要通过 KV Cache 的动态分配来兜底。MultimodalAutoMapParams多模态模型的映射参数对应 Python 类定义见 which.rs L237-L269类型存根见 mistralrs.pyi L350-L359。FieldTypeDefaultmax_seq_lenint4 * 1024即 4096max_batch_sizeint1max_num_imagesint1max_image_lengthint1024前两个字段与文本版含义一致多模态模型额外多出两个字段max_num_images每个请求中预期的最大图片数量。它影响视觉编码器激活值与后续文本侧序列长度的估算。max_image_length预期图片的最大边长按正方形估算边长底层转换为(max_image_length, max_image_length)的图像形状见 lib.rs L1088-L1092。图像尺寸越大视觉编码器产生的 patch/embedding 越多激活内存开销越大。底层默认值同样定义于 auto_device_map.rs L135-L140pub const DEFAULT_MAX_NUM_IMAGES: usize 1; pub const DEFAULT_MAX_IMAGE_LENGTH: usize 1024;实战示例多模态模型仓库提供了完整示例 multimodal_auto_device_map.pyfrom mistralrs import ( Runner, Which, ChatCompletionRequest, MultimodalArchitecture, MultimodalAutoMapParams, ) # MODEL_ID meta-llama/Llama-3.2-11B-Vision-Instruct MODEL_ID lamm-mit/Cephalo-Llama-3.2-11B-Vision-Instruct-128k runner Runner( whichWhich.MultimodalPlain( model_idMODEL_ID, archMultimodalArchitecture.VLlama, auto_map_paramsMultimodalAutoMapParams( max_seq_len4096, max_batch_size2, max_num_images2, max_image_length512 ), ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ { type: image_url, image_url: { url: https://www.nhmagazine.com/content/uploads/2019/05/mtwashingtonFranconia-2-19-18-108-Edit-Edit.jpg }, }, { type: text, text: What is shown in this image? Write a detailed response analyzing the scene., }, ], } ], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.1, ) ) print(res.choices[0].message.content) print(res.usage)示例为视觉模型设置了单请求最多 2 张图、图片边长按 512 估算相比默认值1 张图、1024 边长显著降低了视觉激活内存预算适合在显存紧张的多卡/CPU 溢出场景下使用。参数在Which变体中的接入方式Python 侧的所有模型选择变体Which枚举都支持auto_map_params参数多模态相关变体还支持multimodal_auto_map_params。Runner内部会把 Python 参数统一转换为核心层的AutoDeviceMapParams枚举见 lib.rs L1048-L1132纯文本变体Plain、Lora、LoraGGUF、GGML、LoraGGML、XLora、XLoraGGUF、XLoraGGML→AutoDeviceMapParams::Text { max_seq_len, max_batch_size }MultimodalPlain→AutoDeviceMapParams::Multimodal其中max_image_shape (max_image_length, max_image_length)GGUF变体比较特殊当提供了mmproj_filename多模态投影文件时优先使用multimodal_auto_map_params否则回退到auto_map_params并把图像参数置为默认值见 lib.rs L1079-L1116Embedding、DiffusionPlain、Speech变体固定使用default_text()。另外有两条前置校验见 lib.rs L404-L409GGUF 同时传入auto_map_params与multimodal_auto_map_params会报错只能二选一传入multimodal_auto_map_params但未提供mmproj_filename会报错。最终num_device_layers未指定时映射策略被设为DeviceMapSetting::Auto(auto_map_params)见 lib.rs L1211核心层的AutoDeviceMapParams枚举定义在 auto_device_map.rs L54-L66并可通过maybe_promote_to_multimodal()在检测到多模态配置后把文本参数自动补全为多模态参数默认1024×1024图像形状、1 张图有对应单元测试覆盖见 auto_device_map.rs L517-L573。CLI 与 TOML 配置方式除 Python API 外相同的四个参数也可以通过命令行与 TOML 配置传入。命令行参数CLI 侧在 model_selected.rs L735-L750 定义默认值直接取自AutoDeviceMapParams常量参数默认值说明--max-seq-len4096预期最大 prompt 序列长度影响自动映射但非硬限制--max-batch-size1预期最大 prompt 批量影响自动映射但非硬限制--max-num-images1预期最大图片数量影响自动映射但非硬限制--max-image-length1024预期图片最大边长两边缘均按此值估算影响自动映射但非硬限制例如mistralrs serve --model-id meta-llama/Llama-3.3-70B-Instruct --max-seq-len 8192 --max-batch-size 4TOML 配置在 TOML 选择器中如 toml-selectors/plain.toml各模型段同样支持max_seq_len、max_batch_size多模态段还支持max_num_images、max_image_length通过#[serde(default default_max_seq_len)]等属性自动填充默认值见 toml_selector.rs L27-L41 与 L79-L88。示例[[models]] kind plain model_id meta-llama/Llama-3.3-70B-Instruct max_seq_len 8192 max_batch_size 2底层原理这些参数如何参与显存估算理解参数的真实影响需要看get_device_layers的核心流程auto_device_map.rs L199-L5151. 激活值预算。函数首先通过 loader 的mapped_max_act_size_elems与non_mapped_max_act_size_elems如 multimodal_loaders.rs L598-L615按max_seq_len × max_batch_size多模态再叠加max_num_images与图像形状估算映射层与不可映射子模型视觉/音频编码器的激活峰值乘以dtype字节数后作为激活内存开销。2. KV Cache 预算。启用 PagedAttention 时KV 预算由calculate_cache_config计算并传入max_seq_len * max_batch_size作为 token 容量基准auto_device_map.rs L308-L327未启用时直接按[max_batch_size, num_kv_heads, max_seq_len, head_dim]计算 key/value 形状的元素总数L328-L343。这就是max_seq_len与max_batch_size直接决定预留显存大小的位置。3. 逐设备贪心分配。之后对每块设备执行贪心放置先检查全部剩余内容能否放进当前设备整个模型 激活 KV放得下则全部放置否则按层大小列表从后往前逐个累加层权重与对应 KV 开销直到逼近设备容量上限L413-L475。当某设备一层都放不下时会打印警告Device {} can fit 0 layers. Consider reducing auto map params from current: {params} (ex. reducing max seq len or max num images)这正是调参的直接信号如果映射结果极端某个设备分到 0 层或报错model does not fit首要手段就是调小max_seq_len、max_batch_size、max_num_images、max_image_length来压缩估算预算。4. CPU 回退与统一内存。非统一内存系统会把 CPU 作为最后一个回退设备参与分配L366-L371统一内存iGPU系统则因为 GPU/CPU 共享物理 RAM 而不再追加 CPU 设备避免重复计费。调参实战建议保持默认即可起步默认值4096 序列、batch1对多数单请求场景是合理起点不必一上来就调整。服务长上下文时上调max_seq_len如果业务需要 32K 或 128K 长上下文务必把max_seq_len同步调大否则 KV Cache 预算会被严重低估运行时可能因动态扩容挤压模型层空间导致 OOM。并发服务时上调max_batch_sizeRunner采用连续批处理时把max_batch_size设为期望的并发请求数避免多请求挤占预算。显存不足时优先下调多卡映射失败或某设备分到 0 层时按警告提示依次调小四个参数——文本模型先动max_seq_len/max_batch_size多模态模型再动max_num_images/max_image_length。多模态图片尺寸要如实预估max_image_length按正方形边长估算如果真实图片更大如 2048 边长视觉编码器激活会超出预算应相应上调反之若只处理小图下调该值可以省出显存放更多层。牢记非硬限制语义这些参数只决定映射时的预估预算不是运行时上限超出后模型仍可运行但显存压力由运行时机制承担。追求绝对精确的分配时可改用num_device_layersDeviceMapSetting::Map手工指定每块设备的层数。小结TextAutoMapParams与MultimodalAutoMapParams是 mistral.rs 自动设备映射的预估输入通过max_seq_len、max_batch_size、max_num_images、max_image_length四个字段影响激活值与 KV Cache 的显存预算进而决定模型层在各设备间的贪心分配结果。理解其影响映射但不构成硬限制的本质并根据实际业务形态上下文长度、并发度、图片尺寸调整这四个参数是让超大模型在多卡甚至 CPU 溢出场景下稳定运行的关键技能。更多示例可参考 text_auto_device_map.py 与 multimodal_auto_device_map.py。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考