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

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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

• تستخدم عملية الاستدلال باستخدام نموذج على الجهاز واجهة برمجة التطبيقات 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. يُرجى العِلم أنّ هذه الفترات التجريبية محدودة المدة والاستخدام.

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

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

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

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

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

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

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

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

تستخدِم الأمثلة في الإعداد العام الوضع PREFER_ON_DEVICE، ولكن هذا الوضع هو واحد فقط من أوضاع الاستدلال الأربعة المتاحة.

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

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });
  

• ONLY_ON_DEVICE: استخدام النموذج على الجهاز إذا كان متاحًا، وإلا إصدار استثناء

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
  

• ‫PREFER_IN_CLOUD: استخدِم النموذج المستضاف على السحابة الإلكترونية إذا كان متاحًا، وإلا استخدِم النموذج المتوفّر على الجهاز.

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });
  

• ONLY_IN_CLOUD: استخدِم النموذج المستضاف على السحابة الإلكترونية إذا كان متاحًا، وإلا اطرح استثناءً.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });
  

تحديد ما إذا تم استخدام الاستدلال على الجهاز أو في السحابة

إذا كنت تستخدم وضعَي الاستنتاج PREFER_ON_DEVICE أو PREFER_IN_CLOUD، قد يكون من المفيد معرفة الوضع الذي تم استخدامه لطلبات معيّنة. يتم توفير هذه المعلومات من خلال السمة inferenceSource لكل ردّ (تتوفّر بدءًا من الإصدار 12.5.0 من حزمة تطوير البرامج (SDK) المستندة إلى JavaScript).

عند الوصول إلى هذه السمة، ستكون القيمة المعروضة إما ON_DEVICE أو IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

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

نموذج الاستضافة التلقائي على السحابة الإلكترونية هو gemini-2.5-flash-lite (بدءًا من الإصدار 12.8.0 من حزمة تطوير البرامج (SDK) في JavaScript).

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

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

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

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

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

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

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

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

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

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

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

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

تتوفّر إمكانية إنشاء إخراج منظَّم (مثل 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: InferenceMode.INFERENCE_MODE,
  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

• تزويد النموذج بأدوات لمساعدته في إنشاء الرد (مثل استدعاء الدوال وتنفيذ الرموز البرمجية وسياق عنوان URL والربط بمحرك بحث Google)

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

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

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

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

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