◆ IA in Azienda — Implementare l'IA locale sul lavoro: RGPD, AI Act, costi · 24 € · o tutti i kit 49 € →

#DeepSeek API: l'essenziale prima di iniziare

DeepSeek offre due porte d'ingresso che non devi confondere. Il sito di chat, gratuito, si usa in un browser. L'API, invece, è destinata agli sviluppatori: il tuo programma invia una richiesta, i server di DeepSeek restituiscono una risposta e il costo di ogni scambio viene scalato dal tuo saldo. Questa guida tratta la seconda porta d'ingresso.

Cos'è: Un servizio con pagamento a consumo, ospitato da DeepSeek. Non scarichi nulla: il modello gira presso il fornitore.
Il formato: Compatibile con l'API di OpenAI. Le librerie e gli strumenti che parlano a OpenAI funzionano modificando due parametri: l'indirizzo base e la chiave.
Fatturazione: Per token, su un saldo prepagato. Il tariffario distingue i token inviati, a seconda che siano già in cache o meno, e i token generati.
I tuoi dati: Ogni richiesta lascia la tua infrastruttura e viene elaborata sui server del fornitore. È il punto da esaminare per primo se gestisci dati personali o riservati.
L'alternative: DeepSeek pubblica anche i pesi dei suoi modelli. Una versione adatta al tuo hardware può girare sul tuo computer, senza fatturazione per token né invio di dati.

Perché questa guida non contiene prezzi

Una tariffa copiata in un articolo diventa errata il giorno in cui il fornitore modifica il proprio listino, e nulla te lo segnala. Anziché mostrare importi destinati a diventare obsoleti, questa guida ti insegna a leggere la pagina ufficiale e a fare il calcolo con i dati del giorno. Diffida di qualsiasi tabella dei prezzi DeepSeek che non indichi né la fonte né la data di rilevazione.

#Prerequisiti

Il kit IA Locale in Azienda

Implementare un'IA locale sul lavoro: GDPR, AI Act, architettura multiutente, costi, nota per la direzione.

Spazio online a vita
PDF + file
Aggiornamenti a vita

Il kit IA in azienda →o tutti i kit a vita — 49 € →

Un account sviluppatore: Viene creato sulla piattaforma di DeepSeek, all'indirizzo platform.deepseek.com. Non è lo stesso indirizzo del sito di discussione.
Un mezzo di pagamento: Il servizio funziona con un saldo che ricarichi in anticipo. Senza saldo disponibile, le chiamate vengono rifiutate.
Un tool per chiamare l'API: curl suffit pour un premier essai. Pour un vrai projet, Python 3 avec la bibliothèque openai, ou son équivalent pour Node.js.
Un posto sicuro per la chiave: Una variabile d'ambiente sul tuo computer, un gestore di segreti in produzione. Mai nel codice sorgente.

#Crea una chiave DeepSeek API

01
Aprire un account sulla piattaforma
Vai su platform.deepseek.com digitando tu stesso l'indirizzo, poi registrati. Per un uso professionale, usa un indirizzo condiviso del team invece di un indirizzo personale: l'account contiene il saldo e le chiavi e deve restare utilizzabile anche dopo l'uscita di un collega dal team.
02
Ricaricare il saldo
La sezione di ricarica della piattaforma permette di aggiungere credito. Inizia con un piccolo importo: è ampiamente sufficiente per le prove e limita automaticamente la spesa se un ciclo scritto male va fuori controllo.
03
Genera la chiave
Nella sezione delle chiavi API, crea una nuova chiave e dalle un nome che ne indichi l'uso (« essais-poste-clara », « prod-support »). Copiala subito: come sulla maggior parte delle piattaforme, viene mostrata per intero solo al momento della creazione.
04
Mettere la chiave fuori dal codice
Inseriscila in una variabile d'ambiente. Il tuo programma la leggerà all'avvio e non finirà né in un repository Git né in uno screenshot.

Pagina di gestione delle chiavi (account richiesto)

https://platform.deepseek.com/api_keys

Terminale (Linux, macOS)

export DEEPSEEK_API_KEY="collez-votre-cle-ici"

PowerShell (Windows)

$env:DEEPSEEK_API_KEY = "collez-votre-cle-ici"

Una chiave è un mezzo di pagamento

