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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك أيضًا إنشاء إخراج منظَّم، بما في ذلك JSON والقيم المُعدَّدة.

قبل البدء

يُرجى أخذ ما يلي في الاعتبار:

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

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

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

البدء على المضيف المحلي

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

الخطوة 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 التالية للاستماع إلى تقدّم التنزيل والتأكّد من أنّ النموذج 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 CloudGoogle Cloud الأساسي تلقائيًا) من خلال إدخال اسم مشروع جديد في الخطوة الأولى من سير العمل.

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

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

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

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

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 SDK للويب.

1. ثبِّت حزمة Firebase JS SDK للويب باستخدام 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 في وحدة التحكّم، يتم فرض 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).

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

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

• ضبط وضع الاستنتاج

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

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

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

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

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

• إنشاء نص من أنواع ملفات الصور المدخلة غير 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 للاستنتاج على الجهاز.

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

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