# DeepSeek-V3.1: ローカル実行方法
DeepSeekのV3.1と **Terminus** アップデートでは、ハイブリッド推論推論が導入され、「think」と「non-think」を1つのモデルに統合しています。完全版の671Bパラメータモデルには715GBのディスク容量が必要です。量子化された動的2bit版では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/jp/ji-ben/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) より厳しいベンチマークをご希望とのことでしたので、Aider Polyglotの結果をご紹介します！当社の動的3bit DeepSeek V3.1 GGUFのスコアは **75.6%**で、多くのフル精度SOTA LLMを上回っています。 [続きを読む。](/docs/jp/ji-ben/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/jp/ji-ben/unsloth-dynamic-2.0-ggufs.md) SOTAの5-shot MMLUおよびKL Divergence性能向けであり、精度損失を最小限に抑えて量子化されたDeepSeek LLMを実行・ファインチューニングできます。
**チュートリアルのナビゲーション：**
llama.cpp で実行Ollama/Open WebUI で実行
## :gear: 推奨設定
1-bitの動的量子化TQ1\_0（重要でないMoE層は1bit、重要なMoEは2〜4bit、残りは6〜8bit）では170GBのディスク容量を使用します。これは **1x24GB カードと 128GB の RAM** とMoEオフロードを併用した場合によく機能し、また **Ollama でネイティブに動作します**!
{% hint style="info" %}
使用する必要があります `--jinja` llama.cpp の量子化版ではこれを使ってください。これは当社の [固定チャットテンプレート](#chat-template-bug-fixes) を使用し、正しいテンプレートを有効にします。使用しないと、誤った結果になる可能性があります `--jinja`
{% endhint %}
2-bit量子化版は、1×24GB GPU（MoE層をRAMへオフロードした場合）に収まります。この構成に加えて128GBのRAMがあれば、約5トークン/秒が期待できます。この2-bit版を実行するには少なくとも226GBのRAMを推奨します。最適な性能には、少なくとも226GBのユニファイドメモリ、または226GBのRAM+VRAM合計で5トークン/秒以上が必要です。生成速度を上げ、より長いコンテキストに対応する方法を学ぶには、 [こちらをお読みください](#improving-generation-speed).
{% hint style="success" %}
必須ではありませんが、最高の性能を得るには、VRAM + RAM の合計をダウンロードする量子化モデルのサイズと同じにしてください。そうでない場合でも、llama.cpp ではハードドライブ / SSD へのオフロードが動作しますが、推論速度は遅くなります。
{% endhint %}
## :butterfly:チャットテンプレートのバグ修正
llama.cppや他のエンジンで正しく動作しなかったため、DeepSeek V3.1のチャットテンプレートにいくつかの問題があったのを修正しました:
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｜>`
マルチターン用テンプレートは、非思考モードのマルチターンチャットテンプレートと同じです。つまり、最後のターンのthinkingトークンは削除されますが、 `` は各ターンのコンテキストに保持されます。
#### :bow\_and\_arrow: ツール呼び出し
ツール呼び出しは非思考モードでサポートされています。形式は次のとおりです:
`<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜>` ここで tool\_description を配置するのは system prompt の後ろの領域です。
## :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`を別の端末で呼び出せることに注意してください。修正内容と推奨パラメータ（temperature など）はすべて、Hugging Face のアップロード内の `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"
{% 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- `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": "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デバイス向けに特に高速に動作します。
| 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形式](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 レイヤーのみがオフロードされます。
これは最も少ない VRAM を使用します。 `正規表現をカスタマイズすることもできます。例えば` -ot "\\.(6|7|8|9|\[0-9]\[0-9]|\[0-9]\[0-9]\[0-9])\\.ffn\_(gate|up|down)\_exps.=CPU"
この [最新の 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 キャッシュを 4bit に量子化することもできます** たとえば、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/jp/moderu/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.