Strukturierte Ausgabe für hybride Funktionen in Android-Apps generieren


Gemini-Modelle geben Antworten standardmäßig als unstrukturierten Text zurück. Einige Anwendungsfälle erfordern jedoch strukturierten Text (z. B. JSON oder Enums). Beispielsweise können Sie die Antwort für andere nachgelagerte Aufgaben verwenden, die ein festgelegtes Datenschema erfordern.

Damit die generierte Ausgabe des Modells immer einem bestimmten Schema entspricht, können Sie ein Schema definieren, das als Vorlage für Modellantworten dient. Anschließend können Sie Daten direkt aus der Ausgabe des Modells extrahieren, ohne dass eine umfangreiche Nachbearbeitung erforderlich ist.

Hier ein paar Anwendungsbeispiele:

  • Sorgen Sie dafür, dass die Antwort eines Modells gültiges JSON erzeugt und dem von Ihnen bereitgestellten Schema entspricht.
    Das Modell kann beispielsweise strukturierte Einträge für Rezepte generieren, die immer den Rezeptnamen, die Zutatenliste und die Schritte enthalten. Diese Informationen lassen sich dann leichter parsen und in der Benutzeroberfläche Ihrer App anzeigen.

  • Einschränken, wie ein Modell bei Klassifizierungsaufgaben reagieren kann.
    Sie können das Modell beispielsweise Text mit einem bestimmten Satz von Labels annotieren lassen (z. B. einem bestimmten Satz von Enums wie positive und negative), anstatt Labels zu verwenden, die das Modell erzeugt (die einen gewissen Grad an Variabilität wie good, positive, negative oder bad aufweisen könnten).

Auf dieser Seite wird beschrieben, wie Sie strukturierte Ausgaben (z. B. JSON und Enums) in Ihren Hybrid-Anwendungen für Android-Apps generieren.

Zur JSON-Ausgabe springen Zur Enum-Ausgabe springen

Konfiguration für strukturierte Ausgabe

Das Generieren strukturierter Ausgaben (wie JSON und Enums) wird sowohl für die On-Device- als auch für die cloudbasierte Inferenz unterstützt.

Wenn Sie eine strukturierte Ausgabe generieren möchten, übergeben Sie Ihr Schema direkt an generateObject(). Die Schemaanforderungen hängen vom konfigurierten Inferenzmodus ab:

  • Für On-Device- und Hybrid-Inferenz (ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD):

    • Erfordert die Verwendung der Annotation @Generable für eine Kotlin-data class mit dem KSP-Prozessor. Manuelle Schemas und direkte enum class-Annotationen werden nicht unterstützt.
    • Wenn die Inferenz auf dem Gerät ausgeführt wird, übersetzt das SDK das Schema automatisch in Einschränkungen für das On-Device-Modell (mithilfe der ML Kit Prompt API).
    • Wenn eine Hybridanfrage auf die Cloud-Inferenz zurückgreift, setzt das SDK automatisch den responseMimeType auf application/json und übergibt das Schema an das in der Cloud gehostete Gemini-Modell.

  • Für reine Cloud-Inferenz (ONLY_IN_CLOUD):

    • Unterstützt sowohl @Generable-Annotationen (empfohlen) als auch manuelle Schemas (erstellt mit JsonSchema-Hilfsmethoden).
    • Das SDK setzt responseMimeType automatisch auf application/json und übergibt das Schema an das in der Cloud gehostete Gemini-Modell.

Hinweis

Klicken Sie auf Ihren Gemini API-Anbieter, um anbieterspezifische Inhalte und Code auf dieser Seite aufzurufen.

