快速、灵活的大型语言模型推理。

| 文档 | Rust SDK | Python SDK | Discord |

最新动态

• Gemma 4: 全模态支持：文本、图像、视频和音频输入。指南 | 视频设置
• MXFP4 ISQ 量化: 使用优化解码内核的 MXFP4，使模型更快、更小。量化文档
• 通义千问 3.5 系列模型: 支持包括视觉在内的通义千问 3.5 系列模型。指南

为什么选择 mistral.rs？

• 无需配置即可运行任何 Hugging Face 模型: 只需 mistralrs run -m user/model。
• 真正的多模态支持: 文本、视觉、视频和音频、语音生成、图像生成以及嵌入功能集成在一个引擎中。
• 完全可控的量化: 选择您想要使用的精确量化方式，或者使用 mistralrs quantize 自定义 UQFF。
• 内置 Web UI: 运行 mistralrs serve --ui 即可立即获得 Web 界面。
• 硬件感知: mistralrs tune 会基准测试您的系统，并选择最佳的量化方案和设备映射。
• 灵活的 SDK: 提供 Python 包和 Rust crate，方便您构建自己的项目。
• 智能体特性 — 内置工具调用、网页搜索和 MCP 客户端。

快速入门

安装

Linux/macOS:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/EricLBuehler/mistral.rs/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/EricLBuehler/mistral.rs/master/install.ps1 | iex

手动安装及其他平台

运行您的第一个模型

# 交互式聊天
mistralrs run -m Qwen/Qwen3-4B

# 一次性提示（无交互式会话）
mistralrs run -m Qwen/Qwen3-4B -i "法国的首都是哪里？"

# 带图片的一次性请求
mistralrs run -m google/gemma-4-E4B-it --image photo.jpg -i "请描述这张图片"

# 或者启动带有 Web UI 的服务器
mistralrs serve --ui -m google/gemma-4-E4B-it

然后访问 http://localhost:1234/ui 即可进入 Web 聊天界面。

mistralrs CLI

CLI 设计为 零配置: 只需指向一个模型即可开始使用。

• 自动检测: 自动检测模型架构、量化格式和聊天模板。
• 一体化: 单个二进制文件即可完成聊天、服务、基准测试和 Web UI 功能（run、serve、bench）。
• 硬件调优: 运行 mistralrs tune 自动基准测试并配置适合您硬件的最佳设置。
• 格式无关: 无缝支持 Hugging Face 模型、GGUF 文件以及 UQFF 量化。

# 自动为您的硬件调优并生成配置文件
mistralrs tune -m Qwen/Qwen3-4B --emit-config config.toml

# 使用生成的配置文件运行
mistralrs from-config -f config.toml

# 诊断系统问题（CUDA、Metal、HuggingFace 连接）
mistralrs doctor

完整 CLI 文档

Web 聊天演示

为何如此高效

性能

• 默认在所有设备上支持连续批处理。
• CUDA 配合 FlashAttention V2/V3、Metal 以及 多 GPU 张量并行。
• PagedAttention 用于 CUDA 或 Apple Silicon 上的高吞吐量连续批处理，支持前缀缓存（包括多模态）。

量化（完整文档）

• 对任何 Hugging Face 模型进行 原位量化 (ISQ)。
• 支持 GGUF（2-8 位）、GPTQ、AWQ、HQQ、FP8、BNB。
• ⭐ 逐层拓扑: 可针对每一层微调量化以达到最佳质量与速度。
• ⭐ 自动选择最适合您硬件的量化方法。

灵活性

• LoRA 和 X-LoRA 支持权重合并。
• AnyMoE: 可在任何基础模型上创建专家混合模型。
• 多模型: 支持运行时加载/卸载。

智能体特性

• 集成 工具调用 并支持 Python/Rust 回调函数。
• ⭐ 网页搜索集成。
• ⭐ MCP 客户端: 可自动连接外部工具。

完整功能文档

支持的模型

文本模型

• Granite 4.0
• SmolLM 3
• DeepSeek V3
• GPT-OSS
• DeepSeek V2
• 通义千问 3 Next
• 通义千问 3 MoE
• Phi 3.5 MoE
• 通义千问 3
• GLM 4
• GLM-4.7-Flash
• GLM-4.7（MoE）
• Gemma 2
• 通义千问 2
• Starcoder 2
• Phi 3
• Mixtral
• Phi 2
• Gemma
• Llama
• Mistral

多模态模型

• 通义千问 3.5
• 通义千问 3.5 MoE
• 通义千问 3-VL
• 通义千问 3-VL MoE
• Gemma 3n
• Llama 4
• Gemma 3
• Mistral 3
• Phi 4 多模态
• 通义千问 2.5-VL
• MiniCPM-O
• Llama 3.2 Vision
• 通义千问 2-VL
• Idefics 3
• Idefics 2
• LLaVA Next
• LLaVA
• Phi 3V

语音模型

• Voxtral（ASR/语音转文字）
• Dia

图像生成模型

• FLUX

嵌入模型

• Embedding Gemma
• 通义千问 3 嵌入

请求新增模型 | 完整兼容性表格

Python SDK

pip install mistralrs  # 或 mistralrs-cuda、mistralrs-metal、mistralrs-mkl、mistralrs-accelerate

from mistralrs import Runner, Which, ChatCompletionRequest

runner = Runner(
    which=Which.Plain(model_id="Qwen/Qwen3-4B"),
    in_situ_quant="4",
)

