Generare output strutturato per esperienze ibride nelle app per Android


Per impostazione predefinita, i modelli Gemini restituiscono le risposte come testo non strutturato. Tuttavia, alcuni casi d'uso richiedono testo strutturato (come JSON o enumerazioni). Ad esempio, potresti utilizzare la risposta per altre attività downstream che richiedono uno schema di dati stabilito.

Per assicurarti che l'output generato dal modello rispetti sempre uno schema specifico, puoi definire uno schema, che funziona come un progetto per le risposte del modello. Puoi quindi estrarre direttamente i dati dall'output del modello con una post-elaborazione minore.

Ecco alcuni casi d'uso di esempio:

  • Assicurati che la risposta di un modello produca un JSON valido e sia conforme allo schema che hai fornito.
    Ad esempio, il modello può generare voci strutturate per le ricette che includono sempre il nome della ricetta, l'elenco degli ingredienti e i passaggi. In questo modo, potrai analizzare e visualizzare più facilmente queste informazioni nell'interfaccia utente della tua app.

  • Limita il modo in cui un modello può rispondere durante le attività di classificazione.
    Ad esempio, puoi chiedere al modello di annotare il testo con un insieme specifico di etichette (ad esempio, un insieme specifico di enum come positive e negative), anziché con etichette prodotte dal modello (che potrebbero avere un certo grado di variabilità come good, positive, negative o bad).

Questa pagina descrive come generare output strutturati (come JSON ed enum) nelle tue esperienze ibride per le app per Android.

Vai all'output JSON Vai all'output enum

Configurazione per l'output strutturato

La generazione di output strutturati (come JSON ed enum) è supportata sia per l'inferenza on-device sia per quella ospitata sul cloud.

Per generare un output strutturato, passa lo schema direttamente a generateObject(). I requisiti dello schema dipendono dalla modalità di inferenza configurata:

  • Per l'inferenza on-device e ibrida (ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD):

    • Richiede l'utilizzo dell'annotazione @Generable su un data class Kotlin con il processore KSP; gli schemi manuali e le annotazioni enum class dirette non sono supportati.
    • Quando l'inferenza viene eseguita sul dispositivo, l'SDK traduce automaticamente lo schema in vincoli per il modello on-device (utilizzando l'API ML Kit Prompt).
    • Se una richiesta ibrida esegue il failover all'inferenza sul cloud, l'SDK imposta automaticamente responseMimeType su application/json e passa lo schema al modello Gemini ospitato sul cloud.

  • Per l'inferenza solo sul cloud (ONLY_IN_CLOUD):

    • Supporta sia le annotazioni @Generable (consigliate) sia gli schemi manuali (creati utilizzando i metodi helper JsonSchema).
    • L'SDK imposta automaticamente responseMimeType su application/json e trasferisce lo schema al modello Gemini ospitato sul cloud.

Prima di iniziare

Fai clic sul tuo fornitore Gemini API per visualizzare i contenuti e il codice specifici del fornitore in questa pagina.

Prima di generare l'output strutturato, assicurati di aver completato la configurazione seguente:

  1. Completa la guida introduttiva per la creazione di esperienze ibride, che illustra la configurazione del progetto Firebase, il download del modello sul dispositivo e la configurazione di App Check.

  2. Configura il plug-in Kotlin Symbol Processing (KSP) e aggiungi la dipendenza Firebase AI KSP alla tua app.

    Nel file Gradle del modulo (a livello di app) (ad esempio <project>/<app-module>/build.gradle.kts), aggiungi il plug-in KSP, il plug-in Kotlin Serialization e le dipendenze richieste:

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


Vai all'output JSON Vai all'output enum

Output JSON

Gli esempi seguenti adattano l'esempio di output JSON generale per adattarsi all'inferenza ibrida (ad esempio, PREFER_ON_DEVICE).

Nello scenario di questi esempi, il modello genera un elenco di profili di personaggi per una storia fantasy, con attributi strutturati come nome, età, specie e accessori opzionali.

Puoi definire gli schemi di risposta utilizzando uno dei seguenti approcci:

  • Annotazioni KSP (@Generable e @Guide)

    • Supportato per tutte le modalità di inferenza e obbligatorio per l'inferenza on-device e ibrida (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).
    • Definisci le classi di dati Kotlin per generare automaticamente gli schemi in fase di compilazione e deserializzare le risposte direttamente in oggetti fortemente tipizzati utilizzando getObject().

  • Metodi helper JsonSchema manuali

    • Supportato solo per l'inferenza basata sul cloud (nello specifico, ONLY_IN_CLOUD).
    • Costruisci manualmente un JsonSchema nel codice senza utilizzare il processore KSP e leggi la stringa JSON non elaborata da response.response.text.

Esempio 1: utilizzo delle annotazioni @Generable e @Guide con KSP

Definisci una proprietà Kotlin data class annotata con @Serializable e @Generable. Utilizza le annotazioni @Guide sulle proprietà per fornire al modello descrizioni, limiti di valore o vincoli degli elementi.

Questo approccio è supportato per tutte le modalità di inferenza ed è obbligatorio per le esperienze ibride e sul dispositivo (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, fai clic anche su un pulsante per il provider Gemini API che hai scelto, in modo da visualizzare i contenuti specifici del provider in questa pagina.

Per Kotlin, i metodi in questo SDK sono funzioni di sospensione e devono essere chiamati da un ambito di coroutine. 
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"}")
}

