Come distribuire deepseek-v3.1 localmente tramite ollama: The Eastest Guide

DeepSeek-V3.1 è un modello linguistico MoE ibrido "pensante/non pensante" (671B totali, circa 37B attivati per token) che può essere eseguito localmente se si utilizzano il provider/quantizzazione e gli strumenti giusti. Di seguito spiego cos'è DeepSeek-V3.1, i requisiti hardware/software, tutorial passo passo per l'esecuzione locale (esempi Ollama + llama.cpp) e come implementare e utilizzare la modalità di pensiero (la <think>/</think> modello di chat) con esempi di codice che puoi copiare/incollare.

Che cos'è DeepSeek-V3.1?

DeepSeek-V3.1 è la versione 3.1 della famiglia MoE (Mixture-of-Experts) di DeepSeek. È stato progettato come un modello di inferenza ibrido che supporta due modelli/modalità conversazionali: Pensiero e al Non-pensiero — dallo stesso checkpoint modificando il modello di chat. L'architettura del modello si ispira al design MoE di DeepSeek-V3 (671 miliardi di parametri totali; circa 37 miliardi di parametri attivati per token per l'inferenza) e aggiunge miglioramenti post-addestramento per l'utilizzo degli strumenti, le competenze degli agenti e la gestione di contesti estesi.

Caratteristiche principali in breve

IBRIDO Pensare / Non pensare modalità (attivate tramite tokenizzazione del modello di chat).
Architettura MoE: elevato numero totale di parametri ma parametri attivati limitati per token (consente efficienza).
Potenziamenti post-formazione per chiamate di strumenti e flussi di lavoro degli agenti (formato di chiamata di strumenti e modelli di agenti documentati nelle risorse del modello).

Di cosa ho bisogno per eseguire DeepSeek-V3.1 in locale?

Esecuzione del pieno DeepSeek-V3.1 (checkpoint grezzi) è un'architettura di alto livello: l'archiviazione di training/checkpoint e l'orchestrazione delle inferenze non sono banali. Ma esistono percorsi pratici:

Hardware

Inferenza completamente distribuita (ricerca/cluster): più GPU ad alta capacità di memoria (classe A100/H800) o un cluster di GPU con servizio model-parallel (tipico per checkpoint da 600 miliardi di unità). Da utilizzare solo se si eseguono cluster di ricerca in produzione.
Opzioni locali pratiche: Usa il parametro attivato prospettiva (≈37B attivati) o una build GGUF quantizzata/dinamica a 1 bit. Le quantizzazioni della community (dinamica a 1 bit / GGUF) riducono significativamente i requisiti di disco e RAM: ad esempio, i post della community segnalano la compressione di un checkpoint da 720 GB in ~170 GB di GGUF per una variante quantizzata. Ciò rende fattibile l'inferenza GPU locale su singolo server per desktop/server con risorse adeguate.

Bottom line: aspettarsi un flusso di lavoro di grandi dimensioni (decine o centinaia di GB di disco per artefatti quantizzati); per la VRAM della GPU, utilizzare varianti quantizzate e puntare a ≥24–48 GB di VRAM per una produttività ragionevole; altrimenti utilizzare CPU+swap con compromessi in termini di prestazioni.

Software e strumenti

Python 3.10+ (per strumenti di trasformazione/tokenizzazione e script personalizzati).

transformers (per funzioni tokenizer e helper) — la scheda modello mostra esempi utilizzando transformers.AutoTokenizer.

Uno o più runtime di inferenza locale:

Ollama (facile: ollama pull / ollama run integrazione; alcune build di DeepSeek su Ollama richiedono versioni pre-release, controllare la nota sul modello/ollama). Ollama è diventato un runner locale standard per i modelli della comunità.
llama.cpp / ggml pile o llama-server per file quantizzati GGUF: ottimo per l'esecuzione diretta di GGUF.
inferenza di generazione di testo / Triton / FlashAttention stack per inferenza GPU ad alte prestazioni (configurazioni avanzate).

Disco: ampio spazio libero per i file del modello (decine → centinaia di GB a seconda della quantizzazione).

Artefatti del modello (quale file ottenere)

