Informare gli utenti del download del modello

Thomas Steiner

Data di pubblicazione: 1° ottobre 2025

Prima di poter utilizzare una delle API AI integrate, è necessario scaricare dalla rete il modello sottostante e le eventuali personalizzazioni (ad esempio i perfezionamenti), estrarre i dati compressi e infine caricarli in memoria. Questa guida documenta alcune delle best practice per migliorare l'esperienza utente durante l'attesa del download.

Monitorare e condividere l'avanzamento del download

Ogni API AI integrata ha la funzione create() per avviare una sessione. La funzione create() ha un'opzione monitor che ti consente di accedere allo stato di avanzamento del download per condividerlo con l'utente.

Le API AI integrate sono create per l'AI lato client, in cui i dati vengono elaborati nel browser e sul dispositivo dell'utente, ma alcune applicazioni possono consentire l'elaborazione dei dati su un server. Il modo in cui ti rivolgi all'utente durante il download del modello dipende da questa domanda: il trattamento dei dati deve essere eseguito solo localmente o no? Se è vero, la tua applicazione è solo lato client. In caso contrario, la tua applicazione potrebbe utilizzare un'implementazione ibrida.

Solo lato client

In alcuni scenari, è necessario l'elaborazione dei dati lato client. Ad esempio, un'applicazione sanitaria che consente ai pazienti di porre domande sulle loro informazioni personali probabilmente vuole che queste informazioni rimangano private sul dispositivo dell'utente. L'utente deve attendere che il modello e tutte le personalizzazioni siano scaricati e pronti prima di poter utilizzare le funzionalità di trattamento dei dati.

In questo caso, se il modello non è ancora disponibile, devi mostrare all'utente le informazioni sullo stato di avanzamento del download.

<style>
  progress[hidden] ~ label {
    display: none;
  }
</style>

<button type="button">Create LanguageModel session</button>
<progress hidden id="progress" value="0"></progress>
<label for="progress">Model download progress</label>

Ora, per renderlo funzionale, è necessario un po' di JavaScript. Il codice innanzitutto reimposta l'interfaccia di avanzamento allo stato iniziale (avanzamento nascosto e pari a zero), verifica se l'API è supportata e poi controlla la disponibilità dell'API:

• L'API è 'unavailable': la tua applicazione non può essere utilizzata lato client su questo dispositivo. Avvisa l'utente che la funzionalità non è disponibile.
• L'API è 'available': l'API può essere utilizzata immediatamente, non è necessario mostrare l'UI di avanzamento.
• L'API è 'downloadable' o 'downloading': l'API può essere utilizzata una volta completato il download. Mostra un indicatore di avanzamento e aggiornalo ogni volta che viene attivato l'evento downloadprogress. Dopo il download, mostra lo stato indeterminato per segnalare all'utente che il browser sta estraendo il modello e lo sta caricando in memoria.

const createButton = document.querySelector('.create');
const promptButton = document.querySelector('.prompt');
const progress = document.querySelector('progress');
const output = document.querySelector('output');

let sessionCreationTriggered = false;
let session = null;

const createSession = async (options = {}) => {
  if (sessionCreationTriggered) {
    return;
  }

  progress.hidden = true;
  progress.value = 0;

  try {
    if (!('LanguageModel' in self)) {
      throw new Error('LanguageModel is not supported.');
    }

    const availability = await LanguageModel.availability();
    if (availability === 'unavailable') {
      throw new Error('LanguageModel is not available.');
    }

    let modelNewlyDownloaded = false;
    if (availability !== 'available') {
      modelNewlyDownloaded = true;
      progress.hidden = false;
    }
    console.log(`LanguageModel is ${availability}.`);
    sessionCreationTriggered = true;

    const llmSession = await LanguageModel.create({
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          progress.value = e.loaded;
          if (modelNewlyDownloaded && e.loaded === 1) {
            // The model was newly downloaded and needs to be extracted
            // and loaded into memory, so show the undetermined state.
            progress.removeAttribute('value');
          }
        });
      },
      ...options,
    });

    sessionCreationTriggered = false;
    return llmSession;
  } catch (error) {
    throw error;
  } finally {
    progress.hidden = true;
    progress.value = 0;
  }
};

createButton.addEventListener('click', async () => {
  try {
    localSession = await createSession({
      expectedInputs: [{ type: 'text', languages: ['en'] }],
      expectedOutputs: [{ type: 'text', languages: ['en'] }],
    });
    promptButton.disabled = false;
  } catch (error) {
    output.textContent = error.message;
  }
});

promptButton.addEventListener('click', async () => {
  output.innerHTML = '';
  try {
    const stream = localSession.promptStreaming('Write me a poem');
    for await (const chunk of stream) {
      output.append(chunk);
    }
  } catch (err) {
    output.textContent = err.message;
  }
});

Se l'utente accede all'app mentre il modello viene scaricato attivamente nel browser, l'interfaccia di avanzamento indica a che punto si trova il browser nel processo di download in base ai dati ancora mancanti.

Dai un'occhiata alla demo che mostra questo flusso in azione. Se l'API AI integrata (in questo esempio, l'API Prompt) non è disponibile, l'app non può essere utilizzata. Se il modello di AI integrato deve ancora essere scaricato, all'utente viene mostrato un indicatore di avanzamento. Puoi visualizzare il codice sorgente su GitHub.

Implementazione ibrida

Se preferisci utilizzare l'AI lato client, ma puoi inviare temporaneamente i dati al cloud, puoi configurare un'implementazione ibrida. Ciò significa che gli utenti possono provare le funzionalità immediatamente, mentre scaricano in parallelo il modello locale. Una volta scaricato il modello, passa dinamicamente alla sessione locale.

Puoi utilizzare qualsiasi implementazione lato server per l'ibrido, ma probabilmente è meglio utilizzare la stessa famiglia di modelli sia nel cloud che localmente per garantire una qualità dei risultati comparabile. Guida introduttiva all'API Gemini e alle app web mette in evidenza i vari approcci per l'API Gemini.

La demo mostra questo flusso in azione. Se l'API AI integrata non è disponibile, la demo utilizza l'API Gemini nel cloud. Se il modello integrato deve ancora essere scaricato, all'utente viene mostrato un indicatore di avanzamento e l'app utilizza l'API Gemini nel cloud finché il modello non viene scaricato. Dai un'occhiata al codice sorgente completo su GitHub.

Conclusione

In quale categoria rientra la tua app? Richiedi l'elaborazione lato client al 100% o puoi utilizzare un approccio ibrido? Dopo aver risposto a questa domanda, il passaggio successivo è implementare la strategia di download del modello più adatta alle tue esigenze.

Assicurati che i tuoi utenti sappiano sempre quando e se possono utilizzare il tuo client app mostrando loro l'avanzamento del download del modello come descritto in questa guida.

Ricorda che non si tratta di una sfida una tantum: se il browser elimina il modello a causa della pressione di archiviazione o quando diventa disponibile una nuova versione del modello, il browser deve scaricare nuovamente il modello. Se segui l'approccio lato client o ibrido, puoi essere certo di creare la migliore esperienza possibile per i tuoi utenti e lasciare che il browser gestisca il resto.