mistral.rs Python API 的 Which 枚举详解：一次掌握全部模型加载变体与参数

mistral.rs Python API 的 Which 枚举详解一次掌握全部模型加载变体与参数【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本指南以 mistral.rs 的 Python 参考文档 docs/src/content/docs/reference/python/which.md 为核心系统讲解Which枚举的十余种模型选择变体Plain、Lora、XLora、GGUF、GGML、MultimodalPlain、DiffusionPlain、Speech 等及其全部字段、类型与默认值。读完本文你将能够准确为文本、嵌入、多模态、扩散生成与语音模型构造Which配置并理解每个参数在底层源码中的实际作用从而直接上手仓库中的各类 Python 示例。一、Which是什么在 mistral.rs 的 Python 绑定中Runner构造函数的第一个参数就是which它决定加载哪一类模型、以何种方式加载。Which是一个枚举每个变体对应一种模型加载场景纯文本模型Plain、Lora、XLora量化模型GGUF、XLoraGGUF、LoraGGUF、GGML、XLoraGGML、LoraGGML多模态模型MultimodalPlain扩散模型DiffusionPlain语音模型Speech嵌入模型Embedding使用方式统一为Which.Variant(...)例如文档给出的最小形态 Which.Plain(...)这些变体在 Rust 侧定义于 mistralrs-pyo3/src/which.rs并通过 PyO3 的#[pyclass]暴露给 Python类型签名则同步维护在类型桩文件 mistralrs-pyo3/mistralrs.pyi 中本文参数表均与这两处源码一致。二、公共结构LoraAdapter所有涉及 LoRA 的变体都依赖LoraAdapter来描述一个适配器来源FieldTypeDefaultaliasstrrequiredsourcestrrequiredrevisionstr \| NoneNonealias适配器在运行时中的唯一别名后续请求通过该别名路由到对应适配器source适配器来源可以是 Hugging Face 模型仓库 ID也可以是本地路径从源码看其 Rust 字段为String见 mistralrs-pyo3/src/which.rsrevision可选的版本/commit 标识缺省时使用仓库默认版本。三、纯文本模型变体3.1Which.Plain加载普通的 Hugging Face 权重文本模型是日常推理最常用的入口FieldTypeDefaultmodel_idstrrequiredarchArchitecture \| NoneNonetokenizer_jsonstr \| NoneNonetopologystr \| NoneNoneorganizationIsqOrganization \| NoneNonewrite_uqffstr \| NoneNonefrom_uqffstr \| list[str] \| NoneNonedtypeModelDTypeModelDType.Autoimatrixstr \| NoneNonecalibration_filestr \| NoneNoneauto_map_paramsTextAutoMapParams \| NoneNonehf_cache_pathstr \| NoneNonematformer_config_pathstr \| NoneNonematformer_slice_namestr \| NoneNone典型用法见 examples/python/plain.pyfrom mistralrs import Runner, Which, ChatCompletionRequest, Architecture runner Runner( whichWhich.Plain( model_idmistralai/Mistral-7B-Instruct-v0.1, archArchitecture.Mistral, ), )arch缺省时由model_id自动推断Architecture枚举字符串值见 mistralrs-pyo3/mistralrs.pyi覆盖Mistral、Gemma、Mixtral、Llama、Phi2、Phi3、Qwen2、Gemma2、Starcoder2、Phi3_5MoE、DeepseekV2、DeepseekV3、Qwen3、GLM4、GLM4Moe、GLM4MoeLite、Qwen3Moe、SmolLm3、GraniteMoeHybrid、GptOss、Qwen3Next、Lfm2、Lfm2Moe。需要显式指定时如权重目录与架构名称不匹配手动传入即可。3.2Which.Lora在基础模型之上加载一组 LoRA 适配器FieldTypeDefaultmodel_idstrrequiredadapterslist[LoraAdapter] \| NoneNonearchArchitecture \| NoneNonetokenizer_jsonstr \| NoneNonetopologystr \| NoneNonewrite_uqffstr \| NoneNonefrom_uqffstr \| list[str] \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNonehf_cache_pathstr \| NoneNonemax_adaptersint16max_rankint256max_bytesint8589934592三个容量上限直接对应 Rust 侧常量DEFAULT_LORA_MAX_ADAPTERS、DEFAULT_LORA_MAX_RANK、DEFAULT_LORA_MAX_BYTES定义于 mistralrs-core/src/adapter/runtime.rsmax_bytes 8 * 1024 * 1024 * 1024max_adapters运行时最多可加载的别名/适配器代数量max_rank允许的最大 LoRA 秩max_bytes常驻适配器张量总字节上限。adapters缺省时运行时初始为空可通过runner.load_lora_adapter(...)动态加载——examples/python/lora.py 完整演示了加载、按别名/精确代路由、原地替换带 generation CAS 校验与卸载的完整生命周期。3.3Which.XLora加载 X-LoRA可组合多个 LoRA、按 token 动态加权配置FieldTypeDefaultxlora_model_idstrrequiredorderstrrequiredarchArchitecture \| NoneNonemodel_idstr \| NoneNonetokenizer_jsonstr \| NoneNonetgt_non_granular_indexint \| NoneNonetopologystr \| NoneNonewrite_uqffstr \| NoneNonefrom_uqffstr \| list[str] \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNonehf_cache_pathstr \| NoneNoneorder指向记录适配器层排列顺序的 JSON 文件仓库根目录下的 orderings/xlora-gemma-paper-ordering.json 即为一例。model_id可留空从排序文件自动确定基础模型。参见 examples/python/xlora_gemma.pyrunner Runner( whichWhich.XLora( model_idNone, # Automatically determine from ordering file xlora_model_idlamm-mit/x-lora-gemma-7b, orderorderings/xlora-gemma-paper-ordering.json, tgt_non_granular_indexNone, archArchitecture.Mistral, ) )tgt_non_granular_index指定不做粒度切分的目标层索引。四、量化模型变体4.1Which.GGUF选择 GGUF 量化模型兼容 llama.cpp 生态权重FieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestr \| list[str]requiredtok_model_idstr \| NoneNonetopologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNonetokenizer_jsonstr \| NoneNone (keyword-only)mmproj_filenamestr \| list[str] \| NoneNone (keyword-only)organizationIsqOrganization \| NoneNone (keyword-only)write_uqffstr \| NoneNone (keyword-only)imatrixstr \| NoneNone (keyword-only)calibration_filestr \| NoneNone (keyword-only)max_edgeint \| NoneNone (keyword-only)multimodal_auto_map_paramsMultimodalAutoMapParams \| NoneNone (keyword-only)adapterslist[LoraAdapter] \| NoneNone (keyword-only)max_adaptersint16 (keyword-only)max_rankint256 (keyword-only)max_bytesint8589934592 (keyword-only)hf_cache_pathstr \| NoneNone (keyword-only)matformer_config_pathstr \| NoneNone (keyword-only)matformer_slice_namestr \| NoneNone (keyword-only)encoder_cache_memory_bytesint \| NoneNone (keyword-only)文档特别强调三点使用要点传入adapters[]或设置非默认的 LoRA 上限如改max_adapters可启用空的动态 LoRA 运行时指定mmproj_filename视觉投影权重文件时LoRA 适配器作用于语言模型部分将in_situ_quant传给Runner可在加载过程中对兼容的 GGUF 权重重新量化。quantized_filename支持list[str]对应分片 GGUF 文件。基础用法见 examples/python/gguf.pyrunner Runner( whichWhich.GGUF( quantized_model_idunsloth/Qwen3-0.6B-GGUF, quantized_filenameQwen3-0.6B-Q4_K_M.gguf, ) )tok_model_id仅在自动发现配置与分词器资源失败时才需要显式覆盖。Rust 侧该变体的构造签名带*关键字参数分隔符mistralrs-pyo3/src/which.rs 中的单元测试gguf_constructor_preserves_legacy_positional_prefix专门校验了这一签名兼容性。4.2Which.XLoraGGUF为 Phi3 GGUF 配置选择 X-LoRAFieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestr \| list[str]requiredxlora_model_idstrrequiredorderstrrequiredtok_model_idstr \| NoneNonetgt_non_granular_indexint \| NoneNonetopologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNone4.3Which.LoraGGUF为 Phi3 GGUF 配置选择遗留静态 LoRA对于受支持 GGUF 上的动态适配器官方建议直接向Which.GGUF传adaptersFieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestr \| list[str]requiredadapters_model_idstrrequiredorderstrrequiredtok_model_idstr \| NoneNonetopologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNone4.4Which.GGML选择 GGML 量化模型较旧的 GGML 格式需显式给出分词器模型FieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestrrequiredtok_model_idstrrequiredtokenizer_jsonstr \| NoneNonegqaint1topologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNonegqa为分组查询注意力GQA的组数默认1即不分组。4.5Which.XLoraGGMLGGML X-LoRA 组合FieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestrrequiredxlora_model_idstrrequiredorderstrrequiredtok_model_idstr \| NoneNonetokenizer_jsonstr \| NoneNonetgt_non_granular_indexint \| NoneNonegqaint1topologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNone4.6Which.LoraGGMLGGML 静态 LoRA 组合FieldTypeDefaultquantized_model_idstrrequiredquantized_filenamestrrequiredadapters_model_idstrrequiredorderstrrequiredtok_model_idstr \| NoneNonetokenizer_jsonstr \| NoneNonegqaint1topologystr \| NoneNonedtypeModelDTypeModelDType.Autoauto_map_paramsTextAutoMapParams \| NoneNone五、嵌入、多模态、扩散与语音变体5.1Which.Embedding加载嵌入模型FieldTypeDefaultmodel_idstrrequiredarchEmbeddingArchitecture \| NoneNonetokenizer_jsonstr \| NoneNonetopologystr \| NoneNonewrite_uqffstr \| NoneNonefrom_uqffstr \| list[str] \| NoneNonedtypeModelDTypeModelDType.Autohf_cache_pathstr \| NoneNoneimatrixstr \| NoneNonecalibration_filestr \| NoneNoneEmbeddingArchitecture目前包含EmbeddingGemma与Qwen3Embedding对应示例可参考 examples/python/embedding_gemma.py 与 examples/python/qwen3_embedding.py。5.2Which.MultimodalPlain加载多模态视觉-语言模型FieldTypeDefaultmodel_idstrrequiredarchMultimodalArchitecture \| NoneNonetokenizer_jsonstr \| NoneNonetopologystr \| NoneNonewrite_uqffstr \| NoneNonefrom_uqffstr \| list[str] \| NoneNonedtypeModelDTypeModelDType.Automax_edgeint \| NoneNonecalibration_filestr \| NoneNoneimatrixstr \| NoneNoneauto_map_paramsMultimodalAutoMapParams \| NoneNonehf_cache_pathstr \| NoneNonematformer_config_pathstr \| NoneNonematformer_slice_namestr \| NoneNoneorganizationIsqOrganization \| NoneNoneencoder_cache_memory_bytesint \| NoneNoneMultimodalArchitecture覆盖的架构非常广Phi3V、Idefics2、LLaVANext、LLaVA、Lfm2Vl、VLlama、Qwen2VL、Idefics3、MiniCpmO、Phi4MM、Qwen2_5VL、Gemma3、Mistral3、Llama4、Gemma3n、Qwen3VL、Qwen3VLMoE、Qwen3_5、Qwen3_5Moe、Voxtral、Gemma4、MuseGlimmer、DiffusionGemma。示例见 examples/python/qwen3_vl.pyrunner Runner( whichWhich.MultimodalPlain( model_idQwen/Qwen3-VL-4B-Thinking, archMultimodalArchitecture.Qwen3VL, ), )max_edge限制输入图像最长边encoder_cache_memory_bytes可约束视觉编码器缓存占用。5.3Which.DiffusionPlain加载文生图扩散模型FieldTypeDefaultmodel_idstrrequiredarchDiffusionArchitecturerequireddtypeModelDTypeModelDType.AutoDiffusionArchitecture提供Flux与FluxOffloaded权重卸载到 CPU、按需上载适合显存受限场景两种取值。示例见 examples/python/flux.pyrunner Runner( whichWhich.DiffusionPlain( model_idblack-forest-labs/FLUX.1-schnell, archDiffusionArchitecture.FluxOffloaded, ), ) res runner.generate_image( A vibrant sunset in the mountains, 4k, high quality., ImageGenerationResponseFormat.Url, )注意此变体arch为必填。5.4Which.Speech加载语音合成TTS模型FieldTypeDefaultmodel_idstrrequiredarchSpeechLoaderTyperequireddac_model_idstr \| NoneNonedtypeModelDTypeModelDType.AutoSpeechLoaderType当前仅含Diadac_model_id用于指定可选的 DAC描述音频编码模型。示例见 examples/python/dia.py其返回 PCM 数据后可自行封装为 WAV 文件。六、高频共享参数深入以下参数在多个变体间复用理解它们有助于一次掌握全部变体dtypeModelDType默认Auto权重数据类型。可选Auto、BF16、F16、F32字符串值见 mistralrs-pyo3/mistralrs.pyi。Auto依据硬件能力自动选择。topology设备拓扑描述文件路径配合多 GPU/异构部署使用仓库示例可参考 topologies/isq_and_device.yml。organizationIsqOrganizationISQ就地量化组织方式Default或MoQEMoE 专家专属量化。在 Rust 侧IsqOrganization::MoQE映射为MoeExpertsOnly见 mistralrs-pyo3/src/which.rs。混合专家量化可参考 examples/python/mixture_of_quant_experts.py。write_uqff/from_uqff将模型权重写为 UQFF统一量化文件格式的导出路径 / 从 UQFF 文件加载。from_uqff支持单个路径或路径列表对应 Rust 侧EitherString, VecString。imatrix/calibration_fileISQ 的重要性矩阵文件 / 在线校准数据集文件。校准数据示例见 calibration_data/calibration_datav3.txt在线校准流程见 examples/python/online_calibration.py。auto_map_paramsTextAutoMapParams/MultimodalAutoMapParams自动设备映射的期望负载参数。TextAutoMapParams含max_seq_len默认 4096、max_batch_size默认 1MultimodalAutoMapParams额外含max_num_images默认 1与max_image_length默认 1024。这些默认值对应 mistralrs-core/src/pipeline/loaders/auto_device_map.rs 中的DEFAULT_MAX_SEQ_LEN、DEFAULT_MAX_BATCH_SIZE、DEFAULT_MAX_NUM_IMAGES、DEFAULT_MAX_IMAGE_LENGTH常量且文档明确说明这些参数影响自动设备映射估算并非硬性上限。相关实操可参考 examples/python/auto_device_map.py。hf_cache_pathHugging Face 缓存目录覆盖路径。matformer_config_path/matformer_slice_nameMatFormer 模型的配置 CSV 路径与切片名。仓库内置的 MatFormer 配置见 matformer_configs/gemma3n.csv对应示例为 examples/python/gemma3n.py。tokenizer_json显式提供 tokenizer JSON 文件内容或路径tok_model_idGGUF/GGML 变体则是提供 tokenizer 的独立模型 ID。七、源码实现与类型映射从源码结构看Which的每个变体都在 mistralrs-pyo3/src/which.rs 中通过#[pyo3(constructor (...))]声明构造签名字段顺序、默认值均与本文表格一一对应get_all属性保证各字段在 Python 侧可读。Python 与 Rust 核心的类型桥接通过From实现完成Architecture → NormalLoaderType将 Python 层架构枚举映射为mistralrs-core的普通文本加载器类型EmbeddingArchitecture → EmbeddingLoaderType、MultimodalArchitecture → MultimodalLoaderType、DiffusionArchitecture → DiffusionLoaderType、SpeechLoaderType → mistralrs_core::SpeechLoaderType同理完成嵌入、多模态、扩散与语音加载器的桥接。这意味着Which变体本质上是加载器类型 模型来源 量化/映射选项的组合描述最终在Runner初始化时驱动mistralrs-core的模型加载管线。LoRA 容量默认值16/256/8 GiB与自动映射默认值4096/1/1/1024均在mistralrs-core中定义后向上传递保证了 Python、CLI 与 Rust 三种入口行为一致CLI 侧同一批默认值也出现在 mistralrs-core/src/model_selected.rs。八、选择建议速查使用场景推荐变体关键参数HF 全精度/标准权重文本模型Which.Plainmodel_id、可选arch加载 LoRA 适配器Which.Loraadapters、max_rank、max_bytesX-LoRA 组合推理Which.XLoraxlora_model_id、orderGGUF 量化模型Which.GGUFquantized_model_id、quantized_filenameGGML 旧格式模型Which.GGML三必填quantized_model_id、quantized_filename、tok_model_id视觉-语言模型Which.MultimodalPlainmodel_id、可选arch、max_edge嵌入模型Which.Embeddingmodel_id、可选arch文生图Which.DiffusionPlainmodel_id、必填arch语音合成Which.Speechmodel_id、必填arch量化场景若需在加载时重新量化权重可组合Runner(which..., in_situ_quantQ4K)使用见 examples/python/isq.py若需 UQFF 导出/导入则使用各变体的write_uqff/from_uqff参数。所有变体最终的字段集合、默认值与调用方式都可以在 mistralrs-pyo3/mistralrs.pyi 的类型声明中交叉核对确保你的代码始终与当前版本一致。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考