Varianti ufficiali di safetensors / BF16 / FP8 / GGUF: Hugging Face ospita artefatti del modello V3.1 e quantizzazioni multiple. Se hai bisogno di un file GGUF/quantizzato per llama.cpp, cerca una versione di quantizzazione della community (o uno script di conversione da safetensors → GGUF): la scheda modello elenca le varianti quantizzate.

Come preparo il modello per l'inferenza locale?

Di seguito sono riportati i passaggi di preparazione consigliati, ordinati da semplice → avanzato.

Fase 1: scegliere un runtime (consigliato)

Test principiante/veloce: Ollama: configurazione minima: download, esecuzione del modello, chiamata API. Nota: alcune build di DeepSeek-V3.1 indicano Ollama v0.11.7 come richiesto per funzionalità specifiche.
Controllo avanzato/di basso livello: llama.cpp + GGUF quant (se è disponibile una quantizzazione GGUF). Questo ti dà il controllo diretto dell'inferenza e l'integrazione con llama-server.

Fase 2: Scarica il modello

Se usi Ollama:

# install ollama (see https://ollama.com/docs)

# Pull the model (this downloads the model to your machine)
ollama pull deepseek-ai/DeepSeek-V3.1
# or a specific tag: ollama pull deepseek-ai/DeepSeek-V3.1:quant-q4_0

(di Ollama run verrà estratto automaticamente se non presente; pull consente di controllare i tempi.)

Se usi Hugging Face + llama.cpp:

# Example: download via huggingface-cli or hf_transfer

pip install huggingface_hub
hf_hub_download(repo_id="deepseek-ai/DeepSeek-V3.1", filename="DeepSeek-V3.1.gguf")
# or use a community quant file (gguf) referenced on the Hugging Face model page

Hugging Face elenca gli artefatti del modello, i modelli e le quantizzazioni sulla scheda del modello.

Fase 3: convertire/quantizzare (facoltativo)

Se trovi solo safetensor o artefatti BF16 ma hai bisogno di GGUF per llama.cpp, utilizzare gli script di conversione in llama.cpp (o strumenti della community) per convertire → quantizzare. Esistono strumenti della community per la quantizzazione dinamica a 1 bit che preservano l'accuratezza riducendo al contempo le dimensioni; vedere i post della community che riportano valori fino a ~170 GB.

Come posso eseguire DeepSeek-V3.1 in locale? (Tutorial pratici sull'esecuzione)

Io mostrerò Ollama (facile, consigliato) e lama.cpp Esempi (GGUF) più un breve esempio Python che utilizza gli helper del tokenizzatore della carta modello.

A — Correre con Ollama (avvio rapido)

Installa Ollama (segui le istruzioni ufficiali).
Estrarre ed eseguire il modello:

# pull model to disk (optional; run will pull automatically)

ollama pull deepseek-ai/DeepSeek-V3.1

# start an interactive session (runs model and exposes local API)

ollama run deepseek-ai/DeepSeek-V3.1

Invia una richiesta HTTP al server Ollama locale:

# curl usage example (local Ollama server usually listens on port 11434)

curl -sS -X POST 'http://localhost:11434/api/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"deepseek-ai/DeepSeek-V3.1",
    "prompt":"Explain the difference between thinking and non-thinking mode in DeepSeek.",
    "max_tokens":256
  }'

I modelli CLI e API di Ollama sono progettati per essere semplici: ollama run Verrà eseguito il pull se necessario e verrà avviato un server di modelli. Consultare la documentazione di Ollama e le pagine dei modelli per suggerimenti sulla memoria e nomi/tag esatti dei modelli.

B — Esecuzione di un GGUF quantizzato tramite llama.cpp

Costruiamo llama.cpp con CUDA (facoltativo) o CPU:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# for CUDA:

make clean && make LLAMA_CUBLAS=1
# or CPU only:

make

Inserire il file GGUF del modello in un percorso ed eseguire:

./main -m /path/to/DeepSeek-V3.1.q4_K_M.gguf \
  -p "Explain how to enable thinking mode." \
  --temp 0.2 --n_predict 512

Per l'uso del server, llama-server (progetto della comunità) può esporre un endpoint HTTP:

llama-server -m /path/to/DeepSeek-V3.1.q4_K_M.gguf
# then POST to the server like:

