API GenAI Image Description

Essa API é oferecida na versão Beta e não está sujeita a SLAs nem a políticas de descontinuação. Mudanças podem ser feitas nessa API que quebram a compatibilidade com versões anteriores.

Com a API GenAI Image Description do Kit de ML, é possível gerar descrições curtas de conteúdo para imagens. Isso pode ser útil nos seguintes casos de uso:

• Gerar títulos de imagens
• Gerar texto alternativo (texto alternativo) para ajudar usuários com deficiência visual a entender melhor o conteúdo das imagens
• Usar descrições geradas como metadados para ajudar os usuários a pesquisar ou organizar imagens
• Usar descrições curtas de imagens quando o usuário não puder olhar para a tela, como ao dirigir ou ouvir um podcast

Principais recursos

• Retornar uma descrição curta para uma imagem de entrada

Resultados de exemplo

Entrada	Saída
	Um pequeno robô Android verde com um design de cacto está sentado em uma superfície preta.
	Um pequeno cachorro branco com nariz preto e língua rosa corre por um campo gramado com uma ponte ao fundo.

Primeiros passos

**Observação** :essa API exige o nível 26 ou mais recente da API Android.

Para começar a usar a API GenAI Image Description, adicione essa dependência ao arquivo de build do projeto.

implementation("com.google.mlkit:genai-image-description:1.0.0-beta1")

Para integrar a API Image Description ao app, comece recebendo um ImageDescriber cliente. Em seguida, verifique o status dos recursos de modelo no dispositivo necessários e faça o download do modelo se ele ainda não estiver no dispositivo. Depois de preparar a entrada da imagem em um ImageDescriptionRequest, execute a inferência usando o cliente para receber o texto de descrição da imagem e, por fim, feche o cliente para liberar recursos.

Kotlin

// Create an image describer
val options = ImageDescriberOptions.builder(context).build()
val imageDescriber = ImageDescription.getClient(options)

suspend fun prepareAndStartImageDescription(
    bitmap: Bitmap
) {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  val featureStatus = imageDescriber.checkFeatureStatus().await()

  if (featureStatus == FeatureStatus.DOWNLOADABLE) {
      // Download feature if necessary.
      // If downloadFeature is not called, the first inference request
      // will also trigger the feature to be downloaded if it's not
      // already downloaded.
      imageDescriber.downloadFeature(object : DownloadCallback {
          override fun onDownloadStarted(bytesToDownload: Long) { }

          override fun onDownloadFailed(e: GenAiException) { }

          override fun onDownloadProgress(totalBytesDownloaded: Long) {}

          override fun onDownloadCompleted() {
              startImageDescriptionRequest(bitmap, imageDescriber)
          }
      })
  } else if (featureStatus == FeatureStatus.DOWNLOADING) {
      // Inference request will automatically run once feature is
      // downloaded.
      // If Gemini Nano is already downloaded on the device, the
      // feature-specific LoRA adapter model will be downloaded
      // very quickly. However, if Gemini Nano is not already
      // downloaded, the download process may take longer.
      startImageDescriptionRequest(bitmap, imageDescriber)
  } else if (featureStatus == FeatureStatus.AVAILABLE) {
      startImageDescriptionRequest(bitmap, imageDescriber)
  }
}

fun startImageDescriptionRequest(
    bitmap: Bitmap,
    imageDescriber: ImageDescriber
) {
    // Create task request
    val imageDescriptionRequest = ImageDescriptionRequest
        .builder(bitmap)
        .build()
}

  // Run inference with a streaming callback
  val imageDescriptionResultStreaming =
      imageDescriber.runInference(imageDescriptionRequest) { outputText ->
          // Append new output text to show in UI
          // This callback is called incrementally as the description
          // is generated
      }

  // You can also get a non-streaming response from the request
  // val imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).await().description
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close()

Java

// Create an image describer
ImageDescriberOptions options = ImageDescriberOptions.builder(context).build();
ImageDescriber imageDescriber = ImageDescription.getClient(options);

