DeepSeek e' diventato uno dei nomi piu' citati dell'IA per un motivo concreto: modelli capaci e tariffe tra le piu' basse del mercato. La buona notizia per chi sviluppa e' che le sue API sono compatibili con il formato OpenAI: chi ha gia' usato la libreria openai in Python si trova a casa, basta cambiare due righe. In questa guida vediamo come collegarsi, gestire lo streaming, usare il modello di ragionamento e ottenere output strutturato in JSON.

A chi serve e cosa otterrai

La guida e' per sviluppatori e smanettoni che vogliono integrare un modello linguistico potente e economico nelle proprie applicazioni o script. Al termine saprai autenticarti, fare una chiamata di chat, ricevere le risposte in streaming, sfruttare il modello "reasoner" per i problemi difficili e forzare un output JSON da dare in pasto ad altri programmi.

Prerequisiti

  • Python 3.9 o superiore installato.
  • Un account su platform.deepseek.com e una chiave API generata dal pannello (con un minimo di credito caricato).
  • Nozioni di base di Python; non serve esperienza pregressa con le API dei modelli.

Quale modello scegliere

Al momento DeepSeek offre due famiglie principali via API:

  • deepseek-v4-flash: veloce ed economico, adatto a riassunti, classificazioni, estrazioni e a tutti i compiti ad alto volume dove conta la rapidita'.
  • deepseek-v4-pro: il modello di punta, con capacita' di ragionamento esteso ("thinking") attivabile, indicato per problemi complessi, matematica, codice e analisi.

I vecchi alias deepseek-chat e deepseek-reasoner restano utilizzabili ma sono indicati come deprecati a partire dal 24 luglio 2026: meglio adottare subito i nomi nuovi. Prima scelta: deepseek-v4-flash per la maggior parte dei compiti, passando a deepseek-v4-pro quando serve davvero ragionare.

Passo 1 - Installazione e chiave API

DeepSeek usa lo stesso SDK di OpenAI. Installa la libreria:

pip install openai

Imposta la chiave come variabile d'ambiente, cosi' non finisce nel codice:

export DEEPSEEK_API_KEY="la-tua-chiave"

Su Windows (PowerShell) usa invece: setx DEEPSEEK_API_KEY "la-tua-chiave" e riapri il terminale.

Passo 2 - La prima chiamata

L'unica differenza rispetto a OpenAI e' il base_url:

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, conciso."},
        {"role": "user", "content": "Spiega in 3 righe cos'e' un database vettoriale."}
    ]
)

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

Risultato atteso: una spiegazione breve in italiano. Se ricevi un errore di autenticazione, controlla la chiave e il credito residuo sul pannello.

Le API di DeepSeek riusano l'SDK di OpenAI: cambia solo il base_url.

Passo 3 - Risposte in streaming

Per un'esperienza tipo chat, conviene ricevere il testo man mano che viene generato, invece di aspettare la risposta completa:

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Scrivi una breve email di benvenuto per un nuovo cliente."}],
    stream=True
)

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

Vedrai il testo comparire parola per parola. E' la stessa logica usata dalle interfacce dei chatbot per ridurre l'attesa percepita.

Passo 4 - Il modello di ragionamento

Per i problemi che richiedono passaggi logici - matematica, debug, pianificazione - conviene il modello pro con il ragionamento attivo. Con DeepSeek il modello produce una catena di pensiero interna e poi la risposta finale:

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content":
        "Un treno parte alle 9:40 e viaggia a 120 km/h per 2 ore e 15 minuti. "
        "A che ora arriva e quanti km percorre? Mostra il ragionamento."}]
)

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

Quando usarlo: solo dove il ragionamento serve davvero, perche' i modelli "thinking" sono piu' lenti e costosi. Per un semplice riassunto, deepseek-v4-flash e' la scelta giusta.

Passo 5 - Forzare un output JSON

Per integrare il modello in un programma serve spesso un output strutturato. Puoi richiedere esplicitamente il formato JSON:

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Rispondi solo con JSON valido."},
        {"role": "user", "content":
            "Estrai nome, citta' e professione da: 'Sono Luca, faccio l'architetto a Torino'."}
    ],
    response_format={"type": "json_object"}
)

import json
dati = json.loads(resp.choices[0].message.content)
print(dati)

Risultato atteso: un dizionario Python come {"nome": "Luca", "citta": "Torino", "professione": "architetto"}, pronto da salvare o elaborare. Indica sempre nel prompt i campi esatti che vuoi, per ridurre le sorprese.

Passo 6 - Controllare temperatura e lunghezza

Due parametri utili: temperature regola la creativita' (valori bassi, es. 0.2, per risposte deterministiche; alti, es. 1.0, per testi creativi) e max_tokens limita la lunghezza della risposta per contenere i costi.

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Dammi 3 nomi per una caffetteria."}],
    temperature=1.0,
    max_tokens=100
)

Errori comuni e soluzioni

  • 401 Authentication Error: chiave errata o assente. Verifica la variabile d'ambiente e la validita' della chiave nel pannello.
  • 402 Insufficient Balance: credito esaurito. DeepSeek e' a consumo: ricarica il saldo per continuare.
  • 429 Rate limit: troppe richieste ravvicinate. Inserisci una breve pausa o una logica di retry con backoff esponenziale.
  • JSON non valido: aggiungi response_format={"type": "json_object"} e ribadisci nel system prompt di rispondere solo con JSON.

Quando preferire DeepSeek e quando no

DeepSeek brilla quando contano costo e volume: pipeline di classificazione, estrazione dati, riassunti di massa. Per casi che richiedono integrazione profonda con un ecosistema (strumenti aziendali, agenti complessi, multimodalita' avanzata) i modelli di OpenAI, Anthropic e Google offrono ecosistemi piu' ricchi. Un consiglio pratico: poiche' l'API e' compatibile con OpenAI, puoi mantenere lo stesso codice e cambiare modello e base_url a seconda del compito, scegliendo di volta in volta il miglior rapporto qualita'-prezzo.

Come proseguire

Da qui puoi costruire applicazioni reali: un chatbot sul tuo sito, uno script che riassume PDF, un classificatore di email. Il passo successivo naturale e' combinare DeepSeek con un database vettoriale per un sistema RAG sui tuoi documenti, oppure inserirlo come modello dentro un'automazione n8n. La documentazione ufficiale di DeepSeek elenca tutti i parametri supportati e gli aggiornamenti sui modelli: tienila a portata di mano, perche' i nomi dei modelli e le funzioni evolvono rapidamente.