# DeepSeek-V3.1：如何本地运行
DeepSeek 的 V3.1 和 **Terminus** 更新引入了混合推理推断，将“思考”和“非思考”合并到一个模型中。完整的 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 日更新：**](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) 你们想看更难的基准测试，所以我们展示 Aider Polyglot 结果！我们的动态 3-bit DeepSeek V3.1 GGUF 得分 **75.6%**，超过了许多全精度的 SOTA LLM。 [阅读更多。](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md)
我们的 DeepSeek-V3.1 GGUF 包含 Unsloth [聊天模板修复](#chat-template-bug-fixes) ，适用于 llama.cpp 支持的后端。
{% endhint %}
所有上传都使用 Unsloth [Dynamic 2.0](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs.md) 以获得 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 量化可以装进 1 块 24GB GPU（MoE 层卸载到 RAM）。如果你还有额外的 128GB RAM，这种设置下速度大约为 5 tokens/s。建议至少有 226GB RAM 来运行这个 2-bit 版本。为了获得最佳性能，你需要至少 226GB 统一内存，或 226GB 的 RAM+VRAM 总和，才能达到 5+ tokens/s。要了解如何提高生成速度并支持更长上下文， [请阅读这里](#improving-generation-speed).
{% hint style="success" %}
虽然不是必须的，但为了获得最佳性能，建议你的 VRAM + RAM 总和等于你下载的量化版本大小。如果不满足，使用 llama.cpp 也可以通过硬盘/SSD 卸载运行，只是推理会更慢。
{% 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 能正常运行而不会报错。\
\
在使用其他量化版本时，你会看到以下错误：\
`在抛出 'std::runtime_error' 的实例后调用 terminate：split method 必须有 1 到 1 个位置参数，以及 0 到 0 个关键字参数，位于第 3 行，第 1908 列` 我们已经在所有量化版本中修复了！
### 🐳官方推荐设置
根据 [DeepSeek](https://huggingface.co/deepseek-ai/DeepSeek-V3.1)，以下是 V3.1 推理的推荐设置：
* 将 **温度设为 0.6** 以减少重复和不连贯。
* 将 **top\_p 设为 0.95** （推荐）
* **128K 上下文长度** 或更少
* 使用 `--jinja` 用于 llama.cpp 变体——我们 **也修复了一些聊天模板问题！**
* **使用** `enable_thinking = True` 以使用推理/思考模式。默认情况下，它设置为非推理。
#### :1234: 聊天模板/提示格式
你不需要强制使用 `\n` ，但仍然可以加上！使用给定前缀时，DeepSeek V3.1 会以非思考模式对查询生成响应。与 DeepSeek V3 不同，它引入了一个额外的 token ``.
```
<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>
```
BOS 会被强制添加，而 EOS 会分隔每次交互。为了在推理时抵消双重 BOS token，你应只调用 `tokenizer.encode(..., add_special_tokens = False)` 因为聊天模板也会自动添加 BOS token。对于 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 不同，它引入了一个额外的 token ``.
**多轮**
上下文： `<｜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｜>`
多轮模板与非思考的多轮聊天模板相同。这意味着最后一轮中的 thinking token 会被丢弃，但 `` 会保留在上下文的每一轮中。
#### :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 分片文件合并成 1 个，就像下面的代码。然后你需要在本地运行模型。
```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/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 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 层放到 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-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；动态 1bit 请使用 "*UD-TQ1_0*"
)
```
{% 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*"], # 动态 2bit 请使用 "*UD-Q2_K_XL*"
)
```
{% 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 %}
然后在以下命令之后使用 OpenAI 的 Python 库 `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": "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: 提升生成速度
如果你有更多 VRAM，可以尝试卸载更多 MoE 层，或直接卸载整个层。
通常， `-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 "\.(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 缓存量化为 4bits** ，例如减少 VRAM / RAM 传输，这也可以加快生成过程。
## 📐如何适配长上下文（完整 128K）
要适配更长上下文，你可以使用 **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 缓存，但你需要 **通过以下方式编译带有 Flash Attention 支持的 llama.cpp** ： `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--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.