이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Firebase SDK의 Vertex AI 프리뷰 버전에서 Firebase AI 로직 SDK로 이전

Firebase AI Logic 및 클라이언트 SDK의 이전 이름은 'Vertex AI in Firebase'입니다. 확장된 서비스와 기능(예: 이제 Gemini Developer API 지원)을 더 잘 반영하기 위해 서비스의 이름을 Firebase AI Logic로 변경하고 다시 패키징했습니다.

이제 모바일 또는 웹 앱에서 직접 Google의 생성형 AI 모델에 안전하게 액세스하려면 오래전부터 제공된 Vertex AI Gemini API 또는 새로 출시된 Gemini Developer API 중에서 'Gemini API' 제공업체를 선택할 수 있습니다. 이제 합리적인 비율 제한과 할당량이 있는 무료 등급을 제공하는 Gemini Developer API를 사용할 수 있습니다.

Firebase AI Logic SDK로 이전하는 단계 개요

1단계: 앱 및 사용 사례에 가장 적합한 'Gemini API' 제공업체를 선택합니다.
2단계: 필요한 API를 사용 설정합니다.
3단계: 앱에서 사용되는 라이브러리를 업데이트합니다.
4단계: 앱에서 초기화 업데이트
5단계: 사용하는 기능에 따라 코드를 업데이트합니다.

1단계: 앱에 가장 적합한 'Gemini API' 제공업체 선택

이 마이그레이션을 통해 'Gemini API' 제공업체를 선택할 수 있습니다.

이전 'Vertex AI in Firebase' SDK는 Vertex AI Gemini API만 사용할 수 있었습니다.
새로운 Firebase AI Logic SDK를 사용하면 모바일 또는 웹 앱에서 직접 호출할 'Gemini API' 제공업체(Gemini Developer API 또는 Vertex AI Gemini API)를 선택할 수 있습니다.

지원되는 기능, 가격, 비율 제한 측면에서 두 Gemini API 제공업체 사용 간의 차이점을 검토하세요. 한 가지 예로 Gemini Developer API는 Cloud Storage URL을 사용하여 파일을 제공하는 것을 지원하지 않지만, 무료 등급과 적절한 할당량을 활용하려는 경우에 적합할 수 있습니다.

2단계: 필수 API 사용 설정

선택한 'Gemini API' 제공업체를 사용하려면 Firebase 프로젝트에서 필요한 모든 API가 사용 설정되어 있어야 합니다.

프로젝트에서 두 API 제공자를 동시에 사용 설정할 수 있습니다.

Firebase 콘솔에 로그인한 다음 Firebase 프로젝트를 선택합니다.
Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다.
시작하기를 클릭하여 프로젝트에 필요한 API와 리소스를 설정하는 데 도움이 되는 안내 워크플로를 실행합니다.
Firebase AI Logic SDK와 함께 사용할 'Gemini API' 제공업체를 선택합니다. 원하는 경우 나중에 언제든지 다른 API 제공업체를 설정하고 사용할 수 있습니다.
- Gemini Developer API - 결제 선택사항 (무료 Spark 요금제에서 사용 가능)
  콘솔의 워크플로를 통해 필수 API를 사용 설정하고 프로젝트에 Gemini API 키를 만듭니다.
  이 Gemini API 키를 앱의 코드베이스에 추가하지 마세요. 자세히 알아보기
- Vertex AI Gemini API — 결제 필요 (사용한 만큼만 지불하는 Blaze 요금제 필요)
  콘솔의 워크플로를 통해 프로젝트에서 필요한 API를 사용 설정합니다.
이 이전 가이드에 따라 앱에서 라이브러리와 초기화를 업데이트합니다.

3단계: 앱에서 사용되는 라이브러리 업데이트

Firebase AI Logic 라이브러리를 사용하도록 앱의 코드베이스를 업데이트합니다.

Swift

