> 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.1-flash.md).

# DeepSeek-V4.1-Flash：本地运行指南

使用 Unsloth GGUF 和 Engram n-gram 卸载，在本地运行 DeepSeek-V4.1-Flash-1017。

**DeepSeek-V4.1-Flash-1017** 是 V4.1-Flash 的全新更新，使其成为 **最强** 迄今为止在编码、智能体任务等方面最强的开源模型。凭借 1M 上下文，其 **552B** 骨干网络 + **196B Engram** 参数支持 SSD 卸载，以减少 RAM/VRAM 需求。本指南将展示如何使用 [Unsloth Dynamic](/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs.md) GGUF 文件。

Unsloth + llama.cpp 可实现约**快约 3 倍** 相比其他专注于 CPU/VRAM/n-gram 的仓库，DeepSeek-V4.1 推理更快。我们的 **250.4 GB** 1 位 `UD-IQ1_M` 量化可实现 **88.2% 的 top-1 一致率** 相较原始 DeepSeek，并且可在 128GB 以上 RAM 的配置上本地运行。 `UD-Q8_K_XL` （无损）为 **508.4 GB**，而 `UD-Q4_K_XL` （近乎无损）为 **500.7 GB**. GGUF： [**DeepSeek-V4.1-Flash-1017-GGUF**](https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF)

<a href="/pages/186a58039c49acb85318ef9708c070fd5a5e2a45#run-deepseek-v4.1-flash-1017-tutorials" class="button primary">运行 DeepSeek-V4.1 教程</a><a href="/docs/zh/mo-xing/deepseek-v4.1-flash.md#quantization-analysis" class="button secondary">量化分析</a>

### ⚙️ 使用指南

**DeepSeek-V4.1-Flash-1017** 将 MoE 与 **Engram 条件式记忆**：最长四个 token 的 n-gram 每个 token 只访问少量表行，因此该表不必常驻 GPU 内存。推理时最好使用 Unsloth，因为它最多可实现 **快约 3 倍** 通过在 llama.cpp 之上优化，相比其他专注于 CPU/VRAM/n-gram 的仓库，可让 DeepSeek-V4.1 推理更快。

1 位 `UD-IQ1_S` 可在 128GB RAM 的设备上运行，例如 MacBook、DGX Spark 或 RTX Spark，而 3 位 `UD-IQ3_XXS` 可在 256GB RAM 的设备上运行，例如 Mac Studio。

就像我们中的 PLE / n-gram 层一样 [Qwen3.8-Flash-Next](/docs/zh/mo-xing/qwen3.8-next.md) 指南中，Engram 的 110.6–202.8 GB 表可以通过 mmap 保留在 SSD 上。行会按需加载到 OS 缓存中，在保留完整磁盘需求的同时节省 RAM/VRAM。

#### **DeepSeek-V4.1-Flash-1017 需求：**

**表：硬件需求** （RAM + VRAM，或统一内存；Engram 位于 SSD 上）。

| 1 位        | 2 位        | 3 位        | 4 位    | 8 位    |
| ---------- | ---------- | ---------- | ------ | ------ |
| 128–145 GB | 176–205 GB | 256–290 GB | 305 GB | 315 GB |

估算值比非 Engram 权重大约多预留 5–10 GB。运行时和上下文可能需要更多。

**n-gram 存储：** 查找格式和权重大小如下所示。剩余 GB 是所需 RAM/VRAM 的绝对最小值。

| 量化           | N-gram 格式 / GB  | 剩余 GB |
| ------------ | --------------- | ----- |
| UD-IQ1\_S    | IQ4\_NL / 110.6 | 122.4 |
| UD-IQ1\_M    | IQ4\_NL / 110.6 | 139.8 |
| UD-IQ2\_XXS  | Q5\_K / 135.2   | 165.3 |
| UD-Q2\_K\_XL | Q5\_K / 135.2   | 199.6 |
| UD-IQ3\_XXS  | Q6\_K / 161.3   | 233.5 |
| UD-IQ3\_S    | Q6\_K / 161.3   | 262.3 |
| UD-Q3\_K\_XL | MXFP8 / 202.8   | 282.3 |
| UD-Q4\_K\_XL | MXFP8 / 202.8   | 297.9 |
| UD-Q8\_K\_XL | MXFP8 / 202.8   | 305.6 |

### 推荐设置

DeepSeek 建议将 temperature = 1.0、top-p = 1.0，并禁用 top-k 和 min-p：

| 参数            | 设置                 |
| ------------- | ------------------ |
| `temperature` | `1.0`              |
| `top_p`       | `1.0`              |
| 最大上下文窗口       | `1,048,576` tokens |

DeepSeek 建议允许 **至少 256K 个输出 tokens** 用于其长文本生成配置。

### 📊 量化分析

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FZbUjhpI7wJTjf3pM1uwu%2Fsize_vs_top1(1).png?alt=media&amp;token=4e133008-8026-4e93-baa7-d7f2e2b81ecc" alt=""><figcaption></figcaption></figure>

结果与 DeepSeek 在 wiki1100 和 long17k 上的官方参考进行比较。KL 越低表示下一 token 概率越接近；top-1 越高表示匹配预测越多。

DeepSeek 混合使用 **MXFP4**、FP8 和 BF16。Q4 和 Q8 保留 **MXFP4** 专家层和相同的 Engram 表；其标签并不描述每个张量的精度。Q4 将许多非专家权重存储为 Q8\_0；Q8 使用 BF16。

我们还展示了将 engram 精度从 IQ4\_NL 更改为 Q5\_K、Q6\_K 和 MXFP8 时的情况，并提供 **独立的 engram，方便你自由混搭。**

| 量化           | 总大小      | wiki1100 KL / top-1 | long17k KL / top-1 |
| ------------ | -------- | ------------------- | ------------------ |
| UD-IQ1\_S    | 233.0 GB | 0.457 / 82.8%       | 0.364 / 85.1%      |
| UD-IQ1\_M    | 250.4 GB | 0.314 / 87.1%       | 0.241 / 88.2%      |
| UD-IQ2\_XXS  | 300.5 GB | 0.203 / 90.5%       | 0.142 / 91.2%      |
| UD-Q2\_K\_XL | 334.8 GB | 0.138 / 91.5%       | 0.0879 / 93.3%     |
| UD-IQ3\_XXS  | 394.7 GB | 0.0625 / 94.6%      | 0.043 / 95.1%      |
| UD-IQ3\_S    | 423.6 GB | 0.0316 / 96.0%      | 0.0195 / 96.8%     |
| UD-Q3\_K\_XL | 485.1 GB | 0.0204 / 96.5%      | 0.0114 / 97.4%     |
| UD-Q4\_K\_XL | 500.7 GB | 9.00e-03 / 98.2%    | 4.46e-03 / 98.5%   |
| UD-Q8\_K\_XL | 508.4 GB | 4.76e-03 / 98.5%    | 2.81e-03 / 98.7%   |

**选择量化：** IQ1\_S 相比 Q8 可节省约 54% 的磁盘空间。IQ1\_M 额外增加 17.4 GB，并将 wiki1100 上的 top-1 一致率提高 4.3 个百分点，在 long17k 上提高 3.1 个百分点。IQ3 变体可达到 94.6–96.8% 的一致率。

#### **思考强度**

默认启用思考，使用 `reasoning_effort=75` （“高”）。你可以设置一个介于 **1 到 100**之间的整数。数值越高，模型会进行更充分的推理；这并不是 token 上限。所含模板也接受 `低` = 50, `中` = 62, `高` = 75 和 `最大` = 100.

例如，将以下任一选项添加到你的启动命令中：

```bash
# 默认思考强度
--chat-template-kwargs '{"reasoning_effort":75}'

# 最大思考强度
--chat-template-kwargs '{"reasoning_effort":100}'

# 禁用思考
--chat-template-kwargs '{"enable_thinking":false}'
```

