Inizia a utilizzare l'API Prompt

Questa pagina descrive come:

  • Configura il tuo progetto per utilizzare l'API Prompt
  • Fornire input di solo testo e ricevere una risposta
  • Fornire un input di immagine con un 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).

[Facoltativo] Testare il prompt con il modello Gemma 3n

Prima dell'implementazione, valuta la possibilità di testare il prompt in AI Studio con il modello Gemma 3n E4B. Gli output di Gemma 3n possono essere molto simili a quelli di nano-v3.

Configura il progetto

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

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

Implementare il modello generativo

Per implementare il codice nel tuo 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. Poi, scarica la funzionalità se è disponibile per il download:

    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

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.

Fornire input multimodali (immagini e testo)

Raggruppa un'immagine e un input di testo nella funzione generateContentRequest(), con il prompt di testo che è una domanda o un comando relativo all'immagine:

Kotlin

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

Java

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 riprodurre in streaming la risposta man mano che viene generata per i prompt solo di testo e multimodali.

    • 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 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 la sezione Streaming e non in streaming.

Ottimizzazione della latenza

Per l'ottimizzazione della prima chiamata di inferenza, l'applicazione può chiamare facoltativamente warmup(). Carica Gemini Nano in memoria e inizializza 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à nei risultati.
  • candidateCount : richiede il numero di risposte uniche 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 maggiori informazioni, consulta il riferimento countTokens.
  • Evita i casi d'uso che richiedono un output lungo (più di 256 token).
  • AICore applica una quota di inferenza per app. Per ulteriori informazioni, consulta la sezione Quota per applicazione.
  • Le seguenti lingue sono state convalidate per l'API Prompt:
    • Inglese
    • Coreano

Problemi di configurazione comuni

Le API ML Kit GenAI si basano sull'app Android AICore per accedere a Gemini Nano. Quando un dispositivo viene appena configurato (incluso il ripristino) o l'app AICore viene appena 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 ML Kit GenAI 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 a eseguire l'operazione con il tipo di errore 4-CONNECTION_ERROR e il codice di errore 601-BINDING_FAILURE: il servizio AICore non è riuscito a eseguire il binding. 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. L'aggiornamento dell'app AICore e la reinstallazione dell'app dovrebbero risolvere il problema.
AICore non è riuscito a completare l'operazione con il tipo di errore 3 - PREPARATION_ERROR e il codice di errore 606 - FEATURE_NOT_FOUND: la funzionalità ... non è disponibile. Ciò può accadere quando AICore non ha completato il download delle configurazioni più recenti. Quando il dispositivo è connesso a internet, l'aggiornamento richiede in genere da pochi minuti a qualche ora. Il riavvio del dispositivo può velocizzare l'aggiornamento.

Tieni presente che se il bootloader del dispositivo è sbloccato, visualizzerai anche questo errore. Questa API non supporta i dispositivi con bootloader sbloccati.
AICore non è riuscito a completare l'operazione con il tipo di errore 1-DOWNLOAD_ERROR e il codice di errore 0-UNKNOWN: Feature ... failed with failure status 0 and error esz: UNAVAILABLE: Unable to resolve host ... Mantieni la connessione di rete, attendi qualche minuto e riprova.