Gemini API로 구조화된 출력 생성


Gemini는 기본적으로 구조화되지 않은 텍스트를 생성하지만 일부 애플리케이션에는 구조화된 텍스트가 필요합니다. 이러한 사용 사례의 경우 Gemini가 자동 처리에 적합한 구조화된 데이터 형식인 JSON으로 응답하도록 제한할 수 있습니다. enum에 지정된 옵션 중 하나로 응답하도록 모델을 제한할 수도 있습니다.

다음은 모델의 구조화된 출력이 필요한 몇 가지 사용 사례입니다.

  • 신문 기사에서 회사 정보를 가져와 회사 데이터베이스를 만듭니다.
  • 이력서에서 표준화된 정보를 가져옵니다.
  • 레시피에서 재료를 추출하고 각 재료의 식료품점 웹사이트 링크를 표시합니다.

프롬프트에서 Gemini에 JSON 형식의 출력을 생성하도록 요청할 수 있지만 모델이 JSON만 생성할 수는 없습니다. 더 확정적인 응답을 위해 Gemini가 항상 예상 구조로 응답하도록 responseSchema 필드에 특정 JSON 스키마를 전달할 수 있습니다. 스키마 작업에 관한 자세한 내용은 JSON 스키마에 관한 자세한 내용을 참고하세요.

이 가이드에서는 원하는 SDK를 통해 generateContent 메서드를 사용하거나 REST API를 직접 사용하여 JSON을 생성하는 방법을 보여줍니다. 이 예에서는 텍스트 전용 입력을 보여줍니다. 하지만 Gemini는 이미지, 동영상, 오디오를 포함하는 다중 모드 요청에 대한 JSON 응답을 생성할 수도 있습니다.

시작하기 전에: 프로젝트 및 API 키 설정

Gemini API를 호출하기 전에 프로젝트를 설정하고 API 키를 구성해야 합니다.

API 키 가져오기 및 보호

Gemini API를 호출하려면 API 키가 필요합니다. 아직 키가 없다면 Google AI 스튜디오에서 키를 만드세요.

API 키 가져오기

버전 제어 시스템에 API 키를 체크인하지 마세요.

Google Cloud Secret Manager와 같은 API 키용 보안 비밀 저장소를 사용해야 합니다.

이 튜토리얼의 모든 스니펫은 API 키에 전역 상수로 액세스한다고 가정합니다.

JSON 생성

모델이 JSON을 출력하도록 구성되면 JSON 형식의 출력으로 프롬프트에 응답합니다.

스키마를 제공하여 JSON 응답의 구조를 제어할 수 있습니다. 모델에 스키마를 제공하는 방법에는 두 가지가 있습니다.

  • 프롬프트의 텍스트로
  • 모델 구성을 통해 제공되는 구조화된 스키마

프롬프트에 스키마를 텍스트로 제공

다음 예에서는 모델이 특정 JSON 형식으로 쿠키 레시피를 반환하도록 요청합니다.

모델은 프롬프트의 텍스트에서 형식 사양을 가져오므로 사양을 나타내는 방법을 어느 정도 유연하게 선택할 수 있습니다. JSON 스키마를 나타내는 적절한 형식은 무엇이든 사용할 수 있습니다.

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

출력은 다음과 같이 표시될 수 있습니다.

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

모델 구성을 통해 스키마 제공

다음 예에서는 다음을 실행합니다.

  1. JSON으로 응답하도록 스키마를 통해 구성된 모델을 인스턴스화합니다.
  2. 모델에 쿠키 레시피를 반환하라는 메시지를 표시합니다.

JSON 스키마를 선언하는 이보다 더 공식적인 방법을 사용하면 프롬프트의 텍스트에만 의존하는 것보다 더 정확하게 제어할 수 있습니다.

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

출력은 다음과 같이 표시될 수 있습니다.

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

JSON 스키마에 대한 자세한 내용

JSON 응답을 반환하도록 모델을 구성할 때 Schema 객체를 사용하여 JSON 데이터의 도형을 정의할 수 있습니다. Schema는 OpenAPI 3.0 스키마 객체의 일부 하위 집합을 나타냅니다.

다음은 모든 Schema 필드의 가상 JSON 표현입니다.

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

스키마의 Type는 OpenAPI 데이터 유형 중 하나여야 합니다. 각 Type에는 일부 필드만 유효합니다. 다음 목록은 각 Type를 해당 유형의 유효한 필드에 매핑합니다.

  • string -> enum, format
  • integer -> 형식
  • number -> 형식
  • boolean
  • array -> minItems, maxItems, items
  • object -> 속성, 필수, propertyOrdering, null 허용

다음은 유효한 유형 및 필드 조합을 보여주는 스키마의 예입니다.

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

Gemini API에서 사용되는 스키마 필드에 관한 전체 문서는 스키마 참조를 참고하세요.

숙박 시설 정렬

Gemini API에서 JSON 스키마를 사용할 때는 속성 순서가 중요합니다. 기본적으로 API는 속성을 알파벳순으로 정렬하며 속성이 정의된 순서를 유지하지 않습니다 (단, Google Gen AI SDK는 이 순서를 유지할 수 있음). 구성된 스키마가 있는 모델에 예시를 제공하는 경우 예시의 속성 순서가 스키마의 속성 순서와 일치하지 않으면 출력이 장황하거나 예상치 못할 수 있습니다.

일관되고 예측 가능한 속성 순서를 보장하려면 선택적 propertyOrdering[] 필드를 사용하면 됩니다.

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[]: OpenAPI 사양의 표준 필드가 아니며 응답에서 속성의 순서를 결정하는 데 사용되는 문자열 배열입니다. 속성의 순서를 지정한 다음 동일한 순서로 속성이 포함된 예시를 제공하면 결과 품질을 개선할 수 있습니다.