🐋DeepSeek-V3.1：如何本地运行

关于如何在您自己的本地设备上运行 DeepSeek-V3.1 和 Terminus 的指南！

DeepSeek 的 V3.1 和 终结者 更新引入了混合推理（hybrid reasoning）推断，将“思考”和“非思考”合并到一个模型中。完整的 671B 参数模型需要 715GB 的磁盘空间。量化的动态 2-bit 版本使用 245GB（大小减少 75%）。GGUF： DeepSeek-V3.1-GGUF

新： DeepSeek-V3.1-Terminus 现已发布： DeepSeek-V3.1-Terminus-GGUF 2025 年 9 月 10 日更新： 你们要求更严苛的基准测试，所以我们展示 Aider Polyglot 的结果！我们的动态 3-bit DeepSeek V3.1 GGUF 得分 75.6%，超过了许多全精度的 SOTA 大型语言模型。阅读更多。

我们的 DeepSeek-V3.1 GGUFs 包括 Unsloth 聊天模板修复用于 llama.cpp 支持的后端。

所有上传均使用 Unsloth Dynamic 2.0 用于 SOTA 的 5-shot MMLU 和 KL 散度性能，这意味着你可以以最小的精度损失运行并微调量化的 DeepSeek LLM。

教程导航：

在 llama.cpp 中运行在 Ollama/Open WebUI 中运行

⚙️ 推荐设置

1-bit 动态量化 TQ1_0（对不重要的 MoE 层为 1bit，重要的 MoE 为 2-4bit，其余为 6-8bit）使用 170GB 磁盘空间——这在一个 1x24GB 卡和 128GB 内存 中配合 MoE 卸载效果很好——它也 可以在 Ollama 中本地运行!

您必须使用 --jinja 来对 llama.cpp 的量化进行处理——这会使用我们的固定聊天模板并启用正确的模板！如果不使用，您可能会得到不正确的结果 --jinja

2-bit 量化可以适配 1x 24GB GPU（MoE 层卸载到内存）。如果你还有额外的 128GB 内存，使用此配置大约能达到每秒 5 个 token。推荐至少有 226GB 内存来运行此 2-bit。为了获得最佳性能，你需要至少 226GB 的统一内存或 226GB 的 RAM+VRAM 组合以达到每秒 5+ 个 token。要学习如何提高生成速度并容纳更长的上下文，在此阅读.

虽然不是必须，但为了最佳性能，建议 VRAM + RAM 的总和等于你正在下载的量化模型大小。如果不能，则使用硬盘/SSD 卸载在 llama.cpp 下也能工作，只是推理会更慢。

🦋聊天模板错误修复

我们修复了 DeepSeek V3.1 的几个聊天模板问题，因为它们在 llama.cpp 和其他引擎中无法正确工作：

DeepSeek V3.1 是一个混合推理模型，这意味着你可以更改聊天模板以启用推理。聊天模板引入了 thinking = True ，但其他模型使用 enable_thinking = True 。我们添加了使用 enable_thinking 作为关键字的选项。
llama.cpp 的 jinja 渲染器通过 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，以下是 V3.1 推理的推荐设置：

将 temperature 设为 0.6 以减少重复和不连贯性。
将 top_p 设为 0.95 （推荐）
128K 上下文长度 或更少
使用 --jinja 针对 llama.cpp 变体——我们 也修复了一些聊天模板问题！
使用 enable_thinking = True 以使用推理/思考模式。默认设置为非推理模式。

🔢 聊天模板/提示格式

你不需要强制使用 <think>\n ，但你仍然可以添加它！使用给定的前缀，DeepSeek V3.1 在非思考模式下生成对查询的响应。与 DeepSeek V3 不同，它引入了额外的令牌 </think>.

<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>

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

📔 非思考模式（使用 `thinking = False`或 `enable_thinking = False` ，且为默认）

首轮

前缀： <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>

使用给定的前缀，DeepSeek V3.1 在非思考模式下生成对查询的响应。与 DeepSeek V3 不同，它引入了额外的令牌 </think>.

多轮

上下文： <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>

前缀： <｜User｜>{query}<｜Assistant｜></think>

通过将上下文与前缀串联，我们得到针对该查询的正确提示。

📚 思考模式（使用 `thinking = True`或 `enable_thinking = True` ，且为默认）

首轮

前缀： <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜><think>

思考模式的前缀与 DeepSeek-R1 类似。

多轮

前缀： <｜User｜>{query}<｜Assistant｜><think>

多轮模板与非思考的多轮聊天模板相同。这意味着上一次回合中的思考令牌将被丢弃，但 </think> 在每一轮上下文中被保留。

🏹 工具调用

在非思考模式下支持工具调用。格式为：

<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜></think> 其中我们将 tool_description 放在系统提示之后的位置。

▶️运行 DeepSeek-V3.1 教程：

🦙 在 Ollama/Open WebUI 中运行

安装 ollama 如果您还没有安装！要运行更多模型变体，请参阅这里.

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

运行模型！注意如果失败，您可以在另一个终端中调用 ollama serve我们在 Hugging Face 上传中包含了所有修复和建议参数（如 temperature 等），位于 params 中！ （新）要在 Ollama 中运行完整的 R1-0528 模型，你可以使用我们的 TQ1_0（170GB 量化）：

