Interrompere lo stream

Endpoint

POST /api/ai/chat/:chatId/stop

Richiesta

curl -X POST BOX_URL/api/ai/chat/my-chat-id/stop \
  -H "x-api-key: YOUR_API_KEY"

Sostituisci my-chat-id con l’id che hai usato nella richiesta di chat.

Risposta

{
  "success": true,
  "message": "Stream stopped successfully"
}

Oppure, se non c’è nessuno stream attivo:

{
  "success": false,
  "message": "No active stream found"
}

Controllare lo stato dello stream

Puoi anche verificare se uno stream è ancora attivo:

GET /api/ai/chat/:chatId/stream-status

curl BOX_URL/api/ai/chat/my-chat-id/stream-status \
  -H "x-api-key: YOUR_API_KEY"

Risposta

{
  "status": "active",
  "isActive": true,
  "startTime": "2024-01-15T10:30:00Z",
  "lastActivity": "2024-01-15T10:30:05Z",
  "messageCount": 42
}

Valori di stato

Esempio in JavaScript

const BOX_URL = 'https://your-box.intelligencebox.it'; // Your server URL

async function chatWithTimeout(message, timeoutMs = 30000) {
  const chatId = 'chat-' + Date.now();

  // Start the chat
  const chatPromise = fetch(`${BOX_URL}/api/ai/chat`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      id: chatId,
      messages: [{ role: 'user', content: message }],
      boxAddress: BOX_URL
    })
  });

  // Set up timeout
  const timeoutId = setTimeout(async () => {
    console.log('Timeout - stopping stream...');
    await fetch(`${BOX_URL}/api/ai/chat/${chatId}/stop`, {
      method: 'POST',
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    });
  }, timeoutMs);

  try {
    const response = await chatPromise;
    // Parse response...
    clearTimeout(timeoutId);
    return response;
  } catch (e) {
    clearTimeout(timeoutId);
    throw e;
  }
}

Quando interrompere

Ci sono alcuni casi ricorrenti in cui fermare uno stream da codice è la scelta giusta. Conoscerli aiuta a costruire un’integrazione più reattiva e più parsimoniosa di risorse.

• Annullamento dell’utente: l’utente preme un pulsante «Stop» o «Annulla» nella tua interfaccia. È il caso più comune e dovrebbe far partire subito una richiesta di interruzione.
• Limite di tempo: imposti un tempo massimo di risposta (per esempio 30 secondi) e fermi automaticamente lo stream se lo supera, come nell’esempio JavaScript qui sopra.
• Contenuto già sufficiente: alla tua applicazione serve solo la prima parte della risposta — un riassunto, il primo paragrafo — e il resto si può buttare.
• Deriva dal tema: la tua applicazione osserva il contenuto dello stream e si accorge che l’AI si è allontanata dall’argomento.
• Recupero da errore: si verifica un errore altrove nella tua applicazione e proseguire lo stream non ha più senso.

Risposte parziali

Quando interrompi uno stream, il testo già generato e inviato al client resta disponibile: l’AI non «si riprende» ciò che ha già trasmesso. La tua applicazione può quindi usare la risposta parziale ricevuta prima del segnale di stop. Tieni presente che il contenuto parziale può fermarsi a metà frase o a metà parola, quindi potresti voler tagliare l’ultima frase incompleta prima di mostrarla all’utente.

Consigli sulla gestione degli errori

Chiamare lo stop su uno stream già terminato o inesistente non produce un errore: restituisce semplicemente success: false con un messaggio descrittivo. Puoi quindi chiamarlo in modo difensivo senza controllare prima lo stato. Se però ti serve distinguere tra uno stream già concluso e uno mai avviato, usa l’endpoint stream-status prima della chiamata di stop.

Se ricevi un errore di rete chiamando l’endpoint di stop, lo stream potrebbe essere ancora in corso. In quel caso ripeti la richiesta di stop oppure controlla lo stato dopo una breve attesa. Fai in modo che il codice lato client gestisca con eleganza sia i tentativi riusciti sia quelli falliti.