FAQ 및 문제 해결

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

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

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

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

이전 가이드를 확인하여 Firebase AI Logic의 모든 최신 기능을 사용하고 (원하는 경우 Gemini Developer API 사용 시작)

Gemini Developer API와 Vertex AI Gemini API의 사용 간에 어떤 차이가 있나요?

다음은 두 'Gemini API' 제공업체 간에 일반적으로 액세스 방법과 관계없이 차이가 있는 몇 가지 사항입니다.

• 가격 책정

  • Gemini Developer API는 종량 요금제와 함께 '무료 등급'을 제공합니다.

  • Firebase AI Logic와 함께 사용할 때 Vertex AI Gemini API에는 항상 사용한 만큼만 지불하는 Blaze 요금제가 필요합니다.

  두 API 제공업체의 일회성 요금은 다릅니다(각각의 문서에서 자세히 알아보기).

• 비율 한도 (할당량)

  • Gemini Developer API에는 명시적인 비율 제한이 있습니다.

  • Vertex AI Gemini API는 해당 리전에서 해당 모델을 사용하는 모든 사용자가 공유하는 '동적 공유 할당량 (DSQ)'을 사용합니다. 원하는 경우 프로비저닝된 처리량 (PT)을 설정할 수도 있습니다.

• 모델에 액세스할 위치 지정

  • Vertex AI Gemini API만 모델에 액세스할 위치를 선택할 수 있습니다.

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

¹ Gemini Developer API의 Files 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 콘솔에서 Firebase AI Logic 페이지로 이동합니다.

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

3. Gemini Developer API를 시작하려면 선택합니다.

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

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

• 미리보기 및 실험 버전을 포함하여 Firebase AI Logic SDK와 함께 Gemini 및 Imagen 3 기반 모델을 사용할 수 있습니다. 지원되는 모델 알아보기에서 이러한 모델 목록을 확인하세요.

• Firebase AI Logic SDK에서는 기반이 아닌 Gemini 모델(예: PaLM 모델, 조정된 모델, Gemma 기반 모델)을 사용할 수 없습니다.

  또한 Firebase AI Logic는 이전 Imagen 모델 또는 imagen-3.0-capability-001를 지원하지 않습니다.

• Gemini Developer API는 액세스 방식과 관계없이 imagen-3.0-fast-generate-001 또는 이전 imagen-3.0-generate-001를 지원하지 않습니다.

Google에서는 SDK에 새로운 기능을 자주 추가하므로 출시 노트, 블로그, 소셜 게시물뿐만 아니라 이 FAQ에서 업데이트를 확인하세요.

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

안정화된 모델 버전을 출시할 때는 최소 1년 동안 사용할 수 있도록 노력하고 있습니다. 이 '지원 중단일'은 Firebase 및 Google Cloud 문서의 여러 위치에 나열되어 있습니다 (예: '모델' 페이지).

모델이 지원 중단되면 해당 모델에 대한 모든 요청이 404 오류와 함께 실패합니다. 따라서 새 버전의 앱을 출시하지 않고도 앱의 모델과 버전을 동적으로 변경할 수 있도록 Firebase Remote Config를 설정하고 사용하는 것이 좋습니다.

새 모델 버전을 사용하도록 앱을 업데이트할 때는 앱을 테스트하여 응답이 여전히 예상대로 작동하는지 확인하는 것이 좋습니다. Firebase AI Logic를 사용할 때는 실제로 모델을 호출하는 코드를 수정할 필요가 일반적으로 없습니다.

다음은 다양한 모델의 지원 중단 날짜입니다.

• 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일)

사용자당 비율 한도는 어떻게 설정하나요?

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

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

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

Firebase AI Logic SDK를 사용하려면 어떤 권한이 필요한가요?

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

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

멀티모달 요청에 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 검색을 통한 그라운딩, 코드 실행, 모델 미세 조정, 임베딩 생성, 시맨틱 검색은 다양한 모델 또는 Vertex AI Gemini API에서 지원되지만 Firebase AI Logic를 사용할 때는 사용할 수 없습니다.

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

Gemini API 키란 무엇인가요?

Gemini Developer API는 'Gemini API 키'를 사용하여 호출자를 승인합니다. 따라서 Firebase AI Logic SDK를 통해 Gemini Developer API를 사용하는 경우 Firebase 프로젝트에 유효한 Gemini API 키가 있어야 이 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 키와 직접 상호작용하지는 않습니다. 대신 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를 가리키는 용어로 'Generative Language 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 키를 통해 승인되므로 Gemini Developer API (Google Cloud 콘솔에서는 'Generative Language API'라고 함)를 Firebase API 키의 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 키를 안전하게 보호하기 위한 권장사항을 검토하세요.

404 오류를 해결하려면 어떻게 해야 하나요? Firebase AI Logic genai config not found

Gemini Developer API를 사용하려고 할 때 Firebase AI Logic genai config not found라는 404 오류가 표시되면 일반적으로 Firebase 프로젝트에 Firebase AI Logic 클라이언트 SDK와 함께 사용할 유효한 Gemini API 키가 없다는 의미입니다.

