Gemini API로 구조화된 출력 생성


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

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

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

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

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

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