DeepSeek è diventato uno dei nomi più citati dell'IA per un motivo semplice: offre modelli vicini alla frontiera a una frazione del prezzo dei concorrenti americani. In questa guida imparerai a usare le API di DeepSeek V4 in Python da zero: come ottenere una chiave, fare la prima chiamata, attivare il ragionamento, ottenere output in JSON e usare lo streaming. Il bello è che le API DeepSeek sono compatibili con quelle di OpenAI, quindi userai librerie che probabilmente conosci già.
A chi serve e cosa otterrai
Questa guida è per sviluppatori, data analyst e curiosi con basi di Python che vogliono integrare un modello potente ed economico nelle proprie applicazioni. Alla fine avrai uno script funzionante che dialoga con DeepSeek, sai come gestire risposte strutturate e ragionamento passo-passo, e conosci i costi reali per non avere sorprese in bolletta.
Prerequisiti: Python 3.9 o superiore installato; un account su platform.deepseek.com con una chiave API; e qualche credito caricato (le API sono a consumo, ma molto economiche).
I modelli DeepSeek V4 in breve
DeepSeek V4, rilasciato in versione preview ad aprile 2026, è disponibile in due varianti principali, entrambe con una finestra di contesto da un milione di token e pubblicate a pesi aperti su Hugging Face con licenza MIT:
- DeepSeek-V4-Pro: il modello di punta, un'architettura Mixture-of-Experts da 1,6 trilioni di parametri totali (circa 49 miliardi attivi per token). È quello da usare per ragionamento complesso, codice e compiti difficili.
- DeepSeek-V4-Flash: più leggero (284 miliardi di parametri totali, circa 13 miliardi attivi), pensato per velocità e costi ancora più bassi su compiti ad alto volume.
Sul versante prezzi, DeepSeek-V4-Pro si aggira intorno a 0,44 dollari per milione di token in input (a cache vuota) e 0,87 dollari per milione di token in output, con un costo molto inferiore per i token serviti dalla cache di contesto. Sono ordini di grandezza: verifica sempre le tariffe aggiornate nella pagina ufficiale dei prezzi, perché possono cambiare.
Passo 1: installare la libreria e impostare la chiave
DeepSeek consiglia di usare la libreria ufficiale di OpenAI, perché le sue API ne replicano il formato. Installala con pip:
pip install openaiImposta la tua chiave come variabile d'ambiente, così da non scriverla mai nel codice (regola d'oro per la sicurezza):
export DEEPSEEK_API_KEY="la-tua-chiave"Passo 2: la prima chiamata
Ecco lo script minimo per dialogare con DeepSeek. Nota il parametro base_url: è l'unica vera differenza rispetto a una chiamata a OpenAI.
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", # modello generale (non-thinking)
messages=[
{"role": "system", "content": "Sei un assistente conciso e preciso."},
{"role": "user", "content": "Spiega in 3 punti cosa e' una Mixture-of-Experts."},
],
)
print(risposta.choices[0].message.content)Il risultato atteso è una risposta in tre punti, stampata a schermo. deepseek-chat è l'alias del modello generale; per i compiti più difficili puoi indicare direttamente deepseek-v4-pro.
Passo 3: attivare il ragionamento
Per problemi di matematica, logica o programmazione conviene usare la modalità «reasoner», che fa ragionare il modello passo per passo. La risposta espone sia la catena di ragionamento sia la conclusione finale:
risposta = client.chat.completions.create(
model="deepseek-reasoner",
messages=[
{"role": "user", "content": "Un treno percorre 240 km in 2 ore e 40 minuti. Qual e' la velocita' media in km/h? Mostra i passaggi."},
],
)
msg = risposta.choices[0].message
print("RAGIONAMENTO:\n", msg.reasoning_content)
print("\nRISPOSTA:\n", msg.content)Qui reasoning_content contiene il «pensiero» del modello, mentre content contiene la risposta pulita (in questo caso, 90 km/h). È utile per verificare il procedimento, ma ricorda che i token di ragionamento si pagano come output.
Passo 4: ottenere output strutturato in JSON
Se vuoi integrare DeepSeek in un'applicazione, spesso ti serve una risposta in JSON da elaborare automaticamente. Attivala con response_format e chiedi esplicitamente il JSON nel prompt:
import json
risposta = client.chat.completions.create(
model="deepseek-chat",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Rispondi solo con JSON valido."},
{"role": "user", "content": "Estrai nome, citta' e professione da: 'Marco vive a Torino e fa il geometra'. Usa le chiavi nome, citta, professione."},
],
)
dati = json.loads(risposta.choices[0].message.content)
print(dati["nome"], "-", dati["citta"], "-", dati["professione"])Il risultato atteso è un dizionario Python con i tre campi popolati. DeepSeek-V4 supporta nativamente l'output strutturato e il function calling, quindi puoi anche collegarlo a strumenti esterni.
Passo 5: streaming per risposte in tempo reale
Per un'interfaccia tipo chat, conviene ricevere la risposta «parola per parola» invece di aspettare il testo completo. Basta aggiungere stream=True:
flusso = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "Scrivi una breve poesia sulla primavera."}],
stream=True,
)
for blocco in flusso:
pezzo = blocco.choices[0].delta.content
if pezzo:
print(pezzo, end="", flush=True)Errori comuni e soluzioni
| Errore | Soluzione |
|---|---|
AuthenticationError / 401 | Chiave assente o errata: controlla la variabile d'ambiente DEEPSEEK_API_KEY. |
402 Insufficient Balance | Credito esaurito: ricarica dal pannello DeepSeek. |
RateLimitError / 429 | Troppe richieste: introduci una pausa o un meccanismo di retry con backoff. |
| JSON non valido in output | Specifica response_format e chiedi JSON nel prompt; valida con try/except. |
Quando usare DeepSeek (e quando no)
DeepSeek è un'ottima scelta quando il fattore prezzo conta molto: applicazioni ad alto volume, elaborazione di grandi quantità di testo, prototipi dove vuoi contenere i costi. Grazie ai pesi aperti su Hugging Face, è anche valido per chi vuole l'opzione di eseguire il modello in proprio o evitare il lock-in. Va invece valutato con attenzione per dati particolarmente sensibili: i server DeepSeek sono in Cina e questo può avere implicazioni di conformità (ad esempio rispetto al GDPR) per molte aziende europee. In quei casi conviene usare i pesi aperti su infrastruttura propria, oppure scegliere fornitori con server in UE.
Come proseguire
Da qui puoi costruire molto: un chatbot, un estrattore di dati da documenti, un agente che usa strumenti esterni via function calling. Un buon passo successivo è collegare DeepSeek a un sistema di retrieval sui tuoi documenti (RAG) per rispondere su contenuti privati, oppure confrontarne le risposte con quelle di altri modelli per scegliere il migliore per il tuo caso d'uso. La documentazione ufficiale di DeepSeek è il riferimento per parametri avanzati, limiti di rate e gestione della cache di contesto, che ti permette di abbattere ulteriormente i costi sulle conversazioni lunghe.
Tutti gli esempi di codice sono stati scritti seguendo il formato OpenAI-compatibile documentato da DeepSeek; prezzi e nomi dei modelli vanno verificati sulla documentazione ufficiale, in continuo aggiornamento.
