إنشاء وكيل دعم عملاء مستنِد إلى الذكاء الاصطناعي باستخدام Firebase AI Logic

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستضيف أداة دردشة ذكية لدعم العملاء إلى متجر للتجارة الإلكترونية يبيع معدات خارجية ويُسمى Rugged Terrain Guide. ستستخدم Firebase AI Logic لإنشاء هذا الوكيل، وستتعرّف على كيفية إعداد نموذج طلب من جهة الخادم (product-agent) يتعامل مع شخصية الذكاء الاصطناعي وقواعد ميزانية التهدئة الصارمة، ويستخدم كتالوج المنتجات بشكل ديناميكي كسياق.

الإجراءات التي ستتّخذها:

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

يلزمك ما يلي:

  • متصفّح ويب، مثل Chrome
  • معرفة أساسية بلغة TypeScript وNode.js
  • محرّر نصوص أو بيئة تطوير متكاملة (IDE) من اختيارك يُعدّ Antigravity خيارًا جيدًا.

2. الحصول على الرمز الأوّلي

  1. في نافذة Terminal، أنشئ نسخة طبق الأصل من مستودع الرمز الأولي:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. انتقِل إلى دليل الرمز وثبِّت الموارد التابعة:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3- إعداد مشروع Firebase

إنشاء مشروع Firebase

  1. سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام حساب Google.
  2. انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال، rugged-terrain-ai).
  3. انقر على متابعة.
  4. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
  5. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase").
  6. في هذا الدرس العملي، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
  7. انقر على إنشاء مشروع، وانتظِر إلى أن يتم توفير مشروعك، ثم انقر على متابعة.

ترقية خطة أسعار Firebase

لاستخدام خدمات Firebase في هذا الدرس العملي، يجب أن يكون مشروع Firebase الخاص بك ضمن خطة التسعير "الدفع حسب الاستخدام" (Blaze)، ما يعني أنّه مرتبط بحساب فوترة في Cloud.

لترقية مشروعك إلى خطة Blaze، اتّبِع الخطوات التالية:

  1. في "وحدة تحكّم Firebase"، اختَر ترقية خطتك.
  2. اختَر خطة Blaze. اتّبِع التعليمات الظاهرة على الشاشة لربط حساب فوترة على Cloud بمشروعك.
    إذا كان عليك إنشاء حساب فوترة على Cloud كجزء من عملية الترقية هذه، قد تحتاج إلى الرجوع إلى مسار الترقية في وحدة تحكّم Firebase لإكمال عملية الترقية.

4. إعداد خدمات Firebase وربط تطبيقك

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

إعداد "مساحة تخزين سحابية لـ Firebase"

يستخدم هذا الدرس التطبيقي حول الترميز مساحة تخزين سحابية لـ Firebase لتخزين أوصاف المنتجات.

  1. في "وحدة تحكّم Firebase"، انتقِل إلى قواعد البيانات ومساحة التخزين > مساحة التخزين.
  2. انقر على البدء.
  3. اختَر موقعًا جغرافيًا لحزمة التخزين التلقائية.
    يمكن للحِزم في US-WEST1 وUS-CENTRAL1 وUS-EAST1 الاستفادة من الفئة"دائمًا مجانية" في Google Cloud Storage. تخضع الحِزم في جميع المواقع الجغرافية الأخرى لأسعار واستخدام Google Cloud Storage.
  4. انقر على وضع الإنتاج. في الخطوات أدناه مباشرةً، ستعدّل "قواعد الأمان" هذه لتكون خاصة بهذا الدرس التطبيقي حول الترميز.
  5. انقر على إنشاء.
  6. تعديل "قواعد الأمان":
    1. بعد توفير الحزمة، انتقِل إلى علامة التبويب القواعد.
    2. انسخ القواعد التالية ثم الصِقها:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. انقر على نشر.
  7. حمِّل أوصاف المنتجات من رمز البداية:
    1. انقر على علامة التبويب الملفات لحزمة التخزين.
    2. انقر على تحميل ملف، ثم حمِّل ملف products.txt من رمز البداية. يمكن العثور على هذا الملف في: src/data/products.txt.