## 运行 **DeepSeek-V4.1-Flash-1017** 教程：

在本教程中，我们使用 `UD-Q2_K_XL`。Unsloth 会自动选择接近最优的 DeepSeek-V4.1 卸载、ngram 等配置，确保你的设置获得尽可能接近最佳的速度。

### 🦥 Unsloth 指南

[Unsloth Desktop](https://unsloth.ai/docs/desktop) 是我们面向 macOS、Windows 和 Linux 的本地 AI 开源界面。你可以在一个应用中搜索并下载 GGUF、配置 CPU 和 GPU 卸载、调整推理设置并连接工具。

{% stepper %}
{% step %}

#### 安装 Unsloth

最简单的开始方式是下载 [Unsloth Desktop 应用](/docs/zh/desktop.md)。适用于 [macOS](/docs/zh/kuai-su-kai-shi/install/mac.md), [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md)，以及 [Linux](/docs/zh/kuai-su-kai-shi/install/linux.md).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <i class="fa-apple">:apple:</i> [下载适用于 macOS 的版本](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载适用于 Windows 的版本](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载适用于 Linux 的版本](https://unsloth.ai/download/linux)

或者，如果你更喜欢手动安装：

{% tabs %}
{% tab title="本地安装" %}
**MacOS、Linux、WSL：**

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

**Windows：**

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

{% endtab %}

{% tab title="Docker" %}
该 [Unsloth Docker 镜像](https://hub.docker.com/r/unsloth/unsloth) `unsloth/unsloth` 可在 Docker 上获取。 [阅读指南。](https://unsloth.ai/docs/get-started/install/docker)
{% endtab %}

{% tab title="Homebrew" %}
安装 Unsloth Desktop：

{% code collapsedlinecount="10" %}

```bash
brew install --cask unsloth
```

{% endcode %}

更新 Unsloth Desktop：

```bash
brew upgrade --cask unsloth
```

{% endtab %}

{% tab title="WinGet" %}
安装 Unsloth Desktop：

```powershell
winget install --id UnslothAI.Unsloth -e
```

更新 Unsloth Desktop：

```powershell
winget upgrade --id UnslothAI.Unsloth -e
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### 搜索并下载 DeepSeek-V4.1-Flash-1017

前往 [Unsloth Chat](/docs/zh/xin/studio/chat.md) 或 Model hub，搜索 **DeepSeek-V4.1-Flash-1017** 并选择 [unsloth/DeepSeek-V4.1-Flash-1017-GGUF](https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF)。根据上面的大小和内存需求下载你想要的量化版本。
{% endstep %}

{% step %}

#### 运行 DeepSeek-V4.1-Flash-1017

默认启用思考，使用 `75`，你可以在我们的开关中更改。Unsloth 会自动选择接近最优的 DeepSeek-V4.1 卸载、ngram 等配置，确保你的设置获得尽可能接近最佳的速度。

更多信息请查看我们的 [Unsloth 推理指南](/docs/zh/xin/studio/chat.md).

使用 UD-IQ1\_S 时，233.0 GB 下载包含一个 110.6 GB 的 Engram n-gram 表和 122.4 GB 的其他权重。使用按需加载的 Engram 将查找表保留在 SSD 上，同时为缓存行、上下文和运行时缓冲区预留额外的 RAM/VRAM。请按照上面的使用指南了解内存需求。
{% endstep %}

{% step %}

#### 使用 Unsloth API 提供 DeepSeek-V4.1-Flash-1017 服务

你可以使用 `unsloth run` 命令，并通过 API 提供 DeepSeek-V4.1-Flash-1017 服务，使用 `llama-server` 运行时参数，包括上下文大小、GPU 层数、线程、采样、网络和工具配置。更多信息请参见我们的 [API 文档](/docs/zh/ji-chu-zhi-shi/api.md) 或者 [unsloth start](/docs/zh/ji-cheng/unsloth-start.md).

{% code overflow="wrap" %}

```bash
unsloth run --model unsloth/DeepSeek-V4.1-Flash-1017-GGUF:UD-Q2_K_XL \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --min-p 0.0 \\
    --chat-template-kwargs '{"reasoning_effort":75}'
```

{% endcode %}

使用支持 DeepSeek-V4.1-1017 和 Engram 按需加载的运行时。将 n-gram 表保留在磁盘上时，请应用使用指南中的 SSD 卸载和内存设置。
{% endstep %}

{% step %}

#### Unsloth 现在已就绪

你可以通过 Unsloth Desktop 将 DeepSeek-V4.1-Flash-1017 连接到你的工具。Unsloth 还支持以下工作流：

* **连接工具：** [Claude Code](/docs/zh/ji-chu-zhi-shi/claude-code.md), [Codex](/docs/zh/ji-chu-zhi-shi/codex.md), [网页搜索](/docs/zh/xin/studio/chat.md#advanced-web-search), [MCP](/docs/zh/ji-chu-zhi-shi/mcp.md) 以及更多
* **训练模型：** 微调其他受支持的文本、扩散、 [embedding](/docs/zh/ji-chu-zhi-shi/embedding-finetuning.md)，以及更多
* **生成媒体：** 创建并训练 [图像](/docs/zh/ji-chu-zhi-shi/diffusion-image.md)、视频、 [TTS](/docs/zh/ji-chu-zhi-shi/text-to-speech-tts-fine-tuning.md) 在本地

<div align="center"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FYShiiub5gs5pCQLX6d4U%2FScreenshot%202026-08-15%20at%2012.18.24%E2%80%AFAM.png?alt=media&amp;token=d6996797-a144-4113-b4c3-155cca6c39a0" alt="Unsloth Desktop Agents settings interface example" width="563"><figcaption><p>Unsloth Desktop 的 Agents 设置（界面示例）。连接工具时，请选择 DeepSeek-V4.1-Flash-1017 和你下载的量化版本。</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 在 llama.cpp 中运行 DeepSeek-V4.1-Flash

{% stepper %}
{% step %}
我们需要使用我们特定的 llama.cpp PR [这里](https://github.com/ggml-org/llama.cpp/pull/30817)。你也可以按照下面的构建说明进行。将 `-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 git -y
git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/30817/head:deepseek41
git -C llama.cpp checkout deepseek41
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 %}
要运行模型，你可以这样做：

```bash
pip install -U "huggingface_hub[cli]"
hf download unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
    --local-dir unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
    --include "*UD-Q2_K_XL*"
```

将全部七个分片保留在同一文件夹中，并将 `--model` 指向第一个分片。llama.cpp 会自动加载其余分片。
{% endstep %}

{% step %}
然后运行：

```bash
./llama.cpp/llama-cli \\
    --model unsloth/DeepSeek-V4.1-Flash-1017-GGUF/UD-Q2_K_XL/DeepSeek-V4.1-Flash-1017-UD-Q2_K_XL-00001-of-00007.gguf \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --top-k 0 \\
    --min-p 0.0 \\
    --chat-template-kwargs '{"reasoning_effort":75}' \\
    --load-mode mmap \\
    --lazy-mode on \\
    --override-tensor "per_layer_token_embd.weight=CPU"
```

此示例会按需从 SSD 加载 Engram n-gram 表。保持 `--load-mode mmap` 和 `--lazy-mode on` 启用以进行 SSD 卸载。
{% endstep %}
{% endstepper %}

### ⚡**DSpark** - 推测解码

DeepSeek-V4.1 包含 **DSpark**DSpark，这是一种在主模型验证之前提出多个 token 的推测解码架构。它与 Engram n-gram 查找表是分开的： **Engram 提供学习到的记忆；DSpark 加速解码**。同名的 n-gram 预判解码选项也是另一项不同的功能。

对于 DSpark，请将主模型与匹配的 **V4.1-1017 drafter** 以及支持 DSpark 的运行时配对。请保持 drafter 与主 checkpoint 的版本一致，并为 drafter 预留额外内存。本指南中的 CLI 和服务器示例使用的是普通解码。

**DSpark 使 DeepSeek-V4.1-Flash-GGUF 的推理在解码上大约快 1.3 到 1.5 倍！**

我们提供一个 8GB 的 Q8\_0 DSpark 模块，以及一个 8.5GB 的完整 BF16 模块。

### :checkered\_flag:Engram 的混搭

你也可以将 DeepSeek-V4.1 的 engram 精度更改为你想要的任何版本。

| Engram 精度 | 大小（GB）   |
| --------- | -------- |
| MXFP8（原始） | 202.8 GB |
| Q6\_K     | 161.3 GB |
| Q5\_K     | 135.2 GB |
| IQ4\_NL   | 110.6 GB |

例如，在下载默认使用 IQ4\_NL engram 的动态 1 位量化 IQ1\_S 后，你可以仅下载位于以下位置的 MXFP8 engram，将其替换为 MXFP8 版本： <https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF/tree/main/engram> 名为 `DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file` 要执行此操作，请按照下面的脚本：

```bash
# 1. 获取表 + 脚本
hf download unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
  --include "engram/*MXFP8*" "engram/set_split.py" --local-dir .

# 2. 将其标记为 5/5 分片（UD-IQ1_S 的表槽位）
python engram/set_split.py engram/DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file 5 5

# 3. 将旧表另存一边，然后把新表重命名为表分片的名称
mv UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00005-of-00005.gguf UD-IQ1_S/engram-IQ4_NL.bak
mv engram/DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file \\
   UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00005-of-00005.gguf

# 4. 照常运行
llama-server -m UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00001-of-00005.gguf
```

## 📊 基准测试

### **GGUF KLD 和 Top-1% 基准测试**

我们的量化版本在 wiki1100 上相较官方 F32 参考的 top-1 一致率为 82.8–98.5%，在 long17k 上为 85.1–98.7%。与 UD-Q8\_K\_XL 相比，UD-Q4\_K\_XL 节省 7.7 GB，在 wiki1100 上的一致率差距为 0.3 个百分点，在 long17k 上为 0.2 个百分点。Q8 在两个集合上的 KL 散度也更低。

**我们还将 engram 表精度从 IQ4\_NL 改为 Q5\_K、Q6\_K 和 MXFP8，并展示 KLD 受到了怎样的影响**

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FdIFvyiUQafZ2upn6VdhJ%2Fsize_vs_kld(1).png?alt=media&amp;token=e5d14eab-9143-4d0a-b1a6-f5427d995808" alt=""><figcaption></figcaption></figure>

### **官方基准**

DeepSeek 报告了以下针对 **V4.1-Flash-1017** 相较于之前的 V4.1-Flash 版本的结果。这些是官方模型结果，不是本指南中 GGUF 的测量结果。来源： [DeepSeek 的 1017 模型卡](https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash-1017).

| 基准                      | V4.1-Flash-1017 | V4.1-Flash   |
| ----------------------- | --------------- | ------------ |
| 无工具 HLE                 | 42.6 (44.0†)    | 36.8 (39.1†) |
| Terminal-Bench 4.0      | 42.3            | 31.2         |
| DeepSWE v1.1            | 77.0            | 74.2         |
| ProgramBench            | 29.1            | 20.3         |
| NL2Repo-Bench           | 68.2            | 65.4         |
| Automation-Bench v1.0.6 | 60.5            | 54.8         |
| Agents’ Last Exam       | 35.4            | 31.8         |
| Apex Bench v1.1         | 72.1            | 64.6         |
| Chartography（带工具）       | 83.0            | 78.9         |
| BabyVision（带工具）         | 92.5            | 89.6         |
| ZeroBench-main（带工具）     | 51.0            | 49.0         |

† HLE 的纯文本子集。DeepSeek 在 Terminal-Bench 4.0 中使用 Claude Code harness，在 DeepSWE v1.1 中使用 Mini-SWE-V2。分数取决于评估设置、推理强度和上下文预算。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.