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

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

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

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

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

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

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

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

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

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

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

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

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

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

• إنشاء نصوص من إدخالات نصية وصور، وتحديدًا أنواع صور الإدخال بتنسيقات JPEG وPNG

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

قبل البدء

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

• تستخدم عملية الاستدلال باستخدام نموذج على الجهاز فقط واجهة برمجة التطبيقات Prompt API من Chrome، بينما تستخدم عملية الاستدلال باستخدام نموذج مستضاف على السحابة الإلكترونية موفّر Gemini API الذي اخترته (إما Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI)).

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

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

بدء استخدام 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، ولكن النموذج الذي يعمل على الجهاز فقط غير متاح تلقائيًا. إذا لم يسبق لك تنزيل النموذج قبل طلبك الأول للاستنتاج على الجهاز فقط، سيبدأ الطلب تلقائيًا في تنزيل النموذج في الخلفية.

   عرض التعليمات لتنزيل النموذج على الجهاز فقط

   1. افتح أدوات المطوّرين > وحدة التحكّم.

   2. نفِّذ ما يلي:

      await LanguageModel.availability();
      

   3. تأكَّد من أنّ الناتج هو available أو downloading أو downloadable.

   4. إذا كان الناتج downloadable، ابدأ تنزيل النموذج بتنفيذ الأمر التالي:

      await LanguageModel.create();
      

   5. يمكنك استخدام monitor callback التالي للاستماع إلى تقدّم التنزيل والتأكّد من أنّ النموذج available قبل تقديم الطلبات:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

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

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

   ليس لديك مشروع على Firebase؟

   إذا لم يكن لديك مشروع على Firebase، انقر على الزر لإنشاء مشروع جديد على Firebase، ثم استخدِم أحد الخيارَين التاليَين:

   • الخيار 1: أنشئ مشروعًا جديدًا بالكامل على Firebase (ومشروعًا أساسيًا Google Cloud تلقائيًا) من خلال إدخال اسم مشروع جديد في الخطوة الأولى من سير العمل.

   • الخيار 2: "إضافة Firebase" إلى مشروع Google Cloud حالي من خلال النقر على إضافة Firebase إلى مشروع Google Cloud (في أسفل الصفحة). في الخطوة الأولى من سير العمل، ابدأ بإدخال اسم المشروع الخاص بالمشروع الحالي، ثم اختَر المشروع من القائمة المعروضة.

   أكمِل الخطوات المتبقية من سير العمل الظاهر على الشاشة لإنشاء مشروع على Firebase. يُرجى العِلم أنّه عند مطالبتك بذلك، لا تحتاج إلى إعداد Google Analytics لاستخدام حِزم تطوير البرامج Firebase AI Logic.

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

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

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

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

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

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 لتطبيقات الويب باستخدام npm:

   npm install firebase
   

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

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } 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);
   

الخطوة 4: ضبط 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(firebaseApp, { /* 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، انتقِل إلى علامة التبويب الأمان > فحص التطبيقات > التطبيقات.

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

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

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

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

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

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

الخطوة 6: إعداد النموذج على الجهاز فقط

يجب استدعاء 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}%`)
);

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

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

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

إذا أردت إنشاء إخراج منظَّم (مثل 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).

ما هي المهام الأخرى التي يمكن لمساعد Google تنفيذها؟

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

• ضبط وضع الاستدلال

• تجاوز نموذج الاحتياط التلقائي المستضاف على السحابة الإلكترونية

• استخدام إعدادات النموذج للتحكّم في الردود (مثل درجة الحرارة)

• إنشاء ناتج منظَّم (مثل JSON)

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

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

• إنشاء نصّ من إنشاء الذكاء الاصطناعي من أنواع ملفات الصور التي لا تكون بتنسيق JPEG أو PNG

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

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

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

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

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

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

• محادثة مترابطة

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

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

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

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

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

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

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

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