Guida all'integrazione dell'API DeepSeek: Richieste compatibili con OpenAI tramite ECAIX

Questa guida illustra come testare un ID di modello DeepSeek tramite ECAIX utilizzando un endpoint API compatibile con OpenAI. Copre la richiesta minima funzionale, esempi in Python e curl, verifica dell'ID del modello, streaming, output strutturato, strumenti e un percorso diagnostico per errori comuni.

La guida descrive l'accesso tramite gateway ECAIX a un ID di modello esposto nel catalogo attuale di ECAIX. Non si assume che ECAIX sia l'endpoint ufficiale dell'API DeepSeek o che ogni caratteristica di DeepSeek sia disponibile attraverso ogni percorso di gateway. Verifica sempre la pagina del modello live e la documentazione del provider prima di spostare un lavoro in produzione.

Avvio rapido

Segui questa sequenza se hai già un'applicazione con SDK OpenAI:

1. Apri la pagina del modello DeepSeek v4.1 Flash e conferma che l'ID è disponibile.
2. Crea una chiave API ECAIX.
3. Imposta l'URL base compatibile con OpenAI a https://ecaix.com/api/ai/v1.
4. Mantieni il codice SDK e l'applicazione invariati dove possibile.
5. Esegui la richiesta minima riportata di seguito.
6. Aggiungi lo streaming, l'output JSON o gli strumenti solo dopo che la richiesta di base funziona correttamente.

Endpoint e ID del modello

Per client compatibili con OpenAI, usa:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

L'ID del modello non è una promessa permanente in un articolo blog. Verifica sempre l'ID corretto nella direttoria live dei modelli prima di ogni nuova integrazione o deploy. Se hai bisogno di un membro diverso della famiglia DeepSeek, copia esattamente l'ID dal dettaglio della pagina del modello invece di supporre un suffisso.

Anche la formattazione dell'endpoint è importante. Il SDK riceverà il percorso base che termina in /v1; il client aggiungerà /chat/completions o un altro percorso operativo. Non aggiungere /chat/completions all'URL base se il SDK lo aggiunge già.

Python con il SDK OpenAI

Installa o aggiorna il SDK Python OpenAI nel tuo ambiente virtuale:

python -m pip install --upgrade openai

Poi usa l'URL base di ECAIX e la chiave API:

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

console.log(response.choices[0].message.content);

Utilizza codice server-side per la richiesta API. Un'applicazione browser dovrebbe chiamare il proprio backend piuttosto che esporre una chiave ECAIX in JavaScript client-side.

Richiesta diagnostica con curl

Se il SDK fallisce, rimuovi il SDK dall'equazione e prova l'endpoint direttamente. Salva i header e il corpo separatamente per distinguere un problema HTTP da un problema di formato della risposta.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Non incolla i salvataggi dei header o della risposta in una richiesta pubblica senza rimuovere chiavi API, ID della richiesta, prompt, percorsi di repository e dati dei clienti.

Diagnosi della risposta

Segui questo ordine:

1. Codice HTTP: verifica se la richiesta ha raggiunto un endpoint valido.
2. Corpo della risposta: leggi il codice di errore del provider o gateway.
3. ID del modello: copia l'ID esatto dalla directory attuale del modello.
4. Autenticazione: controlla l'header della chiave, l'account e le permessi.
5. Forma della richiesta: riduci il corpo a model, messages e un limite minimo di output.
6. Campi di funzione: aggiungi lo streaming, il JSON o gli strumenti uno per volta.
7. Comportamento del SDK: confronta la richiesta del SDK con quella diretta via curl.

Questo evita che un problema del client library venga confuso con il routing del modello o le permessi dell'account.

Risposte in streaming

Se l'applicazione ha bisogno di output incrementale, aggiungi lo streaming solo dopo che una richiesta normale funziona correttamente:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

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

Il comportamento esatto degli eventi dipende dall'endpoint e dal SDK. Verifica come la tua framework gestisce un delta vuoto, un evento di utilizzo finale, interruzioni di connessione e terminazione di tipo [DONE]. Non considerare un'implementazione di streaming pronta per la produzione fino a quando non hai testato interruzioni e riavvii.

Output strutturato e JSON

Se hai bisogno di un output leggibile da macchina, inizia con una richiesta normale e poi aggiungi la più piccola opzione di output strutturato supportata dall'endpoint e dal modello. Valida il contenuto restituito con un parser JSON reale. Una richiesta che dice "ritorna JSON" non è la stessa di una risposta con schema vincolante.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

Se response_format è accettato può dipendere dal modello e dal percorso. Se l'endpoint restituisce un errore di parametro non supportato, rimuovi il campo e verifica la documentazione del percorso prima di provare un altro formato.

Appello alle funzioni e strumenti

L'appello alle funzioni richiede un test separato dalla generazione di testo. Inizia con una funzione innocua e ispeziona il nome e gli argomenti restituiti prima di eseguire qualsiasi cosa.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Un modello può restituire una risposta di testo valida mentre fallisce l'appello alle funzioni a causa di conversione schema, parametri non supportati o comportamenti specifici del client. Non esegui mai gli argomenti restituiti contro un sistema produttivo prima di validare lo schema e aggiungere controlli di autorizzazione.

Percorsi compatibili con OpenAI e Anthropic

ECAIX espose diverse superfici di compatibilità per diversi client:

