FAQ 및 문제 해결

Gemini Developer API과 Vertex AI Gemini API 사용의 차이점은 무엇인가요?

다음 표에는 액세스 방식과 관계없이 두 'Gemini API' 제공업체 간의 중요한 차이점이 나열되어 있습니다.

¹ 두 API 제공업체의 종량제 가격이 다릅니다(각 문서에서 자세히 알아보기).

² Gemini Developer API의 파일 API는 Firebase AI Logic SDK를 통해 지원되지 않습니다.

다음 표에는 두 'Gemini API' 제공업체에 대해 자주 묻는 기능의 사용 가능 여부가 나와 있습니다. 이 표는 Firebase AI Logic 클라이언트 SDK를 사용하는 경우에만 적용됩니다.

Gemini Developer API와 Vertex AI Gemini API을 모두 사용할 수 있나요?

예, Firebase 프로젝트에서 'Gemini API' 제공업체를 모두 사용 설정할 수 있으며 앱 자체에서 두 API를 모두 사용할 수 있습니다.

코드에서 API 제공업체 간에 전환하려면 코드에서 백엔드 서비스를 적절하게 설정해야 합니다.

필수 API는 무엇인가요? 사용 설정하려면 어떻게 해야 하나요?

Gemini Developer API와 함께 Firebase AI Logic SDK를 사용하려면 프로젝트에서 다음 두 API가 사용 설정되어 있어야 합니다.

• Gemini Developer API(generativelanguage.googleapis.com명)
• Firebase AI Logic API (firebasevertexai.googleapis.com)

Firebase 콘솔을 사용하여 다음 두 API를 사용 설정해야 합니다.

1. Firebase 콘솔에서 AI 서비스 > AI 로직으로 이동합니다.

2. 시작하기를 클릭합니다.

3. Gemini Developer API를 시작하려면 선택하세요.

   그러면 두 API를 사용 설정하는 안내식 워크플로가 실행됩니다. 콘솔에서 Gemini API 키를 생성하고 Firebase AI Logic API를 Firebase API 키의 허용 목록에 추가합니다.

Firebase 프로젝트에서 API를 사용 중지하려면 어떻게 해야 하나요?

Firebase AI Logic의 경우 선택한 Gemini API 제공업체를 사용하도록 Firebase 프로젝트를 최대한 쉽게 설정할 수 있도록 노력하고 있습니다. 여기에는 Firebase 콘솔의 안내 워크플로와 같은 특정 여정 중에 Firebase 프로젝트에서 필수 API를 사용 설정하는 것이 포함됩니다.

하지만 Firebase AI Logic 또는 Gemini API 제공업체 중 하나를 사용하지 않기로 결정한 경우 Firebase 프로젝트에서 연결된 API를 사용 중지할 수 있습니다.

Firebase AI Logic SDK와 함께 사용할 수 있는 모델은 무엇인가요?

지원되는 모델 목록을 참고하세요. Fitbit에서는 SDK에 새로운 기능을 자주 추가하므로 이 FAQ에서 업데이트를 확인하세요 (출시 노트, 블로그, 소셜 게시물에서도 확인 가능).

• Gemini Developer API

  • Gemini 및 Imagen 파운데이션 모델 모두

    Gemini Developer API은 액세스 방식과 관계없이 특정 안정적인 Imagen 모델만 지원합니다.

• Vertex AI Gemini API

  • Gemini 및 Imagen 파운데이션 모델 모두

• 선택한 Gemini API 제공업체와 관계없이

  • Firebase AI Logic는 다음을 지원하지 않습니다.

    • 기반 모델이 아닌 Gemini 모델(예: PaLM 모델, 조정된 모델, Gemma 기반 모델)

    • 이전 Imagen 모델 또는 imagen-3.0-capability-001

모델이 종료 (지원 중단)되면 어떻게 해야 하나요?

안정화 버전 모델이 출시되면 모델이 지원 중단되기 최소 1년 전에 사용할 수 있도록 노력합니다.

모델의 종료일은 어디에서 확인할 수 있나요?

모델의 서비스 종료일을 확인할 수 있는 방법은 다음과 같습니다.

• 출시 시점: Gemini API 제공업체 문서와 Firebase 문서(지원되는 모델 페이지 참고)의 여러 위치에 각 모델의 예상 종료 날짜가 나열됩니다.

• 종료일이 다가옴에 따라: Google은 적절한 프로젝트 구성원에게 이메일을 보내고 출시 노트 및 기타 채널에 예정된 종료에 관한 알림을 게시합니다 (예: Gemini 1.5 및 1.0 안정화 모델의 종료일 알림).

