オンデバイス モデルとクラウドホスト モデルを使用して Android アプリでハイブリッド エクスペリエンスを構築する


Firebase AI Logic を使用して、ハイブリッド推論を活用した AI 搭載の Android アプリや機能を構築できます。ハイブリッド推論を使用すると、利用可能な場合はオンデバイス モデルを使用して推論を実行し、利用できない場合はクラウドホスト型モデルにシームレスにフォールバックできます（逆も同様）。

このページでは、クライアント SDK の使用を開始する方法について説明します。この標準設定を完了したら、追加の構成オプションと機能を確認してください。

Firebase AI Logic を介したオンデバイス推論は、Firebase AI Logic SDK v17.10.0 以降（BoM v34.10.0 以降）を使用し、特定のデバイスで実行されている Android アプリでサポートされています。これは、ML Kit の利用規約と、ML Kit の生成 AI 側面に固有の利用規約に準拠しています。

コードサンプルを表示する

ユースケースとサポートされている機能

アプリのユースケースに応じて、オンデバイス エクスペリエンスまたはハイブリッド エクスペリエンスのいくつかのメリットを活用できます。

  • 推論にオンデバイス モデルを使用するメリット:

    • プライバシーの強化
    • ローカル コンテキスト
    • 無料の推論
    • オフライン機能

  • ハイブリッド アプローチを使用するメリット:

    • エンドユーザーのデバイスに関係なく、同様のアプリ エクスペリエンスを提供する
    • インターネット接続、割り当て制限、デバイスの機能に関係なく、生成 AI 機能の可用性を向上させる

サポートされているオンデバイス推論機能

デバイス上の推論は、シングルターンのテキスト生成（チャットではない）（ストリーミング出力または非ストリーミング出力）のみをサポートしています。具体的には、次の機能がサポートされています。

このページの下部にある、ハイブリッド推論またはオンデバイス推論でまだサポートされていない機能のリストを確認してください。

サポートされている API とデバイス

以降のセクションでは、サポートされている API と、サポートされているデバイス（およびそのオンデバイス モデル）について説明します。

クラウド内推論とデバイス上推論でサポートされている API

サポートされている Android デバイスとオンデバイス モデル

オンデバイス推論（ML Kit の Prompt API を使用）の場合、サポートされているデバイスとそのオンデバイス モデルのリストについては、ML Kit のドキュメントをご覧ください。

始める

このスタートガイドでは、送信するサポート対象のプロンプト リクエストに必要な一般的な設定について説明します。

ステップ 1: Firebase プロジェクトを設定し、アプリを Firebase に接続する

  1. Firebase コンソールにログインし、Firebase プロジェクトを選択します。

  2. Firebase コンソールで、[AI サービス] > [AI Logic] に移動します。

  3. [開始] をクリックして、プロジェクトの必要な API とリソースの設定に役立つガイド付きワークフローを起動します。

  4. プロンプトが表示されたら、画面上の手順に沿ってアプリを登録し、Firebase 構成をアプリに追加します。

  5. 「Gemini API プロバイダ」を選択するよう求められた場合は、Gemini Developer API を選択することをおすすめします。これにより、費用をかけずにすぐに開始できます。

    後でいつでも、Agent Platform Gemini API (formerly Vertex AI) を設定できます（課金の要件も設定できます）。

  6. ワークフローを続行して、Firebase AI Logic に必要な API と関連サービスを設定します。

    ワークフローのこのステージでは、AI Logic の Firebase App Check が自動的に適用されます。これは、アプリから直接アクセスされたときに Gemini API を保護するのに役立つ重要なサービスです。開始手順の一環として（このガイドの後半の手順を参照）、App Check が適用されたときにローカル開発用の App Check デバッグ プロバイダを構成する必要があります。

  7. このガイドの次のステップに進み、必要な SDK をアプリに追加します。

ステップ 2: 必要な SDK を追加する

Firebase AI Logic SDK for Android（firebase-ai）と Firebase AI Logic On-Device SDK（firebase-ai-ondevice）を使用すると、生成モデルを操作するための API にアクセスできます。

