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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

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

• بعد تنفيذ الميزة، يمكنك السماح للمستخدمين النهائيين بتجربة الميزة في تطبيقك الفعلي.

بدء استخدام localhost

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

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

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

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

   • 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 console، ثم اختَر مشروعك على Firebase.

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

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

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

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

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

2. في وحدة تحكّم Firebase، انتقِل إلى صفحة Firebase AI Logic.

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

4. اضبط مشروعك لاستخدام موفّر "Gemini API".

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

   بالنسبة إلى Gemini Developer API، ستفعّل وحدة التحكّم واجهات برمجة التطبيقات المطلوبة وتنشئ مفتاح واجهة برمجة تطبيقات Gemini في مشروعك.
   لا تُضِف مفتاح واجهة برمجة التطبيقات Gemini هذا إلى قاعدة رموز تطبيقك. مزيد من المعلومات

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

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

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

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

1. ثبِّت حزمة Firebase JS SDK للويب باستخدام 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. يُرجى التأكّد من تنفيذ ما يلي:

   1. استدعاء getGenerativeModel بعد تفاعل المستخدم النهائي أو عند حدوثه (مثل النقر على زر). هذا شرط أساسي لاستخدام inferenceMode.

   2. اضبط قيمة 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

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

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

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

إذا أردت إنشاء إخراج منظَّم (مثل 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 Origin Trials. يُرجى العِلم أنّ هذه الفترات التجريبية محدودة المدة والاستخدام.

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

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

   • قدِّم الرمز المميز كعلامة وصفية في العلامة <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 والربط بمحرك بحث Google)

• احتساب الرموز المميّزة

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

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

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

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