Gemini API를 사용하여 구조화된 출력 (예: JSON 및 enum) 생성

Gemini API는 기본적으로 응답을 비정형 텍스트로 반환합니다. 그러나 일부 사용 사례에서는 JSON과 같은 구조화된 텍스트가 필요합니다. 예를 들어 기존 데이터 스키마가 필요한 다른 다운스트림 태스크에 응답을 사용할 수 있습니다.

모델에서 생성된 출력이 항상 특정 스키마를 준수하도록 하려면 모델 대답의 청사진처럼 작동하는 응답 스키마를 정의하면 됩니다. 그러면 적은 양의 후처리로 모델 출력에서 데이터를 직접 추출할 수 있습니다.

예를 들면 다음과 같습니다.

  • 모델의 응답이 유효한 JSON을 생성하고 제공된 스키마를 준수하는지 확인합니다.
    예를 들어 모델은 항상 레시피 이름, 재료 목록, 단계를 포함하는 레시피의 구조화된 항목을 생성할 수 있습니다. 그러면 이 정보를 더 쉽게 파싱하고 앱의 UI에 표시할 수 있습니다.

  • 분류 작업 중에 모델이 응답하는 방식을 제한합니다.
    예를 들어 모델이 생성하는 라벨 (good, positive, negative, bad와 같이 가변성이 있을 수 있음)이 아닌 특정 라벨 세트 (예: positive 및 negative와 같은 특정 enum 세트)를 사용하여 텍스트에 주석을 달도록 모델을 설정할 수 있습니다.

이 가이드에서는 generateContent 호출에 responseSchema를 제공하여 JSON 출력을 생성하는 방법을 보여줍니다. 텍스트 전용 입력에 중점을 두지만 Gemini는 이미지, 동영상, 오디오를 입력으로 포함하는 멀티모달 요청에 대한 구조화된 응답도 생성할 수 있습니다.

이 페이지 하단에는 enum 값을 출력으로 생성하는 방법과 같은 더 많은 예시가 있습니다. 구조화된 출력을 생성하는 방법에 관한 추가 예시를 보려면 Google Cloud 문서의 스키마 및 모델 응답 예시 목록을 확인하세요.

시작하기 전에

아직 완료하지 않았다면 Firebase 프로젝트를 설정하고, 앱을 Firebase에 연결하고, SDK를 추가하고, Vertex AI 서비스를 초기화하고, GenerativeModel 인스턴스를 만드는 방법을 설명하는 시작 가이드를 완료하세요.

1단계: 응답 스키마 정의

응답 스키마를 정의하여 모델 출력 구조, 필드 이름, 각 필드의 예상 데이터 유형을 지정합니다.

모델에서 응답을 생성할 때 프롬프트의 필드 이름과 컨텍스트를 사용합니다. 의도가 명확하게 전달되도록 명확한 구조, 명확한 필드 이름, 필요한 경우 설명을 사용하는 것이 좋습니다.

응답 스키마 고려사항

응답 스키마를 작성할 때는 다음 사항에 유의하세요.

  • 응답 스키마 크기는 입력 토큰 한도에 반영됩니다.

  • 응답 스키마 기능은 다음과 같은 응답 MIME 유형을 지원합니다.

    • application/json: 응답 스키마에 정의된 대로 JSON을 출력합니다(구조화된 출력 요구사항에 유용).

    • text/x.enum: 응답 스키마에 정의된 대로 열거형 값을 출력합니다(분류 태스크에 유용).

  • 응답 스키마 기능은 다음 스키마 필드를 지원합니다.

    enum
    items
    		 maxItems
    nullable
    		 properties
    required

    지원되지 않는 필드를 사용해도 모델은 요청을 처리할 수 있지만 필드를 무시합니다. 위 목록은 OpenAPI 3.0 스키마 객체의 하위 집합입니다 (Vertex AI 스키마 참조 참고).

  • 기본적으로 Vertex AI in Firebase SDK의 경우 optionalProperties 배열에서 선택사항으로 지정하지 않는 한 모든 필드는 필수 필드로 간주됩니다. 이러한 선택사항 필드의 경우 모델에서 필드를 채우거나 건너뛸 수 있습니다.

    이는 Vertex AI Gemini API의 기본 동작과는 반대입니다.

2단계: 응답 스키마가 포함된 프롬프트를 전송하여 JSON 생성

다음 예는 구조화된 JSON 출력을 생성하는 방법을 보여줍니다.

GenerativeModel 인스턴스를 만들 때 적절한 responseMimeType (이 예에서는 application/json)와 모델에서 사용할 responseSchema를 지정합니다.

Swift 

import FirebaseVertexAI

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let jsonSchema = Schema.object(
  properties: [
    "characters": Schema.array(
      items: .object(
        properties: [
          "name": .string(),
          "age": .integer(),
          "species": .string(),
          "accessory": .enumeration(values: ["hat", "belt", "shoes"]),
        ],
        optionalProperties: ["accessory"]
      )
    ),
  ]
)

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: GenerationConfig(
    responseMIMEType: "application/json",
    responseSchema: jsonSchema
  )
)

