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

1. مقدمة

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

ما ستفعله:

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

يلزمك ما يلي:

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

2. الحصول على رمز البداية

  1. في الوحدة الطرفية، أنشئ نسخة طبق الأصل من مستودع البداية:
    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 بمشروعك.
    • إذا كنت تستخدم أرصدة Google Cloud لهذا الدرس التطبيقي حول الترميز، من المحتمل أن يُطلق على حساب الفوترة اسم Google Cloud Platform Trial Billing Account أو My Billing Account.
    • إذا احتجت إلى إنشاء حساب فوترة على 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"، انتقِل إلى خدمات الذكاء الاصطناعي > Firebase AI Logic.
  2. انقر على البدء.
  3. في بطاقة Agent Platform Gemini API ، انقر على البدء في استخدام واجهة برمجة التطبيقات هذه واتّبِع التعليمات التي تظهر على الشاشة. سيؤدي هذا المسار إلى تفعيل واجهات برمجة التطبيقات المطلوبة لتتمكّن من استخدام Firebase AI Logic مع Agent Platform 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, AgentPlatformBackend } 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 AgentPlatformBackend() });

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

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

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

  1. في "وحدة تحكّم Firebase"، انتقِل إلى خدمات الذكاء الاصطناعي > Firebase AI Logic > علامة التبويب نماذج الطلبات.
  2. انقر على إنشاء نموذج، واختَر نموذج فارغ.
  3. اضبط اسم النموذج على Product Agent ورقم التعريف على product-agent.
  4. اضبط النموذج على gemini-3.1-flash-lite (أو أحدث إصدار متاح).
  5. من رمز البداية المقدَّم لهذا الدرس التطبيقي حول الترميز، انسخ محتويات product-agent.prompt (ابحث عن هذا الملف في الدليل الجذري). بعد ذلك، ألصِق هذا المحتوى في حقل الطلب و (تعليمات النظام الاختيارية) لنموذج الطلب من جهة الخادم في "وحدة تحكّم Firebase". تُعلِم هذه المحتويات النموذج بشكل آمن بكيفية التصرّف كـ "مشغّل Rugged" والإشارة إلى كتالوج المنتجات.
  6. في حقل اختبار الإدخال ، حدِّد مخطط الإدخال تمامًا على النحو التالي:
    {
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "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"
          }
        }
      }
    }
  }
}
  7. انقر على حفظ النموذج لحفظ نموذج 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" لضمان أنّ تطبيق الويب الفعلي فقط هو الذي يمكنه تقديم طلبات ناجحة إلى Gemini API، ما يؤدي إلى حظر برامج الروبوت والعملاء غير المصرّح لهم.

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

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

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

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

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

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

  1. في "وحدة تحكّم Firebase"، انتقِل إلى الإعدادات > علامة التبويب عام.
  2. تأكَّد من أنّ المشروع الذي تعرضه هو المشروع الذي استخدمته في هذا الدرس التطبيقي حول الترميز. إذا لم يكن مشروع الدرس التطبيقي حول الترميز، يمكنك استخدام القائمة المنسدلة لاختيار المشاريع في أعلى يمين الصفحة لتغيير المشاريع.
  3. انتقِل إلى أسفل الصفحة، ثم انقر على حذف المشروع.
  4. اتّبِع التعليمات التي تظهر على الشاشة لتأكيد عملية الحذف.

10. تهانينا!

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

ما أنجزته:

  • إعداد Firebase والخادم الخلفي لـ Agent Platform في تطبيق عميل
  • إعداد نموذج طلب آمن من جهة الخادم باستخدام Handlebars ومخططات الإدخال الصارمة لتحديد السلوك المعقّد للوكيل
  • استدعاء نموذج لغوي كبير بشكل ديناميكي مع تمرير سجلّ المحادثة وأرقام تعريف المنتجات السياقية بشكل آمن بدون عرض منطق الطلب الداخلي للعميل

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