앱 프로젝트를 연 상태로 Xcode에서 다음 옵션 중 하나를 사용하여 Firebase 패키지를 v11.13.0 이상으로 업데이트합니다.
- 옵션 1: 모든 패키지 업데이트: 파일 > 패키지 > 최신 패키지 버전으로 업데이트로 이동합니다.
- 옵션 2: Firebase를 개별적으로 업데이트합니다. 패키지 종속 항목 섹션에서 Firebase 패키지로 이동합니다. Firebase 패키지를 마우스 오른쪽 버튼으로 클릭한 다음 패키지 업데이트를 선택합니다.
Firebase 패키지가 이제 v11.13.0 이상으로 표시되는지 확인합니다. 그렇지 않은 경우 지정된 패키지 요구사항이 v11.13.0 이상으로 업데이트를 허용하는지 확인합니다.
프로젝트 편집기에서 앱의 타겟을 선택한 다음 프레임워크, 라이브러리, 삽입된 콘텐츠 섹션으로 이동합니다.
새 라이브러리 추가: + 버튼을 선택한 다음 Firebase 패키지에서 FirebaseAI를 추가합니다.
앱 마이그레이션을 완료한 후 (이 가이드의 나머지 섹션 참고) 이전 라이브러리를 삭제해야 합니다.
FirebaseVertexAI-Preview를 선택한 다음 — 버튼을 누릅니다.

Kotlin

모듈 (앱 수준) Gradle 파일 (일반적으로 <project>/<app-module>/build.gradle.kts 또는 <project>/<app-module>/build.gradle)에서 이전 종속 항목(해당하는 경우)을 다음으로 바꿉니다.

이전 종속 항목을 삭제하기 전에 앱의 코드베이스를 이전하는 것이 더 쉬울 수 있습니다 (이 가이드의 나머지 섹션 참고).

// BEFORE
dependencies {
  implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
}


// AFTER
dependencies {
  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:33.16.0"))

  // Add the dependency for the Firebase AI Logic library
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
}

Android 프로젝트를 Gradle 파일과 동기화합니다.

Firebase Android BoM를 사용하지 않으려면 firebase-ai 라이브러리의 종속 항목을 추가하고 Android 스튜디오에서 제안하는 최신 버전을 수락하면 됩니다.

Java

이전 종속 항목을 삭제하기 전에 앱의 코드베이스를 이전하는 것이 더 쉬울 수 있습니다 (이 가이드의 나머지 섹션 참고).

// BEFORE
dependencies {
  implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
}


// AFTER
dependencies {
  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:33.16.0"))

  // Add the dependency for the Firebase AI Logic library
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
}

Android 프로젝트를 Gradle 파일과 동기화합니다.

Firebase Android BoM를 사용하지 않으려면 firebase-ai 라이브러리의 종속 항목을 추가하고 Android 스튜디오에서 제안하는 최신 버전을 수락하면 됩니다.

Web

npm을 사용하여 웹용 Firebase JS SDK의 최신 버전을 가져옵니다.
```
npm i firebase@latest
```
또는
```
yarn add firebase@latest
```
라이브러리를 가져온 곳에서는 firebase/ai를 대신 사용하도록 가져오기 문을 업데이트합니다.

이 가이드의 나머지 섹션을 참고하여 이전 가져오기를 삭제하기 전에 앱의 코드베이스를 이전하는 것이 더 쉬울 수 있습니다.
```
// BEFORE
import { initializeApp } from "firebase/app";
import { getVertexAI, getGenerativeModel } from "firebase/vertexai-preview";


// AFTER
import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel } from "firebase/ai";
```

Dart

Flutter 프로젝트 디렉터리에서 다음 명령어를 실행하여 pubspec.yaml 파일에서 firebase_ai 패키지를 사용하도록 업데이트합니다.
```
flutter pub add firebase_ai
```
Flutter 프로젝트를 다시 빌드합니다.
```
flutter run
```
앱 이전을 완료한 후 (이 가이드의 나머지 섹션 참고) 이전 패키지를 삭제해야 합니다.
```
flutter pub remove firebase_vertexai
```

Unity

'Vertex AI in Firebase'에서는 Unity 지원을 사용할 수 없습니다.

Unity용 Firebase AI Logic SDK 시작하기를 알아보세요.

4단계: 앱에서 초기화 업데이트

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠와 코드를 확인합니다.

선택한 API 제공업체의 서비스를 초기화하는 방법을 업데이트하고 GenerativeModel 인스턴스를 만듭니다.

Swift


import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(modelName: "gemini-2.5-flash")

Kotlin


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .generativeModel("gemini-2.5-flash")

Java


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-2.5-flash");

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(ai, { model: "gemini-2.5-flash" });

Dart


import 'package:firebase_ai/firebase_ai.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model =
      FirebaseAI.googleAI().generativeModel(model: 'gemini-2.5-flash');

Unity

'Vertex AI in Firebase'에서는 Unity 지원을 제공하지 않습니다.

Unity용 Firebase AI Logic SDK 시작하기를 알아보세요.

