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

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

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

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

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

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

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

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

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

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

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

• إنشاء المحتوى في محادثة واحدة، سواء كان قابلاً للبث أو غير قابل للبث
• إنشاء نص من إدخال نصي فقط
• إنشاء نص من إدخال نص وصورة، وتحديدًا أنواع صور الإدخال بتنسيقات JPEG وPNG
• إنشاء ناتج منظَّم، بما في ذلك JSON وenums

البدء

يوضّح لك هذا الدليل كيفية بدء استخدام Firebase AI Logic حزمة تطوير البرامج (SDK) للويب لإجراء استدلال مختلط.

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

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

1. نزِّل أحدث إصدار من الإصدار التجريبي من Chrome.

   تتوفّر ميزة الاستدلال على الجهاز من الإصدار 138 من Chrome والإصدارات الأحدث.

2. فعِّل واجهة برمجة التطبيقات Prompt API لمثيل Chrome من خلال ضبط العلامات التالية:

   • chrome://flags/#optimization-guide-on-device-model: اضبطها على مفعَّلة.
   • chrome://flags/#prompt-api-for-gemini-nano: اضبطها على مفعَّلة.

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

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

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input: اضبط القيمة على مفعَّل.

4. التحقّق من صحة واجهة برمجة التطبيقات محليًا:

   1. أعِد تشغيل Chrome.

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

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

      await LanguageModel.availability();
      

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

   5. إذا كانت النتيجة downloadable، يمكنك بدء تنزيل النموذج من خلال تشغيل await LanguageModel.create();. وفي حال عدم إجراء ذلك، سيبدأ الطلب الأول للاستدلال على الجهاز عملية تنزيل النموذج في الخلفية، ما قد يستغرق عدة دقائق.

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

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

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

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

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

   • الخيار 2: "إضافة Firebase" إلى مشروع Google Cloud حالي من خلال اختيار اسم مشروعك Google Cloud من القائمة المنسدلة في الخطوة الأولى من سير عمل "إنشاء مشروع"

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

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

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

4. اختَر مقدّم خدمة "Gemini API" الذي تريد استخدامه مع حِزم تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic. ويمكنك إعداد واستخدام موفّر واجهة برمجة التطبيقات الآخر في وقت لاحق إذا أردت ذلك.

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

   • Vertex AI Gemini API — مطلوب إعداد الفوترة (يتطلّب خطة تسعير Blaze للدفع حسب الاستخدام)
     ستساعدك وحدة التحكّم في إعداد الفوترة وتفعيل واجهات برمجة التطبيقات المطلوبة في مشروعك.

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

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

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

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

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

   يتم إصدار ميزة الوضع المختلط ضمن علامة npm مختلفة، لذا احرص على تضمينها في أمر التثبيت.

   npm install firebase@eap-ai-hybridinference
   

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: تهيئة الخدمة وإنشاء مثيل نموذج

قبل إرسال طلب إلى نموذج Gemini، عليك تهيئة الخدمة لمقدّم خدمة واجهة برمجة التطبيقات الذي اخترته وإنشاء مثيل GenerativeModel.

اضبط قيمة mode على إحدى القيم التالية:

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

• ‫only_on_device: تضبط حزمة تطوير البرامج (SDK) لاستخدام النموذج على الجهاز أو عرض استثناء.

• ‫only_in_cloud: تضبط هذه السمة حزمة SDK على عدم استخدام النموذج على الجهاز مطلقًا.

عند استخدام prefer_on_device أو only_in_cloud، يكون النموذج المستضاف على السحابة الإلكترونية gemini-2.0-flash-lite تلقائيًا، ولكن يمكنك تجاوز الإعداد التلقائي.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: "prefer_on_device" });

إرسال طلب إلى نموذج

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

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

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

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

يمكنك استخدام 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();

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

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

استخدام أوضاع استنتاج بديلة

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

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

  const model = getGenerativeModel(ai, { mode: "only_on_device" });
  

• استخدِم الوضع only_in_cloud لكي تتمكّن حزمة SDK من استخدام نموذج مستضاف على السحابة الإلكترونية فقط.

  const model = getGenerativeModel(ai, { mode: "only_in_cloud" });
  

تجاوز النموذج الاحتياطي التلقائي

عند استخدام وضع prefer_on_device، ستعود حزمة تطوير البرامج (SDK) إلى استخدام نموذج مستضاف على السحابة الإلكترونية إذا لم يتوفّر نموذج على الجهاز. النموذج التلقائي الاحتياطي المستضاف على السحابة الإلكترونية هو gemini-2.0-flash-lite. ويكون هذا النموذج المستضاف على السحابة الإلكترونية هو النموذج التلقائي أيضًا عند استخدام وضعonly_in_cloud.

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

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
  }
});

يمكنك الاطّلاع على أسماء جميع نماذج Gemini المتوافقة.

استخدام إعدادات النموذج للتحكّم في الردود

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

يتم الاحتفاظ بالإعدادات طوال مدة تشغيل الجهاز الافتراضي. إذا أردت استخدام إعداد مختلف، أنشئ مثيلاً جديدًا من GenerativeModel باستخدام هذا الإعداد.

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

استخدِم الخيار inCloudParams لضبط نموذج Gemini مستضاف على السحابة الإلكترونية. مزيد من المعلومات عن المَعلمات المتاحة

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    temperature: 0.8,
    topK: 10
  }
});

ضبط إعدادات نموذج على الجهاز

يُرجى العِلم أنّ الاستنتاج باستخدام نموذج على الجهاز يستخدِم Prompt API من Chrome.

استخدِم الخيار onDeviceParams لضبط نموذج على الجهاز. مزيد من المعلومات عن المَعلمات المتاحة

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

ضبط إعدادات الإخراج المنظَّم

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

بالنسبة إلى الاستدلال المختلط، استخدِم كلّاً من inCloudParams و onDeviceParams لإعداد النموذج للردّ بناتج منظَّم. بالنسبة إلى الأوضاع الأخرى، استخدِم الإعدادات المناسبة فقط.

• بالنسبة إلى inCloudParams: حدِّد responseMimeType المناسب (في هذا المثال، application/json) بالإضافة إلى responseSchema الذي تريد أن يستخدمه النموذج.

• بالنسبة إلى onDeviceParams: حدِّد responseConstraint الذي تريد أن يستخدمه النموذج.

إخراج JSON

يعدّل المثال التالي مثال إخراج JSON العام للاستدلال المختلط:

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

ناتج التعداد

كما هو موضّح أعلاه، ولكن مع تعديل المستندات حول إخراج التعداد للاستدلال المختلط:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...

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

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

• إنشاء نص من أنواع إدخال ملفات الصور غير JPEG وPNG

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

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

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

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

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

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

• محادثة متعدّدة الأدوار

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

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

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

• استدعاء الدوال

  • يتوفر قريبًا!

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

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

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

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

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