Chiunque possieda la tua chiave spende il tuo saldo. Crea una chiave per progetto per poterne revocare una senza interrompere gli altri, non inserirla mai nel codice JavaScript eseguito dal browser né in un'applicazione mobile ed eliminala dalla piattaforma al minimo sospetto che sia stata divulgata.

#Prima chiamata: il formato compatibile con OpenAI

L'indirizzo di base dell'API è https://api.deepseek.com. La chiave viene trasmessa nell'intestazione Authorization, preceduta dalla parola Bearer. Prima di inviare una domanda, inizia richiedendo l'elenco dei modelli che la tua chiave può chiamare: gli identificatori cambiano da una generazione all'altra, ed è l'unico elenco aggiornato per sua stessa natura.

Terminale: elencare i modelli disponibili

curl https://api.deepseek.com/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

La risposta è un oggetto JSON in cui ogni voce contiene un campo id. È questo identificativo, copiato esattamente com'è, che devi inserire nelle tue richieste. Molti tutorial usano i nomi storici deepseek-chat e deepseek-reasoner: prima di riutilizzarli, verifica che siano effettivamente presenti nell'elenco restituito e leggi sulla pagina dei prezzi a quale modello corrisponde oggi ciascun nome.

Terminale: prima domanda

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "IDENTIFIANT_DU_MODELE",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, en trois phrases maximum."},
      {"role": "user", "content": "Explique la notion de token pour un modèle de langage."}
    ],
    "stream": false
  }'

In Python, la libreria ufficiale di OpenAI fa al caso tuo. Rispetto a una chiamata a OpenAI, cambiano solo due parametri: la chiave e l'indirizzo di base.

Terminale

pip install openai

premier_appel.py

import os
from openai import OpenAI

MODELE = "IDENTIFIANT_DU_MODELE"  # un id renvoyé par /models

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

reponse = client.chat.completions.create(
    model=MODELE,
    messages=[
        {"role": "system", "content": "Tu réponds en français, en trois phrases maximum."},
        {"role": "user", "content": "Explique la notion de token pour un modèle de langage."},
    ],
)

print(reponse.choices[0].message.content)
print(reponse.usage)  # le décompte qui sert à la facturation

L'ultima riga è la più utile per il seguito. L'oggetto usage indica quanti token hai inviato (prompt_tokens) e quanti ne ha generati il modello (completion_tokens). La documentazione della cache del contesto descrive due campi aggiuntivi, prompt_cache_hit_tokens e prompt_cache_miss_tokens, che distinguono i token di input già presenti nella cache da quelli che non lo erano. Visualizza l'oggetto restituito dalla tua chiamata: è quello che fa fede, non un esempio.

#Tariffe dell'API DeepSeek: leggere la tabella ufficiale

Tutti i prezzi si trovano su un'unica pagina della documentazione. Aprila accanto a questa guida: i paragrafi successivi spiegano che cosa significa ogni riga, non quale sia il relativo prezzo.

Listino ufficiale (Models & Pricing)

https://api-docs.deepseek.com/quick_start/pricing/

La griglia si presenta come una tabella, con una colonna per ogni modello. I prezzi sono espressi per milione di token. Per un testo francese comune, un token rappresenta un po' meno di una parola, ma il rapporto varia in base al modello e al contenuto: per il conteggio, fai riferimento all'oggetto usage delle tue risposte piuttosto che a una regola di conversione.

Input, mancata corrispondenza nella cache (cache miss): Il prezzo normale dei token che invii: istruzioni di sistema, cronologia della conversazione, documenti allegati, domanda.
Input, dati trovati nella cache (cache hit): Un prezzo ridotto applicato alla parte della tua richiesta che il servizio ha già elaborato di recente e conservato in cache.
Uscita (output): Il costo dei token generati dal modello. Confronta questa riga con quella dell'ingresso: nelle API di questo tipo, solitamente è la più elevata.
Token di ragionamento: Un modello in modalità ragionamento scrive una riflessione prima di rispondere. Controlla la pagina per capire come vengono contati questi token: se vengono fatturati come output, una risposta di tre righe può costare il prezzo di una pagina.
Contesto e output massimi: La stessa tabella indica la lunghezza del contesto e la dimensione massima di una risposta. Non sono prezzi, ma fissano un limite al costo possibile di una richiesta.
Valuta: Prendi nota della valuta visualizzata. Se il listino non è in euro, tieni conto del tasso di cambio e delle eventuali commissioni della tua banca sulle ricariche.