사용하는 기능에 따라 GenerativeModel 인스턴스를 항상 생성하지는 않을 수 있습니다.

Imagen 모델에 액세스하려면 ImagenModel 인스턴스를 만드세요.

5단계: 사용하는 기능에 따라 코드 업데이트

이 단계에서는 사용하는 기능에 따라 필요할 수 있는 변경사항을 설명합니다.

Cloud Storage URL을 사용하고 이 마이그레이션에서 Gemini Developer API를 사용하도록 전환한 경우 멀티모달 요청을 업데이트하여 파일을 인라인 데이터로 포함해야 합니다(또는 동영상에 YouTube URL 사용).
'Vertex AI in Firebase' SDK의 GA 버전에 몇 가지 변경사항이 도입되었습니다. Firebase AI Logic SDK를 사용하려면 동일한 변경사항이 필요합니다. Firebase AI Logic SDK를 수용하기 위해 코드에서 변경해야 할 사항이 있는지 다음 목록을 검토하세요.

모든 언어 및 플랫폼에 필요

함수 호출
GA 전에 이 기능을 구현한 경우 스키마를 정의하는 방식을 업데이트해야 합니다. 업데이트된 함수 호출 가이드를 검토하여 함수 선언을 작성하는 방법을 알아보는 것이 좋습니다.
responseSchema를 사용하여 구조화된 출력 (예: JSON) 생성
GA 전에 이 기능을 구현한 경우 스키마를 정의하는 방식을 업데이트해야 합니다. 새로운 구조화된 출력 가이드를 검토하여 JSON 스키마를 작성하는 방법을 알아보는 것이 좋습니다.
제한 시간
- 요청의 기본 제한 시간을 180초로 변경했습니다.

플랫폼 또는 언어에 따라 필요

Swift

열거형
- 대부분의 enum 유형을 정적 변수가 있는 struct로 대체했습니다. 이 변경사항을 통해 하위 호환 방식으로 API를 발전시킬 수 있는 유연성이 향상됩니다. 이제 switch 문을 사용할 때는 향후 SDK에 추가될 새 값을 비롯해 알 수 없거나 처리되지 않은 값을 포함하는 default: 사례를 포함해야 합니다.
- BlockThreshold 열거형의 이름을 HarmBlockThreshold로 변경했습니다. 이 유형은 이제 struct입니다.
- 다음 열거형 (이제 struct)에서 unknown 및 unspecified 사례가 삭제되었습니다. HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason, FinishReason
- 새 유형을 하위 호환 방식으로 추가할 수 있도록 열거형 ModelContent.Part을 Part이라는 프로토콜로 대체했습니다. 이 변경사항은 콘텐츠 파트 섹션에 자세히 설명되어 있습니다.
콘텐츠 파트
- ThrowingPartsRepresentable 프로토콜을 삭제하고 ModelContent의 이니셜라이저를 간소화하여 가끔 발생하는 컴파일러 오류를 방지했습니다. 올바르게 인코딩되지 않은 이미지는 generateContent에서 사용될 때 여전히 오류가 발생합니다.
- ModelContent.Part 사례를 Part 프로토콜을 준수하는 다음 struct 유형으로 대체했습니다.
  - .text~TextPart
  - .data~InlineDataPart
  - .fileData~FileDataPart
  - .functionCall~FunctionCallPart
  - .functionResponse~FunctionResponsePart
유해 카테고리
- HarmCategory이 더 이상 SafetySetting 유형에 중첩되지 않도록 변경했습니다. SafetySetting.HarmCategory라고 하는 경우 HarmCategory로 바꿀 수 있습니다.
안전 관련 의견
- SafetyFeedback 유형은 대답에 사용되지 않았으므로 삭제했습니다.
인용 메타데이터
- CitationMetadata에서 citationSources 속성의 이름이 citations로 변경되었습니다.
총 청구 가능 문자 수
- 문자가 전송되지 않는 상황을 반영하기 위해 CountTokensResponse의 totalBillableCharacters 속성을 선택사항으로 변경했습니다.
후보자 응답
- 다른 플랫폼과 일치하도록 CandidateResponse의 이름이 Candidate로 변경되었습니다.
생성 구성
- GenerationConfig의 공개 속성을 internal로 변경했습니다. 모두 초기화 프로그램에서 구성할 수 있습니다.

Kotlin

