Erste Schritte mit der Prompt API

Auf dieser Seite wird Folgendes beschrieben:

  • Projekt für die Verwendung der Prompt API konfigurieren
  • Nur-Texteingabe bereitstellen und eine Antwort erhalten
  • Bildeingabe mit zugehöriger Texteingabe bereitstellen und eine Antwort erhalten

Weitere Informationen zur Prompt API finden Sie in der Referenzdokumentation für Kotlin (com.google.mlkit.genai.prompt) und Java (com.google.mlkit.genai.prompt.java, com.google.mlkit.genai.prompt).

Projekt konfigurieren

Fügen Sie die ML Kit Prompt API als Abhängigkeit in Ihrer build.gradle-Konfiguration hinzu:

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

Generatives Modell implementieren

So implementieren Sie den Code in Ihrem Projekt:

  • Erstellen Sie ein generativeModel-Objekt:

    Kotlin

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

    Java

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

  • Prüfen Sie, ob Gemini Nano AVAILABLE, DOWNLOADABLE oder UNAVAILABLE ist. Laden Sie die Funktion herunter, wenn sie heruntergeladen werden kann:

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

Nur-Texteingabe bereitstellen

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

Alternativ können Sie optionale Parameter hinzufügen:

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

Weitere Informationen zu den optionalen Parametern finden Sie unter Optionale Konfigurationen.

Multimodale Eingabe (Bild und Text) bereitstellen

Bündeln Sie eine Bild- und eine Texteingabe in der Funktion generateContentRequest(). Der Text-Prompt ist eine Frage oder ein Befehl, der sich auf das Bild bezieht:

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

Inferenz-Ergebnis verarbeiten

  • Führen Sie die Inferenz aus und rufen Sie das Ergebnis ab. Sie können entweder auf das vollständige Ergebnis warten oder die Antwort streamen, während sie für Nur-Text- und multimodale Prompts generiert wird.

    • Hier wird die nicht streamende Inferenz verwendet, bei der das gesamte Ergebnis vom KI-Modell abgerufen wird, bevor es zurückgegeben wird:

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

    • Die folgenden Snippets sind Beispiele für die Verwendung der streamenden Inferenz, bei der das Ergebnis in Teilen abgerufen wird, während es generiert wird:

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

Weitere Informationen zur streamenden und nicht streamenden Inferenz finden Sie unter Streamende und nicht streamende Inferenz.

Latenzoptimierung

Um den ersten Inferenzaufruf zu optimieren, kann Ihre Anwendung optional warmup() aufrufen. Dadurch wird Gemini Nano in den Arbeitsspeicher geladen und Laufzeitkomponenten werden initialisiert.

Optionale Konfigurationen

Im Rahmen jeder GenerateContentRequest können Sie die folgenden optionalen Parameter festlegen:

  • temperature : Steuert den Grad der Zufälligkeit bei der Tokenauswahl.
  • seed : Ermöglicht das Generieren stabiler und deterministischer Ergebnisse.
  • topK : Steuert die Zufälligkeit und Vielfalt der Ergebnisse.
  • candidateCount : Fordert die Anzahl der zurückgegebenen eindeutigen Antworten an. Beachten Sie, dass die genaue Anzahl der Antworten möglicherweise nicht candidateCount entspricht, da doppelte Antworten automatisch entfernt werden.
  • maxOutputTokens : Definiert die maximale Anzahl von Tokens, die in der Antwort generiert werden können.

Weitere Informationen zum Festlegen optionaler Konfigurationen finden Sie unter GenerateContentRequest.

Unterstützte Funktionen und Einschränkungen

  • Die Eingabe muss weniger als 4.000 Tokens (oder etwa 3.000 englische Wörter) umfassen. Weitere Informationen finden Sie in der countTokens Referenz.
  • Anwendungsfälle, die eine lange Ausgabe erfordern (mehr als 256 Tokens), sollten vermieden werden.
  • AICore erzwingt ein Inferenzkontingent pro App. Weitere Informationen finden Sie unter Kontingent pro Anwendung.
  • Die folgenden Sprachen wurden für die Prompt API validiert:
    • Englisch
    • Koreanisch

Häufig auftretende Probleme bei der Einrichtung

ML Kit GenAI APIs greifen über die Android AICore App auf Gemini Nano zu. Wenn ein Gerät gerade eingerichtet (einschließlich Zurücksetzen) oder die AICore App gerade zurückgesetzt wurde (z.B. Daten gelöscht, deinstalliert und dann neu installiert), hat die AICore App möglicherweise nicht genügend Zeit, die Initialisierung abzuschließen (einschließlich des Herunterladens der neuesten Konfigurationen vom Server). Daher funktionieren die ML Kit GenAI APIs möglicherweise nicht wie erwartet. Hier sind die häufigsten Fehlermeldungen bei der Einrichtung und wie Sie damit umgehen können:

Beispiel für Fehlermeldung Vorgehensweise
AICore ist mit dem Fehlertyp 4-CONNECTION_ERROR und dem Fehlercode 601-BINDING_FAILURE fehlgeschlagen: AICore-Dienst konnte nicht gebunden werden. Das kann passieren, wenn Sie die App mit ML Kit GenAI APIs sofort nach der Geräteeinrichtung installieren oder wenn AICore deinstalliert wird, nachdem Ihre App installiert wurde. Wenn Sie die AICore App aktualisieren und dann Ihre App neu installieren, sollte das Problem behoben sein.
AICore ist mit dem Fehlertyp 3-PREPARATION_ERROR und dem Fehlercode 606-FEATURE_NOT_FOUND fehlgeschlagen: Funktion ... ist nicht verfügbar. Das kann passieren, wenn AICore das Herunterladen der neuesten Konfigurationen noch nicht abgeschlossen hat. Wenn das Gerät mit dem Internet verbunden ist, dauert die Aktualisierung in der Regel einige Minuten bis einige Stunden. Ein Neustart des Geräts kann die Aktualisierung beschleunigen.

Beachten Sie, dass dieser Fehler auch angezeigt wird, wenn der Bootloader des Geräts entsperrt ist. Diese API unterstützt keine Geräte mit entsperrten Bootloadern.
AICore ist mit dem Fehlertyp 1-DOWNLOAD_ERROR und dem Fehlercode 0-UNKNOWN fehlgeschlagen: Funktion ... ist mit dem Fehlerstatus 0 und dem Fehler esz: UNAVAILABLE fehlgeschlagen: Host kann nicht aufgelöst werden ... Behalten Sie die Netzwerkverbindung bei, warten Sie einige Minuten und versuchen Sie es noch einmal.