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

يمكنك إنشاء تطبيقات ويب وميزات مستندة إلى الذكاء الاصطناعي باستخدام الاستنتاج المختلط من خلال 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).

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

البدء على 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 التالية للاستماع إلى مستوى تقدّم عملية التنزيل والتأكّد من أنّ النموذج 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 لاستخدام حِزم تطوير البرامج (SDK) في Firebase AI Logic.

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

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

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

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

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

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

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

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

الخطوة 3: إضافة حزمة تطوير البرامج (SDK)

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

1. ثبِّت حزمة تطوير البرامج (SDK) لبرنامج Firebase JS للويب باستخدام 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 للتطوير على الجهاز

كجزء من سير عمل الإعداد الموجَّه لـ "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 {
    type: "inlineData",
    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 Nano Banana

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

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

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

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

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

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

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

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

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

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

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