> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/deepseek-v4.md).

# DeepSeek-V4：如何本地运行

DeepSeek-V4 是 DeepSeek 的新开源模型，包括 **DeepSeek-V4-Pro** 以及 **1.6T** 参数（49B 激活）以及 **DeepSeek-V4-Flash** 以及 **284B** 参数（13B 激活）。这些模型在编程、智能体工作流以及带有 **100万上下文** 窗口的聊天方面表现出色。在本指南中，我们将展示如何在本地运行 DeepSeek-V4-Flash ： [DeepSeek-V4-Flash GGUF](https://huggingface.co/unsloth/DeepSeek-V4-Flash-GGUF)

对于 **无损** DeepSeek，请使用 Q8（`UD-Q8_K_XL`），它只比 **大 7GB** 比 Q4（`UD-Q4_K_XL`）。 无损 8 位 GGUF 为 **162 GB** 而 3 位为 **103GB** 这可以在一台 **110GB 内存** 设备上运行**.** DeepSeek-V4-Flash 在 MMLU-Pro 上得分 86.2%，在 GPQA Diamond 上得分 88.1%，在 Terminal Bench 2.0 上得分 56.9%。

{% hint style="success" %}
**7 月 7 日：** DeepSeek-V4 现在已经可以运行了！我们还改进了 [DeepSeek-V4 聊天 jinja 模板](#deepseek-v4-chat-template-improvements)，并测试了 4000 多段对话，结果与官方基线一致。
{% endhint %}

<a href="/pages/8cefdd6ae681e7680f74c7b6a344fd7c21933ee8#usage-guide" class="button primary">使用指南</a><a href="/pages/8cefdd6ae681e7680f74c7b6a344fd7c21933ee8#run-deepseek-v4-flash-tutorials" class="button primary">运行教程</a>

### :llama: llama.cpp DeepSeek V4 实现修复

llama.cpp 在 [24162](https://github.com/ggml-org/llama.cpp/pull/24162) - 我们注意到，当使用来自 **任何提供方的**任何 GGUF 时，在使用 KV 缓存量化时，多轮对话与 DS4 的 Hugging Face 基线相比表现不佳 `--cache-type k/v q8_0` - 此问题已于 2026 年 7 月 7 日在 llama.cpp 中修复并合并，使用 [25202](https://github.com/ggml-org/llama.cpp/pull/25202)

具体来说，在修复之前，调用 DeepSeek 量化模型会导致 `overlayotin kinetic academyléléléléulif` ，而在 PR 之后，"法国的首都是巴黎。"，这是正确的。

<table><thead><tr><th>引擎</th><th width="91.54998779296875">分数</th><th width="122.60003662109375">计算</th><th width="114.5">工具选择</th><th width="97.4000244140625">并行工具</th><th width="112.699951171875">多轮工具</th><th>嵌套工具</th></tr></thead><tbody><tr><td>官方代码</td><td><strong>15/15</strong></td><td>3</td><td>3</td><td>3</td><td>3</td><td>3</td></tr><tr><td>任意提供方</td><td><strong>4/15</strong></td><td>1</td><td>2</td><td>0</td><td>0</td><td>1</td></tr><tr><td><strong>之后</strong> <a href="https://github.com/ggml-org/llama.cpp/pull/25202">25202</a></td><td><strong>15/15</strong></td><td>3</td><td>2</td><td>3</td><td>3</td><td>3</td></tr></tbody></table>

### :speech\_balloon: DeepSeek V4 聊天模板改进

我们还改进了 DeepSeek-V4 聊天 jinja 模板，并测试了 4000 多段对话，结果与黄金基线（官方 DS4）一致

我们添加了 `reasoning_effort` ，并且你可以选择 `max、high` ，就像官方 DeepSeek-V4 一样。我们按照 DS4 添加了正确的系统提示，并遵循了 gpt-oss 的风格。

而对于工具调用， `reasoning_content` 在 DS4 中被保留，但 jinja 聊天模板会将其排除。我们把它加回来了。

**禁用思考，调整推理强度**

DeepSeek-V4 默认使用推理。它也支持推理强度，其中 `reasoning_effort` 可以是“high”、“max”或禁用。

要禁用思考，请使用 `--chat-template-kwargs '{"enable_thinking":false}'`。如果你使用的是 **Windows** PowerShell，请使用： `--chat-template-kwargs "{\"enable_thinking\":false}"`

你也可以使用 `--reasoning on` 或 `--reasoning off` 现在也可以在 llama.cpp 中使用！

如需自定义推理强度或禁用推理，请使用以下示例：

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

### 📊 量化分析

我们的 `UD-Q8_K_XL` 量化是完全无损的。DeepSeek-V4-Flash 是 [量化感知训练的](/docs/zh/bo-ke/quantization-aware-training-qat.md)：官方检查点将其路由专家（模型的 96%）原生存储为 MXFP4，其余部分存储为 FP8 或 BF16。GGUF 的 MXFP4 正是这种格式，因此我们将专家按位重新打包，而 FP8 会无舍入地反量化为 BF16。我们将每个张量都与官方 DeepSeek 权重进行了比对：1,328 个全部按位一致，并且在推理时仍然保持无损（KL 散度约为 0，100% 顶部 token 一致）。

**非**Unsloth DeepSeek-V4-Flash GGUF 是在未使用这些路径的情况下转换的，因此与官方权重有所偏离。 `UD-Q4_K_XL` 保留了相同的按位精确专家，只将非专家张量（模型的 4%）量化到 Q8\_0，因此在大小和质量上都与 Q8 非常接近。

<div align="left"><figure><img src="/files/8f29a9f74f33e8dd0c8ce3e4d97b453414ab0c58" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/46726f88c8ac658263b6266a1dca8ce9fb5e3b18" alt="" width="563"><figcaption></figcaption></figure></div>

与官方权重相比，这两种 Unsloth 量化都处在质量/大小前沿。UD-Q8\_K\_XL 是唯一的无损点。UD-Q4\_K\_XL 与其他社区 MXFP4 格式一致，并且比 Q4\_K-experts 转换更准确，后者虽然更大，但 KLD 达到 0.029。

<div align="left"><figure><img src="/files/e3b898a627d874fd6c1fd0420f2a00170560a468" alt="" width="563"><figcaption></figcaption></figure></div>

按层拆分的误差显示了原因。保留原生 MXFP4 专家意味着每一层的权重误差都是 0%。将专家重新量化为 Q4\_K 或 IQ2\_XXS 的转换会对几乎每个权重进行舍入：Q4\_K 为 5%，IQ2\_XXS 超过 30%。

<div align="left"><figure><img src="/files/11b73e0c7fa25f3c535f63d4f8bbc717073fba6c" alt="" width="563"><figcaption><p>我们的 MXFP4 在全部 840 万个权重上都是完全零误差，而 Q4_K 采用的是另一种 4 位网格，必须对每一个权重进行舍入（RMSE 5.2%）。</p></figcaption></figure></div>

我们还发现，对某些张量使用 Q8\_0 和 F16 并非无损，而且由于 DeepSeek 已应用 QAT 来让 MXFP4 / FP8 良好工作，情况会更糟，所以我们不得不直接将它们保留为 BF16。因此，请使用 UD-Q8\_K\_XL 作为真正的无损量化，而 UD-Q4\_K\_XL 会将部分 BF16 项下转为 Q8\_0。

关于以下内容的完整基准表： [GGUF 基准，请看这里](#gguf-benchmarks).

#### ⚙️ 使用指南

DeepSeek-V4-Flash 比 DeepSeek-V4-Pro 更小更快，具有 **284B** 参数（13B 激活），以及 **100万上下文窗口**。该模型有 3 种模式， **非思考**, **思考** **高** 和 **思考** **最大**.&#x20;

建议使用 `UD-IQ3_XXS` 它是 **103GB** 以获得最佳结果。由于文件大小不包括 KV 缓存和上下文分配，请尽量至少有 **110GB 内存** 来运行模型。

该 `UD-Q8_K_XL` 量化是 DeepSeek-V4-Flash 的完整原始精度版本。其大小为 162GB，最好至少有 169GB 可用的 RAM/VRAM。

**表：推理硬件要求** （单位 = 总内存：RAM + VRAM，或统一内存）

<table><thead><tr><th width="129.8004150390625">1 位</th><th width="130.85650634765625">2 位</th><th width="140.26702880859375">3 位</th><th>4 位（接近无损）</th><th>Q8_K_XL（无损）</th></tr></thead><tbody><tr><td>92 GB</td><td>102 GB</td><td>110-135 GB</td><td>162 GB</td><td>169 GB</td></tr></tbody></table>

{% hint style="success" %}
为获得最佳性能，请确保包括 VRAM 和系统 RAM 在内的总可用内存，能比量化后的模型文件大小大出充足的余量。
{% endhint %}

#### 推荐设置

DeepSeek 为获得最佳性能推荐以下参数： `temperature=1.0`, `top-p=1.0`

**思考高 默认开启。** 如果已禁用，你可以通过以下方式启用： `--chat-template-kwargs '{"enable_thinking":true}'` 或者通过以下界面下拉菜单切换： [Unsloth Studio](#unsloth-studio-guide)。另请参见 [#deepseek-v4-chat-template-improvements](#deepseek-v4-chat-template-improvements "mention")

{% columns %}
{% column %}

| `temperature = 1.0` |
| ------------------- |
| `top-p = 1.0`       |
| {% endcolumn %}     |

{% column %}

* **最大上下文窗口：** `1,048,576`
* 对于思考最大，请将上下文至少设置为 **384K 令牌**.
  {% endcolumn %}
  {% endcolumns %}

## 运行 DeepSeek-V4-Flash 教程：

本教程我们将使用 3 位量化 `UD-IQ3_XXS`，因为它可以装在 128GB RAM 设备上。将 `UD-IQ3_XXS` 以及 `UD-Q8_K_XL` （原始质量）或其他量化版本替换掉它，如果你的机器有足够内存。现在你可以在 [Unsloth Studio](#run-in-unsloth-studio).

<a href="/pages/8cefdd6ae681e7680f74c7b6a344fd7c21933ee8#unsloth-studio-guide" class="button primary">🦥 Unsloth Studio 指南</a><a href="/pages/8cefdd6ae681e7680f74c7b6a344fd7c21933ee8#llama.cpp-guide" class="button primary">🦙 Llama.cpp 指南</a>

### 🦥 Unsloth Studio 指南

DeepSeek-V4-Flash 现在可以在 [Unsloth Studio](/docs/zh/xin-de/studio.md)，我们的新本地 AI 开源网页界面。Unsloth Studio 可让你在 **MacOS**, **Windows**、Linux 以及：

{% columns %}
{% column %}

* 搜索、下载， [运行 GGUF](/docs/zh/xin-de/studio.md#run-models-locally) 以及 safetensor 模型
* [**自修复** 工具调用](/docs/zh/xin-de/studio.md#execute-code--heal-tool-calling) + **网页搜索**
* [**代码执行**](/docs/zh/xin-de/studio.md#run-models-locally) （Python、Bash）
* [自动推理](/docs/zh/xin-de/studio.md#model-arena) 参数调优（temp、top-p 等）
* 通过 llama.cpp 实现快速 CPU + GPU 推理
* [训练 LLM](/docs/zh/xin-de/studio.md#no-code-training) 速度提升 2 倍，VRAM 减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/8c44ec261d12e6d57c1557d97d0ed7b99e38be15" 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

**MacOS、Linux、WSL 和 Windows：**

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

然后打开 `http://127.0.0.1:8888` （或你的具体 URL）在浏览器中。
{% endstep %}

{% step %}

#### 搜索并下载 DeepSeek-V4-Flash

首次启动时，你需要创建一个密码来保护你的账户，并重新登录。然后前往 [Unsloth Chat](/docs/zh/xin-de/studio/chat.md) 标签页，在搜索栏中搜索 DeepSeek-V4-Flash，并下载你想要的模型和量化版本。

<figure><img src="/files/05d5af1d09960638f1324979f62472011d50ed21" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 运行 DeepSeek-V4-Flash

在使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。由于 **思考高 默认开启**，你可以到右侧下拉菜单将其切换为非思考或思考最大。你也可以编辑上下文长度、聊天模板和其他设置。

更多信息，你可以查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin-de/studio/chat.md).

<figure><img src="/files/24011740e066568a4f1ece7d3742c125303ef850" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 指南

{% stepper %}
{% step %}
获取最新的 `llama.cpp` **在** [**GitHub 这里**](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明进行操作。将 `-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
```

{% endstep %}

{% step %}
你现在可以使用 `llama.cpp` 直接加载和下载模型，就像 `ollama run`。首先，选择你想要的量化类型，例如 `IQ3_XXS`。同时使用 `export LLAMA_CACHE="folder"` 以强制 `llama.cpp` 保存到特定位置。请注意，此下载过程可能非常慢，因此最好使用下一节中的手动下载流程。

```bash
export LLAMA_CACHE="unsloth/DeepSeek-V4-Flash-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/DeepSeek-V4-Flash-GGUF:UD-IQ3_XXS \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --min-p 0.0
```

{% endstep %}

{% step %}
如果你想手动下载模型，我们可以在安装 `pip install huggingface_hub`之后通过下面的代码下载模型。如果下载卡住，请参见： [Hugging Face Hub、XET 调试](/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md)

```bash
hf download unsloth/DeepSeek-V4-Flash-GGUF \\
    --local-dir unsloth/DeepSeek-V4-Flash-GGUF \\
    --include "*UD-IQ3_XXS*" # 4 位请使用 "*UD-IQ4_XS*"
```

{% endstep %}

{% step %}
你可以编辑 `--threads 32` 来设置 CPU 线程数， `--ctx-size 32768` 来设置上下文长度， `--n-gpu-layers 2` 来指定 GPU 卸载多少层。如果你的 GPU 内存不足，请尝试调整它。如果你只有 CPU 推理，也请将其移除。

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-cli \\
    --model unsloth/DeepSeek-V4-Flash-GGUF/blob/main/UD-IQ3_XXS/DeepSeek-V4-Flash-UD-IQ3_XXS-00001-of-00004.gguf \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --min-p 0.0
```

{% endcode %}
{% endstep %}
{% endstepper %}

## 📊 基准测试

### GGUF 基准

下面是一个表格，用于比较 Unsloth 和其他提供方的量化结果。参考 = 官方权重。在 4x B200 上，以 ctx 512 对 wikitext-2 计算困惑度和 KL 散度。

<figure><img src="/files/8f29a9f74f33e8dd0c8ce3e4d97b453414ab0c58" alt="" width="563"><figcaption></figcaption></figure>

| 量化                              | 大小（GB） | PPL    | 平均 KLD      | RMS delta-p | 相同 top token | 按位完全一致的权重    |
| ------------------------------- | ------ | ------ | ----------- | ----------- | ------------ | ------------ |
| 官方（参考）                          | 156.4  | 4.5319 | 0           | 0%          | 100%         | 100%         |
| **Unsloth UD-Q8\_K\_XL**        | 161.9  | 4.5319 | **约 0（无损）** | 0.000%      | 100.000%     | **100.000%** |
| **Unsloth UD-Q4\_K\_XL**        | 155.1  | 4.5335 | 0.0102      | 3.40%       | 96.28%       | 97.46%       |
| bartowski MXFP4                 | 156.0  | 4.5351 | 0.0105      | 3.42%       | 96.18%       | 97.57%       |
| antirez Q4KExperts-F16（imatrix） | 164.6  | 4.5743 | 0.0291      | 5.87%       | 93.95%       | 0.51%        |
| antirez Q4KExperts-F16          | 164.6  | 4.5726 | 0.0290      | 5.89%       | 93.94%       | 0.93%        |
| antirez 混合 L37-42-Q4K（imatrix）  | 97.6   | 5.8169 | 0.3605      | 21.15%      | 79.74%       | 0.41%        |
| antirez IQ2XXS（imatrix）         | 86.7   | 6.0808 | 0.4079      | 22.23%      | 78.15%       | 0.39%        |
| antirez IQ2XXS                  | 86.7   | 6.1518 | 0.4207      | 22.74%      | 77.92%       | 0.47%        |

### 官方基准

更下方可查看表格形式的基准结果：

<figure><img src="/files/4528a3ba27c1187cc7ce72ddb9d7a70f3cad6254" alt="" width="563"><figcaption></figcaption></figure>

| 基准（指标）                     | V4-Flash 非思考 | V4-Flash 高 | V4-Flash 最大 | V4-Pro 非思考 | V4-Pro 高 | V4-Pro 最大 |
| -------------------------- | :----------: | :--------: | :---------: | :--------: | :------: | :-------: |
| **知识与推理**                  |              |            |             |            |          |           |
| MMLU-Pro（EM）               |     83.0     |    86.4    |     86.2    |    82.9    |   87.1   |  **87.5** |
| SimpleQA-Verified（Pass\@1） |     23.1     |    28.9    |     34.1    |    45.0    |   46.2   |  **57.9** |
| Chinese-SimpleQA（Pass\@1）  |     71.5     |    73.2    |     78.9    |    75.8    |   77.7   |  **84.4** |
| GPQA Diamond（Pass\@1）      |     71.2     |    87.4    |     88.1    |    72.9    |   89.1   |  **90.1** |
| HLE（Pass\@1）               |      8.1     |    29.4    |     34.8    |     7.7    |   34.5   |  **37.7** |
| LiveCodeBench（Pass\@1）     |     55.2     |    88.4    |     91.6    |    56.8    |   89.8   |  **93.5** |
| Codeforces（评级）             |       -      |    2816    |     3052    |      -     |   2919   |  **3206** |
| HMMT 2026 2 月（Pass\@1）     |     40.8     |    91.9    |     94.8    |    31.7    |   94.0   |  **95.2** |
| IMOAnswerBench（Pass\@1）    |     41.9     |    85.1    |     88.4    |    35.3    |   88.0   |  **89.8** |
| Apex（Pass\@1）              |      1.0     |    19.1    |     33.0    |     0.4    |   27.4   |  **38.3** |
| Apex 候选榜（Pass\@1）          |      9.3     |    72.1    |     85.7    |     9.2    |   85.5   |  **90.2** |
| **长上下文**                   |              |            |             |            |          |           |
| MRCR 1M（MMR）               |     37.5     |    76.9    |     78.7    |    44.7    |   83.3   |  **83.5** |
| CorpusQA 1M（ACC）           |     15.5     |    59.3    |     60.5    |    35.6    |   56.5   |  **62.0** |
| **智能体**                    |              |            |             |            |          |           |
| Terminal Bench 2.0（Acc）    |     49.1     |    56.6    |     56.9    |    59.1    |   63.3   |  **67.9** |
| SWE Verified（已解决）          |     73.7     |    78.6    |     79.0    |    73.6    |   79.4   |  **80.6** |
| SWE Pro（已解决）               |     49.1     |    52.3    |     52.6    |    52.1    |   54.4   |  **55.4** |
| SWE Multilingual（已解决）      |     69.7     |    70.2    |     73.3    |    69.8    |   74.1   |  **76.2** |
| BrowseComp（Pass\@1）        |       -      |    53.5    |     73.2    |      -     |   80.4   |  **83.4** |
| 带工具的 HLE（Pass\@1）          |       -      |    40.3    |     45.1    |      -     |   44.7   |  **48.2** |
| MCPAtlas（Pass\@1）          |     64.0     |    67.4    |     69.0    |    69.4    | **74.2** |    73.6   |
| GDPval-AA（Elo）             |       -      |      -     |     1395    |      -     |     -    |  **1554** |
| Toolathlon（Pass\@1）        |     40.7     |    43.5    |     47.8    |    46.3    |   49.0   |  **51.8** |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/deepseek-v4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.