🐋DeepSeek-V3.1 : Comment exécuter localement

Un guide sur la façon d'exécuter DeepSeek-V3.1 et Terminus sur votre propre appareil local !

La V3.1 de DeepSeek et Terminus la mise à jour introduit un raisonnement hybride d'inférence, combinant « penser » et « non-penser » dans un seul modèle. Le modèle complet de 671 milliards de paramètres nécessite 715 Go d'espace disque. La version quantifiée dynamique 2 bits utilise 245 Go (-75 % de réduction de taille). GGUF : DeepSeek-V3.1-GGUF

NOUVEAU : DeepSeek-V3.1-Terminus disponible maintenant : DeepSeek-V3.1-Terminus-GGUF Mise à jour du 10 sept. 2025 : Vous avez demandé des benchmarks plus exigeants, nous présentons donc les résultats Aider Polyglot ! Nos scores DeepSeek V3.1 GGUF dynamiques en 3 bits 75.6%, dépassant de nombreux LLM SOTA en pleine précision. En savoir plus.

Nos GGUF DeepSeek-V3.1 incluent Unsloth corrections du template de chat pour les backends pris en charge par llama.cpp.

Tous les téléversements utilisent Unsloth Dynamic 2.0 pour des performances SOTA sur MMLU 5-shot et la divergence KL, ce qui signifie que vous pouvez exécuter et affiner des LLMs DeepSeek quantifiés avec une perte d'exactitude minimale.

Navigation des tutoriels :

Exécuter dans llama.cppExécuter dans Ollama/Open WebUI

⚙️ Paramètres recommandés

La quantification dynamique 1-bit TQ1_0 (1 bit pour les couches MoE peu importantes, 2–4 bits pour les MoE importantes, et 6–8 bits pour le reste) utilise 170 Go d'espace disque - cela fonctionne bien dans un une carte 1x24Go et 128 Go de RAM avec déchargement MoE - cela nativement dans Ollama!

Vous devez utiliser --jinja pour les quants llama.cpp - cela utilise nos modèles de chat fixes et active le bon modèle ! Vous pourriez obtenir des résultats incorrects si vous n'utilisez pas --jinja

Les quantifications 2 bits tiendront dans un GPU 1x 24 Go (avec les couches MoE déchargées en RAM). Attendez-vous à environ 5 tokens/s avec cette configuration si vous disposez également de 128 Go de RAM supplémentaires. Il est recommandé d'avoir au moins 226 Go de RAM pour exécuter ce 2 bits. Pour des performances optimales, vous aurez besoin d'au moins 226 Go de mémoire unifiée ou de 226 Go combinés RAM+VRAM pour 5+ tokens/s. Pour apprendre comment augmenter la vitesse de génération et prendre en charge des contextes plus longs, lisez ici.

Bien que ce ne soit pas indispensable, pour de meilleures performances, faites en sorte que la VRAM + la RAM combinées soit égale à la taille de la quantification que vous téléchargez. Sinon, le déchargement sur disque dur/SSD fonctionnera avec llama.cpp, seule l'inférence sera plus lente.

🦋Corrections de bugs du modèle de chat

Nous avons corrigé quelques problèmes avec le template de chat de DeepSeek V3.1 car ils ne fonctionnaient pas correctement dans llama.cpp et d'autres moteurs :

1. DeepSeek V3.1 est un modèle de raisonnement hybride, ce qui signifie que vous pouvez modifier le template de chat pour activer le raisonnement. Le template de chat introduisait thinking = True , mais d'autres modèles utilisent enable_thinking = True . Nous avons ajouté l'option d'utiliser enable_thinking comme mot-clé à la place.

2. le renderer jinja de llama.cpp via minja n'autorise pas l'utilisation d'arguments supplémentaires dans la .split() commande, donc utiliser .split(text, 1) fonctionne en Python, mais pas en minja. Nous avons dû changer cela pour que llama.cpp fonctionne correctement sans générer d'erreur. Vous obtiendrez l'erreur suivante lors de l'utilisation d'autres quants : 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 Nous l'avons corrigé dans tous nos quants !

🐳 Paramètres officiels recommandés

Selon DeepSeek, voici les paramètres recommandés pour l'inférence V3.1 :

• Réglez la température 0.6 pour réduire les répétitions et l'incohérence.

• Réglez top_p à 0,95 (recommandé)

• longueur de contexte 128K ou moins

• Utilisez --jinja pour les variantes llama.cpp - nous avons corrigé certains problèmes de modèles de chat aussi !

• Utilisez enable_thinking = True pour utiliser le mode raisonnement / penser. Par défaut, il est réglé sur non-raisonnement.

🔢 Format du template de chat / prompt