Bevor Sie strukturierte Ausgaben generieren, müssen Sie die folgende Einrichtung abgeschlossen haben:

  1. Arbeiten Sie den Startleitfaden zum Erstellen von Hybrid-Anwendungen durch. Darin wird beschrieben, wie Sie Ihr Firebase-Projekt einrichten, das On-Device-Modell herunterladen und App Check konfigurieren.

  2. Konfigurieren Sie das Kotlin Symbol Processing (KSP)-Plug-in und fügen Sie Ihrer App die Abhängigkeit Firebase AI KSP hinzu.

    Fügen Sie in der Gradle-Datei des Moduls (auf App-Ebene) (z. B. <project>/<app-module>/build.gradle.kts) das KSP-Plug-in, das Kotlin Serialization-Plug-in und die erforderlichen Abhängigkeiten hinzu:

    plugins {
   // ... other plugins
   id("com.google.gms.google-services")
   id("com.google.devtools.ksp") version "LATEST_VERSION"
   id("org.jetbrains.kotlin.plugin.serialization") version "LATEST_VERSION"
}

dependencies {
   // ... other androidx dependencies

   // Add the dependencies for the Firebase AI Logic and App Check libraries.
   implementation("com.google.firebase:firebase-ai:18.1.0")
   implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
   implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

   // Add the Firebase AI KSP processor for schema generation.
   ksp("com.google.firebase:firebase-ai-ksp-processor:17.0.0")

   // (Optional) Add kotlinx.serialization JSON library for object decoding.
   implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:LATEST_VERSION")
}


Zur JSON-Ausgabe springen Zur Enum-Ausgabe springen

JSON-Ausgabe

In den folgenden Beispielen wird das allgemeine JSON-Ausgabebeispiel für die hybride Inferenz (z. B. PREFER_ON_DEVICE) angepasst.

In diesen Beispielen generiert das Modell eine Liste von Charakterprofilen für eine Fantasy-Geschichte mit strukturierten Attributen wie Name, Alter, Spezies und optionalem Zubehör.

Sie können Ihre Antwortschemas mit einem der folgenden Ansätze definieren:

  • KSP-Annotationen (@Generable und @Guide)

    • Wird für alle Inferenzmodi unterstützt und ist für die On-Device- und Hybrid-Inferenz (insbesondere ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD) erforderlich.
    • Definieren Sie Kotlin-Datenklassen, um Schemas automatisch zur Kompilierzeit zu generieren und Antworten mit getObject() direkt in stark typisierte Objekte zu deserialisieren.

  • Manuelle JsonSchema-Hilfsmethoden

    • Wird nur für cloudbasierte Inferenz (insbesondere ONLY_IN_CLOUD) unterstützt.
    • Erstellen Sie im Code manuell ein JsonSchema, ohne den KSP-Prozessor zu verwenden, und lesen Sie den JSON-Rohstring aus response.response.text.

Beispiel 1: @Generable- und @Guide-Annotationen mit KSP verwenden

Definieren Sie eine Kotlin-data class, die mit @Serializable und @Generable annotiert ist. Verwenden Sie @Guide-Annotationen für Attribute, um dem Modell Beschreibungen, Wertgrenzen oder Einschränkungen für Elemente bereitzustellen.

Dieser Ansatz wird für alle Inferenzmodi unterstützt und ist für On-Device- und Hybrid-Anwendungen (insbesondere ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD) erforderlich.

Bevor Sie dieses Beispiel ausprobieren, führen Sie die Schritte im Abschnitt Vorbereitung dieses Leitfadens aus, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den ausgewählten Gemini API-Anbieter, damit Sie auf dieser Seite anbieterspezifische Inhalte sehen.

In Kotlin sind die Methoden in diesem SDK Suspend-Funktionen und müssen aus einem Koroutinenbereich aufgerufen werden. 
import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.annotations.Generable
import com.google.firebase.ai.annotations.Guide
import com.google.firebase.ai.ai
import kotlinx.serialization.Serializable