モジュール（アプリレベル）の Gradle ファイル（<project>/<app-module>/build.gradle.kts など）に、Android 用 Firebase AI Logic ライブラリと App Check ライブラリの依存関係を追加します。

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

Java の場合は、2 つの追加ライブラリを追加する必要があります。

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

  // 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: ローカル開発用に App Check デバッグ プロバイダを構成する

コンソールの AI Logic のガイド付き設定ワークフローの一環として、Firebase App Check が自動的に適用され、Gemini API が保護されます。ローカル開発では、App Check の適用を維持しながら、App Check デバッグ プロバイダを構成して、証明書をバイパスする必要があります。

  1. デバッグビルドで、デバッグ プロバイダ Factory を使用するように App Check を構成します。

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. デバッグトークンを取得します。

    1. エミュレータまたはテストデバイスでアプリを実行します。

    2. ログで App Check デバッグ トークンを探します。例:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. トークン（例: 123a4567-b89c-12d3-e456-789012345678）をコピーします。

  3. デバッグ トークンを App Check に登録します。

    1. Firebase コンソールで、[セキュリティ] > [App Check] > [アプリ] タブに移動します。

    2. アプリを見つけて、オーバーフロー メニュー（）をクリックし、[デバッグ トークンを管理] を選択します。

    3. 画面上の手順に沿ってデバッグ トークンを登録します。

デバッグ プロバイダの詳細（新しいデバッグ トークンを取得する方法など）については、App Check の公式ドキュメントをご覧ください。

ステップ 4: オンデバイス モデルが利用可能かどうかを確認する

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, downloading, and warming up 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 システム サービス）は、ダウンロードされるモデルとバージョンを管理し、モデルを最新の状態に保ちます。デバイスにダウンロードされるモデルは 1 つだけです。デバイス上の別のアプリが以前にオンデバイス モデルを正常にダウンロードしている場合、このチェックではモデルが利用可能であることが返されます。

レイテンシの最適化

最初の推論呼び出しを最適化するには、アプリで onDeviceExtension?.warmUp() を呼び出します（現在は Kotlin でのみ使用可能）。これにより、オンデバイス モデルがメモリに読み込まれ、ランタイム コンポーネントが初期化されます。

ステップ 5: サービスを初期化してモデル インスタンスを作成する

Gemini API プロバイダをクリックして、このページでプロバイダ固有のコンテンツとコードを表示します。

モデルにプロンプト リクエストを送信する前に、次の設定を行います。

  1. 選択した API プロバイダのサービスを初期化します。

  2. 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 = "CLOUD_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(
        "CLOUD_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);

ステップ 6: モデルにプロンプト リクエストを送信する

このセクションでは、さまざまな種類の入力を送信して、次のようなさまざまな種類の出力を生成する方法について説明します。

構造化出力（JSON や列挙型など）を生成する場合は、次の「生成されたテキスト」の例のいずれかを使用し、さらに指定されたスキーマに従ってレスポンスを返すようにモデルを構成します。

テキストのみの入力からテキストを生成する

このサンプルを試す前に、このガイドのスタートガイドのセクションを完了していることを確認してください。

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() を使用すると、テキストと最大 1 つの画像ファイル（ビットマップのみ）を含むプロンプトから生成されたテキストを生成できます。各入力ファイルの 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 を使用したテキスト レスポンスのストリーミングもサポートしています。

Google アシスタントの機能

ハイブリッド エクスペリエンスには、さまざまな追加の構成オプションと機能を使用できます。

まだサポートされていない機能

試験運用版リリースであるため、クラウドホスト型モデルまたは Firebase AI Logic SDK のすべての機能がハイブリッド推論またはオンデバイス推論で使用できるわけではありません。

ハイブリッド実装でまだサポートされていない機能

