オンデバイス モデルとクラウドホスト モデルを使用して 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 側面に固有の利用規約に準拠しています。

おすすめのユースケースとサポートされている機能

おすすめのユースケース

  • 推論にオンデバイス モデルを使用すると、次のメリットがあります。

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

  • ハイブリッド機能の特典を使用している場合:

    • オンデバイス モデルの可用性とインターネット接続に対応して、より多くのユーザーにリーチする

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

オンデバイス推論は、ストリーミング出力または非ストリーミング出力による単一ターンのテキスト生成（チャットではない）のみをサポートします。次のテキスト生成機能をサポートしています。

このページの下部にある、オンデバイス推論でまだ利用できない機能のリストを確認してください。

始める前に

次の点に注目してください。

  • サポートされている API:

    • クラウド内推論では、選択した Gemini API プロバイダ（Gemini Developer API または Agent Platform Gemini API (formerly Vertex AI)）を使用します。

    • オンデバイス推論では、ML Kit の Prompt 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 と関連サービスを設定します。

    2026 年 7 月上旬より、ワークフローのこのステージでは、アプリから直接アクセスされたときに Gemini API を保護するのに役立つ重要なサービスである AI Logic に対して Firebase App Check が自動的に適用されます。開始手順（このガイドの後半で説明）の一環として、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.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  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.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  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 デバッグ プロバイダを構成する

2026 年 7 月上旬より、コンソールの AI Logic のガイド付き設定ワークフローの一環として、Gemini API を保護するために Firebase App Check が自動的に適用されます。ローカル開発では、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: モデルにプロンプト リクエストを送信する

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

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

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

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 アシスタントの機能

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

オンデバイス推論でまだ利用できない機能

試験運用版リリースでは、クラウドモデルのすべての機能がオンデバイス推論で使用できるわけではありません。次の機能は、オンデバイス推論ではまだ利用できません（ただし、通常はクラウドベースの推論で利用できます）。

  • 画像を生成しています

    • クラウドホスト型モデルにフォールバックできますが、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 の使用感についてフィードバックを送信する