이 오류의 가장 유력한 원인은 다음과 같습니다.

• Gemini Developer API에 대한 Firebase 프로젝트를 아직 설정하지 않았습니다.

  수행할 작업:
  Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다. 시작하기를 클릭한 다음 Gemini Developer API를 선택합니다. API를 사용 설정하면 콘솔에서 Gemini Developer API용 프로젝트를 설정합니다. 워크플로를 완료한 후 요청을 다시 시도합니다.

• Firebase 콘솔에서 Firebase AI Logic 설정 워크플로를 아주 최근에 완료한 경우 모든 리전의 모든 필수 백엔드 서비스에서 아직 Gemini API 키를 사용할 수 없을 수 있습니다.

  해결 방법:
  몇 분 정도 기다린 후 다시 요청해 보세요.

• Firebase 프로젝트에서 Gemini API 키가 삭제되었을 수 있습니다.

  조치:
  Firebase AI Logic에서 사용하는 Gemini API 키를 변경하는 방법을 알아봅니다.

400 오류를 해결하려면 어떻게 해야 하나요? Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Cloud Storage for Firebase URL을 사용하여 다중 모드 요청을 전송하려고 하면 다음과 같은 400 오류가 발생할 수 있습니다.
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

이 오류는 프로젝트에서 Vertex AI API가 사용 설정되었을 때 필요한 서비스 에이전트가 올바르게 자동 프로비저닝되지 않은 프로젝트로 인해 발생합니다. 이는 일부 프로젝트에서 알려진 문제이며 전 세계적으로 해결하기 위해 노력하고 있습니다.

다음은 프로젝트를 수정하고 이러한 서비스 에이전트를 올바르게 프로비저닝하여 멀티모달 요청에 Cloud Storage for Firebase URL을 포함할 수 있는 해결 방법입니다. 프로젝트의 소유자여야 하며 이 작업 세트는 프로젝트에 대해 한 번만 완료하면 됩니다.

1. gcloud CLI로 액세스하고 인증합니다.
   가장 쉬운 방법은 Cloud Shell에서 하는 것입니다. Google Cloud 문서에서 자세히 알아보세요.

2. 메시지가 표시되면 터미널에 표시된 안내에 따라 gcloud CLI를 Firebase 프로젝트에 대해 실행합니다.

   Firebase 프로젝트 ID가 필요합니다. Firebase Console의 settings 프로젝트 설정 상단에서 확인할 수 있습니다.

3. 다음 명령어를 실행하여 프로젝트에 필요한 서비스 에이전트를 프로비저닝합니다.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. 서비스 에이전트가 프로비저닝될 때까지 몇 분 정도 기다린 후 Cloud Storage for Firebase URL이 포함된 멀티모달 요청을 다시 전송합니다.

몇 분 후에도 이 오류가 계속 발생하면 Firebase 지원팀에 문의하세요.

400 오류를 해결하려면 어떻게 해야 하나요? API key not valid. Please pass a valid API key.

API key not valid. Please pass a valid API key.라는 400 오류가 표시되면 일반적으로 Firebase 구성 파일/객체의 API 키가 없거나 앱 또는 Firebase 프로젝트와 함께 사용하도록 설정되지 않았음을 의미합니다.

Firebase 구성 파일/객체에 나열된 API 키가 앱의 API 키와 일치하는지 확인합니다. Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 모든 API 키를 볼 수 있습니다.

일치하지 않는 경우 새 Firebase 구성 파일/객체를 가져온 후 앱에 있는 구성 파일/객체를 대체합니다. 새 구성 파일/객체에는 앱 및 Firebase 프로젝트의 유효한 API 키가 포함되어야 합니다.

403 오류를 해결하려면 어떻게 해야 하나요? Requests to this API firebasevertexai.googleapis.com ... are blocked.

Requests to this API firebasevertexai.googleapis.com ... are blocked.라는 403 오류가 표시되면 일반적으로 Firebase 구성 파일/객체의 API 키에 사용하려는 제품의 허용 목록에 필수 API가 없음을 의미합니다.

앱에서 사용하는 API 키에 키의 'API 제한사항' 허용 목록에 포함된 필수 API가 모두 있는지 확인합니다. Firebase AI Logic의 경우 API 키의 허용 목록에 최소한 Firebase AI Logic API가 있어야 합니다.

Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 모든 API 키를 볼 수 있습니다.

403 오류를 해결하려면 어떻게 해야 하나요? PERMISSION_DENIED: The caller does not have permission.

PERMISSION_DENIED: The caller does not have permission.라는 403 오류가 표시되면 일반적으로 Firebase 구성 파일/객체의 API 키가 다른 Firebase 프로젝트에 속한다는 의미입니다.

Firebase 구성 파일/객체에 나열된 API 키가 앱의 API 키와 일치하는지 확인합니다. Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 모든 API 키를 볼 수 있습니다.

일치하지 않는 경우 새 Firebase 구성 파일/객체를 가져온 후 앱에 있는 구성 파일/객체를 대체합니다. 새 구성 파일/객체에는 앱 및 Firebase 프로젝트의 유효한 API 키가 포함되어야 합니다.