Xây dựng trải nghiệm kết hợp trong các ứng dụng Android bằng các mô hình được lưu trữ trên thiết bị và trên đám mây


Bạn có thể xây dựng các ứng dụng và tính năng Android dựa trên AI bằng suy luận kết hợp thông qua Firebase AI Logic. Tính năng suy luận kết hợp cho phép chạy suy luận bằng cách sử dụng mô hình trên thiết bị khi có sẵn và quay lại liền mạch mô hình được lưu trữ trên đám mây (và ngược lại).

Trang này mô tả cách bắt đầu sử dụng SDK ứng dụng, cũng như cho thấy các lựa chọn và chức năng cấu hình bổ sung.

Xin lưu ý rằng tính năng suy luận trên thiết bị thông qua Firebase AI Logic được hỗ trợ cho các ứng dụng Android sử dụng SDK Firebase AI Logic phiên bản 17.10.0 trở lên (BoM phiên bản 34.10.0 trở lên) và chạy trên một số thiết bị cụ thể. Tính năng này chịu sự điều chỉnh của Điều khoản của Bộ công cụ học máy, cũng như các điều khoản cụ thể đối với các khía cạnh AI tạo sinh của Bộ công cụ học máy.

Các trường hợp sử dụng nên dùng và các chức năng được hỗ trợ

Trường hợp sử dụng đề xuất

  • Việc sử dụng mô hình trên thiết bị để suy luận mang lại:

    • Quyền riêng tư nâng cao
    • Bối cảnh địa phương
    • Suy luận miễn phí
    • Chức năng ngoại tuyến

  • Sử dụng các chức năng kết hợp:

    • Tiếp cận nhiều đối tượng hơn bằng cách hỗ trợ khả năng kết nối Internet và sử dụng mô hình trên thiết bị

Các tính năng và chức năng được hỗ trợ để suy luận trên thiết bị

Tính năng suy luận trên thiết bị chỉ hỗ trợ tạo văn bản một lượt (không trò chuyện), với đầu ra truyền trực tuyến hoặc không truyền trực tuyến. Công cụ này hỗ trợ các chức năng tạo văn bản sau:

Hãy nhớ xem danh sách các tính năng chưa có sẵn cho tính năng suy luận trên thiết bị ở cuối trang này.

Trước khi bắt đầu

Hãy lưu ý những điều sau:

Các thiết bị Android được hỗ trợ và mô hình trên thiết bị của các thiết bị đó

Đối với suy luận trên thiết bị (sử dụng Prompt API trong Bộ công cụ học máy), bạn có thể tìm thấy danh sách thiết bị được hỗ trợ và các mô hình trên thiết bị trong tài liệu về Bộ công cụ học máy.

Bắt đầu

Các bước bắt đầu này mô tả chế độ thiết lập chung bắt buộc cho mọi yêu cầu về câu lệnh được hỗ trợ mà bạn muốn gửi.

Bước 1: Thiết lập dự án Firebase và kết nối ứng dụng của bạn với Firebase

  1. Đăng nhập vào bảng điều khiển Firebase, sau đó chọn dự án Firebase của bạn.

  2. Trong bảng điều khiển Firebase, hãy chuyển đến Dịch vụ AI > Logic AI.

  3. Nhấp vào Bắt đầu để khởi chạy quy trình công việc có hướng dẫn giúp bạn thiết lập các API và tài nguyên cần thiết cho dự án của mình.

  4. Nếu được nhắc, hãy làm theo hướng dẫn trên màn hình để đăng ký ứng dụng và thêm cấu hình Firebase vào ứng dụng.

  5. Khi được yêu cầu chọn "Nhà cung cấp Gemini API", bạn nên chọn Gemini Developer API để bắt đầu nhanh chóng mà không mất phí.

    Sau này, bạn có thể thiết lập Agent Platform Gemini API (formerly Vertex AI) (và yêu cầu thanh toán của API này) bất cứ lúc nào.

  6. Tiếp tục quy trình để thiết lập các API bắt buộc và dịch vụ liên quan cho Firebase AI Logic.

    Kể từ đầu tháng 7 năm 2026, giai đoạn này của quy trình làm việc sẽ tự động thực thi Firebase App Check cho AI Logic, đây là một dịch vụ quan trọng giúp bảo vệ Gemini API khi được truy cập trực tiếp từ ứng dụng của bạn. Trong quá trình bắt đầu (xem các bước sau trong hướng dẫn này), bạn cần định cấu hình nhà cung cấp dịch vụ gỡ lỗi App Check để phát triển cục bộ khi App Check được thực thi.

  7. Tiếp tục đến bước tiếp theo trong hướng dẫn này để thêm các SDK bắt buộc vào ứng dụng của bạn.