curl -X POST "http://localhost:8080/api/v1/generate" -d '{"prompt":"Hello","max_tokens":200}'

Utilizzare le quantizzazioni GGUF della comunità (q4/q8/dinamiche a 1 bit) per adattarsi ai budget GPU/CPU; llama.cpp repo fornisce strumenti di conversione e guida.

C — Esempio Python che utilizza il modello tokenizer + chat

La carta modello Hugging Face fornisce un tokenizer.apply_chat_template helper e mostra come codificare una conversazione con thinking=TrueEcco un esempio Python minimo adattato dalla scheda modello:

from transformers import AutoTokenizer

tokenizer = 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=?"}
]

# apply thinking chat template

s = tokenizer.apply_chat_template(messages, tokenize=False, thinking=True, add_generation_prompt=True)
print(s)  # the template includes the special <think> token placement

È quindi possibile alimentare il prompt tokenizzato nel runtime di inferenza (Ollama/llama.cpp/TGI) a seconda dello stack.

Come funziona Thinking Mode e come posso distribuirlo localmente?

DeepSeek-V3.1 utilizza modelli di chat che contengono un token di pensiero speciale (ad esempio, <think> e al </think>). Il modello determina se il modello è in modalità Pensiero o Non Pensiero:

Non-pensiero luoghi modello </think> nel prefisso dell'assistente, che istruisce il modello a produrre risposte dirette (il formato toolcall è supportato in modalità non-thinking).
Pensiero luoghi modello <think> nel prefisso dell'assistente che fa sì che il modello emetta segnali intermedi in stile catena di pensiero interna (il modello è addestrato a utilizzare quella sequenza di token per ragionare internamente e produrre risposte multi-step di qualità superiore). La scheda del modello Hugging Face documenta questi token esatti e tokenizer.apply_chat_template(..., thinking=True) API.

Attivazione/disattivazione programmatica (esempi)

A — Con il tokenizzatore (Python):

# thinking=True or thinking=False changes how the prompt is formatted

prompt_thinking = tokenizer.apply_chat_template(messages, thinking=True, add_generation_prompt=True)
prompt_non_thinking = tokenizer.apply_chat_template(messages, thinking=False, add_generation_prompt=True)

Bacheca prompt_thinking al tuo runtime di inferenza per ottenere il comportamento di pensiero.

B — Con prompt raw (llama.cpp / manuale):

inserire <think> prima che l'assistente si giri quando glielo chiedi:

<｜begin_of_sentence｜>You are a helpful assistant<｜User｜>How to optimize this code?<｜Assistant｜><think>

