ساخت تجربه‌های ترکیبی در برنامه‌های اندروید با مدل‌های روی دستگاه و میزبانی ابری


شما می‌توانید برنامه‌ها و ویژگی‌های اندروید مبتنی بر هوش مصنوعی را با استنتاج ترکیبی و با استفاده از منطق هوش مصنوعی فایربیس بسازید. استنتاج ترکیبی، اجرای استنتاج با استفاده از مدل‌های روی دستگاه را در صورت وجود و بازگشت یکپارچه به مدل‌های میزبانی شده در فضای ابری را در غیر این صورت (و برعکس) امکان‌پذیر می‌کند.

این صفحه نحوه شروع به کار با SDK کلاینت و همچنین نمایش گزینه‌ها و قابلیت‌های پیکربندی اضافی ، مانند دما، را شرح می‌دهد.

توجه داشته باشید که استنتاج روی دستگاه از طریق Firebase AI Logic برای برنامه‌های اندروید با استفاده از Firebase AI Logic SDK نسخه ۱۷.۱۰.۰+ ( BoM نسخه ۳۴.۱۰.۰+) و اجرا روی دستگاه‌های خاص پشتیبانی می‌شود. این امر تابع شرایط ML Kit و همچنین شرایط خاص جنبه‌های Gen AI کیت ML است.

موارد استفاده پیشنهادی و قابلیت‌های پشتیبانی‌شده

موارد استفاده توصیه شده

  • استفاده از یک مدل روی دستگاه برای استنتاج، موارد زیر را ارائه می‌دهد:

    • حریم خصوصی پیشرفته
    • زمینه محلی
    • استنتاج بدون هزینه
    • قابلیت آفلاین

  • استفاده از قابلیت‌های ترکیبی موارد زیر را ارائه می‌دهد:

    • با در نظر گرفتن قابلیت دسترسی به مدل روی دستگاه و اتصال به اینترنت، به مخاطبان بیشتری دسترسی پیدا کنید

قابلیت‌ها و ویژگی‌های پشتیبانی‌شده برای استنتاج روی دستگاه

استنتاج روی دستگاه فقط از تولید متن تک نوبتی ( نه چت) با خروجی استریمینگ یا غیر استریمینگ پشتیبانی می‌کند. این قابلیت از قابلیت‌های تولید متن زیر پشتیبانی می‌کند:

حتماً لیست ویژگی‌های هنوز در دسترس برای استنتاج درون دستگاه را در پایین این صفحه بررسی کنید.

قبل از اینکه شروع کنی

به موارد زیر توجه کنید:

دستگاه‌های اندروید پشتیبانی‌شده و مدل‌های روی دستگاه آنها

برای استنتاج روی دستگاه (که از Prompt API از ML Kit استفاده می‌کند)، می‌توانید لیستی از دستگاه‌های پشتیبانی شده و مدل‌های روی دستگاه آنها را در مستندات ML Kit پیدا کنید.

شروع کنید

این مراحل شروع، تنظیمات کلی مورد نیاز برای هر درخواست پشتیبانی‌شده‌ای که می‌خواهید ارسال کنید را شرح می‌دهند.

مرحله ۱ : یک پروژه Firebase راه‌اندازی کنید و برنامه خود را به Firebase متصل کنید

  1. وارد کنسول Firebase شوید و سپس پروژه Firebase خود را انتخاب کنید.

  2. در کنسول Firebase ، به بخش سرویس‌های هوش مصنوعی > منطق هوش مصنوعی بروید.

  3. برای شروع یک گردش کار هدایت‌شده که به شما در تنظیم APIها و منابع مورد نیاز پروژه‌تان کمک می‌کند، روی «شروع به کار» کلیک کنید.

  4. در صورت درخواست، دستورالعمل‌های روی صفحه را دنبال کنید تا برنامه خود را ثبت کنید و پیکربندی Firebase خود را به برنامه خود اضافه کنید.

  5. وقتی از شما خواسته می‌شود «ارائه‌دهنده‌ی API Gemini» را انتخاب کنید، توصیه می‌کنیم API توسعه‌دهنده‌ی Gemini را انتخاب کنید که به شما امکان می‌دهد بدون هیچ هزینه‌ای و به سرعت شروع به کار کنید.

    در هر زمانی بعد، همیشه می‌توانید API مربوط به Vertex AI Gemini (و الزامات آن برای صدور صورتحساب) را تنظیم کنید .

  6. در ادامه، APIهای مورد نیاز و سرویس‌های مرتبط با Firebase AI Logic را تنظیم کنید.

    از اوایل ژوئیه ۲۰۲۶، این مرحله از گردش کار به طور خودکار Firebase App Check برای منطق هوش مصنوعی اجرا می‌کند ، که یک سرویس حیاتی برای کمک به محافظت از API Gemini هنگام دسترسی مستقیم از برنامه شما است. به عنوان بخشی از شروع کار (به مراحل بعدی این راهنما مراجعه کنید)، باید ارائه دهنده اشکال زدایی App Check را برای توسعه محلی هنگام اجرای App Check پیکربندی کنید.

  7. برای افزودن SDK های مورد نیاز به برنامه خود، به مرحله بعدی این راهنما بروید.

