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

Por padrão, os modelos Gemini retornam respostas como texto não estruturado. No entanto, alguns casos de uso exigem texto estruturado, como JSON ou enums. 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 para as respostas. Assim, é possível extrair dados diretamente da saída do modelo com menos pós-processamento.

Veja alguns exemplos de casos de uso:

  • Garantir que a resposta de um modelo gere 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. Assim, é mais fácil analisar e mostrar essas informações na interface do app.

  • Restringir a forma como um modelo pode responder durante tarefas de classificação.
    Por exemplo, você pode permitir 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 que o modelo produz (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 suas experiências híbridas para apps da Web.

Ir para a saída JSON Ir para a saída de enumeração

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.

  • Modos de inferência híbrida: configure inCloudParams e onDeviceParams para que o modelo responda com saída estruturada, independente de a inferência ser executada na nuvem ou no dispositivo:

    • Para modelos no dispositivo: especifique o responseConstraint em onDeviceParams usando um esquema criado com métodos auxiliares Schema ou um esquema JSON simples.

    • Para modelos hospedados na nuvem: especifique o responseMimeType (application/json para JSON ou text/x.enum para enums) e o responseSchema em inCloudParams.

  • Modos de inferência não híbridos: use apenas a configuração aplicável descrita acima.

Antes de começar

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

Confira se você concluiu o guia para iniciantes sobre como criar experiências híbridas.


Ir para a saída JSON Ir para a saída de enumeração

Saída JSON

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

No cenário desses exemplos, o modelo gera uma lista de perfis de personagens para uma história de fantasia, com atributos estruturados como nome, idade, espécie e acessórios opcionais.

É possível definir seus esquemas de resposta usando uma das seguintes abordagens:

  • Métodos auxiliares do Firebase Schema (recomendado): use métodos auxiliares (como Schema.object() e Schema.enumString()) para escrever esquemas concisos e compactos diretamente no seu código sem boilerplate extra.

  • Esquema JSON simples: use um objeto de esquema JSON padrão se você já tiver definições de esquema compartilhadas entre plataformas ou serviços de back-end ou importar esquemas de arquivos JSON.

Exemplo 1: usar métodos auxiliares Schema do Firebase

Este exemplo usa métodos auxiliares Schema (como Schema.object, Schema.array, Schema.string e Schema.number) fornecidos pelo SDK Firebase AI Logic para definir o esquema de objeto.

Antes de testar esta amostra, conclua a seção Antes de começar deste guia para configurar seu projeto e app.
Nessa seção, clique também em um botão para o provedor Gemini API escolhido para ver conteúdo específico do provedor nesta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode,
  Schema
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define a schema using the `Schema` helper methods.
// Optional properties are specified in optionalProperties.
const jsonSchema = Schema.object({
  properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
          accessory: Schema.string()
        },
        optionalProperties: ["accessory"]
      })
    })
  }
});

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    }
  },
  // For on-device models, pass the schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const prompt = "Create profiles for some characters for a fantasy story.";

// Generate the structured output.
const result = await model.generateContent(prompt);

// Access the generated JSON string conforming to the schema from response.text().
console.log(result.response.text());

// Parse the JSON string into a JavaScript object.
console.log(JSON.parse(result.response.text()));

Exemplo 2: usar um esquema JSON simples

Este exemplo define o esquema usando apenas JSON.

Antes de testar esta amostra, conclua a seção Antes de começar deste guia para configurar seu projeto e app.
Nessa seção, clique também em um botão para o provedor Gemini API escolhido para ver conteúdo específico do provedor nesta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define the schema as a plain JSON object.
// Properties are required by default unless omitted from the required array.
const jsonSchema = {
  type: "object",
  properties: {
    characters: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: {
            type: "string",
            nullable: false
          },
          age: {
            type: "number",
            nullable: false
          },
          species: {
            type: "string",
            nullable: false
          },
          accessory: {
            type: "string",
            nullable: true
          }
        },
        nullable: false,
        required: [
          "name",
          "age",
          "species"
        ]
      },
      nullable: false
    }
  },
  nullable: false,
  required: [
    "characters"
  ]
};

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    }
  },
  // For on-device models, pass the schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const prompt = "Create profiles for some characters for a fantasy story.";

// Generate the structured output.
const result = await model.generateContent(prompt);

// Access the generated JSON string conforming to the schema from response.text().
console.log(result.response.text());

// Parse the JSON string into a JavaScript object.
console.log(JSON.parse(result.response.text()));

Saída de enumeração

Os exemplos a seguir adaptam o exemplo de saída de enumeração geral para acomodar a inferência híbrida (por exemplo, PREFER_ON_DEVICE).

No cenário desses exemplos, o modelo classifica uma descrição de filme selecionando um único gênero de uma lista predefinida de opções permitidas (drama, comedy ou documentary).

É possível definir seus esquemas de resposta usando uma das seguintes abordagens:

  • Métodos auxiliares do Firebase Schema (recomendado): use métodos auxiliares (como Schema.object() e Schema.enumString()) para escrever esquemas concisos e compactos diretamente no seu código sem boilerplate extra.

  • Esquema JSON simples: use um objeto de esquema JSON padrão se você já tiver definições de esquema compartilhadas entre plataformas ou serviços de back-end ou importar esquemas de arquivos JSON.

Exemplo 1: usar métodos auxiliares Schema do Firebase

Este exemplo usa o método auxiliar Schema.enumString fornecido pelo SDK Firebase AI Logic para definir valores de enumeração permitidos.

Antes de testar esta amostra, conclua a seção Antes de começar deste guia para configurar seu projeto e app.
Nessa seção, clique também em um botão para o provedor Gemini API escolhido para ver conteúdo específico do provedor nesta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode,
  Schema
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define an enum schema using the `Schema` helper method with allowed string values.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"]
});

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    }
  },
  // For on-device models, pass the enum schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

const 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 enum output.
const result = await model.generateContent(prompt);

// Access the selected enum value string from response.text().
console.log(result.response.text());

Exemplo 2: usar um esquema JSON simples

Este exemplo define o esquema de enumeração usando apenas JSON.

Antes de testar esta amostra, conclua a seção Antes de começar deste guia para configurar seu projeto e app.
Nessa seção, clique também em um botão para o provedor Gemini API escolhido para ver conteúdo específico do provedor nesta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define the enum schema as a plain JSON object.
const enumSchema = {
  type: "string",
  enum: ["drama", "comedy", "documentary"]
};

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    }
  },
  // For on-device models, pass the enum schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

const 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 enum output.
const result = await model.generateContent(prompt);

// Access the selected enum value string from response.text().
console.log(result.response.text());


Envie feedback sobre sua experiência com Firebase AI Logic