API GenAI Image Description

Questa API è offerta in versione beta e non è soggetta a SLA (accordo sul livello del servizio) o norme sul ritiro. A questa API potrebbero essere apportate modifiche che ne compromettono la compatibilità con le versioni precedenti.

Con l'API di descrizione delle immagini basata sull'IA generativa di ML Kit, puoi generare descrizioni brevi dei contenuti per le immagini. Questa opzione può essere utile nei seguenti casi d'uso:

• Generazione dei titoli delle immagini
• Generazione di testo alternativo (testo alt) per aiutare gli utenti con disabilità visiva a comprendere meglio i contenuti delle immagini
• Utilizzo delle descrizioni generate come metadati per aiutare gli utenti a cercare o organizzare le immagini
• Utilizzare descrizioni brevi delle immagini quando l'utente non è in grado di guardare lo schermo, ad esempio quando guida o ascolta un podcast

Funzionalità chiave

• Restituisce una breve descrizione di un'immagine di input

Risultati di esempio

Ingresso	Output
	Un piccolo robot Android verde con un design simile a un cactus è appoggiato su una superficie nera.
	Un piccolo cane bianco con il naso nero e la lingua rosa corre in un campo erboso con un ponte sullo sfondo.

Per iniziare

Nota: questa API richiede il livello API Android 26 o versioni successive.

Per iniziare a utilizzare l'API GenAI Image Description, aggiungi questa dipendenza al file di compilazione del progetto.

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

Per integrare l'API Image Description nella tua app, devi prima creare un client ImageDescriber. Devi quindi controllare lo stato delle funzionalità del modello on-device necessarie e scaricare il modello se non è già sul dispositivo. Dopo aver preparato l'input immagine in un ImageDescriptionRequest, esegui l'inferenza utilizzando il client per ottenere il testo della descrizione dell'immagine e infine, ricordati di chiudere il client per rilasciare le risorse.

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();

Funzionalità supportate e limitazioni

L'API GenAI Image Description supporta l'inglese, ma in futuro verranno aggiunte altre lingue. L'API restituisce una breve descrizione dell'immagine.

La disponibilità della configurazione della funzionalità specifica (specificata da ImageDescriberOptions) può variare in base alla configurazione del singolo dispositivo e ai modelli che sono stati scaricati sul dispositivo.

Il modo più affidabile per gli sviluppatori di assicurarsi che la funzionalità dell'API prevista sia supportata su un dispositivo con il ImageDescriberOptions richiesto è chiamare il metodo checkFeatureStatus(). Questo metodo fornisce lo stato definitivo della disponibilità delle funzionalità sul dispositivo in fase di esecuzione.

Nota: le variazioni hardware tra diversi tipi di dispositivi possono portare a differenze nelle versioni del modello di base di Gemini Nano e, di conseguenza, nelle uscite dell'API ML Kit GenAI. Gli adattatori LoRA vengono applicati per attenuare le differenze.

Problemi di configurazione comuni

Nota: questa API non è supportata sui dispositivi con un bootloader sbloccato.

Le API ML Kit GenAI si basano sull'app Android AICore per accedere a Gemini Nano. Quando un dispositivo è appena stato configurato (incluso il ripristino dei dati di fabbrica) o l'app AICore è appena stata reimpostata (ad es. dati cancellati, disinstallata e reinstallata), l'app AICore potrebbe non avere tempo sufficiente per completare l'inizializzazione (incluso il download delle configurazioni più recenti dal server). Di conseguenza, le API ML Kit GenAI potrebbero non funzionare come previsto. Di seguito sono riportati i messaggi di errore di configurazione più comuni che potresti visualizzare e come gestirli:

Esempio di messaggio di errore	Come gestire
AICore non è riuscito con il tipo di errore 4-CONNECTION_ERROR e il codice di errore 601-BINDING_FAILURE: non è stato possibile eseguire l'associazione del servizio AICore.	Ciò può accadere quando installi l'app utilizzando le API ML Kit GenAI immediatamente dopo la configurazione del dispositivo o quando AICore viene disinstallato dopo l'installazione dell'app. Il problema dovrebbe essere risolto aggiornando l'app AICore e reinstallando la tua app.
AICore non è riuscito con il tipo di errore 3-PREPARATION_ERROR e il codice di errore 606-FEATURE_NOT_FOUND: la funzionalità ... non è disponibile.	Questo può accadere quando AICore non ha completato il download delle configurazioni più recenti. Mantieni la connessione di rete e attendi da alcuni minuti a qualche ora. Tieni presente che se il bootloader del dispositivo è sbloccato, vedrai anche questo errore: questa API non supporta i dispositivi con bootloader sbloccati.
AICore non è riuscito con il tipo di errore 1-DOWNLOAD_ERROR e il codice di errore 0-UNKNOWN: la funzionalità ... non è riuscita con lo stato di errore 0 e l'errore esz: UNAVAILABLE: Unable to resolve host ...	Mantieni la connessione di rete, attendi qualche minuto e riprova.

Nota: sebbene i vari reset siano comuni agli sviluppatori, sono molto meno frequenti per gli utenti. Inoltre, tutti questi casi di errore di configurazione possono essere rilevati dall'API checkFeatureStatus(). Assicurati di chiamare prima checkFeatureStatus() prima di mostrare l'interfaccia utente correlata, in modo che gli utenti dell'app non vedano mai questi errori.