사용 중인 모델이 종료될 예정인 경우 어떻게 해야 하나요?

1. 적합한 현재 지원되는 모델과 모델 이름을 찾습니다.

2. 폐쇄일 전에 앱에서 사용하는 모델 이름을 업데이트하세요. 그렇지 않으면 해당 모델에 대한 요청이 404 오류로 실패합니다.

   • GenerativeModel, LiveModel 또는 ImagenModel 인스턴스를 생성할 때 초기화 중에 모델 이름을 설정합니다. Firebase Remote Config 사용에 관한 아래의 중요한 권장사항을 검토하세요.

   • Firebase AI Logic를 사용할 때는 실제로 모델을 호출하는 코드를 수정할 필요가 일반적으로 없습니다.

3. 앱을 테스트하여 응답이 여전히 예상대로인지 확인합니다.

Imagen 안정화 모델 - 종료일 및 대체

• 2026년 6월 24일에 모든 Imagen 모델이 종료됩니다.

대체: Gemini 이미지 모델('Nano Banana' 모델)을 사용하도록 앱을 이전하세요.

Gemini 2.0 안정화 모델 - 종료일 및 대체

• Gemini 2.0 Flash 및 Gemini 2.0 Flash‑Lite:

  gemini-2.0-flash-001 (및 자동 업데이트된 별칭 gemini-2.0-flash)
  gemini-2.0-flash-lite-001 (및 자동 업데이트된 별칭 gemini-2.0-flash-lite)

  • 2026년 2월 6일: 이전에 모델을 사용한 적이 없는 프로젝트에서 더 이상 이러한 모델을 사용할 수 없습니다.

  • 2026년 3월 31일: 이러한 모델이 종료됩니다.

  안정적인 Gemini Live API 2.0 모델은 영향을 받지 않습니다.

대체: Gemini 2.5 모델 (예: gemini-2.5-flash-lite)을 사용하도록 이전하거나 새로운 Gemini 3 모델(예: gemini-3.1-flash-lite-preview)을 사용해 보세요.

Gemini 1.5 및 1.0 안정화 모델 - 종료일 및 대체

• Gemini 1.5 Pro 모델:

  • gemini-1.5-pro-002 (및 gemini-1.5-pro): 2025년 9월 24일
  • gemini-1.5-pro-001: 2025년 5월 24일

• Gemini 1.5 Flash 모델:

  • gemini-1.5-flash-002 (및 gemini-1.5-flash): 2025년 9월 24일
  • gemini-1.5-flash-001: 2025년 5월 24일

• Gemini 1.0 Pro Vision 모델: 2025년 4월 21일 (이전 일정: 2025년 4월 9일)

• Gemini 1.0 Pro 모델: 2025년 4월 21일 (이전 일정: 2025년 4월 9일)

대체: Gemini 2.5 모델 (예: gemini-2.5-flash-lite)을 사용하도록 이전하거나 새로운 Gemini 3 모델(예: gemini-3.1-flash-lite-preview)을 사용해 보세요.

Firebase AI Logic SDK를 사용하는 데 어떤 권한이 필요할 수 있나요?

Firebase AI Logic은 모델 학습에 내 데이터를 사용하나요?

데이터 거버넌스 및 책임감 있는 AI를 참고하세요.

사용자별 비율 한도를 설정하려면 어떻게 해야 하나요?

기본적으로 Firebase AI Logic는 사용자별 요청 한도를 분당 100개 요청 (RPM)으로 설정합니다.

사용자별 비율 제한을 조정하려면 Firebase AI Logic API의 할당량 설정을 조정해야 합니다.

Firebase AI Logic API 할당량에 대해 자세히 알아보세요. 이 페이지에서 할당량을 확인하고 수정하는 방법도 알아볼 수 있습니다.

지연 시간과 높은 토큰 사용량을 줄이려면 어떻게 해야 하나요?

지연 시간이 길거나 토큰 사용량이 많은 경우 사용 중인 모델의 사고 수준 구성 때문일 수 있습니다.

Gemini 3 이상의 모델은 항상 내부 '사고 과정'을 사용하여 추론 및 다단계 계획 능력을 크게 향상하므로 코딩, 고급 수학, 데이터 분석과 같은 복잡한 작업에 매우 효과적입니다.