مرحله ۲ : اضافه کردن SDK های مورد نیاز

کیت توسعه نرم‌افزاری منطق هوش مصنوعی فایربیس برای اندروید ( firebase-ai ) به همراه کیت توسعه نرم‌افزاری (SDK) مربوط به Firebase AI Logic روی دستگاه ( firebase-ai-ondevice ) دسترسی به APIها را برای تعامل با مدل‌های مولد فراهم می‌کند.

در فایل Gradle ماژول (سطح برنامه) خود (مانند <project>/<app-module>/build.gradle.kts )، وابستگی‌های کتابخانه‌های 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:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.0")
}

Java

برای جاوا، باید دو کتابخانه اضافی اضافه کنید.

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:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.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")
}

مرحله ۳ : پیکربندی ارائه‌دهنده اشکال‌زدایی App Check برای توسعه محلی

از اوایل ژوئیه ۲۰۲۶، به عنوان بخشی از گردش کار تنظیم هدایت‌شده برای منطق هوش مصنوعی در کنسول، Firebase App Check به طور خودکار برای محافظت از API Gemini اعمال می‌شود. برای توسعه محلی، باید ارائه‌دهنده اشکال‌زدایی App Check را طوری پیکربندی کنید که از گواهی‌نامه عبور کند و در عین حال اجرای App Check را حفظ کند.

  1. در نسخه اشکال‌زدایی (debug build)، App Check طوری پیکربندی کنید که از debug provider factory استفاده کند:

    کاتلین 

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

    جاوا 

    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 ، به تب Security > App Check > Apps بروید.

    2. برنامه‌ی خود را پیدا کنید، روی منوی سرریز ( ) کلیک کنید و سپس مدیریت توکن‌های اشکال‌زدایی (Manage debug tokens ) را انتخاب کنید.

    3. برای ثبت توکن اشکال‌زدایی خود، دستورالعمل‌های روی صفحه را دنبال کنید.

برای جزئیات بیشتر در مورد ارائه‌دهنده اشکال‌زدایی (از جمله نحوه دریافت یک توکن اشکال‌زدایی جدید)، به اسناد رسمی App Check مراجعه کنید.

مرحله ۴ : بررسی کنید که آیا مدل روی دستگاه موجود است یا خیر

با استفاده از 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 (یک سرویس سیستم اندروید) مدل و نسخه دانلود شده را برای شما مدیریت می‌کند، مدل را به‌روز نگه می‌دارد و غیره. توجه داشته باشید که دستگاه فقط یک مدل دانلود شده خواهد داشت، بنابراین اگر برنامه دیگری روی دستگاه قبلاً مدل روی دستگاه را با موفقیت دانلود کرده باشد، این بررسی نشان می‌دهد که مدل در دسترس است.

بهینه‌سازی تأخیر

برای بهینه‌سازی اولین فراخوانی استنتاج، می‌توانید فراخوانی برنامه خود را با تابع warmup() انجام دهید. این تابع مدل روی دستگاه را در حافظه بارگذاری کرده و اجزای زمان اجرا را مقداردهی اولیه می‌کند.

مرحله ۵ : سرویس را مقداردهی اولیه کنید و یک نمونه مدل ایجاد کنید

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

قبل از ارسال درخواست سریع به مدل، موارد زیر را تنظیم کنید.

  1. سرویس را برای ارائه‌دهنده API انتخابی خود مقداردهی اولیه کنید.

  2. یک نمونه GenerativeModel ایجاد کنید و mode روی یکی از موارد زیر تنظیم کنید. توضیحات اینجا بسیار سطح بالا هستند، اما می‌توانید جزئیات مربوط به رفتار این حالت‌ها را در Set an inference 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);

مرحله ۶ : ارسال درخواست سریع به یک مدل

این بخش به شما نشان می‌دهد که چگونه انواع مختلف ورودی را برای تولید انواع مختلف خروجی ارسال کنید، از جمله:

تولید متن از ورودی فقط متنی

قبل از امتحان کردن این نمونه، مطمئن شوید که بخش « شروع به کار » این راهنما را تکمیل کرده‌اید.

