Gemini API 가이드: Structured Output으로 JSON 출력 형식 고정하기

AI Studio에서 출력값의 형태(JSON)를 고정하는 방법

 

이 글에서는 Google AI Studio의 'Structured Output' 기능을 사용하여 Gemini API의 출력 형식을 JSON으로 고정하는 방법을 알아봅니다. 이 기능을 활용하면 항상 일정한 구조의 결과물을 얻을 수 있습니다.

 

Gemini API를 사용하다 보면, 출력 형태를 숫자로 한정하거나 특정 목록 내의 값으로 고정하는 등 일관된 결과물이 필요할 때가 있습니다. Gemini API의 'Structured Output' 기능은 출력값의 형태를 JSON 스키마로 정의하여 이러한 요구사항을 간단하게 해결할 수 있도록 돕습니다.

 

이 글에서는 AI Studio를 통해 출력 형식을 제어하는 방법을 단계별로 살펴보겠습니다.

 

1. Structured Output 기능 사용 예시

 

AI Studio의 Structured Output 설정 단계

 

먼저 AI Studio 우측 메뉴에서 'Structured output' 토글을 켜고 'Edit' 버튼을 누릅니다. 스키마 편집기가 나타나면 'Add property'를 클릭하여 속성을 추가합니다.

 

Code Editor 또는 Visual Editor를 사용하여 스키마를 정의합니다.

 

Visual Editor 또는 Code Editor에서 출력될 데이터의 구조(스키마)를 정의합니다. 여기서는 '요일'이라는 속성을 만들고, 가능한 값을 월요일부터 일요일까지로 제한했습니다. 아래 코드를 Code Editor에 복사하여 붙여넣고 'Save'를 눌러 저장할 수 있습니다.

 

{
  "type": "object",
  "properties": {
    "요일": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "월",
          "화",
          "수",
          "목",
          "금",
          "토",
          "일"
        ]
      }
    }
  },
  "propertyOrdering": [
    "요일"
  ],
  "required": [
    "요일"
  ]
}

 

이 JSON 스키마는 API의 출력이 반드시 '요일'이라는 키를 포함하고, 그 값은 "월"부터 "일" 사이의 문자열 배열이어야 함을 의미합니다.

 

2. 실제 활용

 

정의된 JSON 스키마에 따라 정확한 형식으로 응답을 생성하는 모습

 

이제 모델에게 "오늘이 목요일이면 내일은 무슨 요일이지?"라고 질문하면, 미리 정의한 스키마에 맞춰 `{"요일": ["금"]}`과 같이 정확한 JSON 형식으로 답변하는 것을 확인할 수 있습니다.

 

---

 

이처럼 AI Studio의 Structured Output 기능을 활용하면, Gemini API가 항상 약속된 JSON 형식으로만 응답하도록 강제할 수 있어 개발 안정성과 예측 가능성을 크게 높일 수 있습니다.