열거형
- enum 클래스와 sealed 클래스를 일반 클래스로 대체했습니다. 이 변경사항을 통해 역호환 방식으로 API를 발전시킬 수 있는 유연성이 향상됩니다.
- BlockThreshold 열거형의 이름을 HarmBlockThreshold로 변경했습니다.
- HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason, FinishReason 열거형에서 값이 삭제되었습니다.
Blob 메서드
- 이름에 Blob이 포함된 모든 메서드의 이름을 InlineData을 사용하도록 변경했습니다.
안전 설정
- method 필드를 null 허용으로 변경했습니다.
Duration 클래스
- Kotlin의 Duration 클래스의 모든 사용을 삭제하고 long로 대체했습니다. 이 변경사항은 Java와의 상호 운용성을 개선합니다.
인용 메타데이터
- 이전에 CitationMetadata에 선언된 모든 필드를 Citation이라는 새 클래스로 래핑했습니다. 인용은 CitationMetadata의 citations 목록에서 확인할 수 있습니다. 이 변경사항을 통해 플랫폼 전반에서 유형을 더 잘 정렬할 수 있습니다.
토큰 수 계산
- totalBillableCharacters 필드를 null 허용으로 변경했습니다.
총 청구 가능 문자 수
- 문자가 전송되지 않는 상황을 반영하기 위해 CountTokensResponse의 totalBillableCharacters 속성을 선택사항으로 변경했습니다.
모델 인스턴스화
- 다른 플랫폼과 일치하도록 requestOptions 매개변수를 매개변수 목록의 끝으로 이동했습니다.
Live API
- enum 클래스 ResponseModality의 UNSPECIFIED 값을 삭제했습니다. 대신 null을 사용하세요.
- LiveGenerationConfig.setResponseModalities의 이름이 LiveGenerationConfig.setResponseModality로 변경되었습니다.
- LiveContentResponse.Status 클래스를 삭제하고 대신 상태 필드를 LiveContentResponse의 속성으로 중첩했습니다.
- LiveContentResponse 클래스를 삭제하고 대신 모델의 응답과 일치하는 LiveServerMessage의 하위 클래스를 제공했습니다.
- ListenableFuture<LiveSession> 대신 ListenableFuture<LiveSessionFutures>을 반환하도록 LiveModelFutures.connect를 변경했습니다.

Java

열거형
- enum 클래스와 sealed 클래스를 일반 클래스로 대체했습니다. 이 변경사항을 통해 역호환 방식으로 API를 발전시킬 수 있는 유연성이 향상됩니다.
- BlockThreshold 열거형의 이름을 HarmBlockThreshold로 변경했습니다.
- HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason, FinishReason 열거형에서 값이 삭제되었습니다.
Blob 메서드
- 이름에 Blob이 포함된 모든 메서드의 이름을 InlineData을 사용하도록 변경했습니다.
안전 설정
- method 필드를 null 허용으로 변경했습니다.
Duration 클래스
- Kotlin의 Duration 클래스의 모든 사용을 삭제하고 long로 대체했습니다. 이 변경사항은 Java와의 상호 운용성을 개선합니다.
인용 메타데이터
- 이전에 CitationMetadata에 선언된 모든 필드를 Citation이라는 새 클래스로 래핑했습니다. 인용은 CitationMetadata의 citations 목록에서 확인할 수 있습니다. 이 변경사항을 통해 플랫폼 전반에서 유형을 더 잘 정렬할 수 있습니다.
토큰 수 계산
- totalBillableCharacters 필드를 null 허용으로 변경했습니다.
총 청구 가능 문자 수
- 문자가 전송되지 않는 상황을 반영하기 위해 CountTokensResponse의 totalBillableCharacters 속성을 선택사항으로 변경했습니다.
모델 인스턴스화
- 다른 플랫폼과 일치하도록 requestOptions 매개변수를 매개변수 목록의 끝으로 이동했습니다.
Live API
- enum 클래스 ResponseModality의 UNSPECIFIED 값을 삭제했습니다. 대신 null을 사용하세요.
- LiveGenerationConfig.setResponseModalities의 이름이 LiveGenerationConfig.setResponseModality로 변경되었습니다.
- LiveContentResponse.Status 클래스를 삭제하고 대신 상태 필드를 LiveContentResponse의 속성으로 중첩했습니다.
- LiveContentResponse 클래스를 삭제하고 대신 모델의 응답과 일치하는 LiveServerMessage의 하위 클래스를 제공했습니다.
- ListenableFuture<LiveSession> 대신 ListenableFuture<LiveSessionFutures>을 반환하도록 LiveModelFutures.connect를 변경했습니다.
이제 다양한 Java 빌더 메서드가 void 대신 클래스의 인스턴스를 올바르게 반환하도록 변경했습니다.

