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


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

このページでは、クライアント SDK の使用を開始する方法について説明します。また、温度などの追加の設定オプションと機能についても説明します。

Firebase AI Logic を介したオンデバイス推論は、特定のデバイスで実行される Android アプリでサポートされており、ML Kit の利用規約ML Kit の生成 AI 関連の利用規約が適用されます。

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

おすすめのユースケース

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

    • プライバシーの強化
    • ローカル コンテキスト
    • 無料の推論
    • オフライン機能
  • ハイブリッド機能の特典:

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

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

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

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

始める前に

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

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

デバイス上の推論(ML Kit の Prompt API を使用)については、ML Kit のドキュメントでサポートされているデバイスとデバイス上のモデルの一覧をご確認ください。

始める

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

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

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

  2. Firebase コンソールで、[Firebase AI Logic] ページに移動します。

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

  4. Gemini API」プロバイダを使用するようにプロジェクトを設定します。

    Gemini Developer API を使用して始めることをおすすめします。いつでも Vertex AI Gemini API を設定できます(お支払いに関する要件も同様です)。

    Gemini Developer API の場合、コンソールは必要な API を有効にし、プロジェクトに Gemini API キーを作成します。
    この Gemini API キーをアプリのコードベースに追加しないでください。詳細

  5. コンソールのワークフローでプロンプトが表示されたら、画面上の指示に沿ってアプリを登録し、Firebase に接続します。

  6. このガイドの次のステップに進み、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 ライブラリの依存関係を追加します。

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 の場合は、2 つのライブラリを追加する必要があります。

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

レイテンシの最適化

最初の推論呼び出しを最適化するには、アプリで warmup() を呼び出すことができます。これにより、オンデバイス モデルがメモリに読み込まれ、ランタイム コンポーネントが初期化されます。

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

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 = "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 LogicgenerateContentStreamgenerateContent ではなく)を使用したテキスト レスポンスのストリーミングもサポートしています。

テキストと画像(マルチモーダル)入力からテキストを生成する

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

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 LogicgenerateContentStreamgenerateContent ではなく)を使用したテキスト レスポンスのストリーミングもサポートしています。

Google アシスタントの機能

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

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

試験運用版として、クラウドモデルのすべての機能がオンデバイス推論で使用できるわけではありません。

このセクションに記載されている機能は、オンデバイス推論ではまだ利用できません。これらの機能を使用する場合は、より一貫したエクスペリエンスを実現するために 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 レスポンスが返されます。このエラーが発生した場合は、指数バックオフを使用してリクエストを再試行することを検討してください。また、アプリが長期間の割り当て(1 日の割り当てなど)を超過した場合にも、ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED が返されることがあります。


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