DeepSeek e' diventato uno dei modi piu' economici per integrare un modello linguistico di buon livello nelle proprie applicazioni. Con il rilascio della famiglia V4, l'azienda cinese offre un'API compatibile con il formato OpenAI, prezzi molto bassi e un modello di ragionamento dedicato. In questa guida vedremo, passo per passo, come usarla in Python: dalla prima chiamata alla chat, al modello di ragionamento, fino all'output JSON e al function calling.

A chi serve e cosa ti serve prima di iniziare

Questa guida e' pensata per chi sa programmare un minimo in Python e vuole costruire chatbot, assistenti o automazioni a basso costo. Prerequisiti:

  • Python 3.9 o superiore installato.
  • Un account su platform.deepseek.com e una chiave API (la trovi nella sezione API keys; ricorda di copiarla subito, viene mostrata una sola volta).
  • Un piccolo credito sul conto: DeepSeek funziona a consumo, ma le tariffe sono molto contenute.

Quale modello scegliere

Con la generazione V4 i modelli principali sono due:

  • deepseek-v4-flash: veloce ed economico, ideale per chat, classificazione, estrazione dati, riassunti. E' la prima scelta per la maggior parte dei casi.
  • deepseek-v4-pro: piu' capace, adatto a compiti complessi e ragionamento articolato.

I vecchi identificativi deepseek-chat e deepseek-reasoner restano supportati per compatibilita'. A titolo indicativo, deepseek-v4-flash costa circa 0,14 dollari per milione di token in input (con tariffa molto piu' bassa sulla cache) e 0,28 dollari in output; la versione Pro costa di piu' ma resta competitiva. Sono prezzi che, per progetti personali, si traducono spesso in pochi centesimi al giorno. Verifica sempre i valori aggiornati nella documentazione ufficiale.

L'API di DeepSeek e' compatibile con l'SDK ufficiale di OpenAI.

Passo 1: installazione e prima chiamata

Poiche' l'API e' compatibile con OpenAI, useremo direttamente l'SDK ufficiale, cambiando solo il base_url. Installa la libreria:

pip install openai

Per non scrivere la chiave nel codice, salvala in una variabile d'ambiente (su Linux/macOS: export DEEPSEEK_API_KEY="sk-..."). Poi:

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-v4-flash",
    messages=[
        {"role": "system", "content": "Sei un assistente che risponde in italiano, in modo conciso."},
        {"role": "user", "content": "Spiega cos'e' un token in un LLM, in 2 frasi."},
    ],
)
print(risposta.choices[0].message.content)

Se tutto e' configurato bene, vedrai una risposta di due frasi in italiano. Hai appena fatto la tua prima chiamata.

Passo 2: il modello di ragionamento

Per problemi che richiedono passaggi logici (matematica, debugging, pianificazione) conviene il modello Pro, che espone anche la "catena di pensiero" in un campo separato. Cosi' puoi mostrare il risultato finale all'utente senza inondarlo del ragionamento intermedio:

r = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Un treno percorre 240 km in 3 ore. Se aumenta la velocita' del 25%, quanto impiega per 300 km?"}],
)
msg = r.choices[0].message
# il ragionamento, quando disponibile, e' in reasoning_content
print("Ragionamento:", getattr(msg, "reasoning_content", "(non esposto)"))
print("Risposta:", msg.content)

Passo 3: forzare un output JSON

Quando il modello deve "parlare" con il tuo programma, ti serve un formato strutturato. Imposta response_format a json_object e chiedi esplicitamente il JSON nel prompt:

import json

r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Rispondi SOLO con JSON valido."},
        {"role": "user", "content": "Estrai nome, citta' e eta' da: 'Mi chiamo Luca, ho 34 anni e vivo a Bologna'. Campi: nome, citta', eta'."},
    ],
    response_format={"type": "json_object"},
)
dati = json.loads(r.choices[0].message.content)
print(dati["nome"], dati["citta"], dati["eta"])

Risultato atteso: un dizionario Python con i tre campi correttamente estratti. Ricorda di indicare sempre nel prompt che vuoi JSON, altrimenti l'attivazione del formato puo' fallire.

Passo 4: function calling (gli "strumenti")

Il function calling permette al modello di chiederti di eseguire una funzione del tuo codice, ad esempio per consultare un meteo, un database o un'API esterna. Definisci lo strumento, poi gestisci la chiamata:

def meteo(citta):
    # qui chiameresti una vera API; restituiamo un valore finto
    return {"citta": citta, "gradi": 21, "cielo": "sereno"}

tools = [{
    "type": "function",
    "function": {
        "name": "meteo",
        "description": "Ottiene il meteo attuale di una citta'",
        "parameters": {
            "type": "object",
            "properties": {"citta": {"type": "string"}},
            "required": ["citta"],
        },
    },
}]

messaggi = [{"role": "user", "content": "Che tempo fa a Napoli?"}]
r = client.chat.completions.create(model="deepseek-v4-flash", messages=messaggi, tools=tools)
chiamata = r.choices[0].message.tool_calls[0]
args = json.loads(chiamata.function.arguments)
risultato = meteo(args["citta"])

# rimanda il risultato al modello per la risposta finale
messaggi.append(r.choices[0].message)
messaggi.append({"role": "tool", "tool_call_id": chiamata.id, "content": json.dumps(risultato)})
finale = client.chat.completions.create(model="deepseek-v4-flash", messages=messaggi, tools=tools)
print(finale.choices[0].message.content)

Il modello, invece di inventare il meteo, ti chiede di eseguire la funzione meteo e poi compone una risposta in linguaggio naturale usando i dati reali che gli hai restituito. Questo schema (richiesta, esecuzione, risposta) e' la base di qualsiasi agente.

Errori comuni e soluzioni

  • 401 Authentication Error: la chiave non e' corretta o non e' stata caricata. Controlla la variabile d'ambiente e che non ci siano spazi.
  • 402 Insufficient Balance: il credito e' esaurito. Ricarica dal pannello DeepSeek.
  • JSON non valido: hai dimenticato di scrivere nel prompt che vuoi JSON, oppure non hai impostato response_format. Fai entrambe le cose.
  • 429 Rate limit: troppe richieste in poco tempo. Inserisci una breve attesa tra le chiamate o gestisci i tentativi con backoff.

Come proseguire

Da qui puoi costruire un piccolo assistente da terminale, collegare DeepSeek a un'interfaccia web o integrarlo in un'automazione. Poiche' l'API e' compatibile con OpenAI, lo stesso codice funziona, cambiando base_url e modello, anche con altri provider: questo ti permette di confrontare costi e qualita' senza riscrivere l'applicazione. Per progetti che gestiscono dati sensibili, valuta invece un modello eseguito in locale, ad esempio con Ollama. Il prossimo passo naturale e' aggiungere piu' strumenti e una memoria della conversazione, trasformando lo script in un vero agente.