I modelli di DeepSeek sono tra i più interessanti per chi sviluppa: buone prestazioni, costi bassi e — dettaglio comodissimo — un'API compatibile con quella di OpenAI. Questo significa che puoi usarli con la stessa libreria e lo stesso codice che useresti per ChatGPT, cambiando solo due righe. In questa guida vediamo passo passo come integrarli in Python.

Il tutorial è adatto a chi conosce le basi di Python. Alla fine saprai autenticarti, inviare messaggi, ricevere risposte in streaming, usare il modello di ragionamento, ottenere output in JSON e tenere sotto controllo i costi.

A chi serve e cosa ti serve prima di iniziare

  • Un account DeepSeek e una chiave API, che si crea gratuitamente da platform.deepseek.com. Nota: l'uso dell'API è a consumo, quindi serve caricare un piccolo credito; le tariffe sono comunque molto contenute.
  • Python 3.8 o superiore installato sul computer.
  • Dimestichezza di base con il terminale e con l'esecuzione di script Python.

Quali modelli userai? DeepSeek espone due modelli principali via API: deepseek-chat, il modello conversazionale generico, e deepseek-reasoner, pensato per i problemi che richiedono ragionamento passo-passo (matematica, logica, codice complesso). Il primo è più veloce ed economico; il secondo è più accurato sui compiti difficili ma più lento e costoso. La regola pratica: parti da deepseek-chat e passa al reasoner solo quando serve davvero.

Passo 1: installare la libreria e proteggere la chiave

Installa la libreria ufficiale di OpenAI, che useremo per parlare con DeepSeek:

pip install openai

Non scrivere mai la chiave API dentro il codice che condividi. Il metodo corretto è salvarla in una variabile d'ambiente:

# su Linux/macOS
export DEEPSEEK_API_KEY="la_tua_chiave"

# su Windows (PowerShell)
setx DEEPSEEK_API_KEY "la_tua_chiave"

Passo 2: il primo script

Ecco lo scheletro minimo. L'unica differenza rispetto a OpenAI è il parametro base_url, che punta ai server di DeepSeek:

import os
from openai import OpenAI

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

risposta = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "Sei un assistente esperto di cucina italiana."},
        {"role": "user", "content": "Suggeriscimi un primo veloce con 4 ingredienti."}
    ],
    temperature=0.7
)

print(risposta.choices[0].message.content)

Il messaggio system definisce il "ruolo" dell'assistente; i messaggi user sono le domande. Il parametro temperature regola la creatività: valori bassi (0-0,3) per risposte precise e ripetibili, valori alti (0,7-1) per risposte più varie. Risultato atteso: una ricetta breve e pertinente, in italiano.

Passo 3: risposte in streaming

Per un'esperienza tipo "chat", conviene ricevere la risposta parola per parola invece di aspettare l'intero blocco. Basta aggiungere stream=True:

flusso = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Scrivi una filastrocca sull'estate."}],
    stream=True
)

for pezzo in flusso:
    contenuto = pezzo.choices[0].delta.content
    if contenuto:
        print(contenuto, end="", flush=True)

Vedrai il testo comparire progressivamente sul terminale, come accade nelle interfacce chat.

Passo 4: il modello di ragionamento

Per i problemi complessi, deepseek-reasoner genera prima una catena di ragionamento e poi la risposta finale. Puoi accedere separatamente ai due contenuti:

r = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user",
               "content": "Un treno percorre 240 km in 3 ore. Qual e' la velocita' media? Ragiona."}]
)

msg = r.choices[0].message
print("RAGIONAMENTO:\n", getattr(msg, "reasoning_content", ""))
print("\nRISPOSTA:\n", msg.content)

Consiglio: non passare tu stesso il ragionamento come input nei turni successivi; reinserisci solo la risposta finale, altrimenti sprechi token e confondi il modello.

Passo 5: ottenere output in JSON

Se ti serve una risposta strutturata da usare nel codice, chiedi esplicitamente il formato JSON:

r = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "Rispondi solo con JSON valido."},
        {"role": "user", "content": "Estrai nome e citta' da: 'Sono Luca, vivo a Torino'."}
    ],
    response_format={"type": "json_object"}
)
print(r.choices[0].message.content)   # es. {"nome": "Luca", "citta": "Torino"}

Ricordati di validare comunque il JSON nel tuo programma, per gestire i casi in cui il modello devia dal formato.

Tenere sotto controllo i costi

Ogni chiamata consuma "token" (all'incirca frammenti di parole) sia in input sia in output, e paghi per entrambi. Alcune buone pratiche:

  • Usa deepseek-chat per default e il reasoner solo quando indispensabile.
  • Limita la lunghezza delle risposte con il parametro max_tokens.
  • Non inviare cronologie infinite: riassumi i turni precedenti quando la conversazione si allunga.
  • Ricorda che DeepSeek applica tariffe più alte nelle ore di punta: per i lavori non urgenti (elaborazioni batch) conviene programmarli nelle fasce più economiche.

Errori comuni e soluzioni

  • 401 Unauthorized: la chiave è sbagliata o non caricata. Controlla la variabile d'ambiente e di aver rigenerato la chiave se necessario.
  • 402 / Insufficient Balance: credito esaurito. Ricarica dal pannello di DeepSeek.
  • 429 Rate limit: troppe richieste in poco tempo. Inserisci una pausa tra le chiamate o una logica di ripetizione con attesa progressiva.
  • Timeout su prompt lunghi: con contesti molto grandi, aumenta il timeout del client e valuta di spezzare il compito.

Quando usare DeepSeek e quando un'alternativa

DeepSeek è un'ottima scelta quando conta il rapporto qualità-prezzo, per prototipi, automazioni e analisi di grandi volumi di testo. Trattandosi però di un servizio con sede in Cina, per dati personali o aziendali sensibili valuta con attenzione dove vengono elaborati i contenuti e le implicazioni sulla privacy: in questi casi possono essere preferibili modelli eseguiti in locale (con Ollama o LM Studio) o fornitori europei. Il bello dell'API compatibile con OpenAI è che il tuo codice resta quasi identico: cambiare fornitore, se serve, richiede solo di modificare base_url e nome del modello.

Costruire un mini-assistente con memoria della conversazione

Finora abbiamo inviato messaggi singoli. Un vero assistente, pero', deve ricordare i turni precedenti. Il meccanismo e' semplice: mantieni tu una lista di messaggi e la reinvii a ogni chiamata, aggiungendo di volta in volta la nuova domanda dell'utente e la risposta del modello. Ecco un esempio completo di chatbot da terminale:

import os
from openai import OpenAI

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

storia = [{"role": "system", "content": "Sei un tutor di italiano 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-chat", messages=storia)
    risposta = r.choices[0].message.content
    print("IA:", risposta)
    storia.append({"role": "assistant", "content": risposta})

La chiave e' la lista storia: contiene l'intera conversazione e viene passata a ogni giro, cosi' il modello mantiene il contesto. Attenzione pero': piu' la lista cresce, piu' token consumi. Per conversazioni lunghe conviene "tagliare" i messaggi piu' vecchi o sostituirli con un breve riassunto, cosi' da contenere i costi senza perdere il filo del discorso.

Integrare DeepSeek in un'applicazione reale

Il salto dallo script al prodotto richiede qualche attenzione in piu'. Primo: non esporre mai la chiave API nel codice che gira sul dispositivo dell'utente (per esempio in una pagina web o in un'app): le chiamate vanno fatte da un tuo server, che custodisce la chiave. Secondo: gestisci sempre gli errori di rete con una logica di ripetizione, perche' le API remote possono restituire errori temporanei. Terzo: registra un log dei consumi per non avere sorprese in bolletta. Infine, poiche' l'API di DeepSeek e' compatibile con lo standard OpenAI, molti framework di sviluppo per applicazioni IA — dalle librerie per gli agenti a quelle per la ricerca sui documenti (RAG) — funzionano subito, indicando semplicemente l'endpoint di DeepSeek. Questo ti lascia liberta' di scelta: puoi iniziare con un fornitore e cambiarlo in futuro senza riscrivere l'intera applicazione.