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

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

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

يُرجى العِلم أنّ الاستدلال على الجهاز فقط من خلال "Firebase AI Logic" متاح لتطبيقات الويب التي تستخدم الإصدار 12.5.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لـ "Firebase AI Logic" والتي تعمل على متصفّح Chrome على الكمبيوتر المكتبي (الإصدار 139 أو إصدار أحدث).

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

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

بناءً على حالات استخدام تطبيقك، يمكنك الاستفادة من عدة مزايا للتجارب على الجهاز فقط أو التجارب المختلطة:

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

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

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

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

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

يُرجى مراجعة قائمة الميزات غير المتاحة بعد للاستنتاج المختلط أو على الجهاز فقط في أسفل هذه الصفحة.

واجهات برمجة التطبيقات والمنصات المتوافقة

توضّح الأقسام التالية واجهات برمجة التطبيقات المتوافقة، بالإضافة إلى المنصات والمتصفّحات المتوافقة.

واجهات برمجة التطبيقات المتوافقة للاستنتاج في السحابة الإلكترونية مقابل الاستنتاج على الجهاز فقط

  • يستخدم الاستنتاج في السحابة الإلكترونية مقدّم خدمة Gemini API الذي اخترته (إما Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI)).

  • يستخدم الاستنتاج على الجهاز فقط Prompt API من Chrome.

المنصات والمتصفّحات المتوافقة

بالنسبة إلى الاستدلال على الجهاز فقط (الذي يستخدم Prompt API من Chrome)، يجب أن يستخدم المستخدم النهائي لتطبيقك متصفّح Chrome على الكمبيوتر المكتبي (الإصدار 139 أو إصدار أحدث). يمكنك الاطّلاع على مزيد من المعلومات في مستندات Chrome.

البدء على localhost

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

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

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

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

  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. ابحث عن تطبيقك، وانقر على القائمة الكاملة ()، ثم اختَر إدارة الرموز المميّزة لتصحيح الأخطاء.

    3. اتّبِع التعليمات الظاهرة على الشاشة لتسجيل الرمز المميّز لتصحيح الأخطاء.

لمعرفة تفاصيل حول مقدّم خدمة تصحيح الأخطاء (بما في ذلك كيفية الحصول على رمز مميّز جديد لتصحيح الأخطاء)، يُرجى الاطّلاع على مستندات App Check الرسمية.

الخطوة 5: إعداد الخدمة وإنشاء مثيل للنموذج

انقر على مزوّد خدمة Gemini API للاطّلاع على المحتوى والرمز البرمجي الخاصَّين بمزوّد الخدمة على هذه الصفحة.

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

  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).

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

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

الميزات غير المتاحة بعد

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

الميزات غير المتاحة بعد لعمليات التنفيذ المختلطة

لا يمكن استخدام الميزات التالية مع عمليات التنفيذ المختلطة (سواء على الجهاز أو من خلال الاحتياطي السحابي):

  • Gemini Live API: لا يتوفّر البث المباشر الثنائي الاتجاه في الوقت الفعلي.

  • نماذج الطلبات على الخادم: لا تتوفّر نماذج الطلبات على الخادم المُدار.

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

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

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

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

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

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

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

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

    • يمكن الرجوع إلى النموذج المستضاف على السحابة الإلكترونية، ولكن سيظهر خطأ في وضع ONLY_ON_DEVICE.
  • تزويد النموذج بأدوات لمساعدته في إنشاء ردوده (مثل استدعاء الدوال، وتنفيذ الرموز البرمجية، وسياق عناوين URL، والربط بـ Google Search، والربط بـ Google Maps)

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

قيود إضافية

بالإضافة إلى ما سبق، يفرض الاستنتاج على الجهاز فقط القيود التالية:

  • يجب أن يستخدم المستخدم النهائي لتطبيقك متصفّح Chrome على الكمبيوتر المكتبي (الإصدار 139 أو إصدار أحدث) مع تفعيل العلامات المطلوبة.

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


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