Bước 2: Thêm các SDK bắt buộc

Firebase AI Logic SDK cho Android (firebase-ai) cùng với Firebase AI Logic On-Device SDK (firebase-ai-ondevice) cung cấp quyền truy cập vào các API để tương tác với các mô hình tạo sinh.

Trong tệp Gradle (ở cấp ứng dụng) trong mô-đun (chẳng hạn như <project>/<app-module>/build.gradle.kts), hãy thêm các phần phụ thuộc cho thư viện Firebase AI Logic và App Check dành cho Android:

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

Đối với Java, bạn cần thêm hai thư viện bổ sung.

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")
}

Bước 3: Định cấu hình nhà cung cấp dịch vụ gỡ lỗi App Check cho quá trình phát triển cục bộ

Kể từ đầu tháng 7 năm 2026, trong quy trình thiết lập có hướng dẫn cho AI Logic trong Play Console, Firebase App Check sẽ tự động được thực thi để bảo vệ Gemini API. Để phát triển cục bộ, bạn cần định cấu hình App Check nhà cung cấp dịch vụ gỡ lỗi để bỏ qua quy trình chứng thực trong khi vẫn duy trì việc thực thi App Check.

  1. Trong bản gỡ lỗi, hãy định cấu hình App Check để sử dụng nhà máy trình cung cấp gỡ lỗi:

    Kotlin

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

    Java

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

  2. Lấy mã thông báo gỡ lỗi:

    1. Chạy ứng dụng trong trình mô phỏng hoặc trên thiết bị thử nghiệm.

    2. Tìm mã thông báo gỡ lỗi App Check trong nhật ký. Ví dụ:

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

    3. Sao chép mã thông báo (ví dụ: 123a4567-b89c-12d3-e456-789012345678).

  3. Đăng ký mã thông báo gỡ lỗi của bạn với App Check:

    1. Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Security (Bảo mật) > App Check (Kiểm tra ứng dụng) > Apps (Ứng dụng).

    2. Tìm ứng dụng của bạn, nhấp vào trình đơn mục bổ sung (), rồi chọn Quản lý mã gỡ lỗi.

    3. Làm theo hướng dẫn trên màn hình để đăng ký mã gỡ lỗi.

Để biết thông tin chi tiết về nhà cung cấp dịch vụ gỡ lỗi (bao gồm cả cách lấy mã thông báo gỡ lỗi mới), hãy xem tài liệu chính thức về App Check.

Bước 4: Kiểm tra xem mô hình trên thiết bị có sẵn hay không

Sử dụng FirebaseAIOnDevice, kiểm tra xem mô hình trên thiết bị có sẵn hay không và tải mô hình xuống nếu mô hình đó không có sẵn.

Sau khi tải xuống, AICore sẽ tự động cập nhật mô hình. Hãy xem các ghi chú sau đoạn mã để biết thêm thông tin chi tiết về AICore và cách quản lý quá trình tải mô hình trên thiết bị xuống.

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.

Xin lưu ý những điều sau đây về việc tải mô hình trên thiết bị xuống:

  • Thời gian tải mô hình trên thiết bị xuống phụ thuộc vào nhiều yếu tố, bao gồm cả mạng của bạn.

  • Nếu mã của bạn sử dụng một mô hình trên thiết bị cho suy luận chính hoặc dự phòng, hãy đảm bảo rằng mô hình được tải xuống sớm trong vòng đời của ứng dụng để mô hình trên thiết bị có sẵn trước khi người dùng cuối gặp phải mã trong ứng dụng của bạn.

  • Nếu mô hình trên thiết bị không có sẵn khi có yêu cầu suy luận trên thiết bị, thì SDK sẽ không tự động kích hoạt quá trình tải mô hình trên thiết bị xuống. SDK sẽ quay lại mô hình được lưu trữ trên đám mây hoặc gửi một ngoại lệ (xem thông tin chi tiết về hành vi của chế độ suy luận).

  • AICore (một dịch vụ hệ thống Android) quản lý cho bạn mô hình và phiên bản nào được tải xuống, cập nhật mô hình, v.v. Xin lưu ý rằng thiết bị sẽ chỉ tải một mô hình xuống, vì vậy, nếu một ứng dụng khác trên thiết bị đã tải thành công mô hình trên thiết bị xuống, thì quy trình kiểm tra này sẽ trả về kết quả là mô hình đã có sẵn.