let prompt = "For use in a children's card game, generate 10 animal-based characters."

let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

Kotlin

Kotlin의 경우 이 SDK의 메서드는 정지 함수이므로 코루틴 범위에서 호출해야 합니다. 
// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
val jsonSchema = Schema.obj(
    mapOf("characters" to Schema.array(
        Schema.obj(
            mapOf(
                "name" to Schema.string(),
                "age" to Schema.integer(),
                "species" to Schema.string(),
                "accessory" to Schema.enumeration(listOf("hat", "belt", "shoes")),
            ),
            optionalProperties = listOf("accessory")
        )
    ))
)

// Initialize the Vertex AI service and the generative model.
val generativeModel = Firebase.vertexAI.generativeModel(
    modelName = "gemini-2.0-flash",
    // In the generation config, set the `responseMimeType` to `application/json`
    // and pass the JSON schema object into `responseSchema`.
    generationConfig = generationConfig {
        responseMimeType = "application/json"
        responseSchema = jsonSchema
    })

val prompt = "For use in a children's card game, generate 10 animal-based characters."
val response = generativeModel.generateContent(prompt)
print(response.text)

Java

Java의 경우 이 SDK의 스트리밍 메서드는 Reactive Streams 라이브러리의 Publisher 유형을 반환합니다. 
// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
Schema jsonSchema = Schema.obj(
        /* properties */
        Map.of(
                "characters", Schema.array(
                        /* items */ Schema.obj(
                                /* properties */
                                Map.of("name", Schema.str(),
                                        "age", Schema.numInt(),
                                        "species", Schema.str(),
                                        "accessory",
                                        Schema.enumeration(
                                                List.of("hat", "belt", "shoes")))
                        ))),
        List.of("accessory"));

// In the generation config, set the `responseMimeType` to `application/json`
// and pass the JSON schema object into `responseSchema`.
GenerationConfig.Builder configBuilder = new GenerationConfig.Builder();
configBuilder.responseMimeType = "application/json";
configBuilder.responseSchema = jsonSchema;

GenerationConfig generationConfig = configBuilder.build();

// Initialize the Vertex AI service and the generative model.
GenerativeModel gm = FirebaseVertexAI.getInstance().generativeModel(
  /* modelName */ "gemini-2.0-flash",
  /* generationConfig */ generationConfig);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);

Content content = new Content.Builder()
    .addText("For use in a children's card game, generate 10 animal-based characters.")
    .build();

// For illustrative purposes only. You should use an executor that fits your needs.
Executor executor = Executors.newSingleThreadExecutor();

ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(
    response,
    new FutureCallback<GenerateContentResponse>() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
        t.printStackTrace();
      }
    },
    executor);

Web 

import { initializeApp } from "firebase/app";
import { getVertexAI, getGenerativeModel, Schema } from "firebase/vertexai";

// 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 Vertex AI service.
const vertexAI = getVertexAI(firebaseApp);

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
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"],
      }),
    }),
  }
});

// Initialize the generative model.
const model = getGenerativeModel(vertexAI, {
  model: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: jsonSchema
  },
});


let prompt = "For use in a children's card game, generate 10 animal-based characters.";

let result = await model.generateContent(prompt)
console.log(result.response.text());

Dart 

import 'package:firebase_vertexai/firebase_vertexai.dart';
import 'package:firebase_core/firebase_core.dart';

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
final jsonSchema = Schema.object(
        properties: {
          'characters': Schema.array(
            items: Schema.object(
              properties: {
                'name': Schema.string(),
                'age': Schema.integer(),
                'species': Schema.string(),
                'accessory':
                    Schema.enumString(enumValues: ['hat', 'belt', 'shoes']),
              },
            ),
          ),
        },
        optionalProperties: ['accessory'],
      );

await Firebase.initializeApp();
// Initialize the Vertex AI service and the generative model.
final model =
      FirebaseVertexAI.instance.generativeModel(
        model: 'gemini-2.0-flash',
        // In the generation config, set the `responseMimeType` to `application/json`
        // and pass the JSON schema object into `responseSchema`.
        generationConfig: GenerationConfig(
            responseMimeType: 'application/json', responseSchema: jsonSchema));

final prompt = "For use in a children's card game, generate 10 animal-based characters.";
final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

사용 사례 및 앱에 적합한 모델과 원하는 경우 위치를 선택하는 방법을 알아보세요.

추가 예

구조화된 출력을 사용하고 생성하는 방법에 관한 추가 예시를 보려면 Google Cloud 문서의 스키마 및 모델 응답 예시 목록을 확인하세요.

enum 값을 출력으로 생성

다음 예는 분류 작업에 응답 스키마를 사용하는 방법을 보여줍니다. 모델은 설명을 기반으로 영화 장르를 식별하도록 요청받습니다. 출력은 모델이 제공된 응답 스키마에 정의된 값 목록에서 선택하는 일반 텍스트 enum 값 하나입니다.

