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

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

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

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

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

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

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

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

Gemini API를 사용하는 기타 옵션

• 원하는 경우 Gemini API의 대체 'Google AI' 버전을 실험합니다.
  Google AI Studio 및 Google AI 클라이언트 SDK를 사용하여 (한도 내에서 가능한 경우) 무료 액세스 권한을 얻습니다. 이러한 SDK는 모바일 및 웹 앱의 프로토타입 제작에만 사용해야 합니다.

  Gemini API의 작동 방식을 숙지한 후 Vertex AI in Firebase SDK로 이전하세요(이 문서). Firebase App Check를 사용하여 API 악용으로부터 보호하고 요청의 대용량 미디어 파일을 지원하는 등 모바일 및 웹 앱에 중요한 여러 추가 기능이 있습니다.

• Vertex AI Gemini API 서버 측을 호출할 수도 있습니다(예: Python, Node.js 또는 Go).
  Gemini API에 서버 측 Vertex AI SDK, Firebase Genkit 또는 Firebase Extensions를 사용합니다.

시작하기 전에

아직 완료하지 않았다면 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 사용 경험에 관한 의견 보내기