Erste Schritte mit der Prompt API

Auf dieser Seite wird Folgendes beschrieben:

  • Projekt für die Verwendung der Prompt API konfigurieren
  • Nur Text als Eingabe verwenden und eine Antwort erhalten
  • Ein Bild mit zugehörigem Text eingeben 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).

[Optional] Prompt mit dem Gemma 3n-Modell testen

Bevor Sie den Prompt implementieren, sollten Sie ihn in AI Studio mit dem Modell Gemma 3n E4B testen. Die Ausgaben von Gemma 3n sind in der Regel sehr ähnlich denen von nano-v3.

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-alpha1")

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 dann herunter, sofern dies möglich ist:

    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 Text als Eingabe verwenden

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

Fassen Sie ein Bild und eine Texteingabe in der Funktion generateContentRequest() zusammen. 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();

Inferenzresultat 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 generiert wird. Das gilt sowohl für Nur-Text- als auch für multimodale Prompts.

    • Dabei wird die Inferenz ohne Streaming verwendet. Das bedeutet, dass 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 von Streaming-Inferenz, bei der das Ergebnis in Chunks 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 zu Streaming- und Nicht-Streaming-Inferenz finden Sie unter Streaming im Vergleich zu Nicht-Streaming.

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. Die genaue Anzahl der Antworten stimmt möglicherweise nicht mit candidateCount überein, da doppelte Antworten automatisch entfernt werden.
  • maxOutputTokens : Definiert die maximale Anzahl an 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 darf maximal 4.000 Tokens (ca. 3.000 Wörter auf Englisch) umfassen. Weitere Informationen finden Sie in der Referenz zu countTokens.
  • Anwendungsfälle, die eine lange Ausgabe (mehr als 256 Tokens) erfordern, 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

Für den Zugriff auf Gemini Nano nutzen die GenAI-APIs von ML Kit die Android AICore App. Wenn ein Gerät gerade eingerichtet (einschließlich Zurücksetzen) oder die AICore App gerade zurückgesetzt wurde (z.B. Daten löschen, deinstallieren und neu installieren), 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 GenAI-APIs von ML Kit möglicherweise nicht wie erwartet. Hier finden Sie häufige Fehlermeldungen, die während der Einrichtung angezeigt werden, und Informationen dazu, wie Sie sie beheben können:

Beispiel für Fehlermeldung Vorgehensweise
AICore ist mit dem Fehlertyp 4-CONNECTION_ERROR und dem Fehlercode 601-BINDING_FAILURE fehlgeschlagen: Der AICore-Dienst konnte nicht gebunden werden. Das kann passieren, wenn Sie die App mit ML Kit GenAI-APIs unmittelbar nach der Einrichtung des Geräts installieren oder wenn AICore nach der Installation Ihrer App deinstalliert wird. Wenn Sie die AICore App aktualisieren und Ihre App dann neu installieren, sollte das Problem behoben sein.
AICore ist mit dem Fehlertyp 3-PREPARATION_ERROR und dem Fehlercode 606-FEATURE_NOT_FOUND fehlgeschlagen: Das Feature … ist nicht verfügbar. Das kann passieren, wenn AICore die neuesten Konfigurationen noch nicht vollständig heruntergeladen 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 das Update beschleunigen.

Hinweis: Wenn der Bootloader des Geräts entsperrt ist, wird dieser Fehler ebenfalls angezeigt. Diese API unterstützt keine Geräte mit entsperrten Bootloadern.
AICore ist mit dem Fehlertyp 1-DOWNLOAD_ERROR und dem Fehlercode 0-UNKNOWN fehlgeschlagen: Die Funktion ... ist mit dem Fehlerstatus 0 und dem Fehler esz: UNAVAILABLE fehlgeschlagen: Der Host ... konnte nicht aufgelöst werden. Lassen Sie die Netzwerkverbindung bestehen, warten Sie einige Minuten und versuchen Sie es dann noch einmal.