mistral.rsmistralrs tune命令完全指南为模型自动推荐量化等级与设备映射方案【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsmistralrs tune是 mistral.rs 提供的调优推荐器命令它不需要真正加载模型而是通过读取模型配置、探测当前设备CUDA / Metal / CPU与显存容量为模型逐一评估多个量化等级下的预估体积、显存占用、可容纳上下文长度与质量档位最终输出一份可复制可执行的推荐方案含推荐命令与 TOML 配置。阅读完本文你将掌握tune的全部命令行参数、六大子命令的适用场景以及其底层推荐逻辑候选生成、适配判定、上下文余量计算是如何在 tuning.rs 中实现的并能在实际部署前用一条命令完成该用几比特量化、该怎样做设备映射的决策。本文基于仓库内的官方参考文档 docs/src/content/docs/reference/cli/tune.md 编写该文档由 clap 命令行定义经 docgen.rs 自动生成文件头标注 Generated from clap definitions by mistralrs-cli docgen因此所有参数、默认值与语义均与当前源码保持严格一致文中涉及底层实现处均给出对应的源码相对路径供深入阅读。一、tune是什么量化 设备映射的推荐器mistralrs tune的核心定位是在真正运行推理之前回答我的模型在我的机器上应该怎么量化、怎么摆放。它不加载权重、不跑推理而是基于模型config.json本地目录或 Hugging Face 仓库含architectures、num_hidden_layers、KV cache 配置等当前机器探测到的设备与显存CUDA 优先其次 Metal最后 CPU用户通过--profile表达的质量/速度偏好或通过--isq/--quant指定的量化目标生成一份完整分析报告。命令的基本形态为mistralrs tune [OPTIONS] [COMMAND]其中COMMAND是模型类型子命令auto/text/multimodal/diffusion/speech/embedding通过[COMMAND]指定模型种类若不指定子命令而是直接使用-m等选项则走默认的全局选项集合。两条硬性约束理解tune的前提从 tune.rs 的实现可以看出tune有两个刻意的限制拒绝--quant auto。tune本身就是推荐器--quant auto语义是让推理命令自动挑选产物与tune的职责冲突因此直接报错--quant auto is meaningless for tune; tune is the recommender。正确做法是显式传入--quant level或--isq level来偏置推荐方向。拒绝 LoRA / X-LoRA 适配器选项。validate_adapter_optionstune.rs会在检测到--enable-lora、--lora、--legacy-lora、--xlora等配置时直接报错原因在文档中写得很清楚适配器内存没有被计入估算给出推荐反而会误导。multimodal子命令若启用了动态 LoRA 同样会被拒绝。仓库自带的单元测试 tune.rs 验证了这一行为传入lora: vec![...]时断言错误信息包含 does not account for adapter memory。另外从 tuning.rs 的auto_tune入口可以看到还有两类不支持场景预量化 GGUF/GGML 模型已量化无需再推荐量化以及diffusion / speech 模型当前不参与量化推荐遇到会直接bail!报错。二、全局选项总表下表汇总了mistralrs tune的全部选项。由于auto/text/multimodal/embedding子命令共享绝大多数选项只有量化/设备映射之外的少量差异这里先给出完整总表再在各子命令小节说明其专属差异diffusion/speech子命令只保留模型与设备映射相关子集。2.1 模型来源与格式OptionDefaultDescription-m, --model-id MODEL_IDHugging Face 模型 ID 或本地模型目录当-f指定了本地文件时可省略-t, --tokenizer TOKENIZER本地 tokenizer.json 文件路径-a, --arch ARCH模型架构未指定时自动检测--dtype DTYPEauto模型数据类型--hf-overrides HF_OVERRIDES对 Hugging Face 模型配置进行递归合并的 JSON 覆盖项--max-model-len MAX_MODEL_LEN运行时模型上下文长度--format FORMAT模型格式plainsafetensors、gguf、ggml未指定时从-f自动检测-f, --quantized-file QUANTIZED_FILEGGUF/GGML 文件名可多个分号分隔后缀决定格式--mmproj MMPROJGGUF 投影器projector覆盖无歧义时自动选择可多个分号分隔--tok-model-id TOK_MODEL_ID可选模型 ID覆盖量化模型的配置、tokenizer 与 processor 资产--gqa GQA1GGML 模型的 GQA 值--hf-cache HF_CACHE自定义 Hugging Face 缓存目录2.2 量化相关tune的核心输入OptionDescription--quant QUANT量化目标。推理命令会据此挑选匹配的 GGUF 或 UQFF 产物无匹配 UQFF 的源检查点使用原位量化。tune的特殊之处在于它直接评估该等级而不是挑选产物。接受数字等级2、3、4、5、6、8或受支持的量化名称--isq IN_SITU_QUANT原位量化目标。接受数字等级2、3、4、5、6、8或原始量化名q4k、q8_0等支持兼容的 GGUF 源--from-uqff FROM_UQFF要加载的 UQFF 产物。接受文件名、数字量化等级2–6、8或量化类型q4k、afq8等报告声明的产物与常规分片名会展开为全部分片分号仅用于手动罗列不连续分片--isq-organization ISQ_ORGANIZATIONISQ 组织策略default或moqe--imatrix IMATRIX用于增强量化的 imatrix 文件--calibration-file CALIBRATION_FILE用于生成 imatrix 的校准文件需要说明的是--quant与--isq在tune中最终都汇聚成同一个请求等级。从 tune.rs 可以看到extract_quant_flag优先、extract_isq_setting兜底随后统一经mistralrs_core::parse_isq_value校验并转换为IsqType存入AutoTuneRequest.requested_isq若校验失败会给出 Invalid quantization value 错误。这两个提取函数定义于 serve.rs--quant auto的拦截也发生在这里。2.3 LoRA / X-LoRA 选项存在但会被拒绝以下选项在 CLI 层面依然存在与serve等命令共用参数定义见 args/model.rs但tune运行时会主动拒绝OptionDefaultDescription--enable-lorafalse启用动态 LoRA不预加载适配器支持兼容的文本与多模态模型含 GGUFvision、audio、projector 适配器不支持--lora ALIASSOURCE\|JSON以ALIASSOURCE预加载语言模型 LoRA 适配器可重复远程适配器使用 main 分支--lora-max-adapters LORA_MAX_ADAPTERS16最大加载的 LoRA 别名数量以及独立计算的在驻适配器代数--lora-max-rank LORA_MAX_RANK256单个 LoRA 适配器接受的最大秩--lora-max-bytes BYTES8589934592已加载适配器占用的最大内存默认 8 GiB--legacy-lora SOURCEGGML 或 Phi3 GGUF 模型的静态 LoRA 适配器源--legacy-lora-order LEGACY_LORA_ORDER旧版 raw GGUF/GGML LoRA 适配器的 ordering JSON 文件--xlora XLORAX-LoRA 适配器模型 ID--xlora-order XLORA_ORDERX-LoRA ordering JSON 文件--tgt-non-granular-index TGT_NON_GRANULAR_INDEXX-LoRA 的目标非细粒度索引2.4 设备映射OptionDefaultDescription--cpufalse强制仅 CPU 执行-n, --device-layers DEVICE_LAYERS设备层映射格式ORD:NUM;...例如0:10;1:20省略时自动设备映射--topology TOPOLOGY用于设备映射的 Topology YAML 文件--max-seq-len MAX_SEQ_LEN4096自动设备映射的最大序列长度--max-batch-size MAX_BATCH_SIZE1自动设备映射的最大批大小2.5 PagedAttention 与 KV CacheOptionDefaultDescription--paged-attn MODEautoPagedAttention 模式autoCUDA 启用、Metal/CPU 禁用默认、on强制启用不支持时报错、off强制禁用--pa-context-len CONTEXT_LEN为该上下文长度分配 KV cache未指定时默认使用可用显存的 90%--pa-memory-mb MEMORY_MB以 MB 指定 GPU 内存--pa-context-len的替代--pa-memory-fraction MEMORY_FRACTIONGPU 内存利用率分数 0.0–1.0--pa-context-len/--pa-memory-mb的替代--pa-block-size BLOCK_SIZE每块 token 数CUDA 默认 32--pa-cache-type CACHE_TYPEautoKV cache 量化类型2.6 多模态相关仅auto/multimodalOptionDescription--encoder-cache-memory-mb ENCODER_CACHE_MEMORY_MB多模态编码器缓存保留的最大逻辑张量内存MiB--max-edge MAX_EDGE图像缩放的最大边长保持宽高比--max-num-images MAX_NUM_IMAGES每次请求的最大图像数量--max-image-length MAX_IMAGE_LENGTH设备映射的最大图像维度2.7 输出控制OptionDefaultDescription--profile PROFILEbalanced调优 profilequality、balanced、fast--jsonfalse以 JSON 而非人类可读文本输出--emit-config EMIT_CONFIG将推荐设置写入一个 TOML 配置文件三、六大子命令适用场景与专属差异tune通过子命令声明模型类型每个子命令的用法行都以--model-id MODEL_ID为必填项。选择子命令的意义在于不同模型类型参与推荐的量化、设备映射与多模态选项集合不同。3.1mistralrs tune auto推荐mistralrs tune auto [OPTIONS] --model-id MODEL_ID自动检测模型类型是官方推荐用法。auto共享全局选项全量集合含--encoder-cache-memory-mb、--max-edge、--max-num-images、--max-image-length等多模态选项但不含--profile、--json、--emit-config这三个输出控制项——它们挂在tune顶层。类型检测逻辑位于 tuning.rs 的infer_kind若本地目录存在config_sentence_transformers.json判定为Embedding模型tuning.rs 中同时读取config.json与config_sentence_transformers.json若config.json中的唯一architectures[0]能被MultimodalLoaderType解析判定为Multimodal能被EmbeddingLoaderType解析判定为Embedding否则经NormalLoaderType校验后判定为Normal文本若architectures数量不为 1直接报错 Expected exactly one architecture in config。检测结果会以[INFO]形式写入输出如 Detected embedding model configuration.、Detected multimodal model configuration.。3.2mistralrs tune textmistralrs tune text [OPTIONS] --model-id MODEL_ID显式声明的文本生成模型。选项集合 全局选项模型来源 量化 适配器 设备映射 PagedAttention LoRA/X-LoRA不含多模态专属的--encoder-cache-memory-mb、--max-edge、--max-num-images、--max-image-length。3.3mistralrs tune multimodalmistralrs tune multimodal [OPTIONS] --model-id MODEL_ID多模态模型视觉-语言等。选项集合在text基础上补回全部多模态选项--encoder-cache-memory-mb、--max-edge、--max-num-images、--max-image-length。注意该子命令的--enable-lora/--lora描述明确限定为语言模型的 LoRAEnable dynamic LoRA for the language model且同样会被validate_adapter_options拒绝。3.4mistralrs tune diffusionmistralrs tune diffusion [OPTIONS] --model-id MODEL_ID图像生成扩散模型。只保留最小选项集-m/--model-id、-t/--tokenizer、-a/--arch、--dtype、--hf-overrides、--max-model-len以及设备映射的--cpu、-n/--device-layers、--topology、--hf-cache、--max-seq-len、--max-batch-size。无任何量化选项--quant/--isq等均不存在且如前所述auto_tune对 diffusion 模型直接报错不支持。3.5mistralrs tune speechmistralrs tune speech [OPTIONS] --model-id MODEL_ID语音合成模型。选项集与diffusion完全一致模型来源 设备映射同样不支持量化推荐auto_tune中直接bail!。3.6mistralrs tune embeddingmistralrs tune embedding [OPTIONS] --model-id MODEL_IDEmbedding 模型。选项集接近text含模型来源、量化、适配器、设备映射、PagedAttention但不含多模态选项也没有--lora-max-adapters/--lora-max-rank/--lora-max-bytes这三个 LoRA 资源上限参数。四、底层推荐逻辑从候选生成到推荐落定理解了参数再看tune是如何得出推荐结论的。核心实现在 tuning.rs 的auto_tunetuning.rs流程如下4.1 候选量化集合按后端区分all_candidatestuning.rs定义了要评估的完整候选集合从最高质量到最低质量排序Metal 后端None不量化、AFQ8、AFQ6、AFQ4、AFQ3、AFQ2CUDA / CPU 后端None、Q8_0、Q6K、Q5K、Q4K、Q3K、Q2K。也就是说在 Apple Silicon 上推荐以 AFQApple 友好量化系列为主在 CUDA/CPU 上则以 GGUF 风格的 Q 系列为主——这正是设备感知的体现。4.2 profile 决定优先推荐列表default_candidatestuning.rs按 profile 给出偏好顺序推荐时优先从这份列表里挑选能装下的最高质量档ProfileCUDA/CPU 优先列表Metal 优先列表qualityQ8_0, Q6K, Q5K, Q4K, Q3K, Q2KAFQ8, AFQ6, AFQ4, AFQ3balanced默认Q6K, Q5K, Q4K, Q3KAFQ6, AFQ4, AFQ3fastQ4K, Q3K, Q2KAFQ4, AFQ3, AFQ2如果用户显式传了--isq/--quant则preferred_candidates被收窄为单一候选tuning.rs相当于把推荐钉死在用户指定的等级上但仍会评估全部候选用于对比展示。4.3 每个候选的指标计算对每个候选map_for_candidatetuning.rs调用与真实推理共用的设备映射管线通过pack_factor量化类型的压缩系数计算各层体积layer_sizes_in_bytes与非映射体积non_mapped_size_in_bytes得到预估体积调用get_device_layers_for_loader得到设备层映射若映射结果中包含ordinal usize::MAXCPU 序号的哨兵值的层则判定为Hybrid混合需 CPU 卸载否则为Fits完全装进 GPU若映射失败则退化为仅估算体积并标记为TooLarge。三个FitStatus枚举tuning.rs语义为Fits完全放入 GPU、Hybrid需要 CPU 卸载、TooLarge即使卸载也装不下。4.4 上下文余量Context Room计算calculate_max_contexttuning.rs是输出表中 Context Room 一列的依据读取模型原生最大序列长度native_max_seq_len若模型体积已超可用显存返回 0否则用剩余显存 ÷ 每 token KV cache 字节数算出显存允许的上下文长度。其中每 token 的 KV cache 字节数 kv_cache_elements_per_token × dtype 字节数 × 层数kv_cache_elements_per_token来自ModelConfigLiketrait已正确计入num_kv_heads、k_head_dim、v_head_dim取计算结果与模型原生上限的较小值若计算值 ≥ 原生上限则标注(max)表示上下文受模型原生上限而非显存限制。4.5 质量档位映射quality_tiertuning.rs把每个量化类型映射到 5 档QualityTiertuning.rsBaseline不量化FP16 全精度Near-lossless近无损8-bitQ8_0 / Q8_1 / Q8K / AFQ8 / HQQ8Good良好6-bit 与 5-bitQ6K / AFQ6 / Q5_0 / Q5_1 / Q5KAcceptable可接受4-bitQ4_0 / Q4_1 / Q4K / AFQ4 / HQQ4Degraded退化3-bit 与 2-bitQ3K / AFQ3 / Q2K / AFQ2。4.6 推荐落定与兜底推荐规则tuning.rs按优先列表profile 默认列表或用户指定的单一等级顺序选第一个Fits或Hybrid的候选打上recommended true若优先列表里一个都装不下则回退为所有候选中第一个能装的无论质量档位若仍然没有候选能装下auto_tune直接报错No suitable quantization level fits on the available devices. Try a smaller model or enable CPU offload.推荐结果还会生成可直接复制的命令tuning.rsmistralrs serve -m model_id --isq level不量化时省略--isq。同时输出中会提示 PagedAttention 可用性非 CPU 后端且paged_attn_supported()时为auto否则为offtuning.rs。五、输出解读表格、JSON 与 TOML 配置5.1 人类可读输出默认输出由 tune.rs 渲染包含头部信息模型 ID、profile、后端cpu/cuda/metal、总显存GB[INFO]提示如检测到的模型类型Quantization Options 表格列包括列含义Quant量化类型显示名如None (FP16)、Q4KEst. Size预估模型体积GBVRAM %预估体积 ÷ 总显存百分比Context Room显存允许的上下文长度(max)表示已达模型原生上限Quality质量档位Baseline / Near-lossless / Good / Acceptable / DegradedStatus适配状态 Recommended、✅ Fits、 Recommended (Hybrid)、⚠️ Hybrid、❌ Too Large[WARN]警告对每个TooLarge的量化候选给出 X (N.N GB) exceeds available VRAM 提示tuning.rsRecommended Command可直接复制运行的推荐命令。5.2 JSON 输出--json会输出AutoTuneResult的完整序列化结果serde_json::to_string_pretty结构定义于 tuning.rs{ model_id: org/model, profile: balanced, backend: cuda, candidates: [ { isq: q4k, isq_name: Q4K, estimated_size_bytes: 4187596800, vram_usage_percent: 0.81, max_context_tokens: 8192, context_is_model_max: true, quality: acceptable, fit_status: fits, device_layers_cli: 0:28;1:4, recommended: true } ], recommended_isq: q4k, device_layers: null, device_layers_cli: 0:28;1:4, paged_attn_mode: auto, recommended_command: mistralrs serve -m org/model --isq q4k, total_vram_bytes: 51539607552, warnings: [], notes: [] }说明枚举的 JSON 序列化采用 kebab-case如fit_status: fits、profile: balanced便于脚本直接消费。5.3--emit-config生成可直接运行的 TOML--emit-config path会把推荐落成一份 TOML 配置文件生成逻辑见 tune.rs随后即可用mistralrs from-config --file path直接启动服务这是输出中的提示用法tune.rs。生成的配置模板如下command serve [server] host 0.0.0.0 port 1234 [runtime] max_seqs 32 [[models]] kind text model_id org/model dtype bf16 [models.quantization] in_situ_quant q4k [models.device] device_layers [0:28, 1:4]command serve固定为 serve 命令kind来自模型类型auto/text/multimodal/diffusion/speech/embedding其中auto会省略该行见 tune.rsdtype取自ModelSelected中的数据类型auto/f16/bf16/f32tune.rs[models.quantization]仅当存在推荐量化时输出in_situ_quant[models.device]仅当推荐方案含设备层映射如 Hybrid 场景时输出device_layers。六、实战示例6.1 基础用法自动检测 默认 balanced 推荐mistralrs tune auto -m org/llm-model输出一份包含全部量化候选CUDA 上为 Q8_0 → Q2K的分析矩阵与推荐命令。6.2 用--isq偏置推荐方向mistralrs tune auto -m org/llm-model --isq q4k优先列表被收窄为单一候选 Q4K若它装得下则被标记为 Recommended同时表格中仍展示其余候选用于对比。6.3 快速评估 机器可读输出mistralrs tune auto -m org/llm-model --profile fast --jsonfastprofile 只偏好 Q4K/Q3K/Q2K或 Metal 上的 AFQ4/AFQ3/AFQ2--json输出便于接入脚本或 CI。6.4 一键生成并应用推荐配置mistralrs tune auto -m org/llm-model --emit-config tuned.toml mistralrs from-config --file tuned.toml6.5 约束设备映射与上下文预算mistralrs tune auto -m org/llm-model --max-seq-len 8192 --max-batch-size 16 mistralrs tune text -m org/llm-model -n 0:10;1:20--max-seq-len/--max-batch-size影响自动设备映射的内存预算-n则完全手工指定每张卡的层数格式ORD:NUM;...。6.6 典型的错误用法会被拒绝mistralrs tune auto -m org/llm-model --quant auto # 报错tune 本身就是推荐器 mistralrs tune auto -m org/llm-model --lora codeorg/code-lora # 报错适配器内存未计入估算 mistralrs tune auto -f model.gguf # 报错预量化模型无需再推荐量化七、适用边界与注意事项只适用于未量化的 plainsafetensors模型GGUF/GGML 已含量化信息diffusion / speech 模型当前不参与量化推荐这四类会直接报错tuning.rs。适配器选项一律拒绝因为 LoRA/X-LoRA 适配器内存未被计入估算强行推荐会失真。估算基于config.json 本机显存探测与真实加载存在合理误差体积估算使用pack_factor而非逐层真实量化属于估算而非实测。tune不下载模型权重只拉取/读取配置类文件config.json、config_sentence_transformers.json因此速度很快若模型在本地目录则直接读取目录内文件tuning.rs。显存不足且没有任何候选可装时会明确建议换更小的模型或启用 CPU 卸载。文档由 clap 定义自动生成若需确认参数的精确来源可查阅 args/model.rs 与 args/mod.rs其中TuneProfileArg枚举及到核心TuneProfile的转换定义于 args/mod.rs输出渲染与校验逻辑见 tune.rs推荐算法全貌见 tuning.rs。八、小结mistralrs tune把该用几比特量化、层该怎么摆放、能跑多长上下文这三件部署前最常纠结的事压缩成一条命令的决策输出。它复用真实推理的设备映射管线做估算按后端CUDA/Metal/CPU与 profilequality/balanced/fast生成候选通过第一个能装下的最高质量档规则给出推荐并提供人类可读表格、JSON 与 TOML 三种落地形式。理解其参数语义与推荐规则后你可以在任何新模型、新机器上快速获得一份可信的量化与设备映射起点再结合 serve 命令投入实际部署。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考