Vous n'avez pas besoin de forcer <think>\n , mais vous pouvez toujours l'ajouter ! Avec le préfixe donné, DeepSeek V3.1 génère des réponses aux requêtes en mode non-penser. Contrairement à DeepSeek V3, il introduit un token additionnel </think>.

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

Un BOS est ajouté de force, et un EOS sépare chaque interaction. Pour éviter les doubles jetons BOS lors de l'inférence, vous ne devriez appeler que tokenizer.encode(..., add_special_tokens = False) puisque le template de chat ajoute automatiquement aussi un token BOS. Pour l'inférence llama.cpp / GGUF, vous devez omettre le BOS car il l'ajoutera automatiquement.

📔 Mode Non-Penser (utiliser thinking = Falseou enable_thinking = False et est par défaut)

Premier tour

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

Avec le préfixe donné, DeepSeek V3.1 génère des réponses aux requêtes en mode non-penser. Contrairement à DeepSeek V3, il introduit un token additionnel </think>.

Multi-Tour

Contexte : <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>

Préfixe : <｜User｜>{query}<｜Assistant｜></think>

En concaténant le contexte et le préfixe, nous obtenons le prompt correct pour la requête.

📚 Mode Penser (utiliser thinking = Trueou enable_thinking = True et est par défaut)

Premier tour

Préfixe : <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜><think>

Le préfixe du mode penser est similaire à DeepSeek-R1.

Multi-Tour

Contexte : <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>

Préfixe : <｜User｜>{query}<｜Assistant｜><think>

Le template multi-tour est le même que le template multi-tour en mode non-penser. Cela signifie que le token penser du dernier tour sera supprimé mais le </think> est conservé à chaque tour du contexte.

🏹 Appel d'outil

L'appel d'outils est pris en charge en mode non-penser. Le format est :

<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜></think> où nous remplissons la zone tool_description après le system prompt.

▶️Exécuter les tutoriels DeepSeek-V3.1 :

🦙 Exécuter dans Ollama/Open WebUI

1

Installez ollama si vous ne l'avez pas encore fait ! Pour exécuter plus de variantes du modèle, voir ici.

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

2

Exécutez le modèle ! Notez que vous pouvez appeler ollama servedans un autre terminal s'il échoue ! Nous incluons toutes nos corrections et paramètres suggérés (température, etc.) dans params dans notre upload Hugging Face ! &#xNAN;(NOUVEAU) Pour exécuter le modèle complet R1-0528 dans Ollama, vous pouvez utiliser notre quant TQ1_0 (170 Go) :

OLLAMA_MODELS=unsloth ollama serve &

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

3

Pour exécuter d'autres quants, vous devez d'abord fusionner les fichiers GGUF divisés en 1 comme dans le code ci-dessous. Ensuite, vous devrez exécuter le modèle localement.

./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 a également réalisé un tutoriel étape par étape sur comment exécuter R1 et pour V3.1, vous aurez juste besoin de remplacer R1 par le nouveau quant V3.1.

✨ Exécuter dans llama.cpp

1

Obtenez le dernier llama.cpp sur GitHub ici. Vous pouvez suivre les instructions de compilation ci-dessous également. Changez -DGGML_CUDA=ON en -DGGML_CUDA=OFF si vous n'avez pas de GPU ou si vous voulez simplement une inférence 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

2

Si vous voulez utiliser llama.cpp directement pour charger des modèles, vous pouvez faire ce qui suit : (:Q2_K_XL) est le type de quantification. Vous pouvez aussi télécharger via Hugging Face (point 3). C'est similaire à ollama run . Utilisez export LLAMA_CACHE="folder" pour forcer llama.cpp à enregistrer dans un emplacement spécifique. Rappelez-vous que le modèle a seulement une longueur de contexte maximale de 128K.

Veuillez essayer -ot ".ffn_.*_exps.=CPU" pour décharger toutes les couches MoE vers le CPU ! Cela vous permet effectivement de faire tenir toutes les couches non-MoE sur 1 GPU, améliorant les vitesses de génération. Vous pouvez personnaliser l'expression regex pour décharger plus de couches si vous disposez de plus de capacité GPU.

Si vous avez un peu plus de mémoire GPU, essayez -ot ".ffn_(up|down)_exps.=CPU" Cela décharge les couches MoE de projection up et down.

Essayez -ot ".ffn_(up)_exps.=CPU" si vous avez encore plus de mémoire GPU. Cela ne décharge que les couches MoE de projection up.

Et enfin déchargez toutes les couches via -ot ".ffn_.*_exps.=CPU" Ceci utilise le moins de VRAM.

Vous pouvez aussi personnaliser le regex, par exemple -ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU" signifie décharger les couches MoE gate, up et down mais seulement à partir de la 6e couche.

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