Leggi la documentazione Chat Completions, Responses e Anthropic Messages prima di scegliere un percorso. Lo stesso ID del modello potrebbe non esporre campi o comportamenti identici su ogni superficie di compatibilità.

Dettagli attuali del modello

Usa le pagine dettagliate live per verificare capacità e disponibilità:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Queste pagine sono più affidabili di un articolo statico per gli ID dei modelli attuali, le informazioni sul contesto e i collegamenti ai prezzi.

Errori comuni

Checklist di sicurezza e produzione

Prima di spostarti oltre un progetto di prova, conferma:

• Le chiavi API sono memorizzate in modo server-side e possono essere rotate.
• I prompt e le risposte non contengono segreti non approvati o dati dei clienti.
• Capisci se il gateway registra richieste e per quanto tempo vengono conservati i log.
• La disponibilità e i prezzi dei modelli sono verificati dalle pagine live.
• I timeout, i riavvii, l'idempotenza e i limiti di tasso sono gestiti dall'applicazione.
• Le interruzioni di streaming non creano duplicati di lavori.
• Gli appelli alle funzioni hanno whitelist, validazione, autorizzazioni e registri di audit.
• I termini del provider e del gateway permettono il flusso di lavoro che intendi inviare.

Registra l'integrazione prima della pubblicazione

Scrivi la data, la versione del client, l'ID del modello, l'endpoint, il codice HTTP e le prove di funzione che hai effettivamente svolto. Se una prova non è stata eseguita, segnalala come non verificata. Questo registro rende più facile confrontare l'aggiornamento successivo del modello o del gateway

Validazione pre-produzione e gestione affidabile dell’API DeepSeek

La validazione pre-produzione è un passaggio cruciale per garantire che l’integrazione con l’API DeepSeek sia stabile, sicura e performante nel contesto operativo. Prima di procedere con la produzione, è essenziale testare rigorosamente ogni componente critico per evitare disastri legati a errori di configurazione, problemi di autorizzazione o comportamenti inattesi dei modelli linguistici.

Gestione delle chiavi API e sicurezza

L’utilizzo delle chiavi API è fondamentale per l’accesso ai servizi DeepSeek. È fondamentale:

• Non esporre mai le chiavi API in file di configurazione pubblici, log o repository condivisi. Utilizzare strumenti di gestione delle credenziali (come variabili d’ambiente o servizi di Key Management) per proteggere i dati sensibili.
• Validare l’autenticazione tramite endpoint di autenticazione (ad esempio /auth/validate) per confermare che la chiave sia valida e non revocata. Questo evita accessi non autorizzati o comportamenti anomali.
• Restringere i permessi all’indirizzo IP o al dominio di origine se possibile, limitando l’esposizione a potenziali minacce.

Verifica dell’identificatore del modello

I modelli DeepSeek possono subire aggiornamenti frequenti, quindi è importante:

• Confermare l’identificatore del modello (ad esempio deepseek-chat-20240101) prima di inviare richieste, utilizzando un endpoint di verifica (se disponibile) o confrontando la versione attuale con quella documentata.
• Monitorare le modifiche nei modelli tramite notifiche o strumenti di tracking (se supportati dal provider). In caso di aggiornamenti significativi, testare nuovamente l’integrazione per assicurarsi che le nuove funzionalità o correzioni non introducano regressioni.

Logging e tracciamento senza dati sensibili

Il logging è essenziale per il debugging, ma deve essere eseguito in modo responsabile:

• Escludere informazioni sensibili come chiavi API, token di accesso o dati personali dai log. Utilizzare filtri o strumenti di mascheramento (ad esempio, ****-****-**** per chiavi).
• Registrare solo metriche rilevanti (ad esempio, endpoint chiamati, status HTTP, durata della richiesta, errori) in un sistema centralizzato (come CloudWatch, Splunk o un servizio di logging interno).
• Attivare il logging di tracciamento (se disponibile) per monitorare le interazioni con il gateway DeepSeek, identificando pattern anomali o rallentamenti.

Ritentativi e idempotenza

Le richieste all’API DeepSeek possono fallire per motivi temporanei (ad esempio, sovraccarico del server o errori di rete). Per garantire affidabilità:

• Implementare un meccanismo di ritentativo con un intervallo esponenziale (ad esempio, 1 secondi, 2 secondi, 4 secondi) per richieste non idempotenti (come chiamate a /generate).
• Utilizzare l’idempotency-key (se supportato) per garantire che una stessa richiesta non venga elaborata più volte, specialmente in scenari asincroni o con ritentativi.
• Limitare il numero di tentativi per evitare sovraccarichi del sistema o costi eccessivi.

Streaming e gestione delle disconnessioni

I modelli DeepSeek possono supportare output in streaming (ad esempio, tramite /stream), il che richiede una gestione attenta:

• Monitorare la connessione durante la ricezione dei dati in streaming per gestire eventuali disconnessioni improvvise (ad esempio, timeout o interruzioni di rete).
• Implementare un buffer temporaneo per i dati non ancora ricevuti, evitando perdite di informazioni in caso di interruzione.
• Testare la ricostruzione dei dati in caso di interruzione, assicurandosi che il client possa riavviare correttamente la richiesta.

Autorizzazione degli strumenti e test post-modifica

L’integrazione con DeepSeek può richiedere autorizzazioni aggiuntive da parte del provider (ad esempio, accesso a modelli premium o funzionalità avanzate):

• **Ver