🐋DeepSeek-V3.1: ローカル実行方法

DeepSeek-V3.1 と Terminus をご自身のローカル端末で実行する方法のガイド！

DeepSeek の V3.1 と Terminus アップデートでは、ハイブリッド推論推論が導入され、「think」と「non-think」を1つのモデルに統合しています。完全な 671B パラメータモデルには 715GB のディスク容量が必要です。量子化された動的 2 ビット版は 245GB（サイズを 75% 削減）です。GGUF: DeepSeek-V3.1-GGUF

NEW: DeepSeek-V3.1-Terminus が公開されました: DeepSeek-V3.1-Terminus-GGUF 2025年9月10日更新: より厳しいベンチマークを求める声に応えて、Aider Polyglot の結果を紹介します！ 当社の Dynamic 3-bit DeepSeek V3.1 GGUF は 75.6%を記録し、多くのフル精度 SOTA LLM を上回っています。 詳細はこちら。

当社の DeepSeek-V3.1 GGUF には、Unsloth の チャットテンプレート修正 が llama.cpp 対応バックエンド向けに含まれています。

すべてのアップロードでは Unsloth Dynamic 2.0 を使用しており、SOTA の 5-shot MMLU と KL Divergence 性能を実現しています。つまり、量子化された DeepSeek LLM を最小限の精度低下で実行およびファインチューニングできます。

チュートリアル ナビゲーション:

llama.cpp で実行Ollama/Open WebUI で実行

⚙️ 推奨設定

1 ビット動的量子化 TQ1_0（重要でない MoE 層は 1bit、重要な MoE は 2～4bit、残りは 6～8bit）は 170GB のディスク容量を使用します。これは 1x24GB カードと 128GB の RAM で、MoE オフロードと組み合わせてうまく動作します。また、 Ollama でもネイティブに動作します!

必ず --jinja を llama.cpp の量子化版で使用する必要があります。これにより当社の 修正済みチャットテンプレート が使われ、正しいテンプレートが有効になります！ 使用しない場合、誤った結果が出る可能性があります --jinja

2 ビット量子化版は 1x 24GB GPU に収まります（MoE 層は RAM にオフロード）。この構成で、さらに 128GB RAM があれば、およそ 5 トークン/秒が期待できます。この 2 ビット版を実行するには少なくとも 226GB RAM を推奨します。最適な性能のためには、少なくとも 226GB のユニファイドメモリ、または 226GB の RAM+VRAM 合計が必要で、5+ トークン/秒を見込めます。生成速度を上げ、より長いコンテキストを収める方法については、 こちらをお読みください.

必須ではありませんが、最良の性能のためには、VRAM + RAM の合計をダウンロードする量子化版のサイズと同じにしてください。そうでない場合でも、llama.cpp ではハードドライブ / SSD オフロードが機能しますが、推論は遅くなります。

🦋チャットテンプレートのバグ修正

DeepSeek V3.1 のチャットテンプレートには、llama.cpp や他のエンジンで正しく動作しない問題がいくつかあったため、修正しました:

1. DeepSeek V3.1 はハイブリッド推論モデルであり、チャットテンプレートを変更して推論を有効にできます。チャットテンプレートでは thinking = True が導入されましたが、他のモデルでは enable_thinking = True を使用します。そこで、 enable_thinking を代わりにキーワードとして使えるようにしました。

2. 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 これにより reasoning / thinking モードを使用できます。デフォルトでは非推論に設定されています。

🔢 チャットテンプレート / プロンプト形式

強制的に指定する必要はありません <think>\n 、ただし追加しても構いません！ 指定されたプレフィックスでは、DeepSeek V3.1 は non-thinking モードでクエリへの応答を生成します。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 は自動追加されるのでスキップしてください。

📔 Non-Thinking モード（ thinking = Falseまたは enable_thinking = False を使用し、これがデフォルトです）

最初のターン

プレフィックス: <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>

指定されたプレフィックスでは、DeepSeek V3.1 は non-thinking モードでクエリへの応答を生成します。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 モード（ thinking = Trueまたは enable_thinking = True を使用し、これがデフォルトです）

最初のターン

プレフィックス: <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜><think>

Thinking モードのプレフィックスは DeepSeek-R1 に似ています。

マルチターン

コンテキスト: <｜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>

マルチターンのテンプレートは non-thinking のマルチターン チャットテンプレートと同じです。これは、最後のターンの thinking トークンは削除されますが、 </think> はコンテキストの各ターンに保持されることを意味します。