#La cache del contesto, principale fonte di differenze

La cache funziona per prefisso: se l'inizio di una richiesta è identico all'inizio di una richiesta recente, questa parte comune viene fatturata alla tariffa ridotta. Non devi attivare nulla. Tuttavia, l'ordine in cui costruisci la richiesta determina quanto paghi.

Prima i contenuti stabili: Metti all'inizio ciò che non cambia da una chiamata all'altra: istruzione di sistema, esempi, documento di riferimento.
Variabile alla fine: La domanda dell'utente, la data e un identificativo di sessione vanno in fondo. Una data inserita nella prima riga basta a rendere ogni richiesta unica e quindi a perdere il beneficio della cache.
Misurare piuttosto che supporre: La cache non è una garanzia. La quota effettivamente raggiunta si legge nei campi relativi alla cache dell'oggetto usage. Se rimane vicina a zero nonostante le tue richieste siano simili, devi rivedere il modo in cui costruisci le richieste.

#Fasce orarie di minore utilizzo e sconti temporanei

Un listino API può prevedere una tariffa ridotta in una fascia oraria o durante un periodo di lancio. Prima di tenerne conto in un budget, sono necessarie tre verifiche.

Lo sconto è indicato sulla pagina oggi?: Se la pagina ufficiale non menziona né una fascia oraria né uno sconto, considera che non ce ne siano. Non pianificare un budget sulla base di uno sconto letto in un vecchio articolo.
In quale fuso orario?: Le fasce orarie sono generalmente indicate in UTC. In Francia metropolitana, aggiungi un'ora in inverno e due in estate.
Puoi spostare il tuo carico di lavoro ad altri orari?: Una fascia oraria di bassa domanda avvantaggia solo le elaborazioni che possono aspettare: riassunti notturni, classificazione di documenti, generazione in batch. Un assistente che risponde ai clienti durante il giorno non ne trarrà alcun beneficio.

#Il calcolo, con i tuoi numeri

Il costo di una chiamata è la somma di tre prodotti: token di input non in cache, token di input in cache e token di output, ciascuno moltiplicato per il proprio prezzo e poi diviso per un milione. La funzione qui sotto applica questa formula all'oggetto usage di una risposta. I tre prezzi sono lasciati a zero: copiali tu stesso dalla pagina ufficiale, per il modello che stai chiamando.

cout_appel.py

# Prix par million de tokens, à recopier depuis la page officielle
# Relevé le : (notez la date ici)
PRIX_ENTREE_CACHE_MANQUE = 0.0
PRIX_ENTREE_CACHE_ATTEINT = 0.0
PRIX_SORTIE = 0.0

def cout_appel(usage):
    en_cache = getattr(usage, "prompt_cache_hit_tokens", 0) or 0
    hors_cache = usage.prompt_tokens - en_cache
    total = (
        hors_cache * PRIX_ENTREE_CACHE_MANQUE
        + en_cache * PRIX_ENTREE_CACHE_ATTEINT
        + usage.completion_tokens * PRIX_SORTIE
    )
    return total / 1_000_000

# Exemple : print(cout_appel(reponse.usage))

→

Annota la data della rilevazione

Annota la data accanto ai tre prezzi nel tuo file di configurazione e rileggi la pagina ufficiale una volta al mese o prima di ogni decisione di budget. Uno scarto tra il tuo calcolo e il saldo effettivamente consumato è il primo segnale di un cambiamento del tariffario.

#Monitorare i propri consumi

Il saldo residuo si può consultare sulla piattaforma e l'API espone un endpoint che lo restituisce in JSON. È utile per attivare un avviso prima che il credito si esaurisca, anziché dopo.

Terminale: consultare il saldo

curl https://api.deepseek.com/user/balance \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

Registrare ogni chiamata: Registra la data, il modello e i contatori dell'oggetto usage. Due settimane di log in condizioni reali valgono più di qualsiasi stima: sono la base della decisione tra API ed esecuzione locale.
Limitare l'output: Il parametro max_tokens limita la lunghezza di una risposta, quindi il suo costo massimo. Impostalo in base all'attività piuttosto che lasciarlo al valore predefinito.
Monitorare la cronologia: In una conversazione, l'intera cronologia viene reinviata a ogni turno. Una discussione di cinquanta scambi reinvia cinquanta volte il proprio inizio, anche se la cache ne riduce il costo. Riassumi o tronca la cronologia oltre una certa lunghezza.
Credito offerto e credito ricaricato: Se il tuo account dispone di un credito gratuito oltre al credito ricaricato, la pagina dei prezzi specifica in quale ordine vengono consumati. Verifica anche se ha una data di scadenza.