次の機能は、ハイブリッド実装（オンデバイスでもクラウド フォールバック経由でも）では使用できません。

  • Gemini Live API: 双方向のリアルタイム ストリーミングはサポートされていません。

  • サーバー プロンプト テンプレート: マネージド サーバー プロンプト テンプレートはサポートされていません。

  • トークンをカウントする: トークンのカウントは、クラウドホスト型モデルとオンデバイス モデルで異なるため、カウントに依存しないでください。直感的なフォールバックはありません。

オンデバイス推論でまだサポートされていない機能

次の機能はオンデバイス推論ではまだサポートされていませんが、クラウドホスト型モデルでは利用できます。

  • 画像を生成しています

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • ビットマップ（メモリに読み込まれた画像）以外の画像ファイル入力タイプから生成されたテキストを生成する

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • 画像のみのファイル入力から生成されたテキストを生成する。オンデバイス推論の場合、マルチモーダル リクエストの一部としてテキストを指定する必要があります。

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • 複数の画像ファイル入力から生成されたテキストを生成する

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • 音声、動画、ドキュメント（PDF）のマルチモーダル入力からテキストを生成する

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • マルチモーダル リクエストで URL を使用してファイルを提供する。オンデバイス推論の場合は、1 つの画像をビットマップとして指定する必要があります。

    • fileData（FileDataPart）を使用してファイル URL を指定すると、クラウドホスト型モデルにフォールバックできます（ONLY_ON_DEVICE モードでは例外がスローされます）。
    • テキスト プロンプトに URL を直接埋め込んだ場合、クラウドホスト型モデルに自動的にフォールバックすることはありません（埋め込まれた URL はオンデバイス モデルによって無視されます）。

  • 4,000 トークン（約 3,000 英語単語）を超えるリクエストを送信する

    • クラウドホスト型モデルにフォールバックできますが、ONLY_ON_DEVICE モードでは例外がスローされます。

  • マルチターン チャット

    • クラウドホスト型モデルに自動的にフォールバックしない（オンデバイス推論では、プロンプト履歴が 1 つのテキスト プロンプトに連結されます。オンデバイス モデルはロールを区別せず、履歴を 1 つのメッセージとして認識するため、クラウドホスト型モデルほど正確ではありません）。
    • マルチターン チャットを使用する場合は、ONLY_IN_CLOUD モードを使用することをおすすめします。

  • レスポンスの生成に役立つツールをモデルに提供する（関数呼び出し、コード実行、URL コンテキスト、Google Search によるグラウンディング、Google Maps によるグラウンディングなど）

    • クラウドホスト型モデルに自動的にフォールバックしません。ツールを使用する場合は、ONLY_IN_CLOUD モードを使用することをおすすめします。

  • Firebase コンソールの AI モニタリングには、オンデバイス推論（オンデバイス ログを含む）のデータは表示されません。ただし、クラウドホスト型モデルを使用する推論は、Firebase AI Logic を介して他の推論と同様にモニタリングできます。

その他の制限

上記に加えて、オンデバイス推論には次の制限があります（詳しくは、ML Kit のドキュメントをご覧ください）。

  • アプリのエンドユーザーは、オンデバイス推論に対応しているデバイスを使用している必要があります。

  • アプリがフォアグラウンドにある場合にのみ、オンデバイス推論を実行できます。

  • オンデバイス推論で検証されているのは、英語と韓国語のみです。

  • オンデバイス推論リクエスト全体の上限は 4,000 トークンです。リクエストがこの上限を超える可能性がある場合は、クラウドホスト型モデルを使用できる推論モードを構成してください。

  • 長い出力（256 トークン以上）を必要とするオンデバイス推論のユースケースは避けることをおすすめします。

  • AICore（オンデバイス モデルを管理する Android システム サービス）は、アプリごとに推論割り当てを適用します。短期間に API リクエストを送信しすぎると、ErrorCode.BUSY レスポンスが返されます。このエラーが発生した場合は、指数バックオフを使用してリクエストを再試行することを検討してください。また、アプリが長期間の割り当て（1 日の割り当てなど）を超えた場合、ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED が返されることがあります。


Firebase AI Logic の使用感に関するフィードバックを送信する