// Define data classes representing the schema, annotated with @Serializable and @Generable.
// You can provide descriptions on @Generable and @Guide to guide the model's output.
@Serializable
@Generable(description = "A character profile for a fantasy story")
data class Character(
    val name: String,
    val age: Int,
    val species: String,
    // Use @Guide to add property descriptions, value bounds (minimum/maximum), or formats.
    // Properties with default values or nullable types are treated as optional in the schema.
    @Guide(description = "An accessory the character wears or carries")
    val accessory: String? = null
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

@Serializable
@Generable(description = "A list of character profiles")
data class CharacterList(
    // Use minItems or maxItems to specify collection size bounds for the model.
    @Guide(description = "List of characters", minItems = 1)
    val characters: List<Character>
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

// Initialize the Gemini Developer API backend service.
// Create a GenerativeModel instance configured for hybrid inference (like PREFER_ON_DEVICE).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.INFERENCE_MODE)
    )

// Obtain the schema generated by KSP via the firebaseAISchema() extension.
val schema = CharacterList.firebaseAISchema()
val prompt = "Create profiles for some characters for a fantasy story."

// Generate the structured object (the SDK applies the schema to on-device or cloud models).
val response = model.generateObject(schema, prompt)

// Access the strongly-typed deserialized object directly via getObject().
val characterList: CharacterList? = response.getObject()
characterList?.characters?.forEach { character ->
    println("Name: ${character.name}, Species: ${character.species}, Age: ${character.age}")
    println("Accessory: ${character.accessory ?: "None"}")
}

Beispiel 2: Manuelle JsonSchema-Hilfsmethoden verwenden

Wenn Ihre App nur cloudbasierte Inferenz (insbesondere ONLY_IN_CLOUD) verwendet, können Sie mit Hilfsmethoden aus dem Firebase AI Logic SDK manuell ein JsonSchema erstellen.

Bevor Sie dieses Beispiel ausprobieren, führen Sie die Schritte im Abschnitt Vorbereitung dieses Leitfadens aus, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den ausgewählten Gemini API-Anbieter, damit Sie auf dieser Seite anbieterspezifische Inhalte sehen.

In Kotlin sind die Methoden in diesem SDK Suspend-Funktionen und müssen aus einem Koroutinenbereich aufgerufen werden. 
import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.JsonSchema

// Define the schema manually using JsonSchema helper methods.
// Properties are required by default unless specified in optionalProperties.
val jsonSchema = JsonSchema.obj(
    properties = mapOf(
        "characters" to JsonSchema.array(
            items = JsonSchema.obj(
                properties = mapOf(
                    "name" to JsonSchema.string(),
                    "accessory" to JsonSchema.string(),
                    "age" to JsonSchema.integer(),
                    "species" to JsonSchema.string()
                ),
                optionalProperties = listOf("accessory")
            )
        )
    )
)

// Initialize the Gemini Developer API backend service.
// Manual schemas are only supported for cloud-based inference (specifically, ONLY_IN_CLOUD).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.ONLY_IN_CLOUD)
    )

// Call generateObject() with the manual schema and prompt.
val response = model.generateObject(
    jsonSchema,
    "Create profiles for some characters for a fantasy story."
)

// Access the generated JSON string conforming to the schema from response.response.text.
println(response.response.text)

Enum-Ausgabe

In den folgenden Beispielen wird das allgemeine Beispiel für die Enum-Ausgabe für die hybride Inferenz (z. B. PREFER_ON_DEVICE) angepasst.

In diesem Szenario klassifiziert das Modell eine Filmbeschreibung, indem es ein einzelnes Genre aus einer vordefinierten Liste zulässiger Optionen (drama, comedy oder documentary) auswählt.

Sie können Ihre Antwortschemas mit einem der folgenden Ansätze definieren:

  • KSP-Annotationen (@Generable)

    • Wird für alle Inferenzmodi unterstützt und ist für die On-Device- und Hybrid-Inferenz (insbesondere ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD) erforderlich.
    • Definieren Sie ein Enum, das in einer Kotlin-data class-Klasse verpackt ist, um das Schema automatisch zu generieren und Antworten mit getObject() direkt in stark typisierte Objekte zu deserialisieren.

  • Manuelle JsonSchema-Hilfsmethoden

    • Wird nur für cloudbasierte Inferenz (insbesondere ONLY_IN_CLOUD) unterstützt.
    • Erstellen Sie manuell ein Enum JsonSchema mit JsonSchema.enumeration(), ohne den KSP-Prozessor zu verwenden, und lesen Sie den ausgewählten String aus response.response.text.

