Guia de inferência de LLM para Web

A API LLM Inference permite executar modelos de linguagem grandes (LLMs) completamente no dispositivo para aplicativos da Web, que podem ser usados para realizar uma ampla variedade de tarefas, como gerar texto, recuperar informações em linguagem natural e resumir documentos. A tarefa oferece suporte integrado a vários modelos de linguagem grandes de texto para texto. Assim, você pode aplicar os modelos de IA generativa mais recentes no dispositivo aos seus apps da Web. Se você estiver usando os modelos mais recentes do Gemma-3n, também será possível usar entradas de imagem e áudio.

Para adicionar rapidamente a API LLM Inference ao seu aplicativo da Web, siga o guia de início rápido. Para um exemplo básico de um aplicativo da Web que executa a API LLM Inference, consulte o aplicativo de exemplo. Para entender melhor como a API LLM Inference funciona, consulte as seções opções de configuração, conversão de modelo e ajuste de LoRA.

Confira essa tarefa em ação com a demonstração do MediaPipe Studio. Para mais informações sobre os recursos, modelos e opções de configuração dessa tarefa, consulte a Visão geral.

Guia de início rápido

Siga estas etapas para adicionar a API LLM Inference ao seu aplicativo da Web. A API LLM Inference requer um navegador da Web com compatibilidade com WebGPU. Para uma lista completa de navegadores compatíveis, consulte Compatibilidade de navegadores com GPU.

Adicionar dependências

A API LLM Inference usa o pacote @mediapipe/tasks-genai (em inglês).

Instale os pacotes necessários para o preparo local:

npm install @mediapipe/tasks-genai

Para fazer a implantação em um servidor, use um serviço de rede de fornecimento de conteúdo (CDN) como o jsDelivr para adicionar código diretamente à sua página HTML:

<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai/genai_bundle.cjs"
    crossorigin="anonymous"></script>
</head>

Fazer o download de um modelo

Faça o download do Gemma-3n E4B ou E2B da HuggingFace. Os modelos com "-Web" no nome são convertidos especificamente para uso na Web. Por isso, é altamente recomendável usar sempre um deles.

Para mais informações sobre os modelos disponíveis, consulte a documentação de modelos ou navegue pela página da comunidade HuggingFace, que oferece várias outras variantes do Gemma 3 não abordadas na documentação, mas que foram convertidas especialmente para a Web, como 270M, 4B, 12B, 27B e MedGemma-27B-Text.

Armazene o modelo no diretório do projeto:

<dev-project-root>/assets/gemma-3n-E4B-it-int4-Web.litertlm

Especifique o caminho do modelo com o parâmetro modelAssetPath do objeto baseOptions:

baseOptions: { modelAssetPath: `/assets/gemma-3n-E4B-it-int4-Web.litertlm`}

Inicializar a tarefa

Inicialize a tarefa com opções básicas de configuração:

const genai = await FilesetResolver.forGenAiTasks(
    // path/to/wasm/root
    "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai@latest/wasm"
);
llmInference = await LlmInference.createFromOptions(genai, {
    baseOptions: {
        modelAssetPath: '/assets/gemma-3n-E4B-it-int4-Web.litertlm'
    },
    maxTokens: 1000,
    topK: 40,
    temperature: 0.8,
    randomSeed: 101
});

Executar a tarefa

Use a função generateResponse() para acionar inferências.

const response = await llmInference.generateResponse(inputPrompt);
document.getElementById('output').textContent = response;

Para transmitir a resposta, use o seguinte:

llmInference.generateResponse(
  inputPrompt,
  (partialResult, done) => {
        document.getElementById('output').textContent += partialResult;
});

Comandos multimodais

Para modelos do Gemma-3n, as APIs da Web de inferência de LLM oferecem suporte a comandos multimodais. Com a multimodalidade ativada, os usuários podem incluir uma combinação ordenada de imagens, áudio e texto nos comandos. Em seguida, o LLM fornece uma resposta de texto.

Para começar, use Gemma-3n E4B ou Gemma-3n E2B, em um formato compatível com MediaPipe e Web. Para mais informações, consulte a documentação do Gemma-3n.

Para ativar o suporte à visão, verifique se maxNumImages está definido como um valor positivo. Isso determina o número máximo de partes de imagem que o LLM pode processar em um único comando.

Para ativar o suporte de áudio, verifique se supportAudio está definido como true.

llmInference = await LlmInference.createFromOptions(genai, {
    baseOptions: {
        modelAssetPath: '/assets/gemma-3n-E4B-it-int4-Web.litertlm'
    },
    maxTokens: 1000,
    topK: 40,
    temperature: 0.8,
    randomSeed: 101,
    maxNumImages: 5,
    supportAudio: true,
});

As respostas podem ser geradas como antes, mas usando uma matriz ordenada de strings, imagens e dados de áudio:

const response = await llmInference.generateResponse([
  '<ctrl99>user\nDescribe ',
  {imageSource: '/assets/test_image.png'},
  ' and then transcribe ',
  {audioSource: '/assets/test_audio.wav'},
  '<ctrl100>\n<ctrl99>model\n',
]);

Para visão, há suporte para URLs de imagens e os objetos de imagem, vídeo ou tela mais comuns. Para áudio, somente AudioBuffer de canal único e URLs de arquivos de áudio de canal mono são compatíveis. Para mais detalhes, navegue pelo código-fonte.

Exemplo de aplicativo

O aplicativo de exemplo é um exemplo de um app básico de geração de texto para a Web, usando a API LLM Inference. Você pode usar o app como ponto de partida para seu próprio app da Web ou consultá-lo ao modificar um app existente. O código de exemplo está hospedado no GitHub.

