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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

• توضّح هذه الصفحة كيفية البدء في التطوير باستخدام المضيف المحلي (يمكنك الاطّلاع على مزيد من المعلومات حول استخدام واجهات برمجة التطبيقات على المضيف المحلي في مستندات 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 Cloud الأساسي تلقائيًا) من خلال إدخال اسم مشروع جديد في الخطوة الأولى من سير العمل.Google 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، ما يتيح لك البدء بسرعة بدون أي تكلفة.

   في أي وقت لاحق، يمكنك دائمًا إعداد 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) هذه حزمة تطوير البرامج (SDK) من Firebase JavaScript للويب.

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

   npm install firebase
   

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

   import { initializeApp } from "firebase/app";
   
   // 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: إعداد الخدمة وإنشاء مثيل للنموذج

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

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. قدِّم الرمز المميّز في كل صفحة ويب تريد تفعيل الميزة التجريبية لها. استخدِم أحد الخيارات التالية:

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

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

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

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

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

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

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

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

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

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

بما أنّ هذا الإصدار هو إصدار معاينة، لا تتوفّر جميع إمكانات حزمة تطوير البرامج (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 للاستنتاج على الجهاز

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

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