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 erforderlich (z. B. JSON oder Enums). Möglicherweise verwenden Sie die Antwort für andere nachgelagerte Aufgaben, für die ein festgelegtes Datenschema erforderlich ist.

Damit die generierte Ausgabe des Modells immer einem bestimmten Schema entspricht, können Sie ein Schema definieren, das wie eine Vorlage für Modellantworten funktioniert. 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 Ihrem bereitgestellten Schema entspricht.
  Das Modell kann beispielsweise strukturierte Einträge für Rezepte generieren, die immer den Namen des Rezepts, eine Liste der Zutaten und die Schritte enthalten. Anschließend können Sie diese Informationen einfacher in der UI Ihrer App parsen und anzeigen.

• Beschränken Sie die Möglichkeiten, wie ein Modell bei Klassifizierungsaufgaben antworten kann.
  Sie können beispielsweise festlegen, dass das Modell Text mit einer bestimmten Reihe von Labels annotiert (z. B. eine bestimmte Reihe von Enums wie positive und negative) und nicht mit Labels, die das Modell selbst erstellt (die eine gewisse Variabilität aufweisen können, z. B. good, positive, negative oder bad).

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

arrow_downward Zu JSON-Ausgabe springen arrow_downward Zu Enum-Ausgabe springen

Konfiguration für strukturierte Ausgabe

Das Generieren strukturierter Ausgaben (z. B. JSON und Enums) wird sowohl für die Inferenz auf dem Gerät als auch in der Cloud unterstützt.

Wenn Sie strukturierte Ausgaben 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 Modell auf dem Gerät (mit der ML Kit Prompt API).
  • Wenn bei einer hybriden Anfrage auf die Inferenz in der Cloud zurückgegriffen wird, legt das SDK automatisch den responseMimeType auf application/json fest und übergibt das Schema an das in der Cloud gehostete Gemini-Modell.

• Für die reine Inferenz in der Cloud (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

Bevor Sie strukturierte Ausgaben generieren, müssen Sie die folgenden Schritte ausführen:

1. Führen Sie den Startleitfaden für die Entwicklung hybrider Anwendungen aus. 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 Ihrer App die Firebase AI KSP Abhängigkeit hinzu.

   Fügen Sie in der Gradle-Datei Ihres 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:18.0.0")
      implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
      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")
   }

arrow_downward Zu JSON-Ausgabe springen arrow_downward Zu 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).

Im Szenario für diese Beispiele 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 einer der folgenden Methoden definieren:

• KSP-Annotationen (@Generable und @Guide)

  • Werden für alle Inferenzmodi unterstützt und sind für die Inferenz auf dem Gerät und die hybride Inferenz erforderlich (insbesondere für ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD).
  • Definieren Sie Kotlin-Datenklassen, um Schemas zur Kompilierzeit automatisch zu generieren und Antworten mit getObject() direkt in stark typisierte Objekte zu deserialisieren.

• Manuelle JsonSchema Hilfsmethoden

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

Beispiel 1: Verwendung von @Generable- und @Guide-Annotationen mit KSP

Definieren Sie eine Kotlin-data class, die mit @Serializable und @Generable annotiert ist. Verwenden Sie @Guide-Annotationen für Eigenschaften, um dem Modell Beschreibungen, Wertgrenzen oder Elementbeschränkungen zu geben.

Dieser Ansatz wird für alle Inferenzmodi unterstützt und ist für die Inferenz auf dem Gerät und die hybride Inferenz erforderlich (insbesondere für ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD).

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: Verwendung manueller JsonSchema-Hilfsmethoden

Wenn Ihre App nur die cloudbasierte Inferenz verwendet (insbesondere, ONLY_IN_CLOUD), können Sie manuell ein JsonSchema mit Hilfsmethoden erstellen, die vom Firebase AI Logic SDK bereitgestellt 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).

Im Szenario für diese Beispiele klassifiziert das Modell eine Filmbeschreibung, indem es ein Genre aus einer vordefinierten Liste zulässiger Optionen (drama, comedy oder documentary) auswählt.

Sie können Ihre Antwortschemata mit einer der folgenden Methoden definieren:

• KSP-Annotationen (@Generable)

  • Werden für alle Inferenzmodi unterstützt und sind für die Inferenz auf dem Gerät und die hybride Inferenz erforderlich (insbesondere für ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD).
  • Definieren Sie ein Enum, das in eine Kotlin-data class eingebunden ist, um das Schema automatisch zu generieren und Antworten mit getObject() direkt in stark typisierte Objekte zu deserialisieren.

• Manuelle JsonSchema Hilfsmethoden

  • Werden nur für die cloudbasierte Inferenz unterstützt (insbesondere für ONLY_IN_CLOUD).
  • 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: Verwendung von @Generable-Annotationen mit KSP

Definieren Sie eine enum class, die die zulässigen Werte darstellt, und binden Sie sie als Eigenschaft in eine Kotlin-data class ein, die mit @Serializable und @Generable annotiert ist.

Dieser Ansatz wird für alle Inferenzmodi unterstützt und ist für die Inferenz auf dem Gerät und die hybride Inferenz erforderlich (insbesondere für ONLY_ON_DEVICE, PREFER_ON_DEVICE und PREFER_IN_CLOUD).

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: Verwendung manueller JsonSchema-Hilfsmethoden

Wenn Ihre App nur die cloudbasierte Inferenz verwendet (insbesondere, ONLY_IN_CLOUD), können Sie manuell ein Enum JsonSchema mit Hilfsmethoden erstellen, die vom Firebase AI Logic SDK bereitgestellt 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 geben zu Ihren Erfahrungen mit Firebase AI Logic