Inizia a utilizzare l'API Prompt

Questa pagina descrive come:

  • Configura il progetto per utilizzare l'API Prompt
  • Fornisci un input di solo testo e ricevi una risposta
  • Fornire input di immagini 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 di build.gradle:

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

Se hai bisogno di risposte in un determinato formato utilizzando l'API Structured Output, devi configurare KSP e aggiungere altre dipendenze. Per maggiori dettagli, consulta Genera output strutturato.

Implementa il modello generativo

Per implementare il codice nel tuo progetto, segui questi passaggi:

  • 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 un input di solo testo

Kotlin

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

In alternativa, aggiungi parametri facoltativi:

Kotlin

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

Java

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 un input multimodale (immagine e testo)

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

Kotlin

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

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new Content.Builder()
            .addPart(new ImagePart(bitmap1))
            .addPart(new ImagePart(bitmap2))
            .addPart(new TextPart("textPrompt"))
            .build())
    // 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 la risposta in streaming man mano che viene generata sia per i prompt di solo testo che per quelli multimodali.

    • In questo modo viene utilizzata l'inferenza non in streaming, che recupera l'intero risultato dal modello di 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 modalità flusso, 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 saperne di più sull'inferenza in modalità flusso di dati e non in modalità flusso di dati, consulta Flusso di dati e non flusso di dati.

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 vengono inizializzati i componenti di runtime.

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 saperne di più, consulta il riferimento countTokens.
  • I casi d'uso che richiedono un output lungo (più di 4000 token) devono essere evitati.
  • AICore applica una quota di inferenza per app. Per ulteriori informazioni, vedi 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 appena configurato (incluso il reset) o l'app AICore viene appena resettata (ad es. cancellazione dei dati, disinstallazione e reinstallazione), l'app AICore potrebbe non avere abbastanza tempo 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:

Esempio di messaggio di errore Come gestirla
AICore non è riuscito con il tipo di errore 4-CONNECTION_ERROR e il codice di errore 601-BINDING_FAILURE: impossibile associare il servizio AICore. Ciò potrebbe accadere quando installi l'app utilizzando le API GenAI di ML Kit immediatamente dopo la configurazione del dispositivo o quando AICore viene disinstallato dopo l'installazione dell'app. Il problema dovrebbe risolversi 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. Ciò potrebbe accadere quando AICore non ha terminato il download delle configurazioni più recenti. Quando il dispositivo è connesso a internet, l'aggiornamento richiede in genere da alcuni minuti ad alcune ore. Il riavvio del dispositivo può velocizzare l'aggiornamento.

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: impossibile risolvere l'host … Mantieni la connessione di rete, attendi qualche minuto e riprova.