Informar os usuários sobre o download do modelo

Thomas Steiner

Publicado em: 1º de outubro de 2025

Antes que qualquer uma das APIs de IA integrada possa ser usada, o modelo subjacente e as personalizações (como ajustes refinados) precisam ser baixados da rede, os dados compactados precisam ser extraídos e, por fim, carregados na memória. Este guia documenta algumas das práticas recomendadas para melhorar a experiência do usuário enquanto ele aguarda o download.

Monitorar e compartilhar o progresso do download

Todas as APIs de IA integradas têm a função create() para iniciar uma sessão. A função create() tem uma opção monitor para que você possa acessar o progresso do download e compartilhar com o usuário.

Embora as APIs de IA integradas sejam criadas para IA do lado do cliente, em que os dados são processados no navegador e no dispositivo do usuário, alguns aplicativos podem permitir que os dados sejam processados em um servidor. A forma como você se dirige ao usuário no progresso do download do modelo depende da seguinte questão: o processamento de dados precisa ser executado apenas localmente ou não? Se for verdadeiro, seu aplicativo será apenas do lado do cliente. Caso contrário, seu aplicativo poderá usar uma implementação híbrida.

Somente do lado do cliente

Em alguns casos, é necessário processar dados do lado do cliente. Por exemplo, um aplicativo de saúde que permite aos pacientes fazer perguntas sobre as informações pessoais provavelmente quer que essas informações permaneçam privadas no dispositivo do usuário. O usuário precisa esperar até que o modelo e todas as personalizações sejam baixados e estejam prontos para usar os recursos de tratamento de dados.

Nesse caso, se o modelo ainda não estiver disponível, mostre ao usuário informações sobre o progresso do 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>

Agora, para tornar isso funcional, é necessário um pouco de JavaScript. Primeiro, o código redefine a interface de progresso para o estado inicial (progresso oculto e zero), verifica se a API é compatível e, em seguida, verifica a disponibilidade da API:

• A API é 'unavailable': não é possível usar seu aplicativo no lado do cliente neste dispositivo. Avise o usuário que o recurso não está disponível.
• A API é 'available': a API pode ser usada imediatamente, sem necessidade de mostrar a interface de progresso.
• A API é 'downloadable' ou 'downloading': a API pode ser usada depois que o download for concluído. Mostre um indicador de progresso e atualize-o sempre que o evento downloadprogress for acionado. Depois do download, mostre o estado indeterminado para sinalizar ao usuário que o navegador está extraindo o modelo e carregando na memória.

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 o usuário entrar no app enquanto o modelo estiver sendo baixado ativamente para o navegador, a interface de progresso vai indicar em que etapa do processo de download o navegador está com base nos dados ainda ausentes.

Confira a demonstração que mostra esse fluxo em ação. Se a API de IA integrada (neste exemplo, a API Prompt) não estiver disponível, o app não poderá ser usado. Se o modelo de IA integrado ainda precisar ser baixado, um indicador de progresso será mostrado ao usuário. Confira o código-fonte no GitHub.

Implementação híbrida

Se você preferir usar a IA do lado do cliente, mas puder enviar dados temporariamente para a nuvem, configure uma implementação híbrida. Isso significa que os usuários podem aproveitar os recursos imediatamente, enquanto o modelo local é baixado em paralelo. Depois que o modelo for baixado, mude dinamicamente para a sessão local.

É possível usar qualquer implementação do lado do servidor para híbrido, mas provavelmente é melhor manter a mesma família de modelos na nuvem e localmente para garantir uma qualidade de resultado comparável. Como começar a usar a API Gemini e os web apps destaca as várias abordagens da API Gemini.

A demonstração mostra esse fluxo em ação. Se a API de IA integrada não estiver disponível, a demonstração vai usar a API Gemini na nuvem. Se o modelo integrado ainda precisar ser baixado, um indicador de progresso será mostrado ao usuário, e o app usará a API Gemini na nuvem até que o modelo seja baixado. Confira o código-fonte completo no GitHub.

Conclusão

Em qual categoria seu app se enquadra? Você precisa de um processamento 100% do lado do cliente ou pode usar uma abordagem híbrida? Depois de responder a essa pergunta, a próxima etapa é implementar a estratégia de download de modelo que funciona melhor para você.

Mostre aos usuários o progresso do download do modelo, conforme descrito neste guia, para que eles saibam quando e se podem usar o app do lado do cliente.

Lembre-se de que esse não é apenas um desafio único: se o navegador limpar o modelo devido à pressão de armazenamento ou quando uma nova versão do modelo estiver disponível, o navegador precisará fazer o download do modelo novamente. Seja qual for a abordagem (do lado do cliente ou híbrida), você pode ter certeza de que está criando a melhor experiência possível para seus usuários e deixando o navegador cuidar do resto.