می‌توانید از 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 از پخش پاسخ‌های متنی با استفاده از generateContentStream (به جای generateContent ) نیز پشتیبانی می‌کند.

تولید متن از ورودی متن و تصویر (چندوجهی)

قبل از امتحان کردن این نمونه، مطمئن شوید که بخش « شروع به کار » این راهنما را تکمیل کرده‌اید.

شما می‌توانید از 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 از پخش پاسخ‌های متنی با استفاده از generateContentStream (به جای generateContent ) نیز پشتیبانی می‌کند.

چه کار دیگری می‌توانید انجام دهید؟

شما می‌توانید از گزینه‌ها و قابلیت‌های پیکربندی اضافی مختلفی برای تجربیات ترکیبی خود استفاده کنید:

ویژگی‌هایی که هنوز برای استنتاج روی دستگاه در دسترس نیستند

به عنوان یک نسخه آزمایشی، همه قابلیت‌های مدل‌های ابری برای استنتاج روی دستگاه در دسترس نیستند.

ویژگی‌های ذکر شده در این بخش هنوز برای استنتاج روی دستگاه در دسترس نیستند. اگر می‌خواهید از هر یک از این ویژگی‌ها استفاده کنید، توصیه می‌کنیم برای یک تجربه منسجم‌تر از حالت استنتاج ONLY_IN_CLOUD استفاده کنید.

  • تولید خروجی ساختاریافته (مانند JSON یا enums)

  • تولید متن از انواع ورودی فایل تصویری غیر از Bitmap (تصویر بارگذاری شده در حافظه)

  • تولید متن از بیش از یک فایل تصویری

  • تولید متن از ورودی‌های صوتی، تصویری و اسناد (مانند PDF)

  • تولید تصاویر با استفاده از مدل‌های Gemini یا Imagen

  • ارائه فایل‌ها با استفاده از URLها در درخواست‌های چندوجهی. شما باید فایل‌ها را به عنوان داده‌های درون‌خطی به مدل‌های روی دستگاه ارائه دهید.

  • ارسال درخواست‌هایی که بیش از ۴۰۰۰ توکن (یا تقریباً ۳۰۰۰ کلمه انگلیسی) باشند.

  • چت چند نوبتی

  • ارائه ابزارهایی به مدل برای کمک به تولید پاسخ (مانند فراخوانی تابع، اجرای کد، زمینه URL، اتصال به زمین با Google Search و اتصال به زمین با Google Maps )

نظارت بر هوش مصنوعی در کنسول Firebase هیچ داده‌ای برای استنتاج روی دستگاه (از جمله گزارش‌های روی دستگاه) نشان نمی‌دهد . با این حال، هر استنتاجی که از یک مدل میزبانی ابری استفاده می‌کند، می‌تواند درست مانند سایر استنتاج‌ها از طریق Firebase AI Logic نظارت شود.

محدودیت‌های اضافی

علاوه بر موارد فوق، استنتاج روی دستگاه محدودیت‌های زیر را نیز دارد (برای اطلاعات بیشتر به مستندات ML Kit مراجعه کنید):

  • کاربر نهایی برنامه شما باید از یک دستگاه پشتیبانی‌شده برای استنتاج درون‌دستگاهی استفاده کند.

  • برنامه شما فقط زمانی می‌تواند استنتاج روی دستگاه را اجرا کند که در پیش‌زمینه باشد.

  • فقط زبان‌های انگلیسی و کره‌ای برای استنتاج روی دستگاه تأیید شده‌اند.

  • حداکثر محدودیت توکن برای کل درخواست استنتاج روی دستگاه، ۴۰۰۰ توکن است. اگر درخواست‌های شما ممکن است از این محدودیت فراتر رود، حتماً حالت استنتاجی را پیکربندی کنید که بتواند از یک مدل میزبانی ابری استفاده کند.

  • توصیه می‌کنیم از موارد استفاده از استنتاج روی دستگاه که نیاز به خروجی طولانی (بیش از ۲۵۶ توکن) دارند، اجتناب کنید.

  • AICore (یک سرویس سیستم اندروید که مدل‌های روی دستگاه را مدیریت می‌کند) سهمیه استنتاج را برای هر برنامه اعمال می‌کند. ارسال درخواست‌های API زیاد در یک دوره کوتاه منجر به پاسخ ErrorCode.BUSY می‌شود. اگر این خطا را دریافت می‌کنید، استفاده از تابع برگشت نمایی (exponential backoff) را برای امتحان مجدد درخواست در نظر بگیرید. همچنین، اگر یک برنامه از سهمیه طولانی مدت (مثلاً سهمیه روزانه) فراتر رود، می‌توان ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED را برگرداند.


درباره تجربه خود با Firebase AI Logic بازخورد دهید