하지만 작업에 따라 더 높은 수준의 사고가 필요하지 않은 경우도 있으며, 더 낮은 수준의 사고를 사용하도록 모델을 구성할 수 있습니다. 사고 수준을 낮추면 지연 시간과 토큰 사용량을 줄일 수 있습니다. 모델에 필요한 사고 능력을 결정하려면 작업 난이도 비교를 검토하세요.

대부분의 Gemini 3 이상 모델의 경우 기본 사고 수준이 HIGH로 설정됩니다.

멀티모달 요청에 MIME 유형이 필요한가요? (예: 이미지, PDF, 동영상, 오디오 입력)

예. 각 멀티모달 요청에서 항상 다음을 제공해야 합니다.

• 파일의 mimeType입니다. 아래 예외를 참고하세요.

• 파일입니다. 파일을 인라인 데이터로 제공하거나 URL을 사용하여 파일을 제공할 수 있습니다.

지원되는 입력 파일 및 요구사항에서 지원되는 입력 파일 형식, MIME 유형 지정 방법, 파일을 제공하는 두 가지 옵션에 대해 알아보세요.

요청에 MIME 유형을 포함하는 경우의 예외

MIME 유형을 제공하지 않아도 되는 예외는 네이티브 Android 및 Apple 플랫폼 앱의 요청에 대한 인라인 이미지 입력입니다.

Android 및 Apple 플랫폼용 Firebase AI Logic SDK는 요청에서 이미지를 처리하는 간소화된 플랫폼 친화적인 방법을 제공합니다. 모든 이미지(형식과 관계없음)는 서버로 전송되기 전에 클라이언트 측에서 80% 품질의 JPEG로 변환됩니다. 즉, Android 및 Apple 플랫폼 SDK를 사용하여 이미지를 인라인 데이터로 제공하는 경우 요청에서 MIME 유형을 지정할 필요가 없습니다.

이 단순화된 처리는 요청에서 base64로 인코딩된 이미지를 전송하는 예시의 Firebase AI Logic 문서에 나와 있습니다.

이 기능에 관한 플랫폼별 추가 정보는 다음과 같습니다.

• Android:

  • 이미지를 인라인 데이터로 포함하는 멀티모달 프롬프트에서 플랫폼 네이티브 이미지 유형 (Bitmap)을 처리하는 간소화된 방식을 활용할 수 있습니다(예 참고).

  • 이미지 형식과 변환을 더 세밀하게 제어하려면 이미지를 InlineDataPart로 제공하고 특정 MIME 유형을 제공하면 됩니다. 예를 들면 다음과 같습니다.

    content { inlineData(/* PNG as byte array */, "image/png") }

• Apple 플랫폼:

  • 이미지가 인라인 데이터로 포함된 멀티모달 프롬프트에서 플랫폼 네이티브 이미지 유형 (UIImage, NSImage, CIImage, CGImage)을 처리하는 간소화된 방법을 활용할 수 있습니다(예 참고).

  • 이미지 형식과 변환을 더 세밀하게 제어하려면 이미지를 InlineDataPart로 제공하고 특정 MIME 유형을 제공하면 됩니다. 예를 들면 다음과 같습니다.

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

Firebase AI Logic: Google 이미지 검색을 사용한 그라운딩, Google 지도 기반 그라운딩, 모델 미세 조정, 임베딩 생성, 시맨틱 검색을 사용할 때 이러한 기능을 사용할 수 있나요?

다음 기능은 다양한 모델과 API 제공업체에서 지원되지만 Firebase AI Logic를 사용하는 경우에는 사용할 수 없습니다.

• Google 이미지 검색을 사용한 그라운딩
• Google 지도를 사용한 그라운딩
• 모델 미세 조정
• 임베딩 생성
• 시맨틱 검색

이를 기능 요청으로 추가하거나 기존 기능 요청에 투표하려면 Firebase UserVoice를 방문하세요.

이름이 'Vertex AI in Firebase'에서 'Firebase AI Logic'(으)로 변경된 이유는 무엇인가요?

2024년에 Google은 Vertex AI Gemini API와 Firebase 프록시 게이트웨이를 모두 사용하여 API를 악용으로부터 보호하고 다른 Firebase 제품과의 통합을 지원하는 Firebase 클라이언트 SDK 세트를 출시했습니다. 제품 이름은 'Vertex AI in Firebase'였으며, 이 제품 이름은 당시 제품에서 사용할 수 있는 사용 사례를 정확하게 설명했습니다.

하지만 그 이후로 제품의 기능이 확장되었습니다. 예를 들어 2025년 5월부터 Firebase App Check와의 통합을 사용하여 Gemini Developer API를 악용으로부터 보호하는 기능을 비롯해 Gemini Developer API를 지원합니다.

