Firebase AI Logic을 사용하여 하이브리드 추론으로 AI 기반 Android 앱과 기능을 빌드할 수 있습니다. 하이브리드 추론을 사용하면 기기 내 모델을 사용할 수 있는 경우 이를 사용하여 추론을 실행하고, 그렇지 않은 경우 클라우드 호스팅 모델로 원활하게 대체할 수 있습니다 (그 반대의 경우도 마찬가지).
이 페이지에서는 클라이언트 SDK를 시작하는 방법을 설명하고 온도와 같은 추가 구성 옵션 및 기능을 보여줍니다.
Firebase AI Logic를 통한 기기 내 추론은 특정 기기에서 실행되는 Android 앱에 지원되며 ML Kit 약관과 ML Kit의 생성형 AI 측면에 관한 약관의 적용을 받습니다.
권장 사용 사례 및 지원되는 기능
권장 사용 사례
추론을 위해 기기 내 모델을 사용하면 다음과 같은 이점이 있습니다.
- 개인 정보 보호 강화
- 로컬 컨텍스트
- 무료 추론
- 오프라인 기능
하이브리드 기능을 사용하면 다음과 같은 이점이 있습니다.
- 온디바이스 모델 사용 가능 여부와 인터넷 연결을 고려하여 더 많은 잠재고객에게 도달하세요.
온디바이스 추론에 지원되는 기능
온디바이스 추론은 스트리밍 또는 비스트리밍 출력을 사용하여 단일 턴 텍스트 생성 (채팅 아님)만 지원합니다. 다음과 같은 텍스트 생성 기능을 지원합니다.
텍스트 및 이미지 입력에서 텍스트 생성, 특히 단일 비트맵 이미지를 입력으로 사용
이 페이지 하단에서 아직 사용할 수 없는 온디바이스 추론 기능 목록을 검토하세요.
시작하기 전에
다음 사항에 유의합니다.
지원되는 API:
클라우드 내 추론은 선택한 Gemini API 제공자 (Gemini Developer API 또는 Vertex AI Gemini API)를 사용합니다.
기기별 추론은 베타 버전이며 특정 기기에서만 사용할 수 있는 ML Kit의 프롬프트 API를 사용합니다.
이 페이지에서는 시작하는 방법을 설명합니다.
이 표준 설정을 완료한 후 추가 구성 옵션 및 기능(예: 온도 설정)을 확인하세요.
지원되는 Android 기기 및 온디바이스 모델
기기별 추론 (ML Kit의 프롬프트 API 사용)의 경우 ML Kit 문서에서 지원되는 기기 및 기기별 모델 목록을 확인할 수 있습니다.
시작하기
이 시작하기 단계에서는 전송하려는 지원되는 프롬프트 요청에 필요한 일반 설정을 설명합니다.
1단계: Firebase 프로젝트 설정 및 앱을 Firebase에 연결
Firebase 콘솔에 로그인한 다음 Firebase 프로젝트를 선택합니다.
Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다.
시작하기를 클릭하여 프로젝트에 필요한 API 및 리소스를 설정하는 데 도움이 되는 안내 워크플로를 실행합니다.
'Gemini API' 제공업체를 사용하도록 프로젝트를 설정합니다.
Gemini Developer API을 사용하여 시작하는 것이 좋습니다. 언제든지 Vertex AI Gemini API를 설정(및 결제 요구사항)할 수 있습니다.
Gemini Developer API의 경우 콘솔에서 필요한 API를 사용 설정하고 프로젝트에 Gemini API 키를 만듭니다.
이 Gemini API 키를 앱의 코드베이스에 추가하지 마세요. 자세히 알아보기콘솔의 워크플로에서 메시지가 표시되면 화면에 표시된 안내에 따라 앱을 등록하고 Firebase에 연결합니다.
이 가이드의 다음 단계로 이동하여 앱에 SDK를 추가합니다.
2단계: 필수 SDK 추가
Firebase AI Logic Android용 SDK(firebase-aifirebase-ai-ondevice
모듈 (앱 수준) Gradle 파일(예: <project>/<app-module>/build.gradle.kts)에서 Android용 Firebase AI Logic 라이브러리의 종속 항목을 추가합니다.
Kotlin
dependencies { // ... other androidx dependencies // Add the dependencies for the Firebase AI Logic libraries // Note that the on-device SDK is not yet included in the Firebase Android BoM implementation("com.google.firebase:firebase-ai:17.10.0") implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01") }
Java
Java의 경우 두 개의 추가 라이브러리를 추가해야 합니다.
dependencies { // ... other androidx dependencies // Add the dependencies for the Firebase AI Logic libraries // Note that the on-device SDK is not yet included in the Firebase Android BoM implementation("com.google.firebase:firebase-ai:17.10.0") implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01") // Required for one-shot operations (to use `ListenableFuture` from Guava Android) implementation("com.google.guava:guava:31.0.1-android") // Required for streaming operations (to use `Publisher` from Reactive Streams) implementation("org.reactivestreams:reactive-streams:1.0.4") }
3단계: 온디바이스 모델이 사용 가능한지 확인
FirebaseAIOnDevice를 사용하여 온디바이스 모델이 사용 가능한지 확인하고 사용 불가능한 경우 모델을 다운로드합니다.
다운로드되면 AICore에서 모델을 자동으로 업데이트합니다. 스니펫 뒤에 나오는 메모에서 AICore 및 온디바이스 모델 다운로드 관리에 관해 자세히 알아보세요.
Kotlin
val status = FirebaseAIOnDevice.checkStatus()
when (status) {
OnDeviceModelStatus.UNAVAILABLE -> {
Log.w(TAG, "On-device model is unavailable")
}
OnDeviceModelStatus.DOWNLOADABLE -> {
FirebaseAIOnDevice.download().collect { status ->
when (status) {
is DownloadStatus.DownloadStarted ->
Log.w(TAG, "Starting download - ${status.bytesToDownload}")
is DownloadStatus.DownloadInProgress ->
Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")
is DownloadStatus.DownloadCompleted ->
Log.w(TAG, "On-device model download complete")
is DownloadStatus.DownloadFailed ->
Log.e(TAG, "Download failed ${status}")
}
}
}
OnDeviceModelStatus.DOWNLOADING -> {
Log.w(TAG, "On-device model is being downloaded")
}
OnDeviceModelStatus.AVAILABLE -> {
Log.w(TAG, "On-device model is available")
}
}
Java
Checking for and downloading the model is not yet available for Java.
However, all other APIs and interactions in this guide are available for Java.
온디바이스 모델 다운로드와 관련하여 다음 사항에 유의하세요.
온디바이스 모델을 다운로드하는 데 걸리는 시간은 네트워크를 비롯한 여러 요인에 따라 달라집니다.
코드가 기본 또는 대체 추론에 온디바이스 모델을 사용하는 경우 최종 사용자가 앱에서 코드를 접하기 전에 온디바이스 모델을 사용할 수 있도록 앱의 수명 주기 초기에 모델을 다운로드해야 합니다.
온디바이스 추론 요청이 이루어질 때 온디바이스 모델을 사용할 수 없는 경우 SDK는 온디바이스 모델의 다운로드를 자동으로 트리거하지 않습니다. SDK는 클라우드 호스팅 모델로 대체되거나 예외를 발생시킵니다 (추론 모드의 동작에 관한 세부정보 참고).
AICore(Android 시스템 서비스)는 다운로드되는 모델과 버전을 관리하고 모델을 업데이트하는 등의 작업을 실행합니다. 기기에는 하나의 모델만 다운로드되므로 기기의 다른 앱이 이전에 온디바이스 모델을 성공적으로 다운로드한 경우 이 검사에서는 모델이 사용 가능하다고 반환합니다.
지연 시간 최적화
첫 번째 추론 호출을 위해 최적화하려면 앱에서 warmup()를 호출하면 됩니다.
이렇게 하면 온디바이스 모델이 메모리에 로드되고 런타임 구성요소가 초기화됩니다.
4단계: 서비스 초기화 및 모델 인스턴스 생성
|
Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠와 코드를 확인합니다. |
모델에 프롬프트 요청을 보내기 전에 다음을 설정하세요.
선택한 API 제공업체의 서비스를 초기화합니다.
GenerativeModel인스턴스를 만들고mode을 다음 중 하나로 설정합니다. 여기에서는 매우 상위 수준으로 설명하지만 추론 모드 설정에서 이러한 모드의 동작에 관한 세부정보를 확인할 수 있습니다.PREFER_ON_DEVICE: 온디바이스 모델을 사용하려고 시도합니다. 그렇지 않으면 클라우드 호스팅 모델로 대체합니다.ONLY_ON_DEVICE: 온디바이스 모델을 사용하려고 시도합니다. 그렇지 않으면 예외를 발생시킵니다.PREFER_IN_CLOUD: 클라우드 호스팅 모델을 사용하려고 시도합니다. 그렇지 않으면 온디바이스 모델로 대체합니다.ONLY_IN_CLOUD: 클라우드 호스팅 모델을 사용하려고 시도합니다. 그렇지 않으면 예외를 발생시킵니다.
Kotlin
// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)
// ...
// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
.generativeModel(
modelName = "MODEL_NAME",
onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
)
Java
// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
.generativeModel(
"MODEL_NAME",
new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
);
// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);
5단계: 모델에 프롬프트 요청 보내기
이 섹션에서는 다음과 같은 다양한 유형의 출력을 생성하기 위해 다양한 유형의 입력을 전송하는 방법을 보여줍니다.
텍스트 전용 입력에서 텍스트 생성
| 이 샘플을 시도하기 전에 이 가이드의 시작하기 섹션을 완료해야 합니다. |
generateContent()를 사용하여 텍스트가 포함된 프롬프트에서 텍스트를 생성할 수 있습니다.
Kotlin
// Imports + initialization of Gemini API backend service + creation of model instance
// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."
// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)
Java
// Imports + initialization of Gemini API backend service + creation of model instance
// Provide a prompt that contains text
Content prompt = new Content.Builder()
.addText("Write a story about a magic backpack.")
.build();
// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
@Override
public void onSuccess(GenerateContentResponse result) {
String resultText = result.getText();
System.out.println(resultText);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
Firebase AI Logic은 generateContent 대신 generateContentStream을 사용하여 텍스트 응답 스트리밍도 지원합니다.
텍스트 및 이미지 (멀티모달) 입력에서 텍스트 생성
| 이 샘플을 시도하기 전에 이 가이드의 시작하기 섹션을 완료해야 합니다. |
generateContent()를 사용하여 텍스트와 최대 하나의 이미지 파일(비트맵만 해당)이 포함된 프롬프트에서 텍스트를 생성할 수 있습니다. 각 입력 파일의 mimeType 및 파일 자체를 제공하면 됩니다.
Kotlin
// Imports + initialization of Gemini API backend service + creation of model instance
// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)
// Provide a prompt that includes the image specified above and text
val prompt = content {
image(bitmap)
text("What developer tool is this mascot from?")
}
// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)
Java
// Imports + initialization of Gemini API backend service + creation of model instance
Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);
// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
.addImage(bitmap)
.addText("What developer tool is this mascot from?")
.build();
// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
@Override
public void onSuccess(GenerateContentResponse result) {
String resultText = result.getText();
System.out.println(resultText);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
Firebase AI Logic은 generateContent 대신 generateContentStream을 사용하여 텍스트 응답 스트리밍도 지원합니다.
또 뭘 할 수 있어?
하이브리드 환경에 다양한 추가 구성 옵션과 기능을 사용할 수 있습니다.
아직 온디바이스 추론에 사용할 수 없는 기능
실험적 출시이므로 클라우드 모델의 모든 기능을 온디바이스 추론에 사용할 수 있는 것은 아닙니다.
이 섹션에 나열된 기능은 아직 온디바이스 추론에 사용할 수 없습니다. 이러한 기능을 사용하려면 일관된 환경을 위해 ONLY_IN_CLOUD 추론 모드를 사용하는 것이 좋습니다.
구조화된 출력 (예: JSON 또는 열거형) 생성
비트맵(메모리에 로드된 이미지) 이외의 이미지 파일 입력 유형에서 텍스트 생성
두 개 이상의 이미지 파일에서 텍스트 생성
오디오, 동영상, 문서 (예: PDF) 입력에서 텍스트 생성
Gemini 또는 Imagen 모델을 사용하여 이미지 생성
멀티모달 요청에서 URL을 사용하여 파일 제공 온디바이스 모델에 인라인 데이터로 파일을 제공해야 합니다.
4,000개 토큰(또는 약 3,000개의 영단어)을 초과하는 요청을 전송합니다.
멀티턴 채팅
모델이 대답을 생성하는 데 도움이 되는 도구 제공(예: 함수 호출, 코드 실행, URL 컨텍스트, Google 검색으로 그라운딩)
Firebase 콘솔의 AI 모니터링에는 온디바이스 추론 (온디바이스 로그 포함) 데이터가 표시되지 않습니다. 하지만 클라우드 호스팅 모델을 사용하는 추론은 Firebase AI Logic를 통해 다른 추론과 마찬가지로 모니터링할 수 있습니다.
추가 제한사항
위의 내용 외에도 기기 내 추론에는 다음과 같은 제한사항이 있습니다 (자세한 내용은 ML Kit 문서 참고).
앱의 최종 사용자는 온디바이스 추론을 위해 지원되는 기기를 사용해야 합니다.
앱은 포그라운드에 있을 때만 온디바이스 추론을 실행할 수 있습니다.
영어와 한국어만 온디바이스 추론에 대해 검증되었습니다.
전체 온디바이스 추론 요청의 최대 토큰 한도는 4,000개입니다. 요청이 이 한도를 초과할 수 있는 경우 클라우드 호스팅 모델을 사용할 수 있는 추론 모드를 구성해야 합니다.
긴 출력 (256개 이상의 토큰)이 필요한 온디바이스 추론 사용 사례는 피하는 것이 좋습니다.
AICore(온디바이스 모델을 관리하는 Android 시스템 서비스)는 앱별 추론 할당량을 적용합니다. 단기간에 너무 많은 API 요청을 하면
ErrorCode.BUSY응답이 발생합니다. 이 오류가 표시되면 지수 백오프를 사용하여 요청을 재시도하는 것이 좋습니다. 또한 앱이 장기 할당량 (예: 일일 할당량)을 초과하는 경우ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED이 반환될 수 있습니다.
Firebase AI Logic 사용 경험에 관한 의견 보내기