OLLAMA_MODELS=unsloth ollama serve &

OLLAMA_MODELS=unsloth ollama run hf.co/unsloth/DeepSeek-V3.1-Terminus-GGUF:TQ1_0

要运行其他量化版本，您需要先将 GGUF 分割文件合并为一个，如下面代码所示。然后您需要在本地运行模型。

./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

OLLAMA_MODELS=unsloth ollama serve &

OLLAMA_MODELS=unsloth ollama run merged_file.gguf

Open WebUI 也制作了一个逐步教程关于如何运行 R1 的教程，对于 V3.1，你只需将 R1 替换为新的 V3.1 量化模型即可。

✨ 在 llama.cpp 中运行

获取最新的 llama.cpp 在此处的 GitHub。您也可以按照下面的构建说明进行。若 -DGGML_CUDA=ON 更改为 -DGGML_CUDA=OFF 如果您没有 GPU 或仅想要在 CPU 上进行推理。

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

如果您想直接使用 llama.cpp 来加载模型，您可以按下面操作：（:Q2_K_XL）是量化类型。您也可以通过 Hugging Face（第 3 点）下载。这与 ollama run 类似。使用 export LLAMA_CACHE="folder" 来强制 llama.cpp 将模型保存到指定位置。请记住该模型最大上下文长度仅为 128K。

请试用 -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 层。

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"

通过以下方式下载模型（在安装 pip install huggingface_hub hf_transfer 之后）。您可以选择 UD-Q2_K_XL（动态 2bit 量化）或其他量化版本如 Q4_K_M 。我们 建议使用我们的 2.7bit 动态量化 UD-Q2_K_XL 以在大小和准确性之间取得平衡.

# !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
)

您可以编辑 --threads 32 用于设置 CPU 线程数， --ctx-size 16384 用于上下文长度， --n-gpu-layers 2 用于指定将多少层卸载到 GPU。若 GPU 出现内存不足，请尝试调整它。若仅使用 CPU 推理，请移除此项。

./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"

如果你的合并 RAM 和 VRAM 不足，获取 1bit 版本（170GB）：

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
)

✨ 使用 llama-server 和 OpenAI 的完成（completion）库进行部署

要使用 llama-server 进行部署，请使用以下命令：

./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

然后在 pip install openai :

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)

💽模型上传

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

下面是完整的 DeepSeek-V3.1 模型上传：

我们也上传了 IQ4_NL 和 Q4_1 这些量化版本分别专为 ARM 和 Apple 设备优化，运行速度更快。

MoE 位数

类型 + 链接

磁盘大小

详情

1.66bit

TQ1_0

170GB

1.92/1.56bit

1.78bit

IQ1_S

185GB

2.06/1.56bit

1.93bit

IQ1_M

200GB

2.5/2.06/1.56

2.42bit

IQ2_XXS

216GB

2.5/2.06bit

2.71bit

Q2_K_XL

251GB

3.5/2.5bit

3.12bit

IQ3_XXS

273GB

3.5/2.06bit

3.5bit

Q3_K_XL

296GB

4.5/3.5bit

4.5bit

Q4_K_XL

384GB

5.5/4.5bit

5.5bit

Q5_K_XL

481GB

6.5/5.5bit

我们还上传了 BF16 格式，以及原始的 FP8（float8）格式.

🏂 "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 版本还引入了高吞吐量模式。使用 llama-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

上一页Qwen3-Next 下一页DeepSeek-R1-0528

最后更新于4天前

这有帮助吗？

hashtag⚙️ 推荐设置

hashtag🦋聊天模板错误修复

hashtag🐳 官方推荐设置

hashtag🔢 聊天模板/提示格式

hashtag📔 非思考模式（使用 thinking = False或 enable_thinking = False ，且为默认）

hashtag📚 思考模式（使用 thinking = True或 enable_thinking = True ，且为默认）

hashtag🏹 工具调用

hashtag▶️运行 DeepSeek-V3.1 教程：

hashtag🦙 在 Ollama/Open WebUI 中运行

hashtag✨ 在 llama.cpp 中运行

hashtag✨ 使用 llama-server 和 OpenAI 的完成（completion）库进行部署

hashtag💽模型上传

hashtag🏂 "content": [{"type": "text", "text": "用 Python 创建一个 Fibonacci 函数并求 fib(20)。"}],

hashtag例如以减少 VRAM / RAM 数据移动，这也可能使生成过程更快。

⚙️ 推荐设置

🦋聊天模板错误修复

🐳 官方推荐设置

🔢 聊天模板/提示格式

📔 非思考模式（使用 `thinking = False`或 `enable_thinking = False` ，且为默认）

📚 思考模式（使用 `thinking = True`或 `enable_thinking = True` ，且为默认）

🏹 工具调用

▶️运行 DeepSeek-V3.1 教程：

🦙 在 Ollama/Open WebUI 中运行

✨ 在 llama.cpp 中运行

✨ 使用 llama-server 和 OpenAI 的完成（completion）库进行部署

💽模型上传

🏂 "content": [{"type": "text", "text": "用 Python 创建一个 Fibonacci 函数并求 fib(20)。"}],

例如以减少 VRAM / RAM 数据移动，这也可能使生成过程更快。