إنشاء تجارب مختلطة في تطبيقات الويب باستخدام نماذج مستضافة على الجهاز ونماذج مستضافة على السحابة الإلكترونية

يمكنك إنشاء تطبيقات وميزات ويب مستندة إلى الذكاء الاصطناعي مع استنتاج مختلط باستخدام Firebase AI Logic. تتيح الاستدلال المختلط تشغيل الاستدلال باستخدام النماذج المتوفّرة على الجهاز، والرجوع بسلاسة إلى النماذج المستضافة على السحابة الإلكترونية في حال عدم توفّرها (والعكس صحيح).

توضّح هذه الصفحة كيفية البدء في استخدام حزمة تطوير البرامج (SDK) الخاصة بالعميل. بعد إكمال عملية الإعداد العادية، اطّلِع على خيارات وإمكانات الإعدادات الإضافية (مثل الناتج المنظَّم).

يُرجى العِلم أنّ الاستدلال على الجهاز متاح لتطبيقات الويب التي تعمل على Chrome على الكمبيوتر.

الانتقال إلى أمثلة الرموز

حالات الاستخدام المقترَحة والإمكانات المتاحة

حالات الاستخدام المقترَحة:

  • استخدام نموذج استنتاج على الجهاز لتقديم العروض:

    • الخصوصية المحسّنة
    • السياق المحلي
    • الاستدلال بدون تكلفة
    • وظائف بلا إنترنت

  • استخدام عروض الوظائف المختلطة:

    • الوصول إلى% 100 من جمهورك، بغض النظر عن مدى توفّر النموذج على الجهاز أو الاتصال بالإنترنت

الإمكانات والميزات المتوافقة مع الاستدلال على الجهاز:

لا تتيح الاستنتاجات على الجهاز سوى إنشاء النصوص في جولة واحدة (وليس المحادثات)، مع إمكانية بث المحتوى أو عدم بثه. تتيح هذه الميزة إمكانات إنشاء النصوص التالية:

يمكنك أيضًا إنشاء ناتج منظَّم، بما في ذلك JSON وenums.

قبل البدء

يُرجى مراعاة ما يلي:

بدء استخدام localhost

توضّح خطوات البدء هذه الإعدادات العامة المطلوبة لأي طلب موجّه مدعوم تريد إرساله.

الخطوة 1: إعداد Chrome وPrompt API للاستدلال على الجهاز

  1. احرِص على استخدام إصدار حديث من Chrome. يمكنك إجراء التحديث من خلال الانتقال إلى chrome://settings/help.
    تتوفّر ميزة "الاستدلال على الجهاز" في الإصدار 139 من Chrome والإصدارات الأحدث.

  2. فعِّل النموذج المتعدّد الوسائط على الجهاز فقط من خلال ضبط العلامة التالية على مفعَّل:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

  3. أعِد تشغيل Chrome.

  4. (اختياري) نزِّل النموذج على الجهاز قبل الطلب الأول.

    إنّ Prompt API مدمَج في Chrome، ولكن النموذج المتوفّر على الجهاز غير متاح تلقائيًا. إذا لم يسبق لك تنزيل النموذج قبل طلبك الأول للاستدلال على الجهاز، سيبدأ الطلب تلقائيًا في تنزيل النموذج في الخلفية.

الخطوة 2: إعداد مشروع على Firebase وربط تطبيقك بـ Firebase

  1. سجِّل الدخول إلى Firebase وحدة التحكّم، ثم اختَر مشروعك على Firebase.

  2. في وحدة تحكّم Firebase، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي.

  3. انقر على Get started (البدء) لتشغيل سير عمل موجّه يساعدك في إعداد واجهات برمجة التطبيقات المطلوبة والموارد لمشروعك.

  4. إذا طُلب منك ذلك، اتّبِع التعليمات الظاهرة على الشاشة لتسجيل تطبيقك وإضافة إعدادات Firebase إليه.

  5. عندما يُطلب منك اختيار "مقدّم خدمة Gemini API"، ننصحك باختيار Gemini Developer API، ما يتيح لك البدء بسرعة بدون أي تكلفة.

    في أي وقت لاحق، يمكنك إعداد Vertex AI Gemini API (ومتطلباته المتعلقة بالفوترة).

  6. واصِل العمل في سير العمل لإعداد واجهات برمجة التطبيقات والخدمات المرتبطة المطلوبة لتطبيق Firebase AI Logic.

    اعتبارًا من أوائل يوليو 2026، ستفرض هذه المرحلة من سير العمل تلقائيًا استخدام Firebase App Check مع AI Logic، وهي خدمة مهمة تساعد في حماية Gemini API عند الوصول إليه مباشرةً من تطبيقك. وكجزء من خطوات البدء (راجِع الخطوات لاحقًا في هذا الدليل)، عليك ضبط App Check موفر تصحيح الأخطاء لتطوير التطبيق محليًا عند فرض استخدام App Check.

  7. انتقِل إلى الخطوة التالية في هذا الدليل لإضافة حِزم SDK المطلوبة إلى تطبيقك.