따라서 'Vertex AI in Firebase'라는 이름이 더 이상 확장된 제품 범위를 정확하게 나타내지 않습니다. 따라서 새로운 이름인 Firebase AI Logic은 진화하는 기능 세트를 더 잘 반영하며 향후 제품을 계속 확장할 수 있습니다.

이전 가이드를 확인하여 Firebase AI Logic의 모든 최신 기능을 사용하고 Gemini Developer API를 선택적으로 사용하기 시작하세요.

Apple 플랫폼의 Swift 앱 - 모듈 이름이 FirebaseAI에서 FirebaseAILogic로 변경된 경우 어떻게 해야 하나요?

Apple 플랫폼 앱의 경우 Firebase SDK v12.5.0부터 Firebase AI Logic가 이제 FirebaseAILogic 모듈에 따라 배포됩니다. 이번 변경사항은 이전 버전과 호환되며 하위 호환이 가능합니다.

이렇게 변경된 이유는 무엇인가요?

이전에는 이 서비스를 FirebaseAI 모듈로 배포했습니다. 하지만 다음과 같은 이유로 이름을 FirebaseAILogic로 변경해야 했습니다.

• 바이너리 배포에서 문제를 일으키는 모듈과 클래스 간의 이름 충돌을 방지합니다.

• 향후 기능 개발에 Swift 매크로를 사용할 수 있도록 지원

v12.5.0 이상으로 업그레이드하는 경우 어떻게 해야 하나요?

모듈 이름이 FirebaseAILogic로 변경되어도 이전 버전과 호환되므로 중단되지 않습니다. 하지만 향후 주요 Firebase SDK 호환성 변경사항 출시와 함께 이전 모듈이 삭제될 수 있습니다(현재 시기는 미정).

이 모듈 이름 변경에는 필요한 변경사항이 없지만 다음을 권장합니다.

1. Swift PM 종속 항목을 선택할 때는 FirebaseAI 대신 FirebaseAILogic를 선택합니다.

2. import 문을 FirebaseAI 대신 FirebaseAILogic로 변경합니다.

Gemini API 키란 무엇인가요?

Gemini Developer API는 'Gemini API 키'를 사용하여 호출자를 승인합니다. 따라서 Firebase AI Logic SDK를 통해 Gemini Developer API를 사용하는 경우 해당 API를 호출하려면 Firebase 프로젝트에 유효한 Gemini API 키가 필요합니다.

'Gemini API 키'는 API 허용 목록에 Gemini Developer API가 있는 API 키를 의미합니다.

Firebase 콘솔에서 Firebase AI Logic 설정 워크플로를 진행하면 Gemini Developer API로만 제한된 Gemini API 키가 생성되고 이 API 키를 사용하도록 Firebase AI Logic 프록시 서비스가 설정됩니다. 이 Firebase 생성 Gemini API 키는 Google Cloud 콘솔의 사용자 인증 정보 페이지에서 Gemini Developer API 키 (Firebase에서 자동 생성)로 이름이 지정됩니다.

API 키의 API 제한사항에 대해 자세히 알아보세요.

Firebase AI Logic SDK를 사용하는 경우 앱의 코드베이스에 Gemini API 키를 추가하지 않습니다. Gemini API 키를 안전하게 유지하는 방법을 자세히 알아보세요.

모바일 또는 웹 앱의 코드베이스에 Gemini API 키를 추가해야 하나요?

Firebase AI Logic SDK를 사용하는 경우 앱의 코드베이스에 Gemini API 키를 추가하지 마세요.

실제로 Firebase AI Logic SDK로 개발하는 동안 Gemini API 키와 직접 상호작용하지 않습니다. 대신 Google의 Firebase AI Logic 프록시 서비스는 백엔드에서 완전히 Gemini Developer API에 대한 각 요청에 Gemini API 키를 내부적으로 포함합니다.

Gemini Developer API을 호출하는 데 사용되는 Gemini API 키를 어떻게 변경할 수 있나요?

Firebase AI Logic SDK를 사용하는 경우 Gemini API 키를 변경할 필요가 없을 가능성이 높습니다. 하지만 다음 두 가지 경우에는 필요할 수 있습니다.

• 실수로 키가 유출되어 새 보안 키로 바꾸려는 경우

• 실수로 키를 삭제한 경우 삭제 후 30일 이내에 키를 삭제 취소할 수 있습니다.

Firebase AI Logic SDK에서 사용하는 Gemini API 키를 변경하는 방법은 다음과 같습니다.

