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 enum). 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. Potrai quindi estrarre direttamente i dati dall'output del modello con una post-elaborazione ridotta.

Ecco alcuni casi d'uso di esempio:

  • Assicurati che la risposta di un modello produca JSON valido e sia conforme allo schema 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. Potrai quindi 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 fare in modo che il modello annoti 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 strutturato (come JSON ed enum) nelle esperienze ibride per le app per Android.

Vai all'output JSON Vai all'output enum

Configurazione per l'output strutturato

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

Per generare 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 in una data class Kotlin con il processore KSP; gli schemi manuali e le annotazioni enum class dirette non sono supportati.
    • Quando l'inferenza viene eseguita on-device, l'SDK traduce automaticamente lo schema in vincoli per il modello on-device (utilizzando l'API Prompt di ML Kit).
    • Se una richiesta ibrida esegue il fallback all'inferenza cloud, l'SDK imposta automaticamente il responseMimeType su application/json e passa lo schema a il modello Gemini ospitato nel cloud.

  • Per l'inferenza solo 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 passa lo schema al modello Gemini ospitato nel cloud.

Prima di iniziare

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

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

  1. Completa la guida introduttiva alla creazione di esperienze ibride, che illustra la configurazione del progetto Firebase, il download del modello on-device e la configurazione 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 di serializzazione Kotlin 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: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")
}


Vai all'output JSON Vai all'output enum

Output JSON

Gli esempi seguenti adattano l' esempio di output JSON generale per supportare l'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 facoltativi.

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

  • Annotazioni KSP (@Generable e @Guide)

    • Supportate per tutte le modalità di inferenza e obbligatorie per l'inferenza on-device e ibrida (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).
    • Definisci le data class Kotlin per generare automaticamente gli schemi in fase di compilazione e deserializzare le risposte direttamente in oggetti con tipo di dati sicuro utilizzando getObject().

  • Metodi helper JsonSchema manuali

    • Supportati solo per l'inferenza basata sul cloud (in particolare, 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 data class Kotlin annotata con @Serializable e @Generable. Utilizza le annotazioni @Guide nelle 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 on-device e ibride (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 fornitore Gemini API scelto in modo da visualizzare contenuti specifici del fornitore 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 sul cloud (in particolare, ONLY_IN_CLOUD), puoi creare manualmente un JsonSchema utilizzando i metodi helper forniti dall'Firebase AI Logic SDK.

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 fornitore Gemini API scelto in modo da visualizzare contenuti specifici del fornitore 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 enum generale per supportare l'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 KSP (@Generable)

    • Supportate per tutte le modalità di inferenza e obbligatorie per l'inferenza on-device e ibrida (in particolare, ONLY_ON_DEVICE, PREFER_ON_DEVICE e PREFER_IN_CLOUD).
    • Definisci un enum racchiuso in una data class Kotlin per generare automaticamente lo schema e deserializzare le risposte direttamente in oggetti con tipo di dati sicuro utilizzando getObject().

  • Metodi helper JsonSchema manuali

    • Supportati solo per l'inferenza basata sul cloud (in particolare, ONLY_IN_CLOUD).
    • Crea manualmente un enum 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 una enum class che rappresenta i valori consentiti e racchiudila come proprietà all'interno di una data class Kotlin annotata con @Serializable e @Generable.

Questo approccio è supportato per tutte le modalità di inferenza ed è obbligatorio per le esperienze on-device e ibride (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 fornitore Gemini API scelto in modo da visualizzare contenuti specifici del fornitore 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 sul cloud (in particolare, ONLY_IN_CLOUD), puoi creare manualmente un enum JsonSchema utilizzando i metodi helper forniti dall'Firebase AI Logic SDK.

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 fornitore Gemini API scelto in modo da visualizzare contenuti specifici del fornitore 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)


Dai un feedback sulla tua esperienza con Firebase AI Logic