Téléchargez le modèle via (après avoir installé pip install huggingface_hub hf_transfer ). Vous pouvez choisir UD-Q2_K_XL (quantification dynamique 2 bits) ou d'autres versions quantifiées comme Q4_K_M . Nous recommandons d'utiliser notre quant dynamique 2,7 bits UD-Q2_K_XL pour équilibrer taille et précision.

# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0" # Peut parfois limiter les requêtes, donc mettez à 0 pour désactiver
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 Utilisez "*UD-TQ1_0*" pour le 1bit dynamique
)

4

Vous pouvez modifier --threads 32 pour le nombre de threads CPU, --ctx-size 16384 pour la longueur de contexte, --n-gpu-layers 2 pour le déchargement GPU sur le nombre de couches. Essayez de l'ajuster si votre GPU manque de mémoire. Supprimez-le également si vous n'avez qu'une inférence 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

Obtenez la version 1bit (170 Go) si vous n'avez pas suffisamment de RAM et VRAM combinées :

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*"], # Utilisez "*UD-Q2_K_XL*" pour le 2bit dynamique
)

✨ Déployer avec llama-server et la librairie de complétions d'OpenAI

Pour utiliser llama-server pour le déploiement, utilisez la commande suivante :

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

Puis utilisez la bibliothèque Python d'OpenAI après 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)

💽Téléversements de modèles

TOUS nos téléversements - y compris ceux qui ne sont pas basés sur imatrix ou dynamiques, utilisent notre jeu de données de calibration, qui est spécialement optimisé pour les tâches conversationnelles, de codage et de langage.

• Téléversements complets du modèle DeepSeek-V3.1 ci-dessous :

Nous avons également téléversé IQ4_NL et Q4_1 des quants qui s'exécutent spécifiquement plus rapidement pour les appareils ARM et Apple respectivement.

Bits MoE	Type + Lien	Taille sur disque	Détails
1,66 bit	TQ1_0	170 Go	1,92/1,56 bit
1,78 bit	IQ1_S	185 Go	2,06/1,56 bit
1,93 bit	IQ1_M	200 Go	2.5/2.06/1.56
2,42 bit	IQ2_XXS	216 Go	2,5/2,06 bit
2,71 bit	Q2_K_XL	251 Go	3,5/2,5 bit
3,12 bit	IQ3_XXS	273 Go	3,5/2,06 bit
3,5 bit	Q3_K_XL	296 Go	4,5/3,5 bit
4,5 bit	Q4_K_XL	384 Go	5,5/4,5 bit
5,5 bit	Q5_K_XL	481 Go	6,5/5,5 bit

Nous avons également téléversé des versions en format BF16, et l'original format FP8 (float8).

🏂 Amélioration de la vitesse de génération

Si vous avez plus de VRAM, vous pouvez essayer de décharger plus de couches MoE, ou de décharger des couches complètes elles-mêmes.

Normalement, -ot ".ffn_.*_exps.=CPU" décharge toutes les couches MoE vers le CPU ! Cela vous permet effectivement de faire tenir toutes les couches non-MoE sur 1 GPU, améliorant les vitesses de génération. Vous pouvez personnaliser l'expression regex pour décharger plus de couches si vous disposez de plus de capacité GPU.

Si vous avez un peu plus de mémoire GPU, essayez -ot ".ffn_(up|down)_exps.=CPU" Cela décharge les couches MoE de projection up et down.

Essayez -ot ".ffn_(up)_exps.=CPU" si vous avez encore plus de mémoire GPU. Cela ne décharge que les couches MoE de projection up.

Vous pouvez aussi personnaliser le regex, par exemple -ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU" signifie décharger les couches MoE gate, up et down mais seulement à partir de la 6e couche.

Le dernière version de llama.cpp introduit également le mode haut débit. Utilisez llama-parallel. Lisez-en davantage ici. Vous pouvez aussi quantifier le cache KV en 4 bits par exemple pour réduire les mouvements VRAM / RAM, ce qui peut aussi accélérer le processus de génération.

📐Comment adapter un long contexte (128K complet)

Pour adapter un contexte plus long, vous pouvez utiliser la quantification du cache KV pour quantifier les caches K et V en moins de bits. Cela peut aussi augmenter la vitesse de génération en réduisant les mouvements de données RAM / VRAM. Les options autorisées pour la quantification K (par défaut est f16) incluent ci-dessous.

--cache-type-k f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1

Vous devriez utiliser les _1 variantes pour une précision quelque peu accrue, bien que ce soit légèrement plus lent. Par ex. q4_1, q5_1

Vous pouvez aussi quantifier le cache V, mais vous devrez compiler llama.cpp avec le support Flash Attention via -DGGML_CUDA_FA_ALL_QUANTS=ON, et utiliser --flash-attn pour l'activer. Ensuite vous pouvez l'utiliser conjointement avec --cache-type-k :

--cache-type-v f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1