DeepSeek V4 e' uno dei modelli con il miglior rapporto qualita'-prezzo sul mercato, e integrarlo nei propri programmi e' sorprendentemente semplice: l'API e' compatibile con lo standard OpenAI, quindi chi ha gia' lavorato con GPT si trova subito a casa. Questa guida accompagna passo passo dalla creazione della chiave al primo script funzionante, fino a ragionamento, streaming, cache e gestione degli errori.

A chi serve e cosa ti occorre

La guida e' per sviluppatori e smanettoni che vogliono automatizzare compiti con l'IA: chatbot, riassunti, estrazione dati, assistenti al codice. Prerequisiti: Python 3.8 o superiore installato, un minimo di dimestichezza con il terminale e un account su DeepSeek. Non serve GPU: il modello gira sui server di DeepSeek, tu invii richieste via internet.

Passo 1: creare la chiave API e caricare credito

Vai su platform.deepseek.com, registrati e apri la sezione API Keys. Crea una nuova chiave e copiala subito: non sara' piu' visibile per intero in seguito. L'uso delle API e' a consumo, quindi dovrai caricare un piccolo credito iniziale; le tariffe di DeepSeek sono tra le piu' basse in circolazione, per cui bastano pochi euro per settimane di test. Non inserire mai la chiave direttamente nel codice condiviso: usala come variabile d'ambiente.

# Linux / macOS
export DEEPSEEK_API_KEY="la_tua_chiave"

# Windows (PowerShell)
setx DEEPSEEK_API_KEY "la_tua_chiave"

Passo 2: installare la libreria e il primo script

DeepSeek consiglia la libreria ufficiale openai, che grazie alla compatibilita' funziona semplicemente cambiando l'indirizzo di base:

pip install openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com"
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Sei un assistente che risponde in italiano."},
        {"role": "user", "content": "Riassumi in 3 punti la trama de I Promessi Sposi."}
    ],
    temperature=0.7
)
print(resp.choices[0].message.content)

Esegui con python nome_file.py: dopo un paio di secondi vedrai comparire il riassunto in tre punti. Hai appena fatto la tua prima chiamata a un modello di frontiera.

Passo 3: attivare il ragionamento esteso

Per problemi complessi — matematica, logica, codice difficile — conviene la variante Pro con la modalita' di ragionamento. Basta cambiare il nome del modello:

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Un treno parte da Milano alle 9:00 a 120 km/h, un altro da Roma alle 9:30 a 150 km/h sullo stesso binario (574 km). A che ora e dove si incontrano?"}
    ]
)
# Alcune versioni espongono il ragionamento separato:
msg = resp.choices[0].message
print(getattr(msg, "reasoning_content", ""))  # catena di pensiero (se presente)
print(msg.content)                             # risposta finale

Il modello mostra il ragionamento passo passo e poi la soluzione. Attenzione: la modalita' Pro consuma piu' token (quindi costa di piu') perche' «pensa» prima di rispondere. Usala solo dove serve davvero.

L'API di DeepSeek e' compatibile con lo standard OpenAI: si cambia solo l'indirizzo di base.

Passo 4: streaming e cache di contesto

Per un'esperienza tipo chatbot — le parole che appaiono man mano — attiva lo streaming:

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Scrivi una filastrocca sull'autunno."}],
    stream=True
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Un vantaggio spesso trascurato e' la cache di contesto: DeepSeek riconosce automaticamente le parti di prompt gia' viste (ad esempio istruzioni di sistema ripetute o documenti riutilizzati) e le fa pagare una frazione minima, con uno sconto che arriva intorno al 90%. Per applicazioni che rimandano sempre lo stesso «contesto» — un manuale, uno storico di conversazione — il risparmio e' enorme e non richiede alcuna configurazione: basta tenere le parti fisse all'inizio dei messaggi.

Passo 5: gestire gli errori piu' comuni

  • 401 Unauthorized → chiave errata o non caricata: controlla la variabile d'ambiente.
  • 402 Insufficient Balance → credito esaurito: ricarica dalla dashboard.
  • 429 Rate limit / Too Many Requests → troppe richieste: inserisci un breve ritardo e riprova con backoff progressivo.
  • Timeout → su risposte lunghe con la Pro, aumenta il timeout del client o usa lo streaming.

Un blocco try/except attorno alla chiamata, con un paio di tentativi ripetuti in caso di 429, e' sufficiente per rendere robusto uno script di produzione. Ecco uno schema minimo con backoff progressivo:

import time
from openai import APIError, RateLimitError

def chiama(messaggi, tentativi=4):
    for i in range(tentativi):
        try:
            return client.chat.completions.create(
                model="deepseek-v4-flash", messages=messaggi
            )
        except RateLimitError:
            time.sleep(2 ** i)   # 1s, 2s, 4s, 8s
        except APIError as e:
            print("Errore API:", e)
            break
    return None

Costruire una chat a piu' turni

Per un assistente che «ricorda» la conversazione, basta accumulare i messaggi in una lista e rimandarla a ogni giro. E' cosi' che funziona qualsiasi chatbot:

storia = [{"role": "system", "content": "Sei un tutor di matematica paziente."}]
while True:
    domanda = input("Tu: ")
    if domanda.lower() in ("esci", "quit"):
        break
    storia.append({"role": "user", "content": domanda})
    r = client.chat.completions.create(model="deepseek-v4-flash", messages=storia)
    risposta = r.choices[0].message.content
    print("IA:", risposta)
    storia.append({"role": "assistant", "content": risposta})

Attenzione a un dettaglio economico: piu' cresce la conversazione, piu' token invii a ogni turno (paghi tutto lo storico). Qui la cache di contesto aiuta molto, perche' le parti iniziali gia' viste costano una frazione. Per conversazioni molto lunghe conviene comunque «riassumere» periodicamente i turni piu' vecchi in un unico messaggio, per non far lievitare i costi.

Avvertenza: la migrazione dai vecchi modelli

Se in passato hai usato i nomi deepseek-chat e deepseek-reasoner, sappi che sono dismessi dal 24 luglio 2026. Corrispondono rispettivamente alle modalita' non-thinking e thinking di V4-Flash: aggiorna i nomi dei modelli a deepseek-v4-flash e deepseek-v4-pro per non ritrovarti con le chiamate bloccate.

Quando scegliere DeepSeek (e quando no)

DeepSeek e' la scelta giusta quando il costo conta molto (volumi elevati, budget limitato), quando vuoi la possibilita' di passare in futuro all'esecuzione in locale grazie ai pesi aperti con licenza MIT, o quando ti serve un contesto lunghissimo a poco prezzo. Restano invece ragioni per preferire altri fornitori: se hai bisogno di funzioni molto specifiche dell'ecosistema OpenAI o Anthropic, di garanzie contrattuali particolari sul trattamento dei dati, o di modelli specializzati in compiti dove i concorrenti sono ancora avanti. La buona notizia della compatibilita' con lo standard OpenAI e' che provare costa pochissimo: puoi affiancare DeepSeek al tuo stack attuale cambiando due righe e confrontare qualita' e prezzo sui tuoi casi reali.

Riferimenti: la documentazione ufficiale delle API DeepSeek e la piattaforma sviluppatori, dove verificare sempre nomi dei modelli e prezzi aggiornati.