> 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/tutorials/deepseek-r1-0528-how-to-run-locally.md).

# DeepSeek-R1-0528：如何本地运行

关于如何在你自己的本地设备上运行包括 Qwen3 在内的 DeepSeek-R1-0528 的指南！

DeepSeek-R1-0528 是 DeepSeek 对其 R1 推理模型的新更新。完整的 671B 参数模型需要 715GB 磁盘空间。量化动态 **1.66 位** 版本仅需 162GB（体积减少 80%）。GGUF： [DeepSeek-R1-0528-GGUF](https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF)

DeepSeek 还通过微调 Qwen3（8B）发布了一个 R1-0528 蒸馏版本。该蒸馏版的性能与 Qwen3（235B）相近。 ***你也可以*** [***微调 Qwen3 蒸馏版***](#fine-tuning-deepseek-r1-0528-with-unsloth) ***使用 Unsloth***。Qwen3 GGUF： [DeepSeek-R1-0528-Qwen3-8B-GGUF](https://huggingface.co/unsloth/DeepSeek-R1-0528-Qwen3-8B-GGUF)

所有上传都使用 Unsloth [Dynamic 2.0](/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs.md) 适用于 SOTA 5-shot MMLU 和 KL 散度表现，这意味着你可以以极小的准确率损失运行并微调量化后的 DeepSeek LLM。

**教程导航：**

<a href="#run-qwen3-distilled-r1-in-llama.cpp" class="button secondary">在 llama.cpp 中运行</a><a href="#run-in-ollama-open-webui" class="button secondary">在 Ollama/Open WebUI 中运行</a><a href="#fine-tuning-deepseek-r1-0528-with-unsloth" class="button secondary">微调 R1-0528</a>

{% hint style="success" %}
新：工具调用和聊天模板修复方面有巨大改进。\
\
新 [TQ1\_0 动态 1.66 位量化](https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF?show_file_info=DeepSeek-R1-0528-UD-TQ1_0.gguf) - 体积为 162GB。非常适合 192GB 内存（包括 Mac）以及 Ollama 用户。试试： `ollama run hf.co/unsloth/DeepSeek-R1-0528-GGUF:TQ1_0`
{% endhint %}

## :gear: 推荐设置

对于 DeepSeek-R1-0528-Qwen3-8B，这个模型几乎可以适配任何配置，甚至只要 20GB 内存的设备也可以。事先无需任何准备。\
\
不过，对于体积为 715GB 的完整 R1-0528 模型，你需要额外准备。1.78 位（IQ1\_S）量化版可在 1 张 24GB GPU 上运行（所有层都卸载）。如果你还额外配有 128GB 内存，这套配置下的速度大约为 5 tokens/s。

建议至少有 64GB 内存来运行此量化版（没有 GPU 时你将获得 1 token/s）。要获得最佳性能，你至少需要 **180GB 统一内存或 180GB 的 RAM+VRAM 总和** 才能达到 5+ tokens/s。

我们建议使用 2.7 位（Q2\_K\_XL）或 2.4 位（IQ2\_XXS）量化版，在体积和精度之间取得平衡！2.4 位版本也表现很好。

{% hint style="success" %}
虽然不是必须，但为了获得最佳性能，请让你的 VRAM + RAM 总和 = 你下载的量化版本大小。
{% endhint %}

### 🐳 官方推荐设置：

根据 [DeepSeek](https://huggingface.co/deepseek-ai/DeepSeek-R1-0528)，以下是 R1（R1-0528 和 Qwen3 蒸馏版应使用相同设置）推理的推荐设置：

* 将 <mark style="background-color:green;">**temperature 0.6**</mark> 设为较低值，以减少重复和不连贯。
* 将 <mark style="background-color:green;">**top\_p 设为 0.95**</mark> （推荐）
* 运行多次测试并取平均结果，以获得可靠评估。

### :1234: 聊天模板/提示格式

R1-0528 使用与原始 R1 模型相同的聊天模板。你不需要强制 `<think>\n` ，但你仍然可以把它加上！

```
<｜begin▁of▁sentence｜><｜User｜>1+1 等于多少？<｜Assistant｜>是 2。<｜end▁of▁sentence｜><｜User｜>再解释一下！<｜Assistant｜>
```

会强制添加一个 BOS，并且 EOS 会分隔每次交互。为了在推理时抵消双 BOS token，你应该只调用 `tokenizer.encode(..., add_special_tokens = False)` 因为聊天模板也会自动添加 BOS 令牌。\
对于 llama.cpp / GGUF 推理，你应该跳过 BOS，因为它会自动添加：

```
<｜User｜>1+1 等于多少？<｜Assistant｜>
```

“ `<think>` 和 `</think>` 令牌会有各自专属的标记。

## 模型上传

**我们所有的上传** - 包括那些非 imatrix-based 或非动态的版本，都使用了我们的校准数据集，该数据集专门针对对话、编码和语言任务进行了优化。

* Qwen3（8B）蒸馏版： [DeepSeek-R1-0528-Qwen3-8B-GGUF](https://huggingface.co/unsloth/DeepSeek-R1-0528-Qwen3-8B-GGUF)
* 完整的 DeepSeek-R1-0528 模型上传如下：

我们还上传了 [IQ4\_NL](https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/IQ4_NL) 和 [Q4\_1](https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/Q4_1) 量化版本，它们分别专门针对 ARM 和 Apple 设备提供更快的运行速度。

<table data-full-width="false"><thead><tr><th>MoE 位数</th><th>类型 + 链接</th><th>磁盘大小</th><th>详情</th></tr></thead><tbody><tr><td>1.66bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF?show_file_info=DeepSeek-R1-0528-UD-TQ1_0.gguf">TQ1_0</a></td><td><strong>162GB</strong></td><td>1.92/1.56bit</td></tr><tr><td>1.78bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-IQ1_S">IQ1_S</a></td><td><strong>185GB</strong></td><td>2.06/1.56bit</td></tr><tr><td>1.93bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-IQ1_M">IQ1_M</a></td><td><strong>200GB</strong></td><td>2.5/2.06/1.56</td></tr><tr><td>2.42bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-IQ2_XXS">IQ2_XXS</a></td><td><strong>216GB</strong></td><td>2.5/2.06bit</td></tr><tr><td>2.71bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-Q2_K_XL">Q2_K_XL</a></td><td><strong>251GB</strong></td><td>3.5/2.5bit</td></tr><tr><td>3.12bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-IQ3_XXS">IQ3_XXS</a></td><td><strong>273GB</strong></td><td>3.5/2.06bit</td></tr><tr><td>3.5bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-Q3_K_XL">Q3_K_XL</a></td><td><strong>296GB</strong></td><td>4.5/3.5bit</td></tr><tr><td>4.5bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-Q4_K_XL">Q4_K_XL</a></td><td><strong>384GB</strong></td><td>5.5/4.5bit</td></tr><tr><td>5.5bit</td><td><a href="https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF/tree/main/UD-Q5_K_XL">Q5_K_XL</a></td><td><strong>481GB</strong></td><td>6.5/5.5bit</td></tr></tbody></table>

我们还上传了 [BF16 格式](https://huggingface.co/unsloth/DeepSeek-R1-0528-BF16)，以及原始 [FP8（float8）格式](https://huggingface.co/unsloth/DeepSeek-R1-0528).

## 运行 DeepSeek-R1-0528 教程：

### :llama: 在 Ollama/Open WebUI 中运行

1. 安装 `ollama` 如果你还没有的话！你只能运行大小不超过 32B 的模型。要运行完整的 720GB R1-0528 模型， [请看这里](#run-full-r1-0528-on-ollama-open-webui).

```bash
apt-get update
apt-get install pciutils -y
curl -fsSL https://ollama.com/install.sh | sh
```

2. 运行模型！注意，如果失败，你可以在另一个终端中调用 `ollama serve`！我们把所有修复和建议参数（温度等）都包含在 `params` 中，位于我们上传到 Hugging Face 的文件里！

```bash
ollama run hf.co/unsloth/DeepSeek-R1-0528-Qwen3-8B-GGUF:Q4_K_XL
```

3. <mark style="color:绿色;background-color:yellow;">**（新）要在 Ollama 中运行完整的 R1-0528 模型，你可以使用我们的 TQ1\_0（162GB 量化版）：**</mark>

```bash
OLLAMA_MODELS=unsloth_downloaded_models ollama serve &

ollama run hf.co/unsloth/DeepSeek-R1-0528-GGUF:TQ1_0
```

### :llama: 在 Ollama/Open WebUI 上运行完整 R1-0528

Open WebUI 已经制作了一个逐步教程，介绍如何在这里运行 R1；对于 R1-0528，你只需要把 R1 替换成新的 0528 量化版： <https://docs.openwebui.com/tutorials/integrations/llm-providers/deepseekr1-dynamic>

<mark style="background-color:green;">**（新）要在 Ollama 中运行完整的 R1-0528 模型，你可以使用我们的 TQ1\_0（162GB 量化版）：**</mark>

```bash
OLLAMA_MODELS=unsloth_downloaded_models ollama serve &

ollama run hf.co/unsloth/DeepSeek-R1-0528-GGUF:TQ1_0
```

如果你想在 Ollama 上使用任何比 TQ1\_0（162GB）更大的量化版本，你需要先把下面代码中的 3 个 GGUF 分片文件合并成 1 个。然后你需要在本地运行该模型。

```bash
./llama.cpp/llama-gguf-split --merge \\
  DeepSeek-R1-0528-GGUF/DeepSeek-R1-0528-UD-IQ1_S/DeepSeek-R1-0528-UD-IQ1_S-00001-of-00003.gguf \
	merged_file.gguf
```

### ✨ 在 llama.cpp 中运行 Qwen3 蒸馏版 R1

1. <mark style="background-color:yellow;">**要运行完整的 720GB R1-0528 模型，**</mark> [<mark style="background-color:yellow;">**请看这里**</mark>](#run-full-r1-0528-on-llama.cpp)<mark style="background-color:yellow;">**.**</mark> 获取最新的 `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 -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

2. 然后直接使用 llama.cpp 下载模型：

```bash
./llama.cpp/llama-cli -hf unsloth/DeepSeek-R1-0528-Qwen3-8B-GGUF:Q4_K_XL --jinja
```

### ✨ 在 llama.cpp 中运行完整 R1-0528

1. 获取最新的 `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 -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp
```

2. 如果你想使用 `llama.cpp` 直接加载模型的话，可以使用下面的命令：(:IQ1\_S) 是量化类型。你也可以通过 Hugging Face 下载（第 3 点）。这类似于 `ollama run` 。使用 `export LLAMA_CACHE="folder"` 来强制 `llama.cpp` 保存到特定位置。

{% hint style="success" %}
请试试 `-ot ".ffn_.*_exps.=CPU"` 将所有 MoE 层卸载到 CPU！这实际上让你可以把所有非 MoE 层放到 1 张 GPU 上，从而提升生成速度。如果你有更多 GPU 容量，还可以自定义正则表达式以容纳更多层。

如果你有更多一点 GPU 内存，可以尝试 `-ot ".ffn_(up|down)_exps.=CPU"` 这会卸载上投影和下投影 MoE 层。

尝试 `-ot ".ffn_(up)_exps.=CPU"` 如果你有更多 GPU 内存。这只会卸载上投影 MoE 层。

最后通过以下方式卸载所有层： `-ot ".ffn_.*_exps.=CPU"` 这会使用最少的 VRAM。

你也可以自定义正则表达式，例如 `-ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU"` 表示从第 6 层开始，只卸载 gate、up 和 down MoE 层。
{% endhint %}

```bash
export LLAMA_CACHE="unsloth/DeepSeek-R1-0528-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/DeepSeek-R1-0528-GGUF:IQ1_S \
    --cache-type-k q4_0 \
    --threads -1 \\
    --n-gpu-layers 99 \
    --prio 3 \
    --temp 0.6 \\
    --top-p 0.95 \\
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU"
```

3. 通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` 之后）。你可以选择 `UD-IQ1_S`（动态 1.78bit 量化）或其他量化版本，如 `Q4_K_M` . 我们 <mark style="background-color:green;">**建议使用我们的 2.7 位动态量化**</mark><mark style="background-color:green;">**&#x20;**</mark><mark style="background-color:green;">**`UD-Q2_K_XL`**</mark><mark style="background-color:green;">**&#x20;**</mark><mark style="background-color:green;">**以平衡体积和准确率**</mark>。更多版本见： <https://huggingface.co/unsloth/DeepSeek-R1-0528-GGUF>

{% code overflow="wrap" %}

```python
# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0" # 有时可能会触发速率限制，因此将其设为 0 以禁用
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/DeepSeek-R1-0528-GGUF",
    local_dir = "unsloth/DeepSeek-R1-0528-GGUF",
    allow_patterns = ["*UD-IQ1_S*"], # 动态 1bit（168GB）请对动态 2bit（251GB）使用 "*UD-Q2_K_XL*"
)
```

{% endcode %}

4. 按照我们在 DeepSeek R1 的 1.58bit 动态量化中描述的方法运行 Unsloth 的 Flappy Bird 测试。
5. 编辑 `--threads 32` CPU 线程数， `--ctx-size 16384` 用于上下文长度， `--n-gpu-layers 2` 用于 GPU 卸载的层数。如果你的 GPU 显存不足，请尝试调整它。如果你只使用 CPU 推理，也请将其移除。

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-cli \\
    --model unsloth/DeepSeek-R1-0528-GGUF/UD-IQ1_S/DeepSeek-R1-0528-UD-IQ1_S-00001-of-00004.gguf \
    --cache-type-k q4_0 \
    --threads -1 \\
    --n-gpu-layers 99 \
    --prio 3 \
    --temp 0.6 \\
    --top-p 0.95 \\
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU" \\
    -no-cnv \
    --prompt "<｜User｜>用 Python 创建一个 Flappy Bird 游戏。你必须包含以下内容：\n1. 你必须使用 pygame。\n2. 背景颜色应随机选择，并且是浅色。开始时使用浅蓝色。\n3. 多次按下 SPACE 键会让小鸟加速。\n4. 小鸟的形状应随机选择为正方形、圆形或三角形。颜色应随机选择为深色。\n5. 在底部放置一些随机选择为深棕色或黄色的土地。\n6. 在右上角显示分数。成功穿过管道且没有撞上时分数增加。\n7. 随机间距生成足够空隙的管道。颜色随机为深绿色、浅棕色或深灰色。\n8. 失败时，显示最高分。文本要放在屏幕内。按 q 或 Esc 退出游戏。重新开始按 SPACE 键。\n最终游戏应放在 Python 的 markdown 代码块中。在最终 markdown 代码块之前检查代码是否有错误并修正它们。<｜Assistant｜>"
```

{% endcode %}

## :8ball: 七边形测试

你也可以通过以下方式测试我们的动态量化版： [r/Localllama](https://www.reddit.com/r/LocalLLaMA/comments/1j7r47l/i_just_made_an_animation_of_a_ball_bouncing/) 来测试动态量化，该测试会考察模型创建一个基本物理引擎，以模拟球体在一个移动的封闭七边形形状中旋转。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-1371de5a93c6c5b0e43e8bb51980d84554b199f4%2Fsnapshot.jpg?alt=media" alt="" width="563"><figcaption><p>目标是让七边形旋转，而七边形中的球应该移动。</p></figcaption></figure>

<details>

<summary>运行模型的完整提示词</summary>

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-cli \\
    --model unsloth/DeepSeek-R1-0528-GGUF/UD-IQ1_S/DeepSeek-R1-0528-UD-IQ1_S-00001-of-00004.gguf \
    --cache-type-k q4_0 \
    --threads -1 \\
    --n-gpu-layers 99 \
    --prio 3 \
    --temp 0.6 \\
    --top_p 0.95 \
    --min_p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU" \\
    -no-cnv \
    --prompt "<｜User｜>编写一个 Python 程序，在旋转的七边形中显示 20 个弹跳的球：\n- 所有球的半径相同。\n- 所有球上都有 1 到 20 的编号。\n- 所有球在开始时都从七边形中心下落。\n- 颜色如下：#f8b862, #f6ad49, #f39800, #f08300, #ec6d51, #ee7948, #ed6d3d, #ec6800, #ec6800, #ee7800, #eb6238, #ea5506, #ea5506, #eb6101, #e49e61, #e45e32, #e17b34, #dd7a56, #db8449, #d66a35\n- 球应受到重力和摩擦影响，并且必须与旋转的墙壁真实地反弹。球与球之间也应发生碰撞。\n- 所有球的材质决定了它们的碰撞反弹高度不会超过七边形的半径，但要高于球半径。\n- 所有球都带有摩擦旋转，球上的数字可用于表示球的自旋。\n- 七边形绕其中心旋转，旋转速度为每 5 秒 360 度。\n- 七边形大小应足以容纳所有球。\n- 不要使用 pygame 库；请自行实现碰撞检测算法、碰撞响应等。允许使用以下 Python 库：tkinter、math、numpy、dataclasses、typing、sys。\n- 所有代码应放在一个 Python 文件中。<｜Assistant｜>"
```

{% endcode %}

</details>

## 🦥 使用 Unsloth 微调 DeepSeek-R1-0528

要微调 **DeepSeek-R1-0528-Qwen3-8B** 使用 Unsloth，我们制作了一个新的 GRPO notebook，其中包含一个自定义奖励函数，旨在显著增强多语言输出——特别是将期望语言回复的比例（在我们的示例中使用印尼语，但你可以使用任何语言）提高 40% 以上。

* [**DeepSeek-R1-0528-Qwen3-8B notebook**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/DeepSeek_R1_0528_Qwen3_\(8B\)_GRPO.ipynb) **- 新**

虽然许多推理类 LLM 都具备多语言能力，但它们在推理轨迹中常常会产生混合语言输出，将英语与目标语言混在一起。我们的奖励函数通过强烈鼓励以目标语言输出，有效缓解了这一问题，从而显著提升了语言一致性。

这个奖励函数也完全可定制，允许你将其适配到其他语言，或针对特定领域或用例进行微调。

{% hint style="success" %}
这个奖励函数和 notebook 最棒的一点是，你根本不需要语言数据集来强迫模型学习特定语言。这个 notebook 中没有印尼语数据集。
{% endhint %}

Unsloth 让 R1-Qwen3 蒸馏版微调速度提升 2 倍，显存使用减少 70%，并支持 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 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/tutorials/deepseek-r1-0528-how-to-run-locally.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.
