# Mistral 3.5 - 如何本地运行

Mistral 发布了 Mistral-Medium-3.5-128B，这是他们新的稠密型 128B 参数、多模态、混合推理模型。它支持文本和图像输入、文本输出、256K 上下文窗口，并且在推理、编码、长上下文、工具使用、智能体工作流以及多模态文档/图像理解方面表现出色。

Mistral Medium 3.5 为其 5 倍大小的模型提供了极具竞争力的性能。可在约 64GB RAM 上本地运行。GGUF： [Mistral-Medium-3.5-128B-GGUF](https://huggingface.co/unsloth/Mistral-Medium-3.5-128B-GGUF)

{% hint style="success" %}
**2026 年 5 月 1 日更新：** 我们与 Mistral 合作修复了影响某些实现的 Mistral Medium 3.5 推理问题，并发布了包含该修复的更新版 GGUF（**与 Unsloth 无关** 或我们的量化版本）。该问题是由 YaRN 解析怪癖引起的，影响了多个实现，包括 `transformers` 和 `llama.cpp`。修改 `mscale_all_dim` 从 `1` 到 `0` 后已解决。我们还修复了 `mmproj` 文件未正确生成的问题。

<mark style="background-color:$success;">**Mistral 现在已经将我们的修复推送到他们的官方仓库！**</mark>
{% endhint %}

### 使用指南

{% hint style="info" %}
GGUF 的视觉功能目前已经支持。后续还会提供支持。
{% endhint %}

表：Mistral Medium 3.5 推荐硬件需求。单位为总内存：RAM + VRAM，或统一内存。

| Mistral 3.5     | 3 位   | 4 位   | 8 位        |
| --------------- | ----- | ----- | ---------- |
| Medium 3.5 128B | 64 GB | 80 GB | 128-170 GB |

{% hint style="info" %}
你的可用总内存应至少超过你下载的量化模型大小。否则，llama.cpp 仍可通过部分 RAM / 磁盘卸载运行，但生成速度会更慢。对于长上下文、更大的批量、重工具的智能体运行以及图像提示词，你还需要更多内存。
{% endhint %}

#### 推荐设置

使用 Mistral 推荐的推理设置：

* `reasoning_effort="none"` → 快速即时回复、聊天、信息提取和简单指令。
* `reasoning_effort="high"` → 推理模式，推荐用于复杂提示、编码、研究、数学和智能体用法。

推荐的采样默认值：

* 使用 `temperature = 0.7` 用于 `reasoning_effort="high"`.
* 使用 `temperature = 0.0` 到 `0.7` 用于 `reasoning_effort="none"`，具体取决于任务。
* 保持重复惩罚和存在惩罚关闭，或者设为 `1.0` ，除非你看到循环输出。
* 最大上下文长度为 `262,144`

#### **推理模式**

Mistral Medium 3.5 支持即时指令模式和带有 'high' 选项的推理模式。

要为 llama.cpp / llama-server 启用高推理：

```bash
--chat-template-kwargs '{"reasoning_effort":"high"}'
```

要禁用推理：

```bash
--chat-template-kwargs '{"reasoning_effort":"none"}'
```

如果你使用的是 Windows PowerShell，请使用：

```powershell
--chat-template-kwargs "{\"reasoning_effort\":\"none\"}"
```

## 运行 Mistral 3.5 教程

由于 Mistral Medium 3.5 是一个稠密型 128B 模型，本地推理建议从 Dynamic 4-bit GGUF 开始。GGUF： `unsloth/Mistral-Medium-3.5-128B-GGUF`

<a href="/pages/5902f65155c9213c17d6735294471de2eb587dd1#unsloth-studio-guide" class="button primary">在 Unsloth Studio 中运行</a><a href="/pages/5902f65155c9213c17d6735294471de2eb587dd1#llama.cpp-guide" class="button secondary">在 llama.cpp 中运行</a>

{% hint style="warning" %}
目前没有任何多模态/视觉 GGUF 可在 **Ollama** 中工作，因为它们使用单独的 `mmproj` 视觉文件。请使用兼容 llama.cpp 的后端。

请不要使用 **CUDA 13.2** 否则你可能会得到乱码输出。NVIDIA 正在修复。
{% endhint %}

### 🦥 Unsloth Studio 指南

在本教程中，我们将使用 [Unsloth Studio](/docs/zh/xin/studio.md)，这是我们用于运行和训练 LLM 的新 Web UI。使用 Unsloth Studio，你可以在本地于 **音频**、图像和文本上运行模型，支持 **Mac、Windows**和 Linux，并且：

{% columns %}
{% column %}

* 搜索、下载、 [运行 GGUF](/docs/zh/xin/studio.md#run-models-locally) 和 safetensor 模型
* **并排** 比较 **模型**
* [**自愈式** 工具调用](/docs/zh/xin/studio.md#execute-code--heal-tool-calling) + **网页搜索**
* [**代码执行**](/docs/zh/xin/studio.md#run-models-locally) （Python、Bash）
* [自动推理](/docs/zh/xin/studio.md#model-arena) 参数调优（temp、top-p 等）
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度提升 2 倍，VRAM 减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/5af4df407c8134f1ff75a4d7535569361c049e51" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

**MacOS、Linux、WSL：**

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

**Windows PowerShell：**

```bash
irm https://unsloth.ai/install.ps1 | iex
```

{% endstep %}

{% step %}

#### 设置 Unsloth Studio（仅需一次）

设置过程会自动安装 Node.js（通过 nvm）、构建前端、安装所有 Python 依赖，并构建带 CUDA 支持的 llama.cpp。

{% hint style="info" %}
**WSL 用户：** 系统会提示你输入 `sudo` 密码以安装构建依赖（`cmake`, `git`, `libcurl4-openssl-dev`).
{% endhint %}
{% endstep %}

{% step %}

#### 启动 Unsloth

**MacOS、Linux、WSL：**

```bash
source unsloth_studio/bin/activate
unsloth studio -H 0.0.0.0 -p 8888
```

**Windows PowerShell：**

```bash
& .\unsloth_studio\Scripts\unsloth.exe studio -H 0.0.0.0 -p 8888
```

<div data-with-frame="true"><figure><img src="/files/7fd4b2ed7fb55df6d31b4dd1ce1181d57613709b" alt="" width="375"><figcaption></figcaption></figure></div>

**然后在浏览器中打开 `http://localhost:8888` 。**
{% endstep %}

{% step %}

#### 搜索并下载 Mistral Medium 3.5

首次启动时，你需要创建一个密码来保护账户安全，并在以后重新登录。然后前往 [Studio Chat](/docs/zh/xin/studio/chat.md) 选项卡，在搜索栏中搜索 Mistral 3.5，并下载你想要的模型和量化版本。
{% endstep %}

{% step %}

#### 运行 Mistral 3.5

在使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。

如需更多信息，你可以查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 指南

对于本指南，我们将使用 Unsloth Dynamic 4-bit 版本的 Mistral Medium 3.5。参见： `unsloth/Mistral-Medium-3.5-128B-GGUF`.

对于这些教程，我们将使用 llama.cpp 进行快速本地推理，尤其是在你拥有 CPU 或高内存统一内存机器时。

**1. 构建 llama.cpp**

获取最新版本 `llama.cpp` 在 GitHub 上。更改 `-DGGML_CUDA=ON` 到 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想使用 CPU 推理。对于 Apple Mac / Metal 设备，请设置 `-DGGML_CUDA=OFF`；Metal 支持默认开启。

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

**2. 直接从 Hugging Face 运行**

```bash
export LLAMA_CACHE="unsloth/Mistral-Medium-3.5-128B-GGUF"

./llama.cpp/llama-cli \
    -hf unsloth/Mistral-Medium-3.5-128B-GGUF:UD-Q4_K_XL \
    --temp 0.7 \
    --chat-template-kwargs '{"reasoning_effort":"none"}'
```

用于高推理模式：

```bash
./llama.cpp/llama-cli \
    -hf unsloth/Mistral-Medium-3.5-128B-GGUF:UD-Q4_K_XL \
    --temp 0.7 \
    --chat-template-kwargs '{"reasoning_effort":"high"}'
```

**3. 手动下载模型**

安装之后 `huggingface_hub` 和 `hf_transfer`:

```bash
pip install huggingface_hub hf_transfer

hf download unsloth/Mistral-Medium-3.5-128B-GGUF \
    --local-dir unsloth/Mistral-Medium-3.5-128B-GGUF \
    --include "*UD-Q4_K_XL*" \
    --include "*mmproj*"
```

如果下载卡住，请设置：

```bash
export HF_HUB_ENABLE_HF_TRANSFER=1
```

**4. 运行本地 GGUF**

```bash
./llama.cpp/llama-cli \
    --model unsloth/Mistral-Medium-3.5-128B-GGUF/Mistral-Medium-3.5-128B-UD-Q4_K_XL.gguf \
    --temp 0.7 \
    --chat-template-kwargs '{"reasoning_effort":"none"}'
```

如果包含多模态投影器 GGUF，请使用：

```bash
./llama.cpp/llama-cli \
    --model unsloth/Mistral-Medium-3.5-128B-GGUF/Mistral-Medium-3.5-128B-UD-Q4_K_XL.gguf \
    --mmproj unsloth/Mistral-Medium-3.5-128B-GGUF/mmproj-BF16.gguf \
    --temp 0.7 \
    --chat-template-kwargs '{"reasoning_effort":"none"}'
```

#### Llama-server 部署

要在 llama-server 上部署 Mistral Medium 3.5，请使用：

```bash
./llama.cpp/llama-server \
    -hf unsloth/Mistral-Medium-3.5-128B-GGUF:UD-Q4_K_XL \
    --alias "mistral-medium-3.5" \
    --host 0.0.0.0 \
    --port 8001 \
    --temp 0.7 \
    --chat-template-kwargs '{"reasoning_effort":"none"}'
```

用于推理模式：

```bash
--chat-template-kwargs '{"reasoning_effort":"high"}'
```

如果你使用的是 Windows PowerShell，请使用：

```powershell
--chat-template-kwargs "{\"reasoning_effort\":\"high\"}"
```

你可以向 llama-server 发送兼容 OpenAI 的请求来 ping 它：

```bash
curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {"role": "user", "content": "Explain the main difference between instant mode and reasoning mode."}
    ],
    "temperature": 0.7
  }'
```

### Mistral 3.5 最佳实践

#### 提示示例

**简单推理提示**

```
系统：
你是一个精确的推理助手。请仔细解题，并且只呈现最终答案和简短解释。

用户：
一列火车在上午 8:15 出发，并在上午 11:47 到达。旅程持续了多久？
```

使用 `reasoning_effort="high"` 用于这种风格的提示。

**OCR / 文档提示**

对于 OCR 和文档提取，请先放入图像，并要求结构化输出。

```
[先放图像]
从这张收据中提取所有文本。请以 JSON 形式返回商家、日期、项目明细和总计。
```

**多模态比较提示**

```
[图像 1]
[图像 2]
比较这两张截图，并告诉我哪一张更可能让新用户感到困惑。给出 3 个具体理由。
```

**编码智能体提示**

```
你是一个在仓库中工作的编码智能体。
先检查相关文件，然后提出一个最小补丁。
请按以下内容返回最终答案：摘要、已更改文件、运行的测试和风险。
```

使用 `reasoning_effort="high"` 以及用于代码库探索的工具调用。

**JSON / 函数调用提示**

```
只要需要计算或查询，就使用提供的工具。
只返回有效 JSON。不要在 JSON 对象之外包含任何说明性文字。
```

### 基准测试

<div><figure><img src="/files/402c77c25b21861efef8dc65d8879323719202a6" alt=""><figcaption></figcaption></figure> <figure><img src="/files/418f04447937edbc8e45eb946b34e7a4193a1fd7" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/mistral-3.5.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.