🏹 ツール呼び出し

ツール呼び出しは non-thinking モードでサポートされています。形式は次の通りです:

<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜></think> ここで tool_description は system prompt の後の領域に挿入されます。

▶️DeepSeek-V3.1 実行チュートリアル:

🦙 Ollama/Open WebUI で実行

1

インストール ollama まだであれば先に行ってください！ モデルの他のバリアントを実行するには、 こちらをご覧ください.

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

2

モデルを実行します！ 失敗した場合は、別のターミナルで ollama serveを呼び出せることに注意してください！ 当社の修正と推奨パラメータ（temperature など）はすべて、 params として Hugging Face のアップロードに含めています！ （NEW）Ollama で DeepSeek-V3.1 モデルを使うには、当社の TQ1_0（170GB 量子化版）を使用できます:

OLLAMA_MODELS=unsloth ollama serve &

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

3

他の量子化版を実行するには、まず下記コードのように GGUF 分割ファイルを 1 つにマージする必要があります。その後、モデルをローカルで実行する必要があります。

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

4

Open WebUI も ステップバイステップのチュートリアル を作成しており、R1 の実行方法について説明しています。V3.1 では、R1 を新しい V3.1 量子化版に置き換えるだけで済みます。

✨ llama.cpp で実行

1

最新の 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/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

2

もし llama.cpp を使って直接モデルを読み込みたい場合は、以下を実行できます。（:Q2_K_XL）は量子化タイプです。Hugging Face 経由でのダウンロード（ポイント 3）も可能です。これは ollama run に似ています。 export LLAMA_CACHE="folder" を使って、 llama.cpp が特定の場所に保存するよう強制できます。モデルの最大コンテキスト長は 128K のみであることを覚えておいてください。

ぜひ試してください -ot ".ffn_.*_exps.=CPU" これはすべての MoE 層を CPU にオフロードします！ これにより、すべての非 MoE 層を 1 GPU に収められるようになり、生成速度が向上します。GPU 容量に余裕がある場合は、より多くの層に合わせて regex 式をカスタマイズできます。

GPU メモリにもう少し余裕があるなら、 -ot ".ffn_(up|down)_exps.=CPU" を試してください。これは up と down projection の MoE 層をオフロードします。

さらに GPU メモリに余裕があるなら、 -ot ".ffn_(up)_exps.=CPU" を試してください。これは up projection の MoE 層のみをオフロードします。

最後に、次を使ってすべての層をオフロードします -ot ".ffn_.*_exps.=CPU" これは最も少ない VRAM を使用します。

regex をカスタマイズすることもできます。たとえば、 -ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU" は、gate、up、down の MoE 層を、ただし 6 層目以降のみオフロードすることを意味します。

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"

3

（インストール後）次の方法でモデルをダウンロードします 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*"], # Dynamic 2bit Dynamic 1bit には "*UD-TQ1_0*" を使用
)

4

編集できます --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"

5

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*"], # Dynamic 2bit には "*UD-Q2_K_XL*" を使用
)

✨ 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 :

の後に OpenAI の Python ライブラリを使用します
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)

💽モデルのアップロード

当社のすべてのアップロード - imatrix ベースでないものや dynamic でないものを含め、会話、コーディング、言語タスク向けに特化して最適化された当社のキャリブレーション データセットを利用しています。

• 以下は完全な 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）形式.

🏂 生成速度の向上

VRAM に余裕がある場合は、より多くの MoE 層、または層全体そのものをオフロードしてみてください。

通常、 -ot ".ffn_.*_exps.=CPU" はすべての MoE 層を CPU にオフロードします！ これにより、すべての非 MoE 層を 1 GPU に収められるようになり、生成速度が向上します。GPU 容量に余裕がある場合は、より多くの層に合わせて regex 式をカスタマイズできます。

GPU メモリにもう少し余裕があるなら、 -ot ".ffn_(up|down)_exps.=CPU" を試してください。これは up と down projection の MoE 層をオフロードします。

さらに GPU メモリに余裕があるなら、 -ot ".ffn_(up)_exps.=CPU" を試してください。これは up projection の MoE 層のみをオフロードします。

regex をカスタマイズすることもできます。たとえば、 -ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU" は、gate、up、down の MoE 層を、ただし 6 層目以降のみオフロードすることを意味します。

その 最新の llama.cpp リリース では高スループット モードも導入されています。 llama-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