Esempio 2: utilizzo dei metodi helper JsonSchema manuali

Se la tua app utilizza solo l'inferenza basata su cloud (in particolare, ONLY_IN_CLOUD), puoi creare manualmente un JsonSchema utilizzando i metodi helper forniti dall'SDK Firebase AI Logic.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, fai clic anche su un pulsante per il provider Gemini API che hai scelto, in modo da visualizzare contenuti specifici del provider in questa pagina.

Per Kotlin, i metodi in questo SDK sono funzioni di sospensione e devono essere chiamati da un ambito di coroutine. 
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)

Output enum

Gli esempi seguenti adattano l'esempio di output di enumerazione generale per adattarsi all'inferenza ibrida (ad esempio, PREFER_ON_DEVICE).

Nello scenario di questi esempi, il modello classifica la descrizione di un film selezionando un singolo genere da un elenco predefinito di opzioni consentite (drama, comedy o documentary).

Puoi definire gli schemi di risposta utilizzando uno dei seguenti approcci:

  • Annotazioni dei principali punti di forza (@Generable)

    • Supportato per tutte le modalità di inferenza e obbligatorio per l'inferenza on-device e ibrida (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).
    • Definisci un'enumerazione racchiusa in un data class Kotlin per generare automaticamente lo schema e deserializzare le risposte direttamente in oggetti fortemente tipizzati utilizzando getObject().

  • Metodi helper JsonSchema manuali

    • Supportato solo per l'inferenza basata sul cloud (nello specifico, ONLY_IN_CLOUD).
    • Crea manualmente un'enumerazione JsonSchema utilizzando JsonSchema.enumeration() senza utilizzare il processore KSP e leggi la stringa selezionata da response.response.text.

Esempio 1: utilizzo delle annotazioni @Generable con KSP

Definisci un enum class che rappresenti i valori consentiti e inseriscilo come proprietà all'interno di un data class Kotlin annotato con @Serializable e @Generable.

Questo approccio è supportato per tutte le modalità di inferenza ed è obbligatorio per le esperienze ibride e sul dispositivo (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, fai clic anche su un pulsante per il provider Gemini API che hai scelto, in modo da visualizzare contenuti specifici del provider in questa pagina.

Per Kotlin, i metodi in questo SDK sono funzioni di sospensione e devono essere chiamati da un ambito di coroutine. 
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")

Esempio 2: utilizzo dei metodi helper JsonSchema manuali

Se la tua app utilizza solo l'inferenza basata su cloud (in particolare, ONLY_IN_CLOUD), puoi creare manualmente un'enumerazione JsonSchema utilizzando i metodi helper forniti dall'SDK Firebase AI Logic.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, fai clic anche su un pulsante per il provider Gemini API che hai scelto, in modo da visualizzare contenuti specifici del provider in questa pagina.

Per Kotlin, i metodi in questo SDK sono funzioni di sospensione e devono essere chiamati da un ambito di coroutine. 
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)


Fornisci un feedback sulla tua esperienza con Firebase AI Logic