res = runner.send_chat_completion_request(
    ChatCompletionRequest(
        model="default",
        messages=[{"role": "user", "content": "你好！"}],
        max_tokens=256,
    )
)
print(res.choices[0].message.content)

Python SDK | 安装指南 | 示例 | 烹饪书

Rust SDK

cargo add mistralrs

use anyhow::Result;
use mistralrs::{IsqType, TextMessageRole, TextMessages, MultimodalModelBuilder};

#[tokio::main]
async fn main() -> Result<()> {
    let model = MultimodalModelBuilder::new("google/gemma-4-E4B-it")
        .with_isq(IsqType::Q4K)
        .with_logging()
        .build()
        .await?;

    let messages = TextMessages::new().add_message(
        TextMessageRole::User,
        "Hello!",
    );

    let response = model.send_chat_request(messages).await?;

    println!("{:?}", response.choices[0].message.content);

    Ok(())
}

API 文档 | Crate | 示例

Docker

用于快速容器化部署：

docker pull ghcr.io/ericlbuehler/mistral.rs:latest
docker run --gpus all -p 1234:1234 ghcr.io/ericlbuehler/mistral.rs:latest \
  serve -m Qwen/Qwen3-4B

Docker 镜像

对于生产环境，我们建议直接安装 CLI，以获得最大的灵活性。

文档

有关完整文档，请参阅 文档。

快速链接：

• CLI 参考 - 所有命令和选项
• HTTP API - 兼容 OpenAI 的端点
• 量化 - ISQ、GGUF、GPTQ 等
• 设备映射 - 多 GPU 和 CPU 卸载
• MCP 集成 - MCP 集成文档
• 故障排除 - 常见问题及解决方案
• 配置 - 用于配置的环境变量

贡献

欢迎贡献！请 提交议题 讨论新功能或报告 bug。如果您想添加新模型，请通过议题与我们联系，我们将进行协调。

致谢

没有 Candle 的出色工作，本项目将无法实现。感谢所有 贡献者！

mistral.rs 与 Mistral AI 无关联。

返回顶部

mistral.rs 快速上手指南

mistral.rs 是一个高性能、灵活的 LLM 推理引擎，支持文本、图像、视频和音频多模态输入。它无需复杂配置即可运行任意 Hugging Face 模型，并提供 Rust 和 Python SDK。

环境准备

系统要求：

• 操作系统：Linux, macOS, Windows (PowerShell)
• 硬件加速（可选但推荐）：
  • NVIDIA GPU (CUDA)
  • Apple Silicon (Metal)
  • CPU (MKL/Accelerate)
• 依赖：无需额外安装深度学习框架，mistral.rs 为独立二进制文件或通过包管理器安装。

注意：国内用户若访问 Hugging Face 模型受阻，请确保已配置镜像源（如 HF_ENDPOINT 环境变量）或使用本地模型路径。

安装步骤

方式一：命令行一键安装（推荐）

Linux / macOS:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/EricLBuehler/mistral.rs/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/EricLBuehler/mistral.rs/master/install.ps1 | iex

方式二：Python SDK 安装

pip install mistralrs
# 如需特定后端加速，可选择：
# pip install mistralrs-cuda
# pip install mistralrs-metal
# pip install mistralrs-mkl

方式三：Rust SDK 安装

在 Cargo.toml 中添加依赖：

[dependencies]
mistralrs = "latest"

或在终端执行：

cargo add mistralrs

方式四：Docker 部署

docker pull ghcr.io/ericlbuehler/mistral.rs:latest

基本使用

1. 交互式对话 (CLI)

直接运行模型进行聊天（自动下载模型）：

mistralrs run -m Qwen/Qwen3-4B

2. 单次提示推理

不进入交互模式，直接输出结果：

mistralrs run -m Qwen/Qwen3-4B -i "法国首都是哪里？"

3. 多模态推理（图文）

传入图片进行分析：

mistralrs run -m google/gemma-4-E4B-it --image photo.jpg -i "描述这张图片"

4. 启动 Web UI 服务

启动本地服务器并打开网页聊天界面：

mistralrs serve --ui -m google/gemma-4-E4B-it

启动后访问：http://localhost:1234/ui

5. 硬件自动调优

自动测试当前硬件性能并生成最优配置文件：

mistralrs tune -m Qwen/Qwen3-4B --emit-config config.toml

使用生成的配置运行：

mistralrs from-config -f config.toml

6. Python SDK 示例

from mistralrs import Runner, Which, ChatCompletionRequest

runner = Runner(
    which=Which.Plain(model_id="Qwen/Qwen3-4B"),
    in_situ_quant="4",
)

res = runner.send_chat_completion_request(
    ChatCompletionRequest(
        model="default",
        messages=[{"role": "user", "content": "你好！"}],
        max_tokens=256,
    )
)
print(res.choices[0].message.content)

7. Rust SDK 示例

use anyhow::Result;
use mistralrs::{IsqType, TextMessageRole, TextMessages, MultimodalModelBuilder};

#[tokio::main]
async fn main() -> Result<()> {
    let model = MultimodalModelBuilder::new("google/gemma-4-E4B-it")
        .with_isq(IsqType::Q4K)
        .with_logging()
        .build()
        .await?;

    let messages = TextMessages::new().add_message(
        TextMessageRole::User,
        "Hello!",
    );

    let response = model.send_chat_request(messages).await?;

    println!("{:?}", response.choices[0].message.content);

    Ok(())
}