ضبط Firebase AI Logic

‫Firebase AI Logic هي خدمة Firebase الرئيسية التي ستستخدمها في هذا الدرس العملي.

  1. في "وحدة تحكّم Firebase"، انتقِل إلى خدمات الذكاء الاصطناعي > AI Logic.
  2. انقر على البدء.
  3. في بطاقة Vertex AI Gemini API، انقر على البدء باستخدام واجهة برمجة التطبيقات هذه واتّبِع التعليمات الظاهرة على الشاشة. سيؤدي هذا الإجراء إلى تفعيل واجهات برمجة التطبيقات المطلوبة لتتمكّن من استخدام Firebase AI Logic مع Vertex AI Gemini API.
  4. (اختياري) اختَر تتبّع استخدام الذكاء الاصطناعي لتتمكّن من الاطّلاع على مقاييس واستخدامات مختلفة على مستوى التطبيق من أجل الحصول على إمكانية رؤية شاملة لطلباتك من خلال Firebase AI Logic.

ربط الرمز البرمجي بمشروع Firebase

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

  1. عندما يُطلب منك ذلك في مسار إعداد Firebase AI Logic، انقر على رمز الويب () لتسجيل تطبيق ويب جديد.
  2. أدخِل اسمًا للتطبيق (مثلاً، Rugged Web).
  3. انسخ عنصر firebaseConfig من تعليمات الإعداد.

بعد ذلك، عدِّل الرمز الأولي:

  1. في أداة تعديل الرموز، افتح src/firebase.ts.
  2. استبدِل firebaseConfig الحالي بالرمز الذي نسخته من وحدة تحكّم Firebase.

يجب أن يظهر ملفك على النحو التالي:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new VertexAIBackend() });

5- إنشاء نموذج الطلب من جهة الخادم

بدلاً من الترميز الثابت لطلبات الذكاء الاصطناعي المعقّدة في تطبيق العميل، ستستخدم بنية Dotprompt لإدارة التعليمات بأمان على الخادم.

يمنع ذلك المستخدمين النهائيين من الاطّلاع على قواعد "ميزانية التهدئة" السرية.

  1. في وحدة تحكّم Firebase، انتقِل إلى قسم Vertex AI أو إدارة الطلبات.
  2. أنشئ نموذج طلب جديدًا وسمِّه product-agent.
  3. اضبط النموذج على gemini-2.5-flash.
  4. حدِّد مخطط الإدخال على النحو التالي تمامًا:
    input:
  schema:
    query:
      type: string
      description: the customers ask of the robot
    productId?:
      type: string
      description: the product the customer is looking at right now
    history?:
      type: array
      description: list of previous history between the user and system
      items:
        type: object
        required: [role, contents]
        properties:
          role:
            type: string
          contents:
            type: string
  5. انسخ محتوى agent-product.prompt من الدليل الجذر إلى الحقل الطلب وتعليمات النظام الاختيارية. يوجّه هذا الطلب النموذج بشكل آمن إلى كيفية التصرّف كـ "مشغّل أجهزة متينة" ويضيف إليه قائمة المنتجات.
  6. في وحدة تحكّم Firebase، احفظ product-agent النموذج وانشره.

6. استدعاء نموذج الذكاء الاصطناعي

بعد تحديد النموذج بشكل آمن على الخادم، ما عليك سوى استدعائه من الواجهة الأمامية لتطبيقك.

  1. في أداة تعديل الرموز، ارجع إلى src/firebase.ts.
  2. أسفل عملية التهيئة، استخدِم getTemplateGenerativeModel للاتصال بالقالب:
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. تأمين الوكيل باستخدام خدمة "فحص التطبيقات من Firebase"

