> 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/fr/modeles/tutorials/deepseek-v3.1-how-to-run-locally.md). # DeepSeek-V3.1 : comment l'exécuter localement Un guide pour exécuter DeepSeek-V3.1 et Terminus sur votre propre appareil local ! Le V3.1 de DeepSeek et **Terminus** Cette mise à jour introduit l’inférence de raisonnement hybride, combinant « think » et « non-think » en un seul modèle. Le modèle complet de 671B paramètres nécessite 715 Go d’espace disque. La version dynamique quantifiée 2 bits utilise 245 Go (-75 % de réduction de taille). GGUF : [**DeepSeek-V3.1-GGUF**](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF) {% hint style="success" %} **NOUVEAU :** DeepSeek-V3.1-Terminus est désormais disponible : [DeepSeek-V3.1-Terminus-GGUF](https://huggingface.co/unsloth/DeepSeek-V3.1-Terminus-GGUF)\ \ [**Mise à jour du 10 sept. 2025 :**](/docs/fr/notions-de-base/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) Vous avez demandé des benchmarks plus exigeants, alors nous mettons en avant les résultats d’Aider Polyglot ! Notre GGUF DeepSeek V3.1 dynamique 3 bits obtient **75.6%**, dépassant de nombreux LLM de pointe en précision complète. [En savoir plus.](/docs/fr/notions-de-base/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) Nos GGUF DeepSeek-V3.1 incluent les correctifs de modèle de chat d’Unsloth [correctifs du modèle de chat](#chat-template-bug-fixes) pour les backends pris en charge par llama.cpp. {% endhint %} Tous les téléversements utilisent Unsloth [Dynamic 2.0](/docs/fr/notions-de-base/dynamic-3.0-ggufs.md) pour des performances de pointe sur MMLU en 5-shot et sur la divergence KL, ce qui signifie que vous pouvez exécuter et affiner des LLM DeepSeek quantifiés avec une perte de précision minimale. **Navigation des tutoriels :** Exécuter dans llama.cppExécuter dans Ollama/Open WebUI ## :gear: Paramètres recommandés Le quant 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 **carte 1x24 Go et 128 Go de RAM** avec déchargement MoE — il **fonctionne nativement dans Ollama**! {% hint style="info" %} Vous devez utiliser `--jinja` pour les quantifications llama.cpp - cela utilise nos [modèles de conversation fixes](#chat-template-bug-fixes) et active le bon modèle ! Vous risquez d'obtenir des résultats incorrects si vous n'utilisez pas `--jinja` {% endhint %} Les quantifications 2 bits tiennent sur 1 GPU de 24 Go (avec les couches MoE déchargées vers la RAM). Comptez environ 5 tokens/s avec cette configuration si vous disposez aussi de 128 Go de RAM supplémentaires. Il est recommandé d’avoir au moins 226 Go de RAM pour exécuter cette version 2 bits. Pour des performances optimales, vous aurez besoin d’au moins 226 Go de mémoire unifiée ou de 226 Go de RAM+VRAM combinées pour 5+ tokens/s. Pour apprendre à augmenter la vitesse de génération et à prendre en charge des contextes plus longs, [lisez ici](#improving-generation-speed). {% hint style="success" %} Bien que ce ne soit pas obligatoire, pour de meilleures performances, veillez à ce que votre VRAM + 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, mais l’inférence sera plus lente. {% endhint %} ## :butterfly:Corrections de bugs du modèle de conversation Nous avons corrigé quelques problèmes avec le modèle 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 modèle de chat pour activer le raisonnement. Le modèle de chat introduit `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 moteur de rendu jinja de llama.cpp via [minja](https://github.com/google/minja) ne permet pas l’utilisation d’arguments supplémentaires dans la `.split()` commande, donc l’utilisation de `.split(text, 1)` fonctionne en Python, mais pas dans minja. Nous avons dû modifier 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 :\ `arrêt appelé après avoir levé une instance de 'std::runtime_error' what() : la méthode split doit avoir entre 1 et 1 arguments positionnels et entre 0 et 0 arguments nommés à la ligne 3, colonne 1908` Nous l’avons corrigé dans toutes nos quantifications ! ### 🐳 Paramètres recommandés officiels Selon [DeepSeek](https://huggingface.co/deepseek-ai/DeepSeek-V3.1), 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. * Définissez **top\_p à 0,95** (recommandé) * **longueur de contexte de 128K** ou moins * Utilisez `--jinja` pour les variantes de llama.cpp - nous **avons également corrigé certains problèmes de modèle de conversation !** * **Utilisez** `enable_thinking = True` pour utiliser le mode raisonnement/pensée. Par défaut, il est réglé sur non-raisonnement. #### :1234: Format du modèle de chat / du prompt Vous n’avez pas besoin d’imposer `\n` , mais vous pouvez tout de même l’ajouter ! Avec le préfixe donné, DeepSeek V3.1 génère des réponses aux requêtes en mode sans réflexion. Contrairement à DeepSeek V3, il introduit un jeton supplémentaire ``. ``` <｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜> ``` Un BOS est ajouté de force, et un EOS sépare chaque interaction. Pour contrer les doubles jetons BOS pendant l’inférence, vous ne devez appeler que `tokenizer.encode(..., add_special_tokens = False)` car le modèle de chat ajoute automatiquement aussi un jeton BOS. Pour l’inférence llama.cpp / GGUF, vous devez omettre le BOS puisqu’il sera ajouté automatiquement. #### :notebook\_with\_decorative\_cover: Mode sans réflexion (utiliser `thinking = False`ou `enable_thinking = False` et c’est le réglage par défaut) **Premier tour** Préfixe : `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>` Avec le préfixe donné, DeepSeek V3.1 génère des réponses aux requêtes en mode sans réflexion. Contrairement à DeepSeek V3, il introduit un jeton supplémentaire ``. **Multi-tour** Contexte : `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>` Préfixe : `<｜User｜>{query}<｜Assistant｜>` En concaténant le contexte et le préfixe, nous obtenons le prompt correct pour la requête. #### :books: Mode réflexion (utiliser `thinking = True`ou `enable_thinking = True` et c’est le réglage par défaut) **Premier tour** Préfixe : `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>` Le préfixe du mode réflexion est similaire à DeepSeek-R1. **Multi-tour** Contexte : `<｜begin▁of▁sentence｜>{system prompt}<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜>{response}<｜end▁of▁sentence｜>` Préfixe : `<｜User｜>{query}<｜Assistant｜>` Le modèle multi-tour est le même que le modèle de chat multi-tour sans réflexion. Cela signifie que le jeton de pensée du dernier tour sera supprimé, mais le `` est conservé à chaque tour du contexte. #### :bow\_and\_arrow: Appel d'outils L’appel d’outils est pris en charge en mode sans réflexion. Le format est : `<｜begin▁of▁sentence｜>{system prompt}{tool_description}<｜User｜>{query}<｜Assistant｜>` là où nous renseignons tool\_description se trouve la zone après le prompt système. ## :arrow\_forward:Exécuter les tutoriels DeepSeek-V3.1 : ### :llama: Exécuter dans Ollama/Open WebUI {% stepper %} {% step %} Installez `ollama` si ce n'est pas déjà fait ! Pour exécuter d'autres variantes du modèle, [voir ici](#run-in-llama.cpp). ```bash apt-get update apt-get install pciutils -y curl -fsSL https://ollama.com/install.sh | sh ``` {% endstep %} {% step %} Exécutez le modèle ! Notez que vous pouvez appeler `ollama serve`dans un autre terminal si cela échoue ! Nous incluons toutes nos corrections et paramètres suggérés (température, etc.) dans `params` dans notre téléversement Hugging Face !\ **(NOUVEAU) Pour le modèle DeepSeek-V3.1 dans Ollama, vous pouvez utiliser notre TQ1\_0 (quantification 170 Go) :** ```bash OLLAMA_MODELS=unsloth ollama serve & OLLAMA_MODELS=unsloth ollama run hf.co/unsloth/DeepSeek-V3.1-Terminus-GGUF:TQ1_0 ``` {% endstep %} {% step %} Pour exécuter d'autres quantifications, vous devez d'abord fusionner les fichiers GGUF fractionnés en un seul comme dans le code ci-dessous. Ensuite, vous devrez exécuter le modèle localement. ```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 a également réalisé un [tutoriel étape par étape](https://docs.openwebui.com/tutorials/integrations/deepseekr1-dynamic/) sur la façon d’exécuter R1 et, pour V3.1, il vous suffira de remplacer R1 par la nouvelle quantification V3.1. {% endstep %} {% endstepper %} ### ✨ Exécuter dans llama.cpp {% stepper %} {% step %} Obtenez la dernière version `llama.cpp` sur [GitHub ici](https://github.com/ggml-org/llama.cpp). Vous pouvez également suivre les instructions de compilation ci-dessous. Modifiez `-DGGML_CUDA=ON` à `-DGGML_CUDA=OFF` si vous n'avez pas de GPU ou si vous souhaitez simplement une inférence 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 %} Si vous souhaitez 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` pour enregistrer vers un emplacement spécifique. Rappelez-vous que le modèle ne dispose que d'une longueur de contexte maximale de 128K. {% hint style="success" %} Essayez `-ot ".ffn_.*_exps.=CPU"` pour décharger toutes les couches MoE sur le CPU ! Cela vous permet en pratique de faire tenir toutes les couches non-MoE sur 1 GPU, améliorant ainsi les vitesses de génération. Vous pouvez personnaliser l'expression regex pour faire tenir davantage 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 ascendante et descendante. Essayez `-ot ".ffn_(up)_exps.=CPU"` si vous avez encore plus de mémoire GPU. Cela décharge uniquement les couches MoE de projection ascendante. Et enfin, déchargez toutes les couches via `-ot ".ffn_.*_exps.=CPU"` Cela utilise le moins de VRAM. Vous pouvez aussi personnaliser l'expression 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. {% 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 %} 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 quantification dynamique 2,7 bits**** ****`UD-Q2_K_XL`**** ****pour équilibrer taille et précision**. ```python # !pip install huggingface_hub hf_transfer import os os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0" # Peut parfois subir une limitation de débit, donc définissez-le à 0 pour le 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*"], # 2 bits dynamique Utilisez "*UD-TQ1_0*" pour 1 bit dynamique ) ``` {% endstep %} {% step %} 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 de combien de couches. Essayez de l'ajuster si votre GPU manque de mémoire. Supprimez-le aussi si vous faites une inférence uniquement 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 %} Obtenez la version 1 bit (170 Go) si vous n’avez pas assez de RAM et de VRAM combinées : ```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*"], # Utilisez "*UD-Q2_K_XL*" pour 2 bits dynamique ) ``` {% endstep %} {% endstepper %} ### ✨ Déployez avec llama-server et la bibliothèque completion d'OpenAI Pour utiliser llama-server pour le déploiement, utilisez la commande suivante : {% 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 %} Puis utilisez la bibliothèque Python d'OpenAI après `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": "Combien font 2+2 ?"},], ) print(completion.choices[0].message.content) ``` ## :minidisc:Téléversements des modèles **TOUTES nos mises en ligne** - y compris celles qui ne sont pas basées sur imatrix ni dynamiques - utilisent notre ensemble de données de calibration, spécialement optimisé pour les tâches conversationnelles, de codage et de langue. * Téléversements complets du modèle DeepSeek-V3.1 ci-dessous : Nous avons également téléversé [IQ4\_NL](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF/tree/main/IQ4_NL) et [Q4\_1](https://huggingface.co/unsloth/DeepSeek-V3.1-GGUF/tree/main/Q4_1) des quantifications qui s’exécutent spécifiquement plus vite sur les appareils ARM et Apple, respectivement.
Bits MoEType + lienTaille sur disqueDétails
1,66 bitTQ1_0170 Go1,92/1,56 bit
1,78 bitIQ1_S185 Go2,06/1,56 bit
1,93 bitIQ1_M200 Go2.5/2.06/1.56
2,42 bitIQ2_XXS216 Go2,5/2,06 bit
2,71 bitQ2_K_XL251 Go3,5/2,5 bit
3,12 bitIQ3_XXS273 Go3,5/2,06 bit
3,5 bitQ3_K_XL296 Go4,5/3,5 bit
4,5 bitQ4_K_XL384 Go5,5/4,5 bit
5,5 bitQ5_K_XL481 Go6,5/5,5 bit
Nous avons également téléversé des versions au format [BF16](https://huggingface.co/unsloth/DeepSeek-V3.1-BF16), et l’original [format FP8 (float8)](https://huggingface.co/unsloth/DeepSeek-V3.1). ## :snowboarder: Améliorer la vitesse de génération Si vous avez plus de VRAM, vous pouvez essayer de décharger davantage de couches MoE, ou de décharger des couches entières elles-mêmes. Normalement, `-ot ".ffn_.*_exps.=CPU"` décharge toutes les couches MoE sur le CPU ! Cela vous permet en pratique de faire tenir toutes les couches non-MoE sur 1 GPU, améliorant ainsi les vitesses de génération. Vous pouvez personnaliser l'expression regex pour faire tenir davantage de couches si vous avez 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 ascendante et descendante. Essayez `-ot ".ffn_(up)_exps.=CPU"` si vous avez encore plus de mémoire GPU. Cela décharge uniquement les couches MoE de projection ascendante. Vous pouvez aussi personnaliser l'expression 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](https://github.com/ggml-org/llama.cpp/pull/14363) introduit également le mode haut débit. Utilisez `llama-parallel`. En savoir plus à ce sujet [ici](https://github.com/ggml-org/llama.cpp/tree/master/examples/parallel). 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 gérer un long contexte (128K complet) Pour gérer un contexte plus long, vous pouvez utiliser **quantification du cache KV** pour quantifier les caches K et V sur moins de bits. Cela peut aussi augmenter la vitesse de génération grâce à la réduction des transferts de données RAM / VRAM. Les options autorisées pour la quantification K (la valeur par défaut est `f16`) sont les suivantes. `--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 légèrement améliorée, même si c'est un peu plus lent. Par ex. `q4_1, q5_1` Vous pouvez aussi quantifier le cache V, mais vous devrez **compiler llama.cpp avec la prise en charge de Flash Attention** via la prise en charge `-DGGML_CUDA_FA_ALL_QUANTS=ON`, et utiliser `--flash-attn` pour l'activer. Vous pouvez ensuite l'utiliser avec `--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/fr/modeles/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.