Clone o repositório git usando o comando a seguir:

git clone https://github.com/google-ai-edge/mediapipe-samples

Para mais informações, consulte o Guia de configuração para a Web.

Opções de configuração

Use as seguintes opções de configuração para criar um web app:

Nome da opção Descrição Intervalo de valor Valor padrão
modelPath O caminho para onde o modelo é armazenado no diretório do projeto. CAMINHO N/A
maxTokens O número máximo de tokens (tokens de entrada + tokens de saída) que o modelo processa. Número inteiro 512
topK O número de tokens que o modelo considera em cada etapa da geração. Limita as previsões aos k tokens mais prováveis. Número inteiro 40
temperature A quantidade de aleatoriedade introduzida durante a geração. Uma temperatura mais alta resulta em mais criatividade no texto gerado, enquanto uma temperatura mais baixa produz uma geração mais previsível. Ponto flutuante 0,8
randomSeed A seed aleatória usada durante a geração de texto. Número inteiro 0
loraRanks Classificações de LoRA a serem usadas pelos modelos de LoRA durante a execução. Observação: isso só é compatível com modelos de GPU. Matriz de números inteiros N/A

Conversão de modelos

A API LLM Inference é compatível com os seguintes tipos de modelos, alguns dos quais exigem conversão. Use a tabela para identificar as etapas e o método necessários para seu modelo.

Modelos Método de conversão Plataformas compatíveis Tipo de arquivo
Gemma-3 1B Nenhuma conversão necessária Android, web .task
Gemma 2B, Gemma 7B, Gemma-2 2B Nenhuma conversão necessária Android, iOS, Web .bin
Phi-2, StableLM, Falcon Script de conversão do MediaPipe Android, iOS, Web .bin
Todos os modelos de LLM do PyTorch Biblioteca generativa do AI Edge Torch Android, iOS .task

Para saber como converter outros modelos, consulte a seção Conversão de modelo.

Personalização da LoRA

A API LLM Inference oferece suporte ao ajuste de LoRA (Low-Rank Adaptation) usando a biblioteca PEFT (Parameter-Efficient Fine-Tuning). O ajuste do LoRA personaliza o comportamento dos LLMs com um processo de treinamento econômico, criando um pequeno conjunto de pesos treináveis com base em novos dados de treinamento, em vez de treinar todo o modelo novamente.

A API LLM Inference permite adicionar pesos de LoRA às camadas de atenção dos modelos Gemma-2 2B, Gemma 2B e Phi-2. Faça o download do modelo no formato safetensors.

O modelo de base precisa estar no formato safetensors para criar ponderações de LoRA. Depois do treinamento LoRA, é possível converter os modelos para o formato FlatBuffers para execução no MediaPipe.

Preparar ponderações da LoRA

Use o guia LoRA Methods da PEFT para treinar um modelo LoRA refinado no seu próprio conjunto de dados.

A API LLM Inference só oferece suporte a LoRA em camadas de atenção. Portanto, especifique apenas as camadas de atenção em LoraConfig:

# For Gemma
from peft import LoraConfig
config = LoraConfig(
    r=LORA_RANK,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)

# For Phi-2
config = LoraConfig(
    r=LORA_RANK,
    target_modules=["q_proj", "v_proj", "k_proj", "dense"],
)

Depois de treinar no conjunto de dados preparado e salvar o modelo, os pesos do modelo LoRA refinado estarão disponíveis em adapter_model.safetensors. O arquivo safetensors é o checkpoint do LoRA usado durante a conversão do modelo.

Conversão de modelos

Use o pacote Python do MediaPipe para converter os pesos do modelo no formato Flatbuffer. O ConversionConfig especifica as opções de modelo de base e as opções adicionais de LoRA.

import mediapipe as mp
from mediapipe.tasks.python.genai import converter

config = converter.ConversionConfig(
  # Other params related to base model
  ...
  # Must use gpu backend for LoRA conversion
  backend='gpu',
  # LoRA related params
  lora_ckpt=LORA_CKPT,
  lora_rank=LORA_RANK,
  lora_output_tflite_file=LORA_OUTPUT_FILE,
)

converter.convert_checkpoint(config)

O conversor vai produzir dois arquivos compatíveis com o MediaPipe, um para o modelo base e outro para o modelo LoRA.

Inferência de modelo LoRA

A Web oferece suporte ao LoRA dinâmico durante a execução, ou seja, os usuários declaram os ranks do LoRA durante a inicialização. Isso significa que você pode trocar diferentes modelos de LoRA durante a execução.

const genai = await FilesetResolver.forGenAiTasks(
    // path/to/wasm/root
    "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai@latest/wasm"
);
const llmInference = await LlmInference.createFromOptions(genai, {
    // options for the base model
    ...
    // LoRA ranks to be used by the LoRA models during runtime
    loraRanks: [4, 8, 16]
});

Carregue os modelos LoRA durante a execução, depois de inicializar o modelo de base. Acione o modelo LoRA transmitindo a referência do modelo ao gerar a resposta do LLM.

// Load several LoRA models. The returned LoRA model reference is used to specify
// which LoRA model to be used for inference.
loraModelRank4 = await llmInference.loadLoraModel(loraModelRank4Url);
loraModelRank8 = await llmInference.loadLoraModel(loraModelRank8Url);

// Specify LoRA model to be used during inference
llmInference.generateResponse(
  inputPrompt,
  loraModelRank4,
  (partialResult, done) => {
        document.getElementById('output').textContent += partialResult;
});