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


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

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

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

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

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

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

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

시작하기 전에

아직 완료하지 않았다면 Vertex AI in Firebase SDK 시작 가이드를 완료하세요. 다음 작업을 모두 완료했는지 확인합니다.

  1. Blaze 요금제 사용 및 필요한 API 사용 설정을 포함하여 새 Firebase 프로젝트 또는 기존 Firebase 프로젝트를 설정합니다.

  2. 앱을 등록하고 앱에 Firebase 구성을 추가하는 등 앱을 Firebase에 연결합니다.

  3. SDK를 추가하고 앱에서 Vertex AI 서비스와 생성 모델을 초기화합니다.

앱을 Firebase에 연결하고, SDK를 추가하고, Vertex AI 서비스와 생성형 모델을 초기화한 후에는 Gemini API를 호출할 수 있습니다.

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 출력을 생성하는 방법을 보여줍니다.

구조화된 출력을 생성하려면 모델 초기화 중에 적절한 responseMimeType(이 예에서는 application/json)와 모델에서 사용할 responseSchema를 지정해야 합니다.

responseSchema 사용은 Gemini 1.5 Pro 및 Gemini 1.5 Flash에서 지원됩니다.

Gemini 모델 및 사용 사례 및 앱에 적합한 위치(선택사항)를 선택하는 방법을 알아보세요.

추가 예

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

enum 값을 출력으로 생성

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

이 구조화된 분류 작업을 수행하려면 모델을 초기화하는 동안 모델에서 사용할 responseSchema와 함께 적절한 responseMimeType (이 예시에서는 text/x.enum)를 지정해야 합니다.

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

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

  • 모델이 요구사항에 맞는 출력을 생성하도록 영향을 줄 수 있도록 프롬프트 설계에 대해 자세히 알아보세요.
  • 모델의 응답 생성 방식을 제어하도록 모델 매개변수를 구성합니다. 이러한 매개변수에는 최대 출력 토큰, 온도, topK, 최상위 P가 포함됩니다.
  • 안전 설정을 사용하여 증오심 표현 및 음란물 등 유해하다고 간주될 수 있는 응답을 받을 가능성을 조정합니다.
  • 시스템 안내를 설정하여 모델의 동작을 조정합니다. 이 기능은 모델이 최종 사용자의 추가 안내에 노출되기 전에 추가하는 '프롤로그'와 같습니다.


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