Gerar saída estruturada para experiências híbridas em apps da Web

Gemini modelos retornam respostas como texto não estruturado por padrão. No entanto, alguns casos de uso exigem texto estruturado, como JSON. Por exemplo, você pode estar usando a resposta para outras tarefas downstream que exigem um esquema de dados estabelecido.

Para garantir que a saída gerada do modelo sempre siga um esquema específico, defina um esquema, que funciona como um modelo de respostas. Em seguida, você pode extrair dados diretamente da saída do modelo com menos pós-processamento.

Veja alguns exemplos:

  • Garanta que a resposta de um modelo produza um JSON válido e esteja em conformidade com o esquema fornecido.
    Por exemplo, o modelo pode gerar entradas estruturadas para receitas que sempre incluem o nome da receita, a lista de ingredientes e as etapas. Em seguida, você pode analisar e mostrar essas informações com mais facilidade na interface do app.

  • Restrinja a forma como um modelo pode responder durante tarefas de classificação.
    Por exemplo, você pode fazer com que o modelo anote o texto com um conjunto específico de rótulos (por exemplo, um conjunto específico de enums como positive e negative), em vez de rótulos produzidos pelo modelo (que podem ter um grau de variabilidade como good, positive, negative ou bad).

Esta página descreve como gerar saída estruturada (como JSON e enums) nas experiências híbridas para apps da Web.

Antes de começar

Conclua o guia para iniciantes sobre como criar experiências híbridas.

Definir a configuração para saída estruturada

A geração de saída estruturada (como JSON e enums) é compatível com a inferência usando modelos hospedados na nuvem e no dispositivo.

Para inferência híbrida, use both inCloudParams and onDeviceParams para configurar o modelo para responder com saída estruturada. Para os outros modos, use apenas a configuração aplicável.

  • Para inCloudParams: especifique o responseMimeType adequado (por exemplo, application/json), bem como o responseSchema que você quer que o modelo use.

  • Para onDeviceParams: especifique a responseConstraint que você quer que o modelo use.

Saída JSON

Os exemplos a seguir adaptam o exemplo geral de saída JSON para acomodar a inferência híbrida (neste exemplo, PREFER_ON_DEVICE):

Exemplo 1: usar métodos auxiliares Schema do Firebase

Este exemplo usa métodos auxiliares fornecidos pelo SDK Firebase AI Logic para tornar a definição de esquema mais compacta.

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// This schema can also be defined as a plain JSON object.
// See next snippet for an example of a plain JSON schema.
const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

// ...

Exemplo 2: usar um esquema JSON simples

Este exemplo define o esquema usando apenas JSON e retorna os mesmos resultados.

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// The JSON schema defined as a plain JSON object.
const jsonSchema = {
    "type": "object",
    "properties": {
        "characters": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "nullable": false
                    },
                    "accessory": {
                        "type": "string",
                        "nullable": false
                    },
                    "age": {
                        "type": "number",
                        "nullable": false
                    },
                    "species": {
                        "type": "string",
                        "nullable": false
                    }
                },
                "nullable": false,
                "required": [
                    "name",
                    "age",
                    "species"
                ]
            },
            "nullable": false
        }
    },
    "nullable": false,
    "required": [
        "characters"
    ]
};

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

Saída de enumeração

O exemplo a seguir adapta o exemplo geral de saída de enumeração para acomodar a inferência híbrida (neste exemplo, PREFER_ON_DEVICE):

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// enumSchema can also be defined as a plain JSON schema instead of
// using the `Schema` helper methods, just as in the JSON output example.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

// ...