Annullare le chiamate alle API di IA: come fermare il lavoro abbandonato e liberare risorse

Chiudere una schermata non significa fermare un’operazione

Quando si annulla una generazione, spesso l’utente si aspetta che il lavoro si interrompa. Tuttavia, l’azione visibile — fare clic su un pulsante, cambiare schermata o smettere di attendere — descrive soltanto ciò che è successo nell’interfaccia. Da sola non dimostra che cosa sia accaduto alla richiesta HTTP, al processo sul server o all’elaborazione eventualmente in corso presso un fornitore esterno. Sono livelli diversi, ciascuno con un proprio ciclo di vita.

Per questo un’integrazione deve specificare che cosa significa «annullare» a ogni confine. Il browser può smettere di attendere una risposta; il server può chiudere un’attività che controlla; un’API remota potrebbe offrire, oppure no, un meccanismo documentato per annullare un’operazione già accettata. Se un livello non propaga il segnale o non sa quale operazione dovrebbe interrompere, il lavoro può continuare lì anche se l’utente non ne vede più il risultato.

La conseguenza pratica è importante: non mostrare un annullamento come se fosse una risposta valida e non dichiarare che il fornitore ha interrotto l’elaborazione senza averlo verificato. L’applicazione può confermare di aver ricevuto una richiesta di annullamento e di aver smesso di attendere localmente. Qualsiasi affermazione più ampia richiede prove relative al comportamento della specifica integrazione, compresa la documentazione del fornitore e, quando possibile, un test osservabile.

Definisci che cosa annullare prima di scrivere codice

Un segnale di annullamento deve avere un ambito esplicito. Può riguardare l’attesa dell’interfaccia, una connessione HTTP, un’attività nel backend o un’operazione identificabile nel servizio remoto. In un sistema semplice potresti controllare soltanto i primi due livelli. In un’architettura con un server intermedio, l’annullamento dal browser non ferma automaticamente il lavoro del server: occorre che l’applicazione rilevi la disconnessione o riceva un segnale esplicito e lo traduca in un’azione sull’attività corrispondente.

È utile distinguere anche il motivo. Un annullamento esplicito si verifica quando l’utente chiede di fermare il lavoro. L’abbandono può consistere in una navigazione o in una disconnessione senza un’azione deliberata. Un timeout si verifica quando viene raggiunto un limite temporale configurato. Tutti e tre i casi possono far smettere l’applicazione di attendere, ma non significano la stessa cosa, non vanno necessariamente presentati allo stesso modo e non permettono sempre di sapere se il lavoro remoto è terminato.

Definisci stati terminali che descrivano ciò che l’applicazione ha verificato, non ciò che presume. Per esempio: completato, annullamento richiesto, timeout locale e disconnessione rilevata. Se il sistema riesce a confermare un annullamento remoto mediante un meccanismo documentato, registra quel risultato separatamente. Mantenere distinti questi stati migliora sia l’interfaccia sia la diagnosi successiva.

Propaga il segnale attraverso i confini che controlli

Nel browser, AbortController permette di creare un segnale da associare a una richiesta effettuata con fetch. Se il segnale viene annullato, il client può interrompere l’attesa della richiesta. Questo risolve una parte del problema: il codice dell’interfaccia smette di trattare la risposta come un’operazione ancora in attesa. Da solo, però, non dimostra che un’attività avviata oltre la connessione sia stata fermata.

Il confine successivo è spesso il backend. Se il browser comunica con un servizio proprio, quel servizio ha bisogno di una politica per associare la richiesta in ingresso al lavoro che ha avviato. In base alla piattaforma e alla libreria, potrà rilevare un segnale di annullamento, una disconnessione o entrambe le cose. L’applicazione deve verificare le effettive capacità del proprio server e del client HTTP: non si deve presumere che un’astrazione propaghi l’annullamento solo perché l’interfaccia offre un pulsante.

Se il backend chiama un’API esterna, occorre verificare se il client HTTP supporta un segnale di annullamento e che cosa succede quando lo si usa. Poi bisogna consultare la documentazione della specifica API per capire se offre un meccanismo per annullare un’operazione già accettata o se è possibile soltanto interrompere la connessione locale. Sono capacità diverse. Alcune API offrono un’operazione esplicita di annullamento per determinate operazioni, ma ciò non permette di generalizzare alle API di generazione di IA.