#API o modello locale: come decidere

Non esiste una soglia universale oltre la quale l'esecuzione in locale diventa meno costosa, e questa guida non ne inventa una. Il risultato dipende da tre numeri che solo tu conosci: il tuo volume reale di token, il listino del giorno e il prezzo dell'hardware che acquisteresti. I criteri qui sotto permettono spesso di decidere prima ancora di tirare fuori la calcolatrice.

Privacy: Dati personali, contratti, codice proprietario, fascicoli dei clienti: con l'API, questi contenuti vengono inviati a un soggetto terzo stabilito al di fuori dell'Unione europea, un trasferimento che rientra nell'ambito del GDPR e va validato con il tuo responsabile della protezione dei dati. In locale, la questione non si pone. Spesso questo criterio è da solo decisivo.
Volume e regolarità: Un uso poco frequente o irregolare favorisce l'API: non paghi nulla quando non la utilizzi. Un uso continuo e prevedibile favorisce il locale: la macchina costa la stessa cosa se elabora dieci richieste o diecimila.
Qualità necessaria: L'API mette a disposizione i grandi modelli del produttore. Su una scheda con 12-24 GB di VRAM, potrai eseguire modelli nettamente più piccoli: considera circa 9 GB per un 14B e 19 GB per un 32B in Q4_K_M. Se il tuo compito richiede il modello grande, l'esecuzione locale presuppone hardware di un'altra categoria.
Disponibilità: L'API dipende dal carico del fornitore e dalla tua connessione. L'esecuzione in locale dipende dalla tua macchina, che devi monitorare e su cui devi risolvere i problemi da solo.
Prevedibilità del budget: La fattura dell'API varia in base all'utilizzo e può riservare sorprese. L'esecuzione in locale comporta un costo fisso, noto in anticipo: acquisto o noleggio, elettricità, tempo di manutenzione.
Tempo di lavoro: L'API si connette velocemente: una chiave, poche righe di codice. Un server locale richiede un'installazione, aggiornamenti e una persona che sappia cosa fare quando non risponde più. Questo tempo ha un costo, da includere nella comparazione.

#La comparazione in quattro passaggi

01
Misurare
Esegui il tuo caso d'uso tramite l'API per due settimane, registrando l'oggetto usage. Ottieni un volume mensile reale, suddiviso tra input non in cache, input in cache e output.
02
Calcolare il costo dell'API
Applica a questo volume il tariffario ufficiale del giorno. Questo è il tuo costo mensile per l'API, con la data di rilevazione.
03
Calcolare il costo dell'esecuzione in locale
Prendi il prezzo della macchina in grado di eseguire il modello desiderato, ripartiscilo sulla durata d'uso che scegli e aggiungi l'elettricità e il tempo di manutenzione. La guida sul costo di un server GPU spiega questo calcolo in dettaglio.
04
Verificare la qualità prima del prezzo
Sottoponi venti richieste reali al modello locale che il tuo hardware può ospitare e confronta le risposte con quelle dell'API. Se il risultato non è soddisfacente, il confronto dei costi non ha più senso: non stai confrontando lo stesso servizio.

#Lo stesso codice per entrambi

Passare dall'una all'altro non richiede di riscrivere la tua applicazione. Ollama, che è in ascolto per impostazione predefinita su http://localhost:11434, espone anch'esso un'interfaccia compatibile con OpenAI al percorso /v1. Il codice qui sotto passa dall'API DeepSeek a un modello locale e viceversa in base a una variabile d'ambiente.

Terminale: preparare il modello locale

ollama pull deepseek-r1:14b

client_api_ou_local.py

import os
from openai import OpenAI

LOCAL = os.environ.get("LLM_LOCAL") == "1"

if LOCAL:
    client = OpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
    modele = "deepseek-r1:14b"
else:
    client = OpenAI(
        api_key=os.environ["DEEPSEEK_API_KEY"],
        base_url="https://api.deepseek.com",
    )
    modele = "IDENTIFIANT_DU_MODELE"  # un id renvoyé par /models

