DeepSeek-V3.1 è un modello di chat ibrido Mixture-of-Experts (MoE) rilasciato da DeepSeek nell'agosto 2025 che supporta due modalità di inferenza — una modalità "non-thinking" veloce e una modalità "thinking" deliberata — dallo stesso checkpoint. Il modello è disponibile su Hugging Face e può essere eseguito localmente tramite diversi percorsi (vLLM, Ollama/llama.cpp, GGUF in stile Ollama o configurazioni multi-GPU su larga scala). Di seguito vi guiderò attraverso i requisiti, il funzionamento della modalità thinking, diverse opzioni di esecuzione locale (con frammenti di codice eseguibili) e una ricetta passo passo per il "Thinking Mode deploy" con esempi di chiamata di strumenti e modelli di token.
Che cos'è DeepSeek-V3.1 e perché è importante?
DeepSeek-V3.1 è l'aggiornamento della famiglia v3 di DeepSeek che introduce un progettazione di inferenza ibrida: lo stesso modello può essere eseguito in pensiero (deliberativo, multi-step) o non-pensiero (risposta diretta, più veloce) modificando il modello di chat. Dal punto di vista architettonico, si tratta di una famiglia MoE di grandi dimensioni (checkpoint di base con circa 671 miliardi di parametri totali, ~37 miliardi attivati per token) con training a lungo contesto esteso a 128 token e supporto per il micro-scaling FP8. DeepSeek ha posizionato la V3.1 come una versione pronta per gli agenti: migliore chiamata degli strumenti, competenze degli agenti migliorate e maggiore efficienza di pensiero rispetto alle precedenti versioni R1. La versione è stata annunciata nell'agosto 2025 ed è stata integrata in Hugging Face, strumenti CFD/OSS e guide per l'implementazione cloud.
Come funziona il modello ibrido (conciso)
- Un checkpoint, due modelli: Le modalità di pensiero e non pensiero sono controllate da modello di chat e
<think>/</think>Convenzione token nel prompt. La scheda modello documenta i prefissi esatti. - Miglioramenti degli agenti/strumenti: I potenziamenti post-addestramento consentono chiamate di strumenti più intelligenti: il modello prevede un formato JSON rigoroso per le chiamate di strumenti, per un'esecuzione sicura e deterministica degli strumenti.
- Compromessi in termini di prestazioni: La modalità di pensiero spende token in ragionamenti interni basati su una catena di pensiero e può essere più lenta/richiede più token; la modalità di non pensiero è più veloce ed economica. I benchmark nella scheda modello mostrano miglioramenti sostanziali nei benchmark di ragionamento e codice per la versione 3.1.
Come è strutturato il modello
- Spina dorsale del MoE: elevato numero totale di parametri con un sottoinsieme attivato più piccolo per token (inferenza economica).
- Formazione a lungo contesto: La versione V3.1 estende significativamente le fasi di contesto lungo (32k → formazione più ampia su documenti lunghi) per supportare oltre 128K finestre in alcune build.
- Flusso di lavoro nativo FP8: DeepSeek utilizza ampiamente i formati FP8 (w8a8 / UE8M0) per l'efficienza di peso/attivazione; se preferisci BF16/FP16, esistono script di conversione della community.
Quali sono i requisiti per eseguire DeepSeek-V3.1 in locale? (Hardware, storage e software)
Esecuzione del pieno Il modello V3.1 (non quantizzato) è un'impresa ardua. Di seguito sono riportate categorie realistiche di configurazioni e i relativi requisiti tipici.
Secchi pratici
- Cluster / laboratorio di ricerca (modello completo): più GPU ad alta capacità di memoria (classe H100/H800 o molte GPU Ada/Hopper), multi-nodo con decine di GPU, molto spazio di archiviazione NVMe (centinaia di GB) e framework di inferenza specializzati (SGLang, vLLM, LMDeploy, TRT-LLM).
- Server singolo di fascia alta (quantizzato): possibile con una quantizzazione pesante (INT4/AWQ/AWQ2/gguf) e framework come Ollama (preconfezionati) o GGUF della community, ma richiede comunque da decine a centinaia di GB di RAM GPU o un intelligente offload di CPU+GPU.
- Laptop per sviluppatori / box per sviluppatori: non fattibile per il modello completo; utilizzare piccole varianti distillate/ottimizzate o connettersi al server locale/istanza di Ollama.
Lista di controllo hardware (pratica)
- GPU: Per una reale capacità di inferenza dell'intera V3.1: cluster multi-GPU (H100 / H800 / Ada Lovelace+). Per l'esecuzione FP8, sono necessarie GPU con capacità di elaborazione e supporto driver.
- RAM e spazio di archiviazione: Prevediamo centinaia di GB di spazio libero su disco per i file modello (le pagine dei modelli indicano alcune centinaia di GB a seconda del formato/quantizzazione), più spazio di lavoro per i formati convertiti. I metadati di Ollama indicano uno spazio di circa 400 GB per un pacchetto DeepSeek V3.1 Ollama nella libreria.
- Network: Per l'inferenza multi-nodo sono necessarie interconnessioni a bassa latenza (NVLink / InfiniBand) e strumenti di orchestrazione per configurazioni tensor-parallele.
Lista di controllo del software
- OS: Linux è consigliato per gli strumenti di inferenza della comunità (la demo DeepSeek-Infer elenca Linux/Python).
- Python: 3.10+ (in molti esempi DeepSeek). Le versioni tipiche dei pacchetti sono bloccate nel repository
requirements.txt. - Framework e strumenti (scegli uno o più): SGLang, vLLM, LMDeploy, TRT-LLM/TensorRT-LLM, LightLLM o Ollama per installazioni locali più semplici. Ognuno di essi offre istruzioni e un diverso supporto per precisione/quantizzazione.
Nota pratica: Se si dispone di una sola GPU consumer (ad esempio, 24-48 GB), è probabile che si utilizzino GGUF quantizzati o inferenza remota; se si dispone di una workstation con >128 GB di RAM più un cluster GPU di classe H100/H200, è possibile puntare a un'inferenza FP8/FP16 ad alta fedeltà con vLLM.
Come posso eseguire DeepSeek-V3.1 in locale?
Di seguito sono riportati diversi percorsi pratici che puoi utilizzare, dal più manuale/flessibile al percorso più semplice per un singolo sviluppatore. Fornirò tutorial passo passo ed esempi di codice
Opzione A — Demo ufficiale di DeepSeek-Infer (percorso di sviluppo/cluster)
Questo è l'esempio/demo del repository per l'inferenza FP8/BF16. Usatelo se pianificate un'inferenza multi-nodo o volete sperimentare con il codice di inferenza ufficiale.
- Clona, prepara l'ambiente
git clone https://github.com/deepseek-ai/DeepSeek-V3.git
cd DeepSeek-V3/inference
# Create a dedicated venv / conda env
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
(Repo inference/requirements.txt elenca le versioni Torch/Triton/Transformers consigliate dal team.)
- Scarica i pesi del modello
- Scarica dalla pagina del modello Hugging Face (
deepseek-ai/DeepSeek-V3.1) e posizionarli sotto/path/to/DeepSeek-V3La scheda modello e il repository indicano entrambi i link ufficiali per l'archiviazione di Hugging Face.
- Converti i pesi per la demo
# example conversion command shown in the repo
python convert.py --hf-ckpt-path /path/to/DeepSeek-V3 --save-path /path/to/DeepSeek-V3-Demo --n-experts 256 --model-parallel 16
- Esegui la generazione interattiva (distribuita)
torchrun --nnodes 2 --nproc-per-node 8 --node-rank $RANK --master-addr $ADDR \
generate.py --ckpt-path /path/to/DeepSeek-V3-Demo --config configs/config_671B.json \
--interactive --temperature 0.7 --max-new-tokens 200
Questo è l'esempio canonico del repository DeepSeek per le esecuzioni in stile cluster.
Opzione B — vLLM (consigliata per distribuzioni server e API compatibili con OpenAI)
vLLM supporta DeepSeek nelle modalità FP8/BF16 e offre un server compatibile con OpenAI. È un percorso di produzione diffuso per modelli di grandi dimensioni grazie all'ottimizzazione della memoria e alla compatibilità con le API.
Avvia un server vLLM che recupererà il modello da Hugging Face (esempio di modello):
# this will download/serve the model (replace with exact model id if needed)
vllm serve deepseek-ai/DeepSeek-V3.1 --host 0.0.0.0 --port 8000
Quindi richiedi il completamento con curl o un client compatibile con OpenAI:
curl -s -X POST "http://localhost:8000/v1/completions" \
-H "Content-Type: application/json" \
-d '{"model":"DeepSeek-V3.1","prompt":"Explain the QuickSort algorithm", "max_tokens":200}'
Le ricette e la documentazione vLLM includono esempi di DeepSeek e note sulla compatibilità con FP8 e sul parallelismo multi-GPU/pipeline. Per i modelli più complessi saranno comunque necessarie più GPU o una variante quantizzata.
Opzione C — LMDeploy / SGLang / LightLLM e TensorRT-LLM (alte prestazioni)
Il repository DeepSeek raccomanda esplicitamente SGLang, LMDeploye TensorRT-LLM come motori ottimizzati per DeepSeek V3. Offrono latenza di inferenza migliorata, throughput e kernel FP8.
Una tipica invocazione di LMDeploy (fare riferimento alla documentazione di LMDeploy per la CLI esatta):
# pseudo-example; refer to LMDeploy docs for exact options
lmdeploy serve --model /path/to/deepseek_v3.1 --precision fp8 --port 8080
I benchmark e le ricette di lancio di SGLang sono disponibili nel repository e nel progetto SGLang benchmark/deepseek_v3 cartella. Utilizza questi stack quando controlli un cluster GPU e desideri una produttività elevata.
Opzione D — Ollama (il percorso di sviluppo locale più semplice, spesso su una singola macchina)
Se desideri eseguire DeepSeek localmente nel modo meno gravoso (e puoi risparmiare il disco), Ollama fornisce modelli confezionati e una semplice CLI (ollama pull, ollama run). DeepSeek-V3.1 è presente nella libreria Ollama e può essere eseguito localmente (Ollama potrebbe richiedere una versione recente/pre-release per alcune funzionalità).
Esempio (Ollama CLI):
# Pull the model (downloads the model artifacts to your disk)
ollama pull deepseek-v3.1
# Start an interactive session:
ollama run deepseek-v3.1
# Or run as a local API server (Ollama supports a local API)
# Example: POSTing to Ollama's local API (adjust host/port to your setup)
curl -X POST http://localhost:11434/api/generate \
-H 'Content-Type: application/json' \
-d '{"model":"deepseek-v3.1","prompt":"Summarize the following paper: ..."}'
Ollama astrae molti dettagli di distribuzione/quantizzazione e può essere un ottimo modo per testare il comportamento del modello su un singolo host. Nota: la pagina del modello elenca una dimensione di pacchetto di circa 404 GB per la voce Ollama, quindi pianificare di conseguenza disco e RAM.
Cos'è la modalità pensiero e come utilizzarla
DeepSeek-V3.1 implementa un token di pensiero ibrido approccio: lo stesso checkpoint può essere eseguito in pensiero modalità (token di "catena di pensiero" interna) o non-pensiero modalità cambiando il modello di chat/prompt. Il modello utilizza token espliciti come <think> (e chiusura </think> in alcuni modelli) per segnalare la catena di pensiero interna rispetto alla generazione diretta di risposte. La scheda modello documenta i prefissi di pensiero e non pensiero e mostra le differenze tra i modelli.
Esempio: costruzione di un messaggio in Python (tokenizer helper)
La scheda modello Hugging Face include un utile frammento che mostra come applicare il modello di chat tramite il tokenizzatore. Questo è il modello consigliato per la generazione pensiero or non-pensiero prompt formattati:
import transformers
tokenizer = transformers.AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")
messages = [
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "Who are you?"},
{"role": "assistant", "content": "<think>Hmm</think>I am DeepSeek"},
{"role": "user", "content": "1+1=?"}
]
# Thinking mode
tokenizer.apply_chat_template(messages, tokenize=False, thinking=True, add_generation_prompt=True)
# Non-thinking mode
tokenizer.apply_chat_template(messages, tokenize=False, thinking=False, add_generation_prompt=True)
Interruttore thinking=True per produrre un prompt che utilizza il <think> prefisso; thinking=False produce il modello non-pensante. Il modello si comporterà in modo diverso (deliberazione interna vs risposta immediata) a seconda di questo flag.
Riferimento rapido: risoluzione di piccoli problemi e best practice
Se si esaurisce la memoria della GPU: Provate build quantizzate (AWQ/q4/INT4) o GGUF della community; molti spazi della community pubblicano quantizzazioni per uso locale. Ollama/vLLM possono anche servire build quantizzate più piccole.
Se è necessario che il modello chiami strumenti esterni: Adotta il ToolCall schema nel modello di chat. Testa il formato JSON dello strumento offline e verifica che il codice di orchestrazione (la parte che esegue lo strumento) restituisca al modello un JSON tipizzato e ripulito.
Se hai bisogno di un contesto lungo: Utilizzare vLLM o SGLang con plugin a contesto lungo; DeepSeek è stato addestrato/esteso esplicitamente per contesti da 32K/128K e gli strumenti correlati supportano tale finestra. Prevedere compromessi in termini di memoria.
Posso effettivamente eseguire DeepSeek-V3.1 su un laptop o un piccolo server?
Risposta breve: Sì, ma con qualche riserva. Le quantizzazioni della community (AWQ/GGUF/dinamiche a 1 bit) riducono drasticamente l'ingombro di memoria e di archiviazione e hanno consentito agli appassionati di eseguire le varianti V3.1 su desktop di fascia alta (dichiarazioni di un working set di circa 170 GB). Tuttavia:
- Compromesso tra fedeltà e dimensioni: La quantizzazione aggressiva riduce la memoria ma può influire sulle prestazioni del ragionamento e del codice. Esegui test sui tuoi carichi di lavoro.
- Legale e licenze: il modello è concesso in licenza dal MIT in base alla scheda modello, ma le quantizzazioni di terze parti potrebbero avere le proprie licenze; esaminarle prima dell'uso in produzione.
Parole finali
DeepSeek-V3.1 rappresenta un passo significativo verso modelli "agent" ibridi con comportamento di pensiero/non pensiero esplicito e un utilizzo migliorato degli strumenti. Se si desidera eseguirlo localmente, è necessario scegliere un percorso che corrisponda al proprio hardware e alla propria tolleranza al rischio:
Per la ricerca: transformers + safetensori quantizzati e accelerano.
Per produzione e produttività: vLLM + multi-GPU (H100/H200).
Per esperimenti locali: Ollama/llama.cpp + GGUF della community (unione + esecuzione).
Iniziamo
CometAPI è una piattaforma API unificata che aggrega oltre 500 modelli di intelligenza artificiale (IA) di provider leader, come la serie GPT di OpenAI, Gemini di Google, Claude di Anthropic, Midjourney, Suno e altri, in un'unica interfaccia intuitiva per gli sviluppatori. Offrendo autenticazione, formattazione delle richieste e gestione delle risposte coerenti, CometAPI semplifica notevolmente l'integrazione delle funzionalità di IA nelle tue applicazioni. Che tu stia sviluppando chatbot, generatori di immagini, compositori musicali o pipeline di analisi basate sui dati, CometAPI ti consente di iterare più velocemente, controllare i costi e rimanere indipendente dal fornitore, il tutto sfruttando le più recenti innovazioni nell'ecosistema dell'IA.
Gli sviluppatori possono accedere Versione DeepSeek-V3.1 tramite CometAPI, le ultime versioni dei modelli elencate sono quelle aggiornate alla data di pubblicazione dell'articolo. Per iniziare, esplora le capacità del modello in Parco giochi e consultare il Guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l'accesso a CometAPI e di aver ottenuto la chiave API. CometaAPI offrire un prezzo molto più basso rispetto al prezzo ufficiale per aiutarti a integrarti.