Anche le linee guida di progettazione delle API asincrone sostengono che un’operazione in corso dovrebbe disporre di un modo per essere annullata. È un principio di progettazione, non una garanzia che ogni dipendenza o fornitore implementi questa capacità, né una procedura per propagarla tra sistemi. Documenta il percorso livello per livello: chi riceve il segnale, quale azione può intraprendere e quale risultato è in grado di osservare.

Esempio con AbortController nel browser

L’esempio seguente invia una richiesta a una route del backend e consente di annullare l’attesa nel browser. Si presume che la route riceva un oggetto con un campo prompt e, se l’elaborazione riesce, restituisca JSON con un campo text. La route è illustrativa: il backend deve implementare il contratto e decidere separatamente come trattare la richiesta, come propagare l’annullamento e che cosa può confermare sull’API esterna.

La funzione controlla se il segnale era già annullato prima di avviare l’invio e impedisce di aggiornare l’interfaccia con una risposta se l’annullamento viene registrato per primo. In un’interfaccia reale, collega la funzione cancel al pulsante corrispondente e disattivalo quando l’operazione raggiunge uno stato terminale. L’esempio non dimostra che il backend o il fornitore abbiano interrotto l’elaborazione.

async function generate(prompt, output, signal) {
  if (signal.aborted) {
    output.textContent = "Annullamento richiesto prima dell'invio.";
    return;
  }

  output.textContent = "Generazione in corso…";

  try {
    const response = await fetch("/api/generate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ prompt }),
      signal
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const result = await response.json();

    if (!signal.aborted) output.textContent = result.text;
  } catch (error) {
    if (signal.aborted || error.name === "AbortError") {
      output.textContent = "Si è smesso di attendere la risposta.";
      return;
    }
    output.textContent = "Impossibile completare la richiesta.";
  }
}

const controller = new AbortController();
const task = generate("Riassumi il documento", document.querySelector("#output"), controller.signal);
// Chiama controller.abort() dall'azione di annullamento.
// Conserva task se devi attendere la fine del codice locale.

Considera il timeout come un limite temporale, non come prova di annullamento

Un timeout definisce per quanto tempo un livello è disposto ad attendere. Potrebbero esserci un limite nell’interfaccia, un altro nel server e un altro ancora nel client HTTP che si collega al fornitore. Questi limiti vanno coordinati consapevolmente: se un livello abbandona prima degli altri senza comunicarlo, il lavoro può continuare a occupare risorse in un livello che lo considera ancora attivo.

Quando scade un termine, registra quale orologio è scaduto e a quale livello. «Timeout del browser» è più preciso di «il modello è andato in timeout», a meno che il servizio remoto non abbia comunicato quel risultato. L’applicazione può smettere di attendere, richiedere l’interruzione ai livelli disponibili e mostrare uno stato di termine scaduto. Non dovrebbe trasformare quell’azione in una dichiarazione di annullamento confermato.

Gli effetti sull’utilizzo o sulla fatturazione dipendono dall’API e dalle sue condizioni. La documentazione di una specifica API può descrivere che cosa annulla la relativa operazione; non bisogna dedurne il comportamento di un altro endpoint o fornitore. Se questo effetto è importante, consulta la documentazione ufficiale relativa all’integrazione, verifica quale unità di lavoro viene annullata e convalida il risultato con un test controllato. Se la documentazione non chiarisce la questione, mantieni esplicita l’incertezza nel prodotto e nella politica dei costi.

Evita stati incoerenti in caso di eventi concorrenti

La risposta e l’annullamento possono arrivare quasi nello stesso momento. Se l’interfaccia gestisce entrambi gli eventi senza una regola condivisa, potrebbe mostrare prima «annullato» e poi sovrascriverlo con una risposta tardiva. Può accadere anche il contrario: mostrare una risposta arrivata dopo che l’utente ha già chiesto di interrompere l’operazione. La soluzione non è indovinare quale evento si sia verificato per primo nel sistema remoto, ma definire quale stato terminale deve prevalere nell’applicazione.

Una regola semplice per l’interfaccia consiste nel fare in modo che la prima transizione terminale registrata per un’operazione impedisca gli aggiornamenti successivi della stessa operazione. Un’altra possibilità è assegnare un identificatore a ogni richiesta e scartare le risposte relative a un’operazione che non è più quella attiva. La scelta deve essere coerente con il prodotto: se si decide di conservare una risposta completata nonostante un annullamento tardivo, anche questa politica deve essere esplicita.

Non confondere ciò che viene mostrato con la realtà operativa. L’interfaccia può contrassegnare localmente l’operazione come annullata mentre il backend registra che l’annullamento remoto non è stato confermato. Quando sono rilevanti, mantieni questi dati separati nei log o negli stati interni. In questo modo una risposta tardiva non sembrerà la prova che l’annullamento sia stato revocato e la chiusura di una connessione non sembrerà la conclusione del lavoro.

Metti alla prova ogni fase e ogni confine

Un test che fa clic su «Annulla» soltanto dopo aver ricevuto una risposta non verifica l’annullamento durante l’elaborazione. Progetta casi distinti per i momenti rilevanti e osserva sia l’interfaccia sia il backend. Se è coinvolta un’API esterna, verifica soltanto ciò che l’integrazione e la documentazione permettono di osservare; non usare la scomparsa del risultato dallo schermo come indicatore del fatto che il fornitore abbia interrotto l’elaborazione.

Includi un caso di annullamento prima dell’invio: se il segnale è già annullato quando la funzione viene chiamata, l’operazione non dovrebbe avviare la richiesta. Prova anche ad annullare dopo l’avvio della richiesta ma prima di ricevere una risposta, e durante una risposta in corso se l’endpoint usa una modalità che consente di osservare quell’intervallo. Verifica il comportamento quando si chiude o si abbandona la vista, secondo la politica definita dal prodotto.

Infine, crea una condizione di concorrenza tra risposta e annullamento e verifica che lo stato terminale sia deterministico. Per un timeout, controlla che venga registrato come scadenza del termine e non come azione esplicita dell’utente. In ogni test, verifica se restano attività e connessioni locali aperte e se il backend continua a svolgere lavoro. Se non è possibile ispezionare l’attività remota, annotalo come limite invece di affermare che sia stata interrotta.

Verifica risorse e conseguenze prima del rilascio

La verifica deve coprire l’intera catena, non soltanto il codice del pulsante. Conferma che il client HTTP locale possa ricevere un segnale di annullamento, che il backend colleghi il segnale all’attività corretta e che il meccanismo remoto — se esiste — sia compatibile con l’endpoint e il tipo di operazione utilizzati. Le funzionalità di annullamento specifiche di un prodotto non dimostrano che un’altra API dello stesso fornitore, o un altro fornitore, si comporti allo stesso modo.

Controlla anche la pulizia locale: attività ausiliarie, listener, connessioni e riferimenti associati a una richiesta non dovrebbero restare attivi senza una ragione nota. Nei servizi con più richieste simultanee, assicurati che un segnale annulli soltanto l’operazione associata e non un’attività condivisa con altri utenti. Registra identificatori di operazione e stati finali in modo da poter ricostruire che cosa è stato richiesto e che cosa è stato confermato.

Prima di dichiarare qualcosa su costi, utilizzo o elaborazione remota, consulta la documentazione ufficiale di quella specifica integrazione ed esegui test limitati, compatibili con le relative condizioni. Per esempio, un’API di chiamate in batch documenta un’operazione di annullamento per le proprie chiamate e i relativi destinatari: è una prova che riguarda quell’endpoint, non la generazione di testo. Mantieni questa distinzione nella progettazione, nei test e nelle comunicazioni all’utente.

Criterio finale: comunica ciò che sai e verifica ciò che non sai

Il modello essenziale è semplice, anche se la sua implementazione dipende dall’architettura: registra il motivo, propaga il segnale attraverso i livelli che controlli, applica una politica deterministica per gli stati e verifica quali risorse restano attive. AbortController può aiutare a interrompere l’attesa nel browser; non sostituisce l’annullamento nel backend né l’eventuale meccanismo remoto offerto da un’API.

Prima di integrare un servizio, rispondi per iscritto a queste domande: la libreria HTTP supporta l’annullamento? Il backend rileva l’abbandono? L’API esterna offre un’operazione documentata per interrompere un’attività già accettata? Che cosa si osserva dopo averla usata? Che cosa si sa sull’utilizzo e sulla fatturazione? Se manca una risposta, registra l’incertezza ed evita promesse più ampie di quanto l’integrazione dimostri.

Annullare correttamente non significa garantire che ogni lavoro scompaia da tutti i livelli. Significa definire stati chiari, interrompere ciò che l’applicazione può interrompere, liberare le risorse locali, testare gli eventi concorrenti e comunicare con trasparenza l’ambito di ogni azione.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.