> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/jp/moderu/tutorials/deepseek-v3.1-how-to-run-locally.md). # 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**](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-chu/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) より厳しいベンチマークをご希望だったので、Aider Polyglot の結果をご紹介します！当社の Dynamic 3-bit DeepSeek V3.1 GGUF のスコアは **75.6%**、多くのフル精度 SOTA LLM を上回っています。 [詳細を見る。](/docs/jp/ji-chu/dynamic-3.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-chu/dynamic-3.0-ggufs.md) は、SOTA の 5-shot MMLU と KL Divergence の性能向けであり、量子化された DeepSeek LLM を精度損失を最小限に抑えて実行・ファインチューニングできることを意味します。 **チュートリアルナビゲーション:** llama.cpp で実行Ollama/Open WebUI で実行 ## :gear: 推奨設定 1ビット動的量子化 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ビット量子化版は 24GB GPU 1基に収まります（MoE レイヤーは RAM にオフロード）。さらに 128GB の RAM があれば、この構成で約 5 token/s が見込めます。この 2 ビット版を動かすには、少なくとも 226GB の RAM を推奨します。最適な性能には、5+ token/s を得るために少なくとも 226GB のユニファイドメモリ、または 226GB の RAM+VRAM 合計が必要です。生成速度の上げ方や、より長いコンテキストを収める方法については、 [こちらを読む](#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 がエラーを出さずに正しく機能するよう、これを変更する必要がありました。\n\n他の量子化版を使用すると、次のエラーが表示されます:\ `terminate called after throwing an instance of 'std::runtime_error' what(): split メソッドには 1 つから 1 つまでの位置引数と 0 つから 0 つまでのキーワード引数しか指定できません（3 行目、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 を埋め込むのは 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 など）はすべて `params` として Hugging Face のアップロードに含めています！\ **（NEW）Ollama で DeepSeek-V3.1 モデルを使うには、当社の 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"` を試してください。これは up と down の projection MoE 層をオフロードします。 試してみてください `-ot ".ffn_(up)_exps.=CPU"` GPU メモリがさらに多い場合はこちら。これは up projection の 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（dynamic 2bit quant）または次のような他の量子化版 `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 デバイスで特に高速に動作する量子化版です。
MoE ビット数種類 + リンクディスクサイズ詳細
1.66bitTQ1_0170GB1.92/1.56bit
1.78bitIQ1_S185GB2.06/1.56bit
1.93bitIQ1_M200GB2.5/2.06/1.56
2.42bitIQ2_XXS216GB2.5/2.06bit
2.71bitQ2_K_XL251GB3.5/2.5bit
3.12bitIQ3_XXS273GB3.5/2.06bit
3.5bitQ3_K_XL296GB4.5/3.5bit
4.5bitQ4_K_XL384GB5.5/4.5bit
5.5bitQ5_K_XL481GB6.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"` を試してください。これは up と down の projection MoE 層をオフロードします。 試してみてください `-ot ".ffn_(up)_exps.=CPU"` GPU メモリがさらに多い場合はこちら。これは up projection の MoE 層のみをオフロードします。 これは最も少ない 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 層をオフロードすることを意味します。 その [最新の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 のキャッシュをより低い bit に量子化できます。これにより、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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://unsloth.ai/docs/jp/moderu/tutorials/deepseek-v3.1-how-to-run-locally.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.