void prepareAndStartImageDescription(
      Bitmap bitmap
) throws ExecutionException, InterruptedException {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  try {
      int featureStatus = imageDescriber.checkFeatureStatus().get();
      if (featureStatus == FeatureStatus.DOWNLOADABLE) {
          // Download feature if necessary.
          // If downloadFeature is not called, the first inference request
          // will also trigger the feature to be downloaded if it's not
          // already downloaded.
          imageDescriber.downloadFeature(new DownloadCallback() {
              @Override
              public void onDownloadCompleted() {
                  startImageDescriptionRequest(bitmap, imageDescriber);
              }

              @Override
              public void onDownloadFailed(GenAIException e) {}

              @Override
              public void onDownloadProgress(long totalBytesDownloaded) {}

              @Override
              public void onDownloadStarted(long bytesDownloaded) {}
          });
      } else if (featureStatus == FeatureStatus.DOWNLOADING) {
          // Inference request will automatically run once feature is
          // downloaded.
          // If Gemini Nano is already downloaded on the device, the
          // feature-specific LoRA adapter model will be downloaded
          // very quickly. However, if Gemini Nano is not already
          // downloaded, the download process may take longer.
          startImageDescriptionRequest(bitmap, imageDescriber);
      } else if (featureStatus == FeatureStatus.AVAILABLE) {
          startImageDescriptionRequest(bitmap, imageDescriber);
      }
  } catch (ExecutionException | InterruptedException e) {
      e.printStackTrace();
  }
}

void startImageDescriptionRequest(
     Bitmap bitmap,
     ImageDescriber imageDescriber
) {
  // Create task request
  ImageDescriptionRequest imageDescriptionRequest =
          ImageDescriptionRequest.builder(bitmap).build();

  // Start image description request with streaming response
  imageDescriber.runInference(imageDescriptionRequest, newText -> {
      // Append new output text to show in UI
      // This callback is called incrementally as the description
      // is generated
  });

  // You can also get a non-streaming response from the request
  // String imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).get().getDescription();
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close();

Recursos e limitações compatíveis

A API GenAI Image Description oferece suporte ao inglês, e o suporte a mais idiomas será adicionado no futuro. A API retorna uma descrição curta da imagem.

A disponibilidade da configuração de recurso específica (especificada por ImageDescriberOptions) pode variar dependendo da configuração do dispositivo e dos modelos que foram baixados para ele.

A maneira mais confiável para os desenvolvedores garantirem que o recurso de API pretendido seja compatível com um dispositivo com o ImageDescriberOptions solicitado é chamar o checkFeatureStatus() método. Esse método fornece o status definitivo da disponibilidade de recursos no dispositivo em tempo de execução.

Observação: as variações de hardware em diferentes tipos de dispositivos podem levar a diferenças nas versões do modelo base do Gemini Nano e, consequentemente, nas saídas da API GenAI do Kit de ML. Os adaptadores LoRA são aplicados para atenuar as diferenças.

Problemas comuns de configuração

**Observação**: essa API está indisponível em dispositivos com um bootloader desbloqueado.

As APIs GenAI do Kit de ML dependem do app Android AICore para acessar o Gemini Nano. Quando um dispositivo é configurado (incluindo a redefinição) ou o app AICore é redefinido (por exemplo, dados limpos, desinstalados e reinstalados), o app AICore pode não ter tempo suficiente para concluir a inicialização (incluindo o download das configurações mais recentes do servidor). Como resultado, as APIs GenAI do Kit de ML podem não funcionar como esperado. Confira as mensagens de erro de configuração comuns que podem aparecer e como lidar com elas:

Exemplo de mensagem de erro	Como lidar
O AICore falhou com o tipo de erro 4-CONNECTION_ERROR e o código de erro 601-BINDING_FAILURE: falha na vinculação do serviço do AICore.	Isso pode acontecer quando você instala o app usando as APIs GenAI do Kit de ML imediatamente após a configuração do dispositivo ou quando o AICore é desinstalado após a instalação do app. Atualizar o app AICore e reinstalar o app deve corrigir o problema.
O AICore falhou com o tipo de erro 3-PREPARATION_ERROR e o código de erro 606-FEATURE_NOT_FOUND: o recurso ... não está disponível.	Isso pode acontecer quando o AICore não terminar de baixar as configurações mais recentes. Quando o dispositivo está conectado à Internet, geralmente leva alguns minutos a algumas horas para atualizar. Reiniciar o dispositivo pode acelerar a atualização. Se o carregador de inicialização do dispositivo estiver desbloqueado, esse erro também vai aparecer. Essa API não oferece suporte a dispositivos com carregadores de inicialização desbloqueados.
O AICore falhou com o tipo de erro 1-DOWNLOAD_ERROR e o código de erro 0-UNKNOWN: o recurso ... falhou com o status de falha 0 e o erro esz: UNAVAILABLE: não foi possível resolver o host ...	Mantenha a conexão de rede, aguarde alguns minutos e tente novamente.

Observação: embora várias redefinições sejam comuns para desenvolvedores, elas são muito menos frequentes para os usuários. Além disso, todos esses casos de falha de configuração podem ser detectados pelas APIs checkFeatureStatus() ou checkStatus(). Chame checkFeatureStatus() ou checkStatus() primeiro antes de mostrar qualquer interface relacionada para que os usuários do app não vejam esses erros em nenhum caso.

Exemplo de código

• Exemplos de GenAI do Kit de ML