Generowanie danych strukturalnych na potrzeby funkcji hybrydowych w aplikacjach internetowych

Gemini modele domyślnie zwracają odpowiedzi w postaci nieustrukturyzowanego tekstu. W niektórych przypadkach wymagany jest jednak tekst ustrukturyzowany, np. JSON. Może się zdarzyć, że używasz odpowiedzi do innych zadań, które wymagają ustalonego schematu danych.

Aby mieć pewność, że wygenerowane dane wyjściowe modelu zawsze będą zgodne z określonym schematem, możesz zdefiniować schemat, który będzie działać jak plan odpowiedzi modelu. Dzięki temu możesz bezpośrednio wyodrębniać dane z danych wyjściowych modelu, ograniczając przetwarzanie końcowe.

Oto przykłady:

  • Upewnij się, że odpowiedź modelu jest prawidłowym kodem JSON i jest zgodna z podanym schematem.
    Model może np. generować ustrukturyzowane wpisy dotyczące przepisów, które zawsze zawierają nazwę przepisu, listę składników i instrukcje. Dzięki temu możesz łatwiej analizować i wyświetlać te informacje w interfejsie aplikacji.

  • Ogranicz sposób, w jaki model może odpowiadać podczas zadań klasyfikacji.
    Możesz np. poprosić model o oznaczanie tekstu określonym zestawem etykiet (np. określonym zestawem wyliczeń, takich jak positive i negative), a nie etykietami generowanymi przez model (które mogą mieć pewien stopień zmienności, np. good, positive, negative lub bad).

Na tej stronie opisujemy, jak generować ustrukturyzowane dane wyjściowe (np. JSON i wyliczenia) w hybrydowych interfejsach aplikacji internetowych.

Zanim zaczniesz

Upewnij się, że masz za sobą przewodnik dla początkujących dotyczący tworzenia hybrydowych interfejsów.

Ustawianie konfiguracji ustrukturyzowanych danych wyjściowych

Generowanie ustrukturyzowanych danych wyjściowych (np. JSON i wyliczeń) jest obsługiwane w przypadku wnioskowania za pomocą modeli hostowanych w chmurze i modeli na urządzeniu.

W przypadku wnioskowania hybrydowego użyj zarówno inCloudParams jak i onDeviceParams , aby skonfigurować model tak, aby odpowiadał ustrukturyzowanymi danymi wyjściowymi. W przypadku pozostałych trybów użyj tylko odpowiedniej konfiguracji.

  • W przypadku inCloudParams: określ odpowiedni responseMimeType (np. application/json) oraz responseSchema, którego chcesz używać w modelu.

  • W przypadku onDeviceParams: określ responseConstraint, którego chcesz używać w modelu.

Dane wyjściowe JSON

Poniższe przykłady dostosowują ogólny przykład danych wyjściowych JSON do wnioskowania hybrydowego (w tym przykładzie PREFER_ON_DEVICE):

Przykład 1. Używanie metod pomocniczych Firebase Schema

Ten przykład używa metod pomocniczych udostępnianych przez pakiet Firebase AI Logic SDK, aby definicja schematu była bardziej zwarta.

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()));

// ...

Przykład 2. Używanie zwykłego schematu JSON

Ten przykład definiuje schemat tylko za pomocą JSON i zwraca te same wyniki.

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()));

Dane wyjściowe wyliczeń

Poniższy przykład dostosowuje ogólny przykład danych wyjściowych wyliczeń do wnioskowania hybrydowego (w tym przykładzie 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
    }
  }
});

// ...