이 정형 분류 작업을 실행하려면 모델 초기화 중에 적절한 responseMimeType (이 예에서는 text/x.enum)와 모델에서 사용할 responseSchema를 지정해야 합니다.

Swift 

import FirebaseVertexAI

// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let enumSchema = Schema.enumeration(values: ["drama", "comedy", "documentary"])

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `text/x.enum`
  // and pass the enum schema object into `responseSchema`.
  generationConfig: GenerationConfig(
    responseMIMEType: "text/x.enum",
    responseSchema: enumSchema
  )
)

let 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.
"""

let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

Kotlin

Kotlin의 경우 이 SDK의 메서드는 정지 함수이므로 코루틴 범위에서 호출해야 합니다. 
// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
val enumSchema = Schema.enumeration(listOf("drama", "comedy", "documentary"))

// Initialize the Vertex AI service and the generative model.
val generativeModel = Firebase.vertexAI.generativeModel(
    modelName = "gemini-2.0-flash",
    // In the generation config, set the `responseMimeType` to `text/x.enum`
    // and pass the enum schema object into `responseSchema`.
    generationConfig = generationConfig {
        responseMimeType = "text/x.enum"
        responseSchema = enumSchema
    })

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.
    """
val response = generativeModel.generateContent(prompt)
print(response.text)

Java

Java의 경우 이 SDK의 스트리밍 메서드는 Reactive Streams 라이브러리의 Publisher 유형을 반환합니다. 
// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
Schema enumSchema = Schema.enumeration(List.of("drama", "comedy", "documentary"));

// In the generation config, set the `responseMimeType` to `text/x.enum`
// and pass the enum schema object into `responseSchema`.
GenerationConfig.Builder configBuilder = new GenerationConfig.Builder();
configBuilder.responseMimeType = "text/x.enum";
configBuilder.responseSchema = enumSchema;

GenerationConfig generationConfig = configBuilder.build();

// Initialize the Vertex AI service and the generative model.
GenerativeModel gm = FirebaseVertexAI.getInstance().generativeModel(
  /* modelName */ "gemini-2.0-flash",
  /* generationConfig */ generationConfig);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);

String 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.";

Content content = new Content.Builder().addText(prompt).build();

// For illustrative purposes only. You should use an executor that fits your needs.
Executor executor = Executors.newSingleThreadExecutor();

ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(
    response,
    new FutureCallback<GenerateContentResponse>() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
        t.printStackTrace();
      }
    },
    executor);

Web 

import { initializeApp } from "firebase/app";
import { getVertexAI, getGenerativeModel, Schema } from "firebase/vertexai";

// 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 Vertex AI service.
const vertexAI = getVertexAI(firebaseApp);

// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

// Initialize the generative model.
const model = getGenerativeModel(vertexAI, {
  model: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `text/x.enum`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: {
    responseMimeType: "text/x.enum",
    responseSchema: enumSchema,
  },
});

let 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.`;

let result = await model.generateContent(prompt);
console.log(result.response.text());

Dart 

import 'package:firebase_vertexai/firebase_vertexai.dart';
import 'package:firebase_core/firebase_core.dart';

// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
final enumSchema = Schema.enumString(enumValues: ['drama', 'comedy', 'documentary']);

await Firebase.initializeApp();
// Initialize the Vertex AI service and the generative model.
final model =
      FirebaseVertexAI.instance.generativeModel(
        model: 'gemini-2.0-flash',
        // In the generation config, set the `responseMimeType` to `text/x.enum`
        // and pass the enum schema object into `responseSchema`.
        generationConfig: GenerationConfig(
            responseMimeType: 'text/x.enum', responseSchema: enumSchema));

final 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.
      """;
final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

사용 사례 및 앱에 적합한 모델과 원하는 경우 위치를 선택하는 방법을 알아보세요.

콘텐츠 생성을 제어하는 기타 옵션

  • 모델에 영향을 주어 필요에 맞는 출력을 생성할 수 있도록 프롬프트 디자인에 대해 자세히 알아보세요.
  • 모델 매개변수를 구성하여 모델의 응답 생성 방식을 제어합니다. Gemini 모델의 경우 이러한 매개변수에는 최대 출력 토큰, 온도, topK, topP가 포함됩니다. Imagen 모델의 경우 여기에는 가로세로 비율, 인물 생성, 워터마킹 등이 포함됩니다.
  • 안전 설정을 사용하여 증오심 표현 및 성적으로 노골적인 콘텐츠를 포함하여 유해하다고 간주될 수 있는 대답을 받을 가능성을 조정합니다.
  • 시스템 안내를 설정하여 모델의 동작을 조정합니다. 이 기능은 모델이 최종 사용자의 추가 안내에 노출되기 전에 추가하는 '프리앰블'과 같습니다.


Vertex AI in Firebase 사용 경험에 관한 의견 보내기