(L'esatta inquadratura del token è riportata sulla scheda modello: se si utilizza il modello grezzo, è necessario rispettare la spaziatura e i marcatori speciali.)

C — Con Ollama (attivazione/disattivazione dell'interfaccia utente):
La demo web ufficiale di DeepSeek e le note di rilascio menzionano un pulsante/toggle "DeepThink" per cambiare modalità nell'interfaccia utente ospitata. Localmente, Ollama o la tua app dovrebbero replicare tale comportamento cambiando il template della chat (ovvero, modificando il prompt inviato al runtime tra i due form tokenizzati). Se esegui DeepSeek tramite Ollama, puoi implementarlo nella tua applicazione mantenendo due template di prompt (pensante vs non pensante) e attivandoli tramite l'API di Ollama.

Come posso distribuire Thinking Mode come agente (chiamate di strumenti, agenti di codice)?

Documenti DeepSeek-V3.1 chiamata di strumento e al agente Modelli nelle risorse del modello. Il modello prevede che gli strumenti siano presentati in uno specifico formato JSON/istruzioni e supporta il concatenamento di più chiamate di strumenti in un singolo turno se si seguono esattamente i token wrapper descritti nella scheda del modello.

Esempio: semplice wrapper di chiamata strumento (pseudo)

Il modello specifica un blocco descrittore dello strumento e uno stretto tool_calls_begin / tool_call_begin formato. Un esempio minimo (concettuale):

## Tools

You have access to the following tools:

### web_search

Description: Query the web
Parameters: {"q": "string"}

<｜begin_of_sentence｜>{system prompt}

## Tools

...tool descriptions...

<｜User｜>Find the population of Tokyo<｜Assistant｜></think>
<｜tool_calls_begin｜><｜tool_call_begin｜>web_search<｜tool_sep｜>{"q":"population of Tokyo 2025"}<｜tool_call_end｜><｜tool_calls_end｜>

L'output dello strumento dovrebbe quindi essere reimmesso nel modello nel turno successivo seguendo il formato prescritto dal modello (vedere assets/search_tool_trajectory.html sulla pagina del modello per il flusso esatto). L'implementazione degli agenti richiede un'orchestrazione programmatica: chiama lo strumento → cattura il risultato → reinserisci il risultato nel contesto della chat esattamente come prescritto dal modello → chiama nuovamente il modello.

Suggerimenti pratici, risoluzione dei problemi e note di sicurezza (A cosa devo fare attenzione?)

I modelli di token sono rigorosi. Utilizzare il modello tokenizer.apply_chat_template o riprodurre l'esatto <think>/</think> token come mostrato. Una spaziatura errata o marcatori mancanti modificheranno il comportamento del modello.
Il formato dello strumento deve essere JSON valido. Il modello analizzerà gli argomenti dello strumento come JSON: un JSON non valido interromperà le chiamate dello strumento.
Compromessi di quantizzazione. Le quantizzazioni dinamiche/aggressive a 1 bit riducono lo spazio di archiviazione e la RAM, ma possono alterare leggermente la fedeltà numerica. Eseguite dei test sui vostri carichi di lavoro. Esistono quantizzazioni della community che riducono l'80% dell'utilizzo del disco (esempio di report: 720 GB → ~170 GB), ma convalidate sempre seguendo le istruzioni.
Compatibilità con Ollama. Alcune varianti di DeepSeek indicano Ollama v0.11.7 come richiesto per le funzionalità pre-rilascio: controllare la pagina del modello Ollama e aggiornare di conseguenza.

Esempio end-to-end: eseguire DeepSeek-V3.1 localmente con Thinking Mode (mini guida dettagliata)

Installa Ollama ed estrai il modello:

# install ollama per docs, then:

ollama pull deepseek-ai/DeepSeek-V3.1
ollama run deepseek-ai/DeepSeek-V3.1 &

Utilizza il tokenizzatore Python per comporre un prompt di riflessione:

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")

msgs = [
  {"role":"system","content":"You are a helpful assistant."},
  {"role":"user","content":"Plan a multi-step strategy to prototype a mobile app in 2 weeks."}
]
prompt = tokenizer.apply_chat_template(msgs, thinking=True, add_generation_prompt=True)

import requests
resp = requests.post("http://localhost:11434/api/generate", json={
    "model": "deepseek-ai/DeepSeek-V3.1",
    "prompt": prompt,
    "max_tokens": 400
})
print(resp.json())

Se il modello restituisce una chiamata allo strumento nel formato toolcall, analizza il JSON ed esegui lo strumento, quindi inserisci i risultati nel messaggio successivo in base ai modelli della scheda modello.

Come dovresti scegliere il tuo percorso di distribuzione?

Se vuoi il percorso più veloce per sperimentare: uso Ollama e gli esempi della scheda modello Hugging Face. Ollama nasconde molti dettagli infrastrutturali e fornisce un'API HTTP locale.
Se hai bisogno di costi inferiori/maggiore portabilità: utilizzare una comunità GGUF quantizzato artefatto e correre con llama.cpp or llama-serverLa quantizzazione consente di risparmiare spazio su disco e memoria, ma verifica l'accuratezza del carico di lavoro.
Se stai creando agenti o strumenti: seguire il modello della carta chiamata di strumento e al agente modelli esatti; orchestrare gli output degli strumenti nel contesto del modello.

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

Conclusione

DeepSeek-V3.1 introduce una filosofia di inferenza ibrida pratica (un checkpoint + comportamento di pensiero basato su modelli) che semplifica la sperimentazione di ragionamenti basati su catene di pensiero e l'utilizzo di strumenti di agenti, purché si rispettino i modelli di chat e i requisiti degli strumenti. Utilizzate la scheda modello Hugging Face e le note di rilascio di DeepSeek come prima tappa, scegliete un runtime locale (Ollama per semplicità, llama.cpp per il controllo) e testare build quantizzate per implementazioni locali pratiche.