reponse = client.chat.completions.create(
    model=modele,
    messages=[{"role": "user", "content": "Résume ce texte en deux phrases : ..."}],
)
print(reponse.choices[0].message.content)

Il modello deepseek-r1:14b è una versione distillata che rientra nella memoria di una scheda da 12 GB come una RTX 3060. Non è il modello fornito dall'API: aspettati risposte meno precise nei compiti difficili. Questa configurazione serve proprio a verificarlo sulle tue richieste, al quarto passaggio del metodo.

Non sei obbligato a schierarti da una sola parte

Poiché il codice è lo stesso, è possibile una configurazione mista: l'elaborazione locale per i contenuti sensibili e il carico di base, l'API per i picchi o le attività che superano le capacità del modello locale. La regola di routing deve quindi basarsi sulla natura dei dati, non sul carico: un documento riservato non viene inviato all'API perché il server locale è occupato.

#Risoluzione dei problemi: errori comuni

La documentazione di DeepSeek include una pagina dedicata ai codici di errore. I casi seguenti sono quelli che si incontrano all'avvio; in caso di dubbio, la pagina ufficiale ha la precedenza su questo riassunto.

401, autenticazione rifiutata: La chiave è mancante, tagliata o revocata. Verifica che la variabile d'ambiente sia correttamente definita nel terminale che avvia il programma e che non sia stato inserito uno spazio durante il copia-incolla.
402, saldo insufficiente: L'account non ha più credito. Ricarica dalla piattaforma. Un avviso basato sull'endpoint del saldo evita che ciò accada in produzione.
400 o 422, richiesta invalida: Il corpo JSON è mal formato o un parametro non è accettato. La causa più comune è un identificativo di modello copiato da un vecchio tutorial: torna nella lista /models.
429, troppe richieste: Invii richieste più rapidamente di quanto il servizio riesca ad accettarle. Distanzia le chiamate e riprova dopo un intervallo di attesa crescente.
500 o 503, errore o sovraccarico del server: Il problema è lato fornitore. Riprova dopo un po' di attesa e prevedi nella tua applicazione un messaggio chiaro o un modello di fallback.
Risposta molto lenta: Nei periodi di carico elevato, una richiesta può restare in attesa a lungo prima che inizi ad arrivare la risposta. Imposta un timeout lato client e attiva la modalità streaming per visualizzare la risposta man mano che viene generata.
Fattura più alta di quanto previsto: Tre sospetti abituali: token di ragionamento conteggiati in uscita, una cache utilizzata di rado, una cronologia della conversazione reinviata per intero a ogni turno. Il log dell'oggetto usage permette di distinguere quale sia la causa.

#Fonti ufficiali

I prezzi, l'elenco dei modelli e le regole di fatturazione cambiano nel tempo. Queste pagine del fornitore sono il riferimento da consultare prima di qualsiasi decisione basata su cifre.

Modelli e prezzi

https://api-docs.deepseek.com/quick_start/pricing/

Documentazione dell'API (prima chiamata, guide, codici di errore)

https://api-docs.deepseek.com/

Pesi pubblicati da DeepSeek su Hugging Face

https://huggingface.co/deepseek-ai

#Per approfondire

Questa guida si limita alla chiave, alla lettura del listino e al metodo per decidere. Per stimare i costi e procedere all'installazione, puoi proseguire con queste guide del sito:

Quanto costa un server GPU per LLM?: Acquisto, noleggio o API: i costi da sommare per la terza fase della comparazione. https://quelllm.fr/guide/cout-serveur-gpu-llm
API LLM gratuite: il vero confronto: Le offerte gratuite, le loro quote di utilizzo e cosa succede ai tuoi dati, se le tue esigenze rientrano in un piano gratuito. https://quelllm.fr/guide/api-llm-gratuites-vs-local
DeepSeek V4 Pro in locale: L'hardware richiesto dal grande modello della famiglia quando si vuole eseguirlo localmente. https://quelllm.fr/guide/guide-deepseek-v4-pro
IA locale vs ChatGPT: La stessa domanda, cloud o locale, posta per un uso conversazionale anziché tramite API. https://quelllm.fr/guide/ia-locale-vs-chatgpt

Questa guida ti è stata utile?

Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.

I kit QuelLLMLa guida di riferimento per ogni uso

IA in Azienda Copilota Locale IA locale Agenti Locali RAG Locale IA Senza Filtri Mac Immagini IA

Tutti i kit a vita — 49 €