تتسم نماذج الذكاء الاصطناعي بقدرات هائلة، ولكن يمكن إساءة استخدامها إذا لم تتم حماية نقاط النهاية العامة. عليك دائمًا استخدام ميزة "فحص التطبيقات من Firebase" للتأكّد من أنّ تطبيق الويب الفعلي فقط يمكنه استدعاء النموذج التوليدي في Vertex AI، ما يؤدي إلى حظر برامج التتبّع والعملاء غير المصرّح لهم.

  1. في وحدة تحكّم Firebase، انتقِل إلى إنشاء > فحص التطبيقات.
  2. انقر على علامة التبويب التطبيقات، ووسِّع تطبيق الويب (Rugged Web)، ثم انقر على موفّر reCAPTCHA Enterprise.
  3. اختَر إنشاء مفتاح جديد في reCAPTCHA Enterprise واملأ الطلب:
    • الاسم: Codelab Key
    • النطاقات: أضِف localhost و127.0.0.1 حتى يُسمح لخادم Vite المحلي بإرسال الطلبات.
  4. انقر على حفظ لتسجيل التطبيق.
  5. بعد التسجيل، ستعرض "وحدة تحكّم Firebase" مفتاح الموقع. انسخ هذه السلسلة.
  6. في أداة تعديل الرموز، افتح src/firebase.ts مرة أخرى.
  7. أضِف عمليات الاستيراد التالية في الأعلى:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. أضِف عملية تهيئة فحص التطبيقات بعد استدعاء initializeApp(firebaseConfig) مباشرةً، والصِق مفتاح الموقع الإلكتروني الذي نسخته:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. عدِّل استدعاء الدالة getAI() لاستخدام هذه الرموز المميزة. أجرِ التغيير التالي:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    من خلال ضبط قيمة useLimitedUseAppCheckTokens على "صحيح"، يمكنك التأكّد من تطبيق الرموز المميزة القصيرة الأمد للمساعدة في الحدّ من إساءة الاستخدام التي قد يتلقّاها الخادم الخلفي.

8. تشغيل التطبيق

بعد إعداد Firebase وربط التطبيق المصغّر لدردشة الدعم، حان الوقت لتشغيل التطبيق.

  1. في الوحدة الطرفية، شغِّل خادم تطوير Vite:
    npm run dev
  2. افتح عنوان URL المحلي المقدَّم (عادةً http://localhost:5173/).
  3. انقر على زرّ الإجراء الرئيسي (FAB) الدعم التكتيكي في أسفل يسار الصفحة.
  4. جرِّب طرح أسئلة حول المنتجات، مثل:
    • "أبحث عن غطاء مقاوم للعوامل الجوية"
    • قبعة التزلج التي اشتريتها تتضمّن عيوبًا، ماذا يمكنني أن أفعل؟
    • استمر في تأجيل الدفع لتفعيل منطق "ميزانية التهدئة" في الذكاء الاصطناعي.

9. (اختياري) تنظيف الموارد من الدرس التطبيقي حول الترميز

لتجنُّب فرض رسوم محتملة على حساب الفوترة في Google Cloud، يمكنك حذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

  1. انتقِل إلى وحدة تحكُّم Firebase.
  2. اختَر مشروع rugged-terrain-ai.
  3. انتقِل إلى إعدادات المشروع (رمز الترس).
  4. انتقِل إلى أسفل الصفحة وانقر على حذف المشروع.
  5. اتّبِع التعليمات الظاهرة على الشاشة لتأكيد الحذف.

10. تهانينا!

🎊 اكتملت المهمة! لقد دمجت بنجاح وكيل دعم عملاء قويًا مستندًا إلى الذكاء الاصطناعي ومزوّدًا بنماذج.

الإنجازات:

  • إعداد Firebase وخادم Vertex AI الخلفي على تطبيق عميل
  • ضبط نموذج آمن لطلب من جهة الخادم باستخدام Handlebars ومخططات إدخال صارمة لتحديد السلوك المعقّد للوكيل
  • استدعاء نموذج لغوي كبير (LLM) بشكل ديناميكي مع تمرير سجلّ المحادثات ومعرّفات المنتجات السياقية بشكل آمن بدون الكشف عن منطق الطلب الداخلي للعميل

ما هي الخطوات التالية؟