Inizia a utilizzare l'API Prompt

Questa pagina descrive come:

• Configurare il progetto per utilizzare l'API Prompt
• Fornire input di solo testo e ricevere una risposta
• Fornire un input di immagine con input di testo correlato e ricevere una risposta

Per maggiori dettagli sull'API Prompt, consulta la documentazione di riferimento per Kotlin (com.google.mlkit.genai.prompt) e Java (com.google.mlkit.genai.prompt.java, com.google.mlkit.genai.prompt).

Configura il progetto

Aggiungi l'API Prompt di ML Kit come dipendenza nella configurazione build.gradle:

implementation("com.google.mlkit:genai-prompt:1.0.0-beta2")

Se hai bisogno delle risposte in un determinato formato utilizzando l'API Output strutturato, devi configurare KSP e aggiungere dipendenze aggiuntive. Per i dettagli, consulta Generare output strutturato.

Implementa il modello generativo

Per implementare il codice nel progetto:

• Crea un oggetto generativeModel:

  Kotlin

  // Get a GenerativeModel instance
  val generativeModel = Generation.getClient()
  

  Java

  // Get a GenerativeModel instance
  GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
      .from(Generation.INSTANCE.getClient());
  

• Controlla se Gemini Nano è AVAILABLE, DOWNLOADABLE o UNAVAILABLE. Quindi, scarica la funzionalità se è scaricabile:

  Kotlin

  val status = generativeModel.checkStatus()
  when (status) {
      FeatureStatus.UNAVAILABLE -> {
          // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
      }
  
      FeatureStatus.DOWNLOADABLE -> {
          // Gemini Nano can be downloaded on this device, but is not currently downloaded
          generativeModel.download().collect { status ->
              when (status) {
                  is DownloadStatus.DownloadStarted ->
                      Log.d(TAG, "starting download for Gemini Nano")
  
                  is DownloadStatus.DownloadProgress ->
                      Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")
  
                  DownloadStatus.DownloadCompleted -> {
                      Log.d(TAG, "Gemini Nano download complete")
                      modelDownloaded = true
                  }
  
                  is DownloadStatus.DownloadFailed -> {
                      Log.e(TAG, "Nano download failed ${status.e.message}")
                  }
              }
          }
      }
  
      FeatureStatus.DOWNLOADING -> {
          // Gemini Nano currently being downloaded
      }
  
      FeatureStatus.AVAILABLE -> {
          // Gemini Nano currently downloaded and available to use on this device
      }
  }
  

  Java

  ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
  Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
      @Override
      public void onSuccess(Integer featureStatus) {
          switch (featureStatus) {
              case FeatureStatus.AVAILABLE - > {
                  // Gemini Nano currently downloaded and available to use on this device
              }
              case FeatureStatus.UNAVAILABLE - > {
                  // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
              }
              case FeatureStatus.DOWNLOADING - > {
                  // Gemini Nano currently being downloaded
              }
              case FeatureStatus.DOWNLOADABLE - > {
                  generativeModelFutures.download(new DownloadCallback() {
                      @Override
                      public void onDownloadStarted(long l) {
                          Log.d(TAG, "starting download for Gemini Nano");
                      }
                      @Override
                      public void onDownloadProgress(long l) {
                          Log.d(TAG, "Nano " + l + " bytes downloaded");
                      }
                      @Override
                      public void onDownloadCompleted() {
                          Log.d(TAG, "Gemini Nano download complete");
                      }
                      @Override
                      public void onDownloadFailed(@NonNull GenAiException e) {
                          Log.e(TAG, "Nano download failed: " + e.getMessage());
                      }
                  });
              }
          }
      }
      @Override
      public void onFailure(@NonNull Throwable t) {
          // Failed to check status
      }
  }, ContextCompat.getMainExecutor(context));
  
  

Fornisci input di solo testo

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

In alternativa, aggiungi parametri facoltativi:

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

Per ulteriori informazioni sui parametri facoltativi, consulta Configurazioni facoltative.

Fornisci input multimodale (immagine e testo)

Raggruppa un'immagine e un input di testo nella funzione generateContentRequest(), con il prompt testuale che è una domanda o un comando relativo all'immagine. Puoi raggruppare più immagini e testo nella stessa richiesta.

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new ImagePart(bitmap),
        new TextPart("textPrompt"))
    // optional parameters
    .build())
.get();

Elabora il risultato dell'inferenza

• Esegui l'inferenza e recupera il risultato. Puoi scegliere di attendere il risultato completo o di trasmettere in streaming la risposta man mano che viene generata per i prompt di solo testo e multimodali.

  • Questa opzione utilizza l'inferenza non in streaming, che recupera l'intero risultato dal modello AI prima di restituirlo:

  Kotlin

  // Call the AI model to generate content and store the complete
  // in a new variable named 'response' once it's finished
  val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")
  

  Java

  GenerateContentResponse response = generativeModelFutures.generateContent(
          new GenerateContentRequest.Builder(
                  new TextPart("Write a 3 sentence story about a magical dog."))
                  .build())
          .get();
  

  • I seguenti snippet sono esempi di utilizzo dell'inferenza in streaming, che recupera il risultato in blocchi man mano che viene generato:

  Kotlin

  // Streaming inference
  var fullResponse = ""
  generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
      val newChunkReceived = chunk.candidates[0].text
      print(newChunkReceived)
      fullResponse += newChunkReceived
  }
  

  Java

  // Streaming inference
  StringBuilder fullResponse = new StringBuilder();
  generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
      (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
          chunk -> {
              Log.d(TAG, chunk);
              fullResponse.append(chunk);
          });
  

Per ulteriori informazioni sull'inferenza in streaming e non in streaming, consulta Streaming versus non-streaming.

Ottimizzazione della latenza

Per ottimizzare la prima chiamata di inferenza, l'applicazione può facoltativamente chiamare warmup(). In questo modo, Gemini Nano viene caricato in memoria e i componenti di runtime vengono inizializzati.

Configurazioni facoltative

Nell'ambito di ogni GenerateContentRequest, puoi impostare i seguenti parametri facoltativi:

• temperature : controlla il grado di casualità nella selezione dei token.
• seed : consente di generare risultati stabili e deterministici.
• topK : controlla la casualità e la diversità dei risultati.
• candidateCount : richiede il numero di risposte univoche restituite. Tieni presente che il numero esatto di risposte potrebbe non corrispondere a candidateCount perché le risposte duplicate vengono rimosse automaticamente.
• maxOutputTokens : definisce il numero massimo di token che possono essere generati nella risposta.

Per ulteriori indicazioni sull'impostazione delle configurazioni facoltative, consulta GenerateContentRequest.

Funzionalità supportate e limitazioni

• L'input deve contenere meno di 4000 token (o circa 3000 parole in inglese). Per ulteriori informazioni, consulta il countTokens riferimento.
• Evita i casi d'uso che richiedono un output lungo (più di 4000 token).
• AICore applica una quota di inferenza per app. Per ulteriori informazioni, consulta Quota per applicazione.

Problemi di configurazione comuni

Le API GenAI di ML Kit si basano sull'app Android AICore per accedere a Gemini Nano. Quando un dispositivo viene configurato (incluso il ripristino) o l'app AICore viene ripristinata (ad es. cancellazione dei dati, disinstallazione e reinstallazione), 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 GenAI di ML Kit potrebbero non funzionare come previsto. Di seguito sono riportati i messaggi di errore di configurazione comuni che potresti visualizzare e come gestirli: