SDK API DeepSeek: usa l'SDK OpenAI e cambia endpoint

Perché l'SDK OpenAI è l'SDK API DeepSeek

Quando le persone cercano un SDK API DeepSeek, si aspettano un pacchetto con il nome del fornitore. In pratica, la documentazione ufficiale di DeepSeek descrive la chiamata alla sua API tramite l'SDK OpenAI con un URL base diverso, perché l'API segue il formato di richiesta e risposta OpenAI. Controlla la loro documentazione attuale per l'URL base e i nomi dei modelli esatti; sono l'autorità sul loro servizio.

La conseguenza è utile. Qualsiasi codice scritto contro la libreria client OpenAI può comunicare con qualsiasi server che implementa gli stessi endpoint, che qui sono POST /v1/chat/completions, POST /v1/responses e GET /v1/models. Passare tra provider diventa una modifica di configurazione piuttosto che una riscrittura. Il resto di questo articolo mostra il pattern in Python, Node e curl, poi una struttura che rende il cambio banale.

Configurazione Python

Installa il pacchetto ufficiale e puntalo all'endpoint:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Ottieni una chiave nella pagina delle chiavi API. Gli utenti nuovi possono richiedere $0,50 di credito di prova con un solo clic, senza carta. L'articolo API Python di DeepSeek entra nel dettaglio su questo linguaggio, inclusa la gestione degli errori.

Configurazione Node.js

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Il pattern è identico: base URL, chiave, modello. Lo streaming restituisce Server-Sent Events e la libreria li trasforma in un iteratore asincrono. Il tool calling segue lo stesso schema delle altre API compatibili con OpenAI: passa tools, leggi tool_calls in streaming e restituisci i risultati come messaggi role: "tool".

Rendi l'endpoint intercambiabile

Non fissare hardcoded i tre valori. Leggili dall'ambiente e avvolgi la creazione del client in una funzione. Poi passare da un endpoint all'altro significa modificare un file .env, non il codice sorgente.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

Ora un provider diverso ha bisogno solo di tre variabili d'ambiente. Gli SDK ufficiali leggono anche OPENAI_API_BASE e OPENAI_API_KEY in alcune versioni, ma variabili esplicite sono più chiare ed evitano sorprese quando esegui più provider contemporaneamente.

Se usi TypeScript o un altro linguaggio, l'idea è la stessa: una funzione factory, tre variabili, nessun nome del provider sparpagliato nel codice sorgente. Un errore comune è lasciare che il nome del fornitore trapeli nei nomi delle funzioni, nei log e nei nomi delle variabili, il che rende un cambio successivo più difficile del necessario. Nomina le cose in base al lavoro (ask, summarise) invece che al provider.

Tieni un piccolo test che invia un prompt fisso tramite ask() e verifica che la risposta non sia vuota. Esegui dopo ogni cambio di endpoint; cattura URL e chiavi errati in pochi secondi.

Cosa resta uguale e cosa cambia quando cambi

L'ultima riga è quella che coglie di sorpresa. Un endpoint è compatibile a livello di protocollo, non a livello di comportamento. Due provider possono accettare richieste identiche e dare risposte molto diverse. Il modello qui è un singolo modello a pesi aperti di un provider indipendente, ottimizzato per rispondere senza rifiuti sui contenuti per uso adulto legale, e non è l'API ufficiale di DeepSeek o di qualsiasi altro laboratorio. Ritestare i prompt che hai ottimizzato per un altro modello.

Funzionalità che questo endpoint ha e non ha

• Supportato: completamenti chat, il formato Responses, elenco modelli, streaming, tool calling, modalità JSON (response_format con json_object), e passaggio di temperature, top_p, stop, seed e le penalità.
• Non offerto: generazione di immagini, audio o video, embeddings, fine-tuning.
• Limiti: finestra di 100.000 token, corpo massimo di 8 MB, 8 richieste parallele e 300 al minuto su una chiave completa (2 e 60 su una chiave di prova).
• Errori: HTTP 429 con il codice rate_limited o concurrency, e un'intestazione Retry-After: 5 in caso di sovraccarico temporaneo.

Se il tuo codice chiama un endpoint embeddings, avrai bisogno di un altro provider per quella parte e puoi mantenere la chat qui. Dividere per attività è una ragione comune per il pattern delle variabili d'ambiente sopra.

Una checklist di migrazione

Quando cambi un endpoint con un altro in un progetto esistente, segui una breve lista invece di cambiare tutto insieme.

1. Verifica l'endpoint. Invia una richiesta con curl e conferma di ricevere testo. Chiama GET /v1/models e verifica che l'ID uncensored sia elencato.
2. Modifica i tre valori. Base URL, chiave, nome del modello, nient'altro. Non toccare ancora i prompt.
3. Esegui i tuoi test esistenti. Se hai test di regressione dei prompt, eseguili e annota quali falliscono. I fallimenti sono solitamente comportamentali, come un formato di output diverso, non errori di protocollo.
4. Verifica i parametri. Rimuovi le opzioni non necessarie per l'endpoint. Mantieni temperature, top_p, stop e seed se li usi.
5. Testa lo streaming e gli strumenti separatamente. I bug dello streaming spesso si nascondono nel codice client che presuppone un layout specifico dei chunk. Le chiamate di funzioni richiedono uno schema che il modello segue bene, quindi testa con le tue funzioni reali.
6. Misura costi e latenza sul traffico reale. Confronta un giorno di richieste, non un singolo prompt.

Fai questo in un branch o con un flag di funzionalità che instrada una piccola quota di traffico verso il nuovo endpoint. Poiché il codice client è condiviso, il rollback consiste nel modificare una variabile d'ambiente.

Gestisci i retry e leggi l'utilizzo

Gli SDK gestiscono automaticamente alcuni errori, ma dovresti comunque gestire tu il 429, poiché i limiti di concorrenza sono reali in produzione. Cattura l'eccezione del limite di richieste, attendi i secondi indicati in Retry-After (5 in caso di sovraccarico) e riprova. Le richieste fallite non vengono addebitate, quindi i tentativi sono sicuri per il tuo saldo.

Registra usage.prompt_tokens e usage.completion_tokens in ogni chiamata. I prezzi sono $0,15 per 1M di token di input e $0,50 per 1M di token di output, quindi una chiamata con 2.000 token di input e 600 token di output costa 2.000 × $0,15 / 1M + 600 × $0,50 / 1M = $0,0003 + $0,0003 = $0,0006. Le intestazioni di risposta includono anche X-Balance-USD per il credito residuo. Consulta la pagina dei prezzi per ricariche e bonus, e la documentazione per l'elenco completo dei parametri.

Editor e altri strumenti

I tre valori vengono ereditati da qualsiasi strumento con un'impostazione del provider compatibile con OpenAI. L'articolo su come usare un'API stile DeepSeek in Cursor illustra un editor di questo tipo. In ogni strumento, i campi sono etichettati in modo leggermente diverso, ma inserisci sempre l'URL base che termina con /v1, la chiave e il nome del modello.

Altre guide

• Costo API DeepSeek vs API OpenAI: Esempi pratici
• Chiave API DeepSeek: Accesso API LLM senza censura