Web

열거형
- HarmCategory, BlockThreshold, HarmProbability, HarmSeverity, BlockReason, FinishReason 열거형에서 값이 삭제되었습니다.
차단 이유
- PromptFeedback에서 blockReason을 선택사항으로 변경했습니다.

Vertex AI Gemini API 대신 Gemini Developer API을 사용하기 시작하는 경우에만 변경이 필요합니다.

안전 설정
- 지원되지 않는 SafetySetting.method의 사용 사례를 삭제했습니다.
인라인 데이터
- 지원되지 않는 InlineDataPart.videoMetadata의 사용 사례를 삭제했습니다.

Dart

열거형
- HarmCategory, HarmProbability, BlockReason, FinishReason 열거형에서 값이 삭제되었습니다.
데이터 부분
- 다른 플랫폼과의 일관성을 위해 DataPart의 이름이 InlineDataPart로, static data 함수의 이름이 inlineData로 변경되었습니다.
요청 옵션
- timeout이 작동하지 않으므로 RequestOptions를 삭제했습니다. 조만간 다시 추가될 예정이지만 다른 플랫폼과 일치하도록 GenerativeModel 유형으로 이동됩니다.
중지 시퀀스
- GenerationConfig의 stopSequences 매개변수를 선택사항으로 변경하고 빈 배열 대신 null로 기본 설정했습니다.
인용
- CitationMetadata에서 citationSources 속성의 이름이 citations로 변경되었습니다. 다른 플랫폼과 일치하도록 CitationSource 유형의 이름을 Citation로 변경했습니다.
불필요한 공개 유형, 메서드, 속성
- 의도치 않게 노출된 다음 유형, 메서드, 속성이 삭제되었습니다. defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest, EmbedContentResponse
토큰 수 계산
- 더 이상 필요하지 않은 countTokens 함수의 추가 필드가 삭제되었습니다. contents만 있으면 됩니다.
모델 인스턴스화
- 다른 플랫폼과 일치하도록 systemInstruction 매개변수를 매개변수 목록의 끝으로 이동했습니다.
삽입 기능
- 모델에서 지원되지 않는 삽입 기능 (embedContent 및 batchEmbedContents)이 삭제되었습니다.

Unity

'Vertex AI in Firebase'에서는 Unity 지원을 사용할 수 없습니다.

Unity용 Firebase AI Logic SDK 시작하기를 알아보세요.

이전과 관련된 발생 가능한 오류

Firebase AI Logic의 정식 버전을 사용하도록 마이그레이션할 때 이 마이그레이션 가이드에 설명된 필수 변경사항을 모두 완료하지 않으면 오류가 발생할 수 있습니다.

403 오류: `Requests to this API firebasevertexai.googleapis.com ... are blocked.`

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

앱에서 사용하는 Firebase API 키에 키의 'API 제한사항' 허용 목록에 포함된 필수 API가 모두 있는지 확인합니다. Firebase AI Logic의 경우 Firebase API 키의 허용 목록에 최소한 Firebase AI Logic API가 있어야 합니다. Firebase 콘솔에서 필수 API를 사용 설정하면 이 API가 API 키의 허용 목록에 자동으로 추가되었어야 합니다.

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

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

Firebase SDK의 Vertex AI 프리뷰 버전에서 Firebase AI 로직 SDK로 이전

Firebase AI Logic SDK로 이전하는 단계 개요

1단계: 앱에 가장 적합한 'Gemini API' 제공업체 선택

2단계: 필수 API 사용 설정

3단계: 앱에서 사용되는 라이브러리 업데이트

Swift

Kotlin

Java

Web

Dart

Unity

4단계: 앱에서 초기화 업데이트

Swift

Kotlin

Java

Web

Dart

Unity

5단계: 사용하는 기능에 따라 코드 업데이트

모든 언어 및 플랫폼에 필요

플랫폼 또는 언어에 따라 필요

Swift

Kotlin

Java

Web

Dart

Unity

이전과 관련된 발생 가능한 오류

403 오류: Requests to this API firebasevertexai.googleapis.com ... are blocked.

403 오류: `Requests to this API firebasevertexai.googleapis.com ... are blocked.`