# DeepSeek-V3.1：如何本地运行
DeepSeek 的 V3.1 和 **终结者** 更新引入了混合推理（hybrid reasoning）推断，将“思考”和“非思考”合并到一个模型中。完整的 671B 参数模型需要 715GB 的磁盘空间。量化的动态 2-bit 版本使用 245GB（大小减少 75%）。GGUF： [**DeepSeek-V3.1-GGUF**](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF)
{% hint style="success" %}
**新：** DeepSeek-V3.1-Terminus 现已发布： [DeepSeek-V3.1-Terminus-GGUF](https://huggingface.co/unsloth/DeepSeek-V3.1-Terminus-GGUF)\
\
[**2025 年 9 月 10 日 更新：**](https://unsloth.ai/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot) 你们要求更严苛的基准测试，所以我们展示 Aider Polyglot 的结果！我们的动态 3-bit DeepSeek V3.1 GGUF 得分 **75.6%**，超过了许多全精度的 SOTA 大型语言模型。 [阅读更多。](https://unsloth.ai/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot)
我们的 DeepSeek-V3.1 GGUFs 包括 Unsloth [聊天模板修复](#chat-template-bug-fixes) 用于 llama.cpp 支持的后端。
{% endhint %}
所有上传均使用 Unsloth [Dynamic 2.0](https://unsloth.ai/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs) 用于 SOTA 的 5-shot MMLU 和 KL 散度性能，这意味着你可以以最小的精度损失运行并微调量化的 DeepSeek LLM。
**教程导航：**
在 llama.cpp 中运行在 Ollama/Open WebUI 中运行
## :gear: 推荐设置
1-bit 动态量化 TQ1\_0（对不重要的 MoE 层为 1bit，重要的 MoE 为 2-4bit，其余为 6-8bit）使用 170GB 磁盘空间——这在一个 **1x24GB 卡和 128GB 内存** 中配合 MoE 卸载效果很好——它也 **可以在 Ollama 中本地运行**!
{% hint style="info" %}
您必须使用 `--jinja` 来对 llama.cpp 的量化进行处理——这会使用我们的 [固定聊天模板](#chat-template-bug-fixes) 并启用正确的模板！如果不使用，您可能会得到不正确的结果 `--jinja`
{% endhint %}
2-bit 量化可以适配 1x 24GB GPU（MoE 层卸载到内存）。如果你还有额外的 128GB 内存，使用此配置大约能达到每秒 5 个 token。推荐至少有 226GB 内存来运行此 2-bit。为了获得最佳性能，你需要至少 226GB 的统一内存或 226GB 的 RAM+VRAM 组合以达到每秒 5+ 个 token。要学习如何提高生成速度并容纳更长的上下文， [在此阅读](#improving-generation-speed).
{% hint style="success" %}
虽然不是必须，但为了最佳性能，建议 VRAM + RAM 的总和等于你正在下载的量化模型大小。如果不能，则使用硬盘/SSD 卸载在 llama.cpp 下也能工作，只是推理会更慢。
{% endhint %}
## :butterfly:聊天模板错误修复
我们修复了 DeepSeek V3.1 的几个聊天模板问题，因为它们在 llama.cpp 和其他引擎中无法正确工作：
1. DeepSeek V3.1 是一个混合推理模型，这意味着你可以更改聊天模板以启用推理。聊天模板引入了 `thinking = True` ，但其他模型使用 `enable_thinking = True` 。我们添加了使用 `enable_thinking` 作为关键字的选项。
2. llama.cpp 的 jinja 渲染器通过 [minja](https://github.com/google/minja) 不允许在 `.split()` 命令中使用额外的参数，因此在 `.split(text, 1)` 在 Python 中可行，但在 minja 中不可行。我们不得不更改此项以使 llama.cpp 正常工作而不会报错。\
\
当使用其他量化版本时，你会遇到以下错误：\
`terminate called after throwing an instance of 'std::runtime_error' what(): split method must have between 1 and 1 positional arguments and between 0 and 0 keyword arguments at row 3, column 1908` 我们在所有量化版本中都修复了它！
### 🐳 官方推荐设置
根据 [DeepSeek](https://huggingface.co/deepseek-ai/DeepSeek-V3.1)，以下是 V3.1 推理的推荐设置：
* 将 **temperature 设为 0.6** 以减少重复和不连贯性。
* 将 **top\_p 设为 0.95** （推荐）
* **128K 上下文长度** 或更少
* 使用 `--jinja` 针对 llama.cpp 变体——我们 **也修复了一些聊天模板问题！**
* **使用** `enable_thinking = True` 以使用推理/思考模式。默认设置为非推理模式。
#### :1234: 聊天模板/提示格式
你不需要强制使用 `\n` ，但你仍然可以添加它！使用给定的前缀，DeepSeek V3.1 在非思考模式下生成对查询的响应。与 DeepSeek V3 不同，它引入了额外的令牌 ``.
```
<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>
```
会强制添加一个 BOS，并且每次交互由一个 EOS 分隔。为了在推理期间对抗双重 BOS 令牌，你应该只调用 `tokenizer.encode(..., add_special_tokens = False)` 因为聊天模板会自动添加一个 BOS 令牌。对于 llama.cpp / GGUF 推理，你应该跳过 BOS，因为它会自动添加。
#### :notebook\_with\_decorative\_cover: 非思考模式（使用 `thinking = False`或 `enable_thinking = False` ，且为默认）
**首轮**
前缀： `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>`
使用给定的前缀，DeepSeek V3.1 在非思考模式下生成对查询的响应。与 DeepSeek V3 不同，它引入了额外的令牌 ``.
**多轮**
上下文： `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>`
前缀： `<｜User｜>{query}<｜Assistant｜>`
通过将上下文与前缀串联，我们得到针对该查询的正确提示。
#### :books: 思考模式（使用 `thinking = True`或 `enable_thinking = True` ，且为默认）
**首轮**
前缀： `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>`
思考模式的前缀与 DeepSeek-R1 类似。
**多轮**
上下文： `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>`
前缀： `<｜User｜>{query}<｜Assistant｜>`
多轮模板与非思考的多轮聊天模板相同。这意味着上一次回合中的思考令牌将被丢弃，但 `` 在每一轮上下文中被保留。
#### :bow\_and\_arrow: 工具调用
在非思考模式下支持工具调用。格式为：
`<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜>` 其中我们将 tool\_description 放在系统提示之后的位置。
## :arrow\_forward:运行 DeepSeek-V3.1 教程：
### :llama: 在 Ollama/Open WebUI 中运行
{% stepper %}
{% step %}
安装 `ollama` 如果您还没有安装！要运行更多模型变体， [请参阅这里](#run-in-llama.cpp).
```bash
apt-get update
apt-get install pciutils -y
curl -fsSL https://ollama.com/install.sh | sh
```
{% endstep %}
{% step %}
运行模型！注意如果失败，您可以在另一个终端中调用 `ollama serve`我们在 Hugging Face 上传中包含了所有修复和建议参数（如 temperature 等），位于 `params` 中！\
\&#xNAN;**（新）要在 Ollama 中运行完整的 R1-0528 模型，你可以使用我们的 TQ1\_0（170GB 量化）：**
```bash
OLLAMA_MODELS=unsloth ollama serve &
OLLAMA_MODELS=unsloth ollama run hf.co/unsloth/DeepSeek-V3.1-Terminus-GGUF:TQ1_0
```
{% endstep %}
{% step %}
要运行其他量化版本，您需要先将 GGUF 分割文件合并为一个，如下面代码所示。然后您需要在本地运行模型。
```bash
./llama.cpp/llama-gguf-split --merge \
DeepSeek-V3.1-Terminus-GGUF/DeepSeek-V3.1-Terminus-UD-Q2_K_XL/DeepSeek-V3.1-Terminus-UD-Q2_K_XL-00001-of-00006.gguf \
merged_file.gguf
```
```bash
OLLAMA_MODELS=unsloth ollama serve &
OLLAMA_MODELS=unsloth ollama run merged_file.gguf
```
{% endstep %}
{% step %}
Open WebUI 也制作了一个 [逐步教程](https://docs.openwebui.com/tutorials/integrations/deepseekr1-dynamic/) 关于如何运行 R1 的教程，对于 V3.1，你只需将 R1 替换为新的 V3.1 量化模型即可。
{% endstep %}
{% endstepper %}
### ✨ 在 llama.cpp 中运行
{% stepper %}
{% step %}
获取最新的 `llama.cpp` 在 [此处的 GitHub](https://github.com/ggml-org/llama.cpp)。您也可以按照下面的构建说明进行。若 `-DGGML_CUDA=ON` 更改为 `-DGGML_CUDA=OFF` 如果您没有 GPU 或仅想要在 CPU 上进行推理。
```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggerganov/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 llama-server
cp llama.cpp/build/bin/llama-* llama.cpp
```
{% endstep %}
{% step %}
如果您想直接使用 `llama.cpp` 来加载模型，您可以按下面操作：（:Q2\_K\_XL）是量化类型。您也可以通过 Hugging Face（第 3 点）下载。这与 `ollama run` 类似。使用 `export LLAMA_CACHE="folder"` 来强制 `llama.cpp` 将模型保存到指定位置。请记住该模型最大上下文长度仅为 128K。
{% hint style="success" %}
请试用 `-ot ".ffn_.*_exps.=CPU"` 将所有 MoE 层卸载到 CPU！这实际上允许您将所有非 MoE 层放在一块 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-V3.1-GGUF"
./llama.cpp/llama-cli \
-hf unsloth/DeepSeek-V3.1-Terminus-GGUF:UD-Q2_K_XL \
--jinja \
--n-gpu-layers 99 \
--temp 0.6 \
--top-p 0.95 \
--min-p 0.01 \
--ctx-size 16384 \
--seed 3407 \
-ot ".ffn_.*_exps.=CPU"
```
{% endstep %}
{% step %}
通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` 之后）。您可以选择 `UD-`Q2\_K\_XL（动态 2bit 量化）或其他量化版本如 `Q4_K_M` 。我们 **建议使用我们的 2.7bit 动态量化**** ****`UD-Q2_K_XL`**** ****以在大小和准确性之间取得平衡**.
```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-V3.1-Terminus-GGUF",
local_dir = "unsloth/DeepSeek-V3.1-Terminus-GGUF",
allow_patterns = ["*UD-Q2_K_XL*"], # 动态 2bit 使用 "*UD-TQ1_0*" 表示 动态 1bit
)
```
{% endstep %}
{% step %}
您可以编辑 `--threads 32` 用于设置 CPU 线程数， `--ctx-size 16384` 用于上下文长度， `--n-gpu-layers 2` 用于指定将多少层卸载到 GPU。若 GPU 出现内存不足，请尝试调整它。若仅使用 CPU 推理，请移除此项。
{% code overflow="wrap" %}
```bash
./llama.cpp/llama-cli \
--model unsloth/DeepSeek-V3.1-Terminus-GGUF/UD-Q2_K_XL/DeepSeek-V3.1-Terminus-UD-Q2_K_XL-00001-of-00006.gguf \
--jinja \
--n-gpu-layers 99 \
--temp 0.6 \
--top-p 0.95 \
--min-p 0.01 \
--ctx-size 16384 \
--seed 3407 \
-ot ".ffn_.*_exps.=CPU"
```
{% endcode %}
{% endstep %}
{% step %}
如果你的合并 RAM 和 VRAM 不足，获取 1bit 版本（170GB）：
```python
from huggingface_hub import snapshot_download
snapshot_download(
repo_id = "unsloth/DeepSeek-V3.1-Terminus-GGUF",
local_dir = "unsloth/DeepSeek-V3.1-Terminus-GGUF",
allow_patterns = ["*UD-TQ1_0*"], # 使用 "*UD-Q2_K_XL*" 表示 动态 2bit
)
```
{% endstep %}
{% endstepper %}
### ✨ 使用 llama-server 和 OpenAI 的完成（completion）库进行部署
要使用 llama-server 进行部署，请使用以下命令：
{% code overflow="wrap" %}
```bash
./llama.cpp/llama-server \
--model unsloth/DeepSeek-V3.1-Terminus-GGUF/DeepSeek-V3.1-Terminus-UD-TQ1_0.gguf \
--alias "unsloth/DeepSeek-V3.1-Terminus" \
--n-gpu-layers 999 \
-ot ".ffn_.*_exps.=CPU" \
--prio 3 \
--min_p 0.01 \
--ctx-size 16384 \
--port 8001 \
--jinja
```
{% endcode %}
然后在 `pip install openai` :
```python
from openai import OpenAI
import json
openai_client = OpenAI(
base_url = "http://127.0.0.1:8001/v1",
api_key = "sk-no-key-required",
)
completion = openai_client.chat.completions.create(
model = "unsloth/DeepSeek-V3.1-Terminus",
messages = [{"role": "user", "content": "What is 2+2?"},],
)
print(completion.choices[0].message.content)
```
## :minidisc:模型上传
**我们所有的上传** - 包括那些不是基于 imatrix 或 动态 的版本，均使用我们的校准数据集，该数据集专门为对话、编码和语言任务进行了优化。
* 下面是完整的 DeepSeek-V3.1 模型上传：
我们也上传了 [IQ4\_NL](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF/tree/main/IQ4_NL) 和 [Q4\_1](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF/tree/main/Q4_1) 这些量化版本分别专为 ARM 和 Apple 设备优化，运行速度更快。
我们还上传了 [BF16 格式](https://huggingface.co/unsloth/DeepSeek-V3.1-BF16)，以及原始的 [FP8（float8）格式](https://huggingface.co/unsloth/DeepSeek-V3.1).
## :snowboarder: "content": \[{"type": "text", "text": "用 Python 创建一个 Fibonacci 函数并求 fib(20)。"}],
如果你有更多显存，可以尝试卸载更多 MoE 层，或将整个层本身卸载（offload）。
通常， `-ot ".ffn_.*_exps.=CPU"` 会将所有 MoE 层卸载到 CPU！这实际上允许你将所有非 MoE 层放在一块 GPU 上，从而提高生成速度。如果你有更多 GPU 容量，可以自定义正则表达式以适配更多层。
如果你有稍多的 GPU 内存，尝试 `-ot ".ffn_(up|down)_exps.=CPU"` 这会卸载上投影和下投影的 MoE 层。
尝试 `-ot ".ffn_(up)_exps.=CPU"` 如果你有更多的 GPU 内存。这只会卸载上投影的 MoE 层。
你也可以自定义正则表达式，例如 `-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 层。
最新的 [llama.cpp 版本](https://github.com/ggml-org/llama.cpp/pull/14363) 还引入了高吞吐量模式。使用 `llama-parallel`。在此处阅读更多内容 [这里](https://github.com/ggml-org/llama.cpp/tree/master/examples/parallel)。你也可以 **例如将 KV 缓存量化为 4 bit** 将 KV 缓存量化为 4 位
## 例如以减少 VRAM / RAM 数据移动，这也可能使生成过程更快。
要适配更长的上下文，你可以使用 **KV 缓存量化** 将 K 和 V 缓存量化到更低位数。这也可以由于减少 RAM / VRAM 数据移动而提高生成速度。K 量化的可用选项（默认是 `f16`）包括下列项。
`--cache-type-k f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1`
你应当使用那些 `_1` 变体以获得稍高的准确性，尽管速度会略慢。例如 `q4_1, q5_1`
你也可以对 V 缓存进行量化，但你需要 **在编译 llama.cpp 时启用 Flash Attention 支持** 通过 `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--flash-attn` --flash-attn `来启用它。然后您可以与` :
`--cache-type-k 一起使用 --cache-type-v f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1`
---
# 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/tutorials/deepseek-v3.1-how-to-run-locally.md?ask=
```
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.