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


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

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

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

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

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

  • استفاده از مدل درون‌دستگاهی برای استنباط مزایای زیر را دارد:

    • حریم خصوصی بهبودیافته
    • بافت محلی
    • استنباط بدون هزینه
    • عملکرد آفلاین

  • استفاده از عملکرد ترکیبی این مزایا را دارد:

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

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

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

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

قبل از شروع

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

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

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

شروع کنید

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

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

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

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

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

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

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

    هرزمان بخواهید می‌توانید Agent Platform Gemini API (formerly Vertex AI) (و الزامات آن برای صدور صورت‌حساب) را راه‌اندازی کنید.

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

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

  7. برای افزودن کیت‌های توسعه نرم‌افزار موردنیاز به برنامه، به مرحله بعدی در این راهنما بروید.

مرحله ۲: افزودن کیت‌های توسعه نرم‌افزار موردنیاز

«کیت توسعه نرم‌افزار Firebase AI Logic برای Android» (firebase-ai) به‌همراه «کیت توسعه نرم‌افزار Firebase AI Logic On-Device» (firebase-ai-ondevice) دسترسی به «میاناهای برنامه‌سازی کاربردی» برای تعامل با مدل‌های زایا را فراهم می‌کنند.

در فایل Gradle واحد (سطح برنامه) (مثل <project>/<app-module>/build.gradle.kts)، وابستگی‌های Firebase AI Logic و App Check کتابخانه‌ها را برای 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

برای 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: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")
}

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

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

  1. در ساخت اشکال‌زدایی، App Check را پیکربندی کنید تا از کارخانه فراهم‌کننده اشکال‌زدایی استفاده کند:

    Kotlin

    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، به امنیت > بررسی برنامه > برگه برنامه‌ها بروید.

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

    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, 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.

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

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

  • اگر کد شما از مدل درون‌دستگاهی برای استنباط اصلی یا بازگشتی استفاده می‌کند، مطمئن شوید که مدل در مراحل اولیه چرخه حیات برنامه شما بارگیری شده است تا مدل درون‌دستگاهی قبل‌از اینکه کاربران نهایی شما با کد در برنامه شما مواجه شوند دردسترس باشد.

  • اگر مدل درون‌دستگاهی هنگام درخواست استنباط درون‌دستگاهی دردسترس نباشد، کیت توسعه نرم‌افزار بارگیری مدل درون‌دستگاهی را به‌طور خودکار راه‌اندازی نخواهد کرد. کیت توسعه نرم‌افزار یا به مدل میزبانی‌شده در فضای ابری برمی‌گردد یا استثنایی ایجاد می‌کند (جزئیات مربوط به عملکرد حالت‌های استنباط را ببینید).

  • AICore (خدمات سیستم Android) مدیریت می‌کند که کدام مدل و نسخه بارگیری شود، مدل را به‌روز نگه می‌دارد، و غیره. توجه داشته باشید که فقط یک مدل در دستگاه بارگیری می‌شود، بنابراین اگر برنامه دیگری در دستگاه قبلاً مدل درون‌دستگاهی را با موفقیت بارگیری کرده باشد، این بررسی نشان می‌دهد که مدل دردسترس است.

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

برای بهینه‌سازی اولین تماس استنباط، می‌توانید برنامه خود را برای تماس با onDeviceExtension?.warmUp() (درحال‌حاضر فقط برای Kotlin دردسترس است) تنظیم کنید. این کار مدل درون‌دستگاهی را در حافظه بار می‌کند و اجزای زمان اجرا را مقداردهی اولیه می‌کند.

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

روی ارائه‌دهنده 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);

مرحله ۶: ارسال درخواست پیام‌واره به مدل

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

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

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

می‌توانید از 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() برای تولید نوشتار از پیام‌واره‌ای که حاوی نوشتار و حداکثر یک فایل تصویری (فقط Bitmap) است استفاده کنید — با ارائه 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 برای تجربه یکنواخت‌تر استفاده کنید.

  • تولید نوشتار از انواع ورودی فایل تصویر به‌جز «بیت‌مپ» (تصویر در حافظه بار شده است)

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

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

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

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

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

  • گپ چندنوبتی

  • ارائه ابزارها به مدل برای کمک به تولید پاسخ (مانند فراخوانی تابع، اجرای کد، زمینه نشانی وب، «پایه‌گذاری» با Google Search، و «پایه‌گذاری» با Google Maps)

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

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

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

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

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

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

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

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

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


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