Beispiel 1: @Generable-Annotationen mit KSP verwenden

Definieren Sie ein enum class, das die zulässigen Werte darstellt, und verpacken Sie es als Property in einer Kotlin-data class, die mit @Serializable und @Generable annotiert ist.

Dieser Ansatz wird für alle Inferenzmodi unterstützt und ist für On-Device- und Hybrid-Anwendungen (insbesondere ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD) erforderlich.

Bevor Sie dieses Beispiel ausprobieren, führen Sie die Schritte im Abschnitt Vorbereitung dieses Leitfadens aus, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den ausgewählten Gemini API-Anbieter, damit Sie auf dieser Seite anbieterspezifische Inhalte sehen.

In Kotlin sind die Methoden in diesem SDK Suspend-Funktionen und müssen aus einem Koroutinenbereich aufgerufen werden. 
import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.annotations.Generable
import com.google.firebase.ai.annotations.Guide
import com.google.firebase.ai.ai
import kotlinx.serialization.Serializable

// Define an enum class representing the allowed options.
@Serializable
enum class FilmGenre {
    DRAMA,
    COMEDY,
    DOCUMENTARY
}

// Wrap the enum in a data class annotated with @Serializable and @Generable.
// On-device inference requires an @Generable data class.
// Direct enum annotations are not supported on-device.
@Serializable
@Generable(description = "The classification result for the film")
data class FilmClassification(
    @Guide(description = "The genre of the film")
    val genre: FilmGenre
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

// Initialize the Gemini Developer API backend service.
// Create a GenerativeModel instance configured for hybrid inference (like PREFER_ON_DEVICE).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.INFERENCE_MODE)
    )

// Obtain the schema generated by KSP via the firebaseAISchema() extension.
val schema = FilmClassification.firebaseAISchema()
val prompt = """
    The film aims to educate and inform viewers about real-life subjects, events, or people.
    It offers a factual record of a particular topic by combining interviews, historical footage,
    and narration. The primary purpose of a film is to present information and provide insights
    into various aspects of reality.
    """

// Generate the structured object (the SDK applies the schema to on-device or cloud models).
val response = model.generateObject(schema, prompt)

// Access the strongly-typed deserialized object and enum value directly via getObject().
val classification: FilmClassification? = response.getObject()
val genre: FilmGenre? = classification?.genre
println("Selected genre: $genre")

Beispiel 2: Manuelle JsonSchema-Hilfsmethoden verwenden

Wenn Ihre App nur cloudbasierte Inferenz (insbesondere ONLY_IN_CLOUD) verwendet, können Sie mit Hilfsmethoden aus dem Firebase AI Logic SDK manuell ein Enum JsonSchema erstellen.

Bevor Sie dieses Beispiel ausprobieren, führen Sie die Schritte im Abschnitt Vorbereitung dieses Leitfadens aus, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den ausgewählten Gemini API-Anbieter, damit Sie auf dieser Seite anbieterspezifische Inhalte sehen.

In Kotlin sind die Methoden in diesem SDK Suspend-Funktionen und müssen aus einem Koroutinenbereich aufgerufen werden. 
import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.JsonSchema

// Define an enum schema with allowed string values and a description.
val enumSchema = JsonSchema.enumeration(
    values = listOf("drama", "comedy", "documentary"),
    description = "The genre of the film"
)

// Initialize the Gemini Developer API backend service.
// Manual schemas are only supported for cloud-based inference (specifically, ONLY_IN_CLOUD).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.ONLY_IN_CLOUD)
    )

val prompt = """
    The film aims to educate and inform viewers about real-life subjects, events, or people.
    It offers a factual record of a particular topic by combining interviews, historical footage,
    and narration. The primary purpose of a film is to present information and provide insights
    into various aspects of reality.
    """

// Call generateObject() with the enum schema and prompt.
val response = model.generateObject(enumSchema, prompt)

// Access the selected enum value string from response.response.text.
println(response.response.text)


Feedback zu Ihren Erfahrungen mit Firebase AI Logic geben