الخطوة 3: إضافة حزمة SDK

تتيح مكتبة Firebase الوصول إلى واجهات برمجة التطبيقات للتفاعل مع النماذج التوليدية. يتم تضمين المكتبة كجزء من حزمة تطوير البرامج (SDK) على الإنترنت لبرنامج Firebase JavaScript.

  1. ثبِّت حزمة تطوير البرامج (SDK) على الإنترنت من Firebase JS باستخدام npm:

    npm install firebase

  2. إعداد Firebase في تطبيقك:

    import { initializeApp } from "firebase/app";
import { initializeAppCheck, DebugProvider } from "firebase/app-check";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

الخطوة 3: ضبط موفّر تصحيح الأخطاء App Check للتطوير المحلي

اعتبارًا من أوائل يوليو 2026، وفي إطار سير عمل الإعداد الموجّه لميزة AI Logic في Play Console، سيتم فرض استخدام Firebase App Check تلقائيًا لحماية Gemini API. للتطوير على الجهاز، عليك ضبط App Check موفّر تصحيح الأخطاء لتجاوز عملية التصديق مع الحفاظ على فرض App Check.

في ما يلي كيفية استخدام موفّر تصحيح الأخطاء أثناء تشغيل تطبيقك من localhost بشكل تفاعلي (على سبيل المثال، أثناء التطوير المحلي):

  1. في إصدار تصحيح الأخطاء، فعِّل وضع تصحيح الأخطاء من خلال ضبط self.FIREBASE_APPCHECK_DEBUG_TOKEN على true قبل بدء App Check. على سبيل المثال:

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(app, { /* App Check options */ });

  2. انتقِل إلى تطبيق الويب على جهازك وافتح أدوات المطوّرين في المتصفّح. في وحدة تصحيح الأخطاء، سيظهر رمز تصحيح الأخطاء:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. سجِّل رمز تصحيح الأخطاء في App Check باتّباع الخطوات التالية:

    1. في Firebase، انتقِل إلى علامة التبويب الأمان > App Check > التطبيقات.

    2. ابحث عن تطبيقك، وانقر على قائمة الخيارات الإضافية ()، ثم اختَر إدارة رموز تصحيح الأخطاء.

    3. اتّبِع التعليمات الظاهرة على الشاشة لتسجيل رمز تصحيح الأخطاء.

للحصول على تفاصيل حول مقدّم خدمة تصحيح الأخطاء (بما في ذلك كيفية الحصول على رمز تصحيح أخطاء جديد)، يُرجى الاطّلاع على مستندات App Check الرسمية.

الخطوة 4: تهيئة الخدمة وإنشاء مثيل للنموذج

انقر على موفّر Gemini API لعرض المحتوى والرمز الخاصين بموفّر الخدمة على هذه الصفحة.

يجب إعداد ما يلي قبل إرسال طلب إلى النموذج:

  1. ابدأ الخدمة لمقدّم واجهة برمجة التطبيقات الذي اخترته.

  2. أنشئ مثيلاً من GenerativeModel. تأكَّد من ضبط mode على إحدى القيم التالية:

    • PREFER_ON_DEVICE: استخدِم النموذج المتوفّر على الجهاز إذا كان متاحًا، وإلا استخدِم النموذج المستضاف على السحابة الإلكترونية.

    • ONLY_ON_DEVICE: استخدام النموذج على الجهاز إذا كان متاحًا، وإلا إصدار استثناء

    • PREFER_IN_CLOUD: استخدِم النموذج المستضاف على السحابة الإلكترونية إذا كان متاحًا، وإلا استخدِم النموذج المتوفّر على الجهاز.

    • ONLY_IN_CLOUD: استخدِم النموذج المستضاف على السحابة الإلكترونية إذا كان متاحًا، وإلا اطرح استثناءً.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

الخطوة 5: تهيئة النموذج على الجهاز

يجب استدعاء initializeDeviceModel() بعد أو عند تفاعل المستخدم النهائي مع الصفحة (مثل النقر على زر) وقبل إرسال طلب إلى النموذج. يمكنك الاطّلاع على مزيد من المعلومات حول متطلبات تفعيل المستخدم في مستندات Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

الخطوة 6: إرسال طلب إلى نموذج

يوضّح لك هذا القسم كيفية إرسال أنواع مختلفة من المدخلات لإنشاء أنواع مختلفة من المخرجات، بما في ذلك:

إذا أردت إنشاء إخراج منظَّم (مثل JSON أو تعدادات)، استخدِم أحد الأمثلة التالية على "إنشاء نص"، بالإضافة إلى ضبط النموذج للرد وفقًا لمخطط متوفّر.

إنشاء نص من إدخال نصي فقط

