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


Gemini-Modelle geben Antworten standardmäßig als unstrukturierten Text zurück. Für einige Anwendungsfälle ist jedoch strukturierter Text (z. B. JSON oder Enums) erforderlich. Möglicherweise verwenden Sie die Antwort für andere nachgelagerte Aufgaben, für die ein etabliertes Datenschema erforderlich ist.

Damit die vom Modell generierte Ausgabe immer einem bestimmten Schema entspricht, können Sie ein Schema definieren, das als Vorlage für Modellantworten dient. Sie können dann 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 Ihrem bereitgestellten Schema entspricht.
    Das Modell kann beispielsweise strukturierte Einträge für Rezepte generieren, die immer den Rezeptnamen, die Zutatenliste und die Zubereitungsschritte enthalten. Anschließend können Sie diese Informationen 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 einer bestimmten Gruppe von Labels annotieren lassen (z. B. eine bestimmte Gruppe von Enums wie positive und negative) anstelle von Labels, die das Modell generiert (die eine gewisse Variabilität aufweisen können, z. B. good, positive, negative oder bad).

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

 Zur JSON-Ausgabe springen  Zur Enum-Ausgabe springen

Konfiguration für strukturierte Ausgabe

Die Generierung strukturierter Ausgaben (wie JSON und Enums) wird sowohl für die Inferenz auf dem Gerät als auch in der Cloud 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 die Inferenz auf dem Gerät und die hybride 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 (mit der ML Kit Prompt API).
    • Wenn eine Hybridanfrage auf die Cloud-Inferenz zurückgreift, legt das SDK responseMimeType automatisch auf application/json fest und übergibt das Schema an das cloudbasierte Gemini-Modell.

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

    • Unterstützt sowohl @Generable-Annotationen (empfohlen) als auch manuelle Schemas (die mit JsonSchema-Hilfsmethoden erstellt wurden).
    • Das SDK legt responseMimeType automatisch auf application/json fest 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 folgenden Schritte ausführen:

  1. Folgen Sie der Anleitung für den Einstieg in die Entwicklung hybrider Lösungen. Dort 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 die Firebase AI KSP-Abhängigkeit zu Ihrer App 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-Serialisierungs-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:17.17.0")
   implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta05")
   implementation("com.google.firebase:firebase-appcheck-debug:19.4.1")

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

   // (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 Beispiel für die JSON-Ausgabe an die hybride Inferenz angepasst (z. B. PREFER_ON_DEVICE).

In diesem Szenario 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 Antwortschemata 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 mithilfe von getObject() direkt in stark typisierte Objekte zu deserialisieren.

  • Manuelle JsonSchema-Helper-Methoden

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

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-Anmerkungen für Properties, um dem Modell Beschreibungen, Wertgrenzen oder Artikelbeschränkungen 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, müssen Sie den Abschnitt Vorbereitung in diesem Leitfaden durcharbeiten, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den von Ihnen ausgewählten Gemini API-Anbieter, damit auf dieser Seite anbieterspezifische Inhalte angezeigt werden.

Für Kotlin sind die Methoden in diesem SDK suspend-Funktionen und müssen aus einem Coroutine-Bereich 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 den Hilfsmethoden des Firebase AI Logic SDK manuell ein JsonSchema erstellen.

Bevor Sie dieses Beispiel ausprobieren, müssen Sie den Abschnitt Vorbereitung in diesem Leitfaden durcharbeiten, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den von Ihnen ausgewählten Gemini API-Anbieter, damit auf dieser Seite anbieterspezifische Inhalte angezeigt werden.

Für Kotlin sind die Methoden in diesem SDK suspend-Funktionen und müssen aus einem Coroutine-Bereich 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 an die hybride Inferenz angepasst (z. B. PREFER_ON_DEVICE).

In den Beispielen 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 Antwortschemata mit einem der folgenden Ansätze definieren:

  • KSP-Anmerkungen (@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 ein Kotlin-data class eingeschlossen ist, um das Schema automatisch zu generieren und Antworten mithilfe von getObject() direkt in stark typisierte Objekte zu deserialisieren.

  • Manuelle JsonSchema-Helper-Methoden

    • Wird nur für die 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 umschließen 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, müssen Sie den Abschnitt Vorbereitung in diesem Leitfaden durcharbeiten, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den von Ihnen ausgewählten Gemini API-Anbieter, damit auf dieser Seite anbieterspezifische Inhalte angezeigt werden.

Für Kotlin sind die Methoden in diesem SDK suspend-Funktionen und müssen aus einem Coroutine-Bereich 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 manuell ein Enum JsonSchema mit den Hilfsmethoden des Firebase AI Logic-SDK erstellen.

Bevor Sie dieses Beispiel ausprobieren, müssen Sie den Abschnitt Vorbereitung in dieser Anleitung durcharbeiten, um Ihr Projekt und Ihre App einzurichten.
In diesem Abschnitt klicken Sie auch auf eine Schaltfläche für den von Ihnen ausgewählten Gemini API-Anbieter, damit auf dieser Seite anbieterspezifische Inhalte angezeigt werden.

Für Kotlin sind die Methoden in diesem SDK suspend-Funktionen und müssen aus einem Coroutine-Bereich 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 Firebase AI Logic geben