1. Firebase에서 생성된 Gemini API 키가 아직 있으면 삭제합니다.

   Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 이 API 키를 삭제할 수 있습니다. 이름은
   Gemini Developer API 키 (Firebase에서 자동 생성)입니다.

2. Google Cloud 콘솔의 동일한 페이지에서 새 API 키를 만듭니다.
   Firebase용 Gemini Developer API 키와 같은 이름을 지정하는 것이 좋습니다.

3. 이 새 API 키에 API 제한사항을 추가하고 Generative Language API만 선택합니다.
   Google Cloud 콘솔에서 Gemini Developer API를 '생성형 언어 API'라고 부르기도 합니다.

   앱 제한사항을 추가하면 Firebase AI Logic 프록시 서비스가 예상대로 작동하지 않으므로 추가하지 않습니다.

4. 다음 명령어를 실행하여 이 새 키를 Firebase AI Logic 프록시 서비스가 사용해야 하는 Gemini API 키로 설정합니다.

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   gcloud CLI에 대해 알아보세요.

이 새 Gemini API 키를 앱의 코드베이스에 추가하지 마세요. Gemini API 키를 안전하게 유지하는 방법을 자세히 알아보세요.

'Firebase API 키'를 Gemini API 키로 사용할 수 있나요?

아니요. 'Firebase API 키'를 Gemini API 키로 사용하면 안 됩니다. Firebase API 키의 허용 목록에 Gemini Developer API를 추가하지 않는 것이 좋습니다.

Firebase API 키는 앱을 Firebase에 연결하기 위해 앱의 코드베이스에 추가하는 Firebase 구성 파일 또는 객체에 나열된 API 키입니다. Firebase 관련 API(예: Firebase AI Logic)에서만 키를 사용하는 경우 코드에 Firebase API 키를 포함해도 됩니다. Firebase API 키에 관한 중요 정보 알아보기

Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 Firebase API 키는 다음과 같이 표시됩니다.

Firebase 관련 API가 작동하려면 Firebase API 키를 앱의 코드베이스에 추가해야 하고 Gemini Developer API는 API 키를 통해 승인되므로 Firebase API 키의 API 허용 목록에 Gemini Developer API (Google Cloud 콘솔에서는 'Generative Language API'라고 함)를 추가하지 않는 것이 좋습니다. 이렇게 하면 Gemini Developer API가 악용될 수 있습니다.

Gemini API 키를 안전하게 유지하려면 어떻게 해야 하나요?

이 FAQ에서는 Gemini API 키를 안전하게 보호하기 위한 몇 가지 권장사항을 설명합니다.

모바일 또는 웹 앱에서 Gemini Developer API를 직접 호출하는 경우:

• Firebase AI Logic 클라이언트 SDK를 사용합니다.
• Gemini API 키를 앱의 코드베이스에 추가하지 마세요.

Firebase AI Logic는 Gemini Developer API에 대한 각 요청에 Gemini API 키를 내부적으로 포함하는 프록시 서비스를 제공합니다(완전히 백엔드에서).

또한 다음을 적극 권장합니다.

• 앱을 본격적으로 개발하기 시작하면 Firebase App Check와 통합하여 백엔드 리소스와 생성형 모델에 액세스하는 데 사용되는 API를 보호하세요.

• Firebase에서 생성된 Gemini API 키를 Firebase AI Logic 외부에서 재사용하지 마세요. 다른 사용 사례에 Gemini API 키가 필요한 경우 별도의 키를 만드세요.

• 일반적으로 Firebase에서 생성한 Gemini API 키는 수정하면 안 됩니다. 이 키는 Google Cloud 콘솔에서 Gemini Developer API 키 (Firebase에서 자동 생성)로 명명됩니다.

  • Firebase에서 생성한 Gemini API 키의 API 허용 목록에 추가 API를 추가하지 마세요. API 허용 목록에서 Gemini API 키에는 Gemini Developer API (Google Cloud 콘솔에서 'Generative Language API'라고 함)만 있어야 합니다.

  • 앱 제한사항을 추가하면 Firebase AI Logic 프록시 서비스가 예상대로 작동하지 않으므로 추가하지 않습니다.

내 Gemini API 키가 도용되었습니다. 어떤 조치를 취해야 하나요?

Gemini API 키가 손상된 경우 안내에 따라 Gemini Developer API를 호출하는 데 사용되는 Gemini API 키를 변경하세요.

또한 Gemini API 키를 안전하게 유지하기 위한 권장사항을 검토하세요.