قبل تجربة هذا النموذج، تأكَّد من إكمال قسم البدء في هذا الدليل.

يمكنك استخدام generateContent() لإنشاء نص من طلب يتضمّن نصًا:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

يُرجى العِلم أنّ السمة Firebase AI Logic تتيح أيضًا بث الردود النصية باستخدام generateContentStream (بدلاً من generateContent).

إنشاء نص من إدخال نصي ومرئي (متعدد الوسائط)

قبل تجربة هذا النموذج، تأكَّد من إكمال قسم البدء في هذا الدليل.

يمكنك استخدام generateContent() لإنشاء نص من طلب يتضمّن ملفات نصية وملفات صور، وذلك من خلال توفير mimeType لكل ملف إدخال والملف نفسه.

أنواع صور الإدخال المتوافقة مع الاستدلال على الجهاز هي PNG وJPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

يُرجى العِلم أنّ السمة Firebase AI Logic تتيح أيضًا بث الردود النصية باستخدام generateContentStream (بدلاً من generateContent).

السماح للمستخدمين النهائيين بتجربة الميزة

لكي يتمكّن المستخدمون النهائيون من تجربة الميزة في تطبيقك، عليك التسجيل في برنامج "التجارب الأصلية" في Chrome. يُرجى العِلم أنّ هذه الفترات التجريبية محدودة المدة والاستخدام.

  1. سجِّل في مرحلة التجربة والتقييم في Chrome لواجهة برمجة التطبيقات Prompt API. سيتم منحك رمزًا مميزًا.

  2. قدِّم الرمز المميّز على كل صفحة ويب تريد تفعيل الميزة التجريبية عليها. استخدِم أحد الخيارات التالية:

    • قدِّم الرمز المميز كعلامة وصفية في العلامة <head>: <meta http-equiv="origin-trial" content="TOKEN">

    • قدِّم الرمز المميز كعنوان HTTP: Origin-Trial: TOKEN

    • قدِّم الرمز المميز برمجيًا.

ما هي الإجراءات الأخرى التي يمكنك تنفيذها؟

يمكنك استخدام خيارات وإمكانات إضافية متنوعة لتكوين تجاربك المختلطة:

الميزات غير المتوفّرة بعد للاستدلال على الجهاز

بما أنّ هذه الميزة هي إصدار معاينة، لن تتوفّر جميع إمكانات حزمة تطوير البرامج (SDK) على الويب للاستدلال على الجهاز. لا تتوفّر الميزات التالية بعد للاستدلال على الجهاز (ولكنها تتوفّر عادةً للاستدلال المستند إلى السحابة الإلكترونية).

  • إنشاء نص من أنواع إدخال ملفات الصور غير JPEG وPNG

    • يمكن الرجوع إلى النموذج المستضاف على السحابة الإلكترونية، ولكن سيؤدي وضع ONLY_ON_DEVICE إلى ظهور خطأ.

  • إنشاء نص من مدخلات الصوت والفيديو والمستندات (مثل ملفات PDF)

    • يمكن الرجوع إلى النموذج المستضاف على السحابة الإلكترونية، ولكن سيؤدي وضع ONLY_ON_DEVICE إلى ظهور خطأ.

  • إنشاء صور باستخدام نماذج Gemini أو Imagen

    • يمكن الرجوع إلى النموذج المستضاف على السحابة الإلكترونية، ولكن سيؤدي وضع ONLY_ON_DEVICE إلى ظهور خطأ.

  • توفير الملفات باستخدام عناوين URL في الطلبات المتعددة الوسائط يجب تقديم الملفات كبيانات مضمّنة لنماذج على الجهاز.

  • محادثة متعدّدة الجولات

    • يمكن الرجوع إلى النموذج المستضاف على السحابة الإلكترونية، ولكن سيؤدي وضع ONLY_ON_DEVICE إلى ظهور خطأ.

  • البث ثنائي الاتجاه مع "Gemini Live API"

  • تزويد النموذج بالأدوات التي تساعده في إنشاء الردود (مثل استدعاء الدوال، وتنفيذ الرموز، وسياق عنوان URL، وGrounding with Google Search، وGrounding with Google Maps)

  • عدد الرموز المميّزة

    • يُظهر دائمًا خطأً. سيختلف العدد بين النماذج المستضافة على السحابة الإلكترونية والنماذج التي تعمل على الجهاز، لذا لا يتوفّر خيار احتياطي سهل الاستخدام.

  • ميزة مراقبة الذكاء الاصطناعي في وحدة تحكّم Firebase للاستدلال على الجهاز

    • يُرجى العِلم أنّه يمكن مراقبة أي استنتاج يتم باستخدام النماذج المستضافة على السحابة الإلكترونية تمامًا مثل أي استنتاج آخر يتم باستخدام حزمة تطوير البرامج (SDK) Firebase AI Logic للعميل على الويب.


تقديم ملاحظات حول تجربتك مع Firebase AI Logic