Tối ưu hoá độ trễ

Để tối ưu hoá cho lệnh gọi suy luận đầu tiên, bạn có thể yêu cầu ứng dụng gọi onDeviceExtension?.warmUp() (hiện chỉ dùng được cho Kotlin). Thao tác này sẽ tải mô hình trên thiết bị vào bộ nhớ và khởi chạy các thành phần thời gian chạy.

Bước 5: Khởi chạy dịch vụ và tạo một thực thể mô hình

Nhấp vào nhà cung cấp Gemini API để xem nội dung và mã dành riêng cho nhà cung cấp trên trang này.

Hãy thiết lập những thông tin sau trước khi bạn gửi yêu cầu câu lệnh đến mô hình.

  1. Khởi chạy dịch vụ cho nhà cung cấp API mà bạn đã chọn.

  2. Tạo một thực thể GenerativeModel và đặt mode thành một trong các giá trị sau. Các nội dung mô tả ở đây rất chung chung, nhưng bạn có thể tìm hiểu thông tin chi tiết về hành vi của các chế độ này trong phần Đặt chế độ suy luận.

    • PREFER_ON_DEVICE: Thử dùng mô hình trên thiết bị; nếu không, hãy chuyển về mô hình được lưu trữ trên đám mây.

    • ONLY_ON_DEVICE: Cố gắng sử dụng mô hình trên thiết bị; nếu không, hãy gửi một ngoại lệ.

    • PREFER_IN_CLOUD: Cố gắng sử dụng mô hình được lưu trữ trên đám mây; nếu không, hãy quay lại mô hình trên thiết bị.

    • ONLY_IN_CLOUD: Cố gắng sử dụng mô hình được lưu trữ trên đám mây; nếu không, hãy gửi một ngoại lệ.

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);

Bước 6: Gửi yêu cầu cho mô hình

Phần này hướng dẫn bạn cách gửi nhiều loại dữ liệu đầu vào để tạo ra nhiều loại dữ liệu đầu ra, bao gồm:

Tạo văn bản do AI tạo từ dữ liệu đầu vào chỉ có văn bản

Trước khi thử mẫu này, hãy đảm bảo rằng bạn đã hoàn tất phần Bắt đầu của hướng dẫn này.

Bạn có thể sử dụng generateContent() để tạo văn bản do AI tạo từ một câu lệnh chứa văn bản:

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);

Xin lưu ý rằng Firebase AI Logic cũng hỗ trợ truyền trực tuyến các câu trả lời bằng văn bản bằng cách sử dụng generateContentStream (thay vì generateContent).

Tạo văn bản do AI tạo từ dữ liệu đầu vào dạng văn bản và hình ảnh (đa phương thức)

Trước khi thử mẫu này, hãy đảm bảo rằng bạn đã hoàn tất phần Bắt đầu của hướng dẫn này.

Bạn có thể sử dụng generateContent() để tạo văn bản do AI tạo từ một câu lệnh chứa văn bản và tối đa một tệp hình ảnh (chỉ Bitmap) — cung cấp mimeType của mỗi thông tin đầu vào và chính tệp đó.

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);

Xin lưu ý rằng Firebase AI Logic cũng hỗ trợ truyền trực tuyến các câu trả lời bằng văn bản bằng cách sử dụng generateContentStream (thay vì generateContent).

Bạn có thể làm gì khác?

Bạn có thể sử dụng nhiều tuỳ chọn và chức năng cấu hình bổ sung cho trải nghiệm kết hợp:

Các tính năng chưa có sẵn cho hoạt động suy luận trên thiết bị

Vì đây là bản phát hành thử nghiệm, nên không phải tất cả các chức năng của mô hình đám mây đều có sẵn cho hoạt động suy luận trên thiết bị. Các tính năng sau đây hiện chưa hỗ trợ suy luận trên thiết bị (nhưng thường hỗ trợ suy luận dựa trên đám mây).

  • Đang tạo hình ảnh

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ gửi một ngoại lệ.

  • Tạo văn bản do AI tạo từ các loại tệp hình ảnh đầu vào khác ngoài Bitmap (hình ảnh được tải vào bộ nhớ)

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ gửi một ngoại lệ.

  • Tạo văn bản do AI tạo từ tệp đầu vào chỉ có hình ảnh. Đối với suy luận trên thiết bị, bạn phải cung cấp văn bản trong yêu cầu đa phương thức.

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ đưa ra một ngoại lệ.

  • Tạo văn bản do AI tạo từ nhiều tệp hình ảnh đầu vào

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ gửi một ngoại lệ.

  • Tạo văn bản do AI tạo từ dữ liệu đầu vào là âm thanh, video và tài liệu (chẳng hạn như tệp PDF)

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ đưa ra một ngoại lệ.

  • Cung cấp tệp bằng URL trong các yêu cầu đa phương thức. Đối với suy luận trên thiết bị, bạn phải cung cấp một hình ảnh duy nhất dưới dạng Bitmap.

    • Nếu bạn cung cấp URL của tệp bằng fileData (FileDataPart), thì URL đó có thể quay lại mô hình được lưu trữ trên đám mây (chế độ ONLY_ON_DEVICE sẽ gửi một ngoại lệ).
    • Nếu bạn nhúng trực tiếp một URL vào câu lệnh dạng văn bản, thì URL đó sẽ không tự động chuyển về mô hình được lưu trữ trên đám mây (mô hình trên thiết bị sẽ bỏ qua các URL được nhúng).

  • Gửi yêu cầu vượt quá 4.000 mã thông báo (hoặc khoảng 3.000 từ tiếng Anh)

    • Có thể quay lại mô hình được lưu trữ trên đám mây; tuy nhiên, chế độ ONLY_ON_DEVICE sẽ gửi một ngoại lệ.

  • Cuộc trò chuyện nhiều lượt

    • Không tự động quay lại mô hình được lưu trữ trên đám mây (suy luận trên thiết bị nối nhật ký câu lệnh thành một câu lệnh văn bản duy nhất; vì mô hình trên thiết bị không phân biệt giữa các vai trò và xem nhật ký là một thông báo duy nhất, nên mô hình này sẽ không chính xác như mô hình được lưu trữ trên đám mây).
    • Nếu muốn sử dụng chế độ trò chuyện nhiều lượt, bạn nên dùng chế độ ONLY_IN_CLOUD.

  • Cung cấp cho mô hình các công cụ để giúp mô hình tạo câu trả lời (chẳng hạn như gọi hàm, thực thi mã, bối cảnh từ URL, Xác minh bằng Google Search và Xác minh bằng Google Maps)

    • Không tự động quay lại mô hình được lưu trữ trên đám mây. Nếu bạn muốn sử dụng các công cụ, bạn nên dùng chế độ ONLY_IN_CLOUD.

Tính năng giám sát bằng AI trong bảng điều khiển Firebase không cho thấy bất kỳ dữ liệu nào về hoạt động suy luận trên thiết bị (bao gồm cả nhật ký thiết bị). Tuy nhiên, mọi hoạt động suy luận sử dụng mô hình được lưu trữ trên đám mây đều có thể được giám sát giống như các hoạt động suy luận khác thông qua Firebase AI Logic.

Các hạn chế khác

Ngoài những điểm trên, suy luận trên thiết bị còn có nhữnghạn chế sau đây (tìm hiểu thêm trong tài liệu về Bộ công cụ học máy):

  • Người dùng cuối của ứng dụng phải sử dụng một thiết bị được hỗ trợ để suy luận trên thiết bị.

  • Ứng dụng của bạn chỉ có thể chạy suy luận trên thiết bị khi ở nền trước.

  • Chỉ tiếng Anh và tiếng Hàn mới được xác thực cho tính năng suy luận trên thiết bị.

  • Giới hạn mã thông báo tối đa cho toàn bộ yêu cầu suy luận trên thiết bị là 4.000 mã thông báo. Nếu các yêu cầu của bạn có thể vượt quá giới hạn này, hãy nhớ định cấu hình một chế độ suy luận có thể sử dụng mô hình được lưu trữ trên đám mây.

  • Bạn nên tránh các trường hợp sử dụng suy luận trên thiết bị đòi hỏi đầu ra dài (hơn 256 mã thông báo).

  • AICore (một dịch vụ hệ thống Android quản lý các mô hình trên thiết bị) thực thi hạn mức suy luận cho mỗi ứng dụng. Việc đưa ra quá nhiều yêu cầu API trong một khoảng thời gian ngắn sẽ dẫn đến phản hồi ErrorCode.BUSY. Nếu bạn gặp lỗi này, hãy cân nhắc sử dụng thuật toán đợi luỹ tuyến để thử lại yêu cầu. Ngoài ra, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED có thể được trả về nếu một ứng dụng vượt quá hạn mức dài hạn (ví dụ: hạn mức hằng ngày).


Gửi ý kiến phản hồi về trải nghiệm của bạn với Firebase AI Logic