1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستضيف أداة محادثة ذكية لدعم العملاء إلى متجر للتجارة الإلكترونية يبيع معدات خارجية باسم Rugged Terrain Guide. ستستخدم Firebase AI Logic لإنشاء هذا الوكيل، وستتعرّف على كيفية إعداد نموذج طلب من جهة الخادم (product-agent) يتعامل مع شخصية الذكاء الاصطناعي وقواعد ميزانية التهدئة الصارمة، ويستخدم كتالوج المنتجات بشكل ديناميكي كسياق.
الإجراءات المطلوب اتّخاذها:
- احصل على الرمز الأولي لتطبيق الويب الخاص بهذا الدرس التطبيقي حول الترميز.
- إعداد مشروع Firebase.
- إعداد خدمات Firebase (مثل Firebase AI Logic) وتهيئتها في تطبيق ويب
- إعداد نموذج طلب من جهة الخادم في وحدة تحكّم Firebase
- يمكنك الوصول إلى النموذج من خلال طلب إلى خدمة الذكاء الاصطناعي التوليدي من واجهة أمامية مكتوبة بلغة TypeScript تشبه React.
يلزمك ما يلي:
- متصفّح ويب، مثل Chrome
- يجب أن تكون على دراية أساسية بلغتَي TypeScript وNode.js.
- بيئة تطوير متكاملة (IDE) أو محرّر نصوص من اختيارك مضاد الجاذبية هو خيار جيد.
2. الحصول على الرمز الأوّلي
- في نافذة الأوامر، أنشئ نسخة طبق الأصل من مستودع الرموز الأوّلية:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git - انتقِل إلى دليل الرمز وثبِّت الموارد التابعة:
cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab npm install
3- إعداد مشروع Firebase
إنشاء مشروع Firebase
- سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام حساب Google.
- انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال،
rugged-terrain-ai).
- انقر على متابعة.
- إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثمّ انقر على متابعة.
- (اختياري) فعِّل ميزة "الدعم المستند إلى الذكاء الاصطناعي" في "وحدة تحكّم Firebase" (المعروفة باسم "Gemini في Firebase").
- في هذا الدرس العملي، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
- انقر على إنشاء مشروع، وانتظِر إلى أن يتم توفير مشروعك، ثم انقر على متابعة.
ترقية خطة أسعار Firebase
لاستخدام خدمات Firebase في هذا الدرس العملي، يجب أن يكون مشروعك على Firebase ضمن خطة التسعير "الدفع حسب الاستخدام" (Blaze)، ما يعني أنّه مرتبط بحساب فوترة على Cloud.
- يتطلّب حساب الفوترة في Cloud توفُّر طريقة دفع، مثل بطاقة الائتمان.
- خلال العروض الترويجية الخاصة أو إذا كنت تجري هذا الدرس التطبيقي حول الترميز كجزء من فعالية، قد تتوفّر أرصدة Google Cloud.
- إذا كنت مستخدمًا جديدًا في Firebase وGoogle Cloud، تحقّق مما إذا كنت مؤهلاً للحصول على رصيد بقيمة 300 دولار أمريكي وحساب فوترة في Cloud خلال الفترة التجريبية المجانية.
لترقية مشروعك إلى خطة Blaze، اتّبِع الخطوات التالية:
- في "وحدة تحكّم Firebase"، اختَر ترقية خطتك.
- اختَر خطة Blaze. اتّبِع التعليمات الظاهرة على الشاشة لربط حساب فوترة على Cloud بمشروعك.
- إذا كنت تستخدم أرصدة Google Cloud لهذا الدرس التطبيقي، من المحتمل أن يكون اسم حساب الفوترة هو
Google Cloud Platform Trial Billing AccountأوMy Billing Account. - إذا كان عليك إنشاء حساب فوترة في Cloud كجزء من عملية الترقية هذه، قد تحتاج إلى الرجوع إلى مسار الترقية في وحدة تحكّم Firebase لإكمال عملية الترقية.
- إذا كنت تستخدم أرصدة Google Cloud لهذا الدرس التطبيقي، من المحتمل أن يكون اسم حساب الفوترة هو
4. إعداد خدمات Firebase وربط تطبيقك بها
في هذا الدرس العملي، عليك إعداد "التخزين السحابي لبرنامج Firebase" وFirebase AI Logic في مشروعك على Firebase. عليك أيضًا ربط الرمز المصدر لتطبيقك بمشروع Firebase.
إعداد "مساحة تخزين سحابية لـ Firebase"
يستخدم هذا الدرس التطبيقي حول الترميز "مساحة تخزين سحابية لـ Firebase" لتخزين أوصاف المنتجات.
- في "وحدة تحكّم Firebase"، انتقِل إلى قواعد البيانات ومساحة التخزين > مساحة التخزين.
- انقر على البدء.
- اختَر موقعًا جغرافيًا لحزمة Storage التلقائية.
يمكن للحِزم فيUS-WEST1وUS-CENTRAL1وUS-EAST1الاستفادة من الفئة"دائمًا مجانية" في Google Cloud Storage. تخضع الحِزم في جميع المواقع الجغرافية الأخرى لأسعار واستخدام Google Cloud Storage. - انقر على وضع الإنتاج. في الخطوات أدناه مباشرةً، ستعدّل "قواعد الأمان" هذه لتكون خاصة بهذا الدرس العملي.
- انقر على إنشاء.
- تعديل قواعد الأمان:
- بعد توفير الحزمة، انتقِل إلى علامة التبويب القواعد.
- انسخ القواعد التالية ثم الصِقها:
rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /products.txt { allow read; } } } - انقر على نشر.
- حمِّل أوصاف المنتجات من الرمز الأولي:
- انقر على علامة التبويب الملفات لحزمة التخزين.
- انقر على تحميل ملف، ثم حمِّل ملف
products.txtمن رمز البداية. يمكن العثور على هذا الملف في:src/data/products.txt.
ضبط إعدادات Firebase AI Logic
Firebase AI Logic هي خدمة Firebase الرئيسية التي ستستخدمها في هذا الدرس التطبيقي حول الترميز.
- في "وحدة تحكّم Firebase"، انتقِل إلى خدمات الذكاء الاصطناعي > AI Logic.
- انقر على البدء.
- في بطاقة Agent Platform Gemini API، انقر على البدء باستخدام واجهة برمجة التطبيقات هذه واتّبِع التعليمات الظاهرة على الشاشة. سيتيح لك هذا المسار تفعيل واجهات برمجة التطبيقات المطلوبة لاستخدام Firebase AI Logic مع Agent Platform Gemini API.
- (اختياري) اختَر تفعيل ميزة "المراقبة المستنِدة إلى الذكاء الاصطناعي" لتتمكّن من الاطّلاع على مقاييس واستخدامات مختلفة على مستوى التطبيق من أجل الحصول على إمكانية رؤية شاملة لطلباتك من خلال Firebase AI Logic.
ربط الرمز البرمجي بمشروع Firebase
كجزء من عملية إعداد Firebase AI Logic، سيُطلب منك إنشاء تطبيق ويب على Firebase وإضافة إعداداتك إلى الرمز المصدر.
- عندما يُطلب منك ذلك في مسار إعداد Firebase AI Logic، انقر على رمز الويب (
) لتسجيل تطبيق ويب جديد. - أدخِل اسمًا للتطبيق (على سبيل المثال،
Rugged Web). - انسخ عنصر
firebaseConfigمن تعليمات الإعداد.
بعد ذلك، عدِّل الرمز الأوّلي:
- في أداة تعديل الرموز، افتح
src/firebase.ts. - استبدِل
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 لإدارة التعليمات بشكل آمن على الخادم.
يمنع ذلك المستخدمين النهائيين من الاطّلاع على قواعد "ميزانية التهدئة" السرية.
- في "وحدة تحكّم Firebase"، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي > علامة التبويب نماذج الطلبات.
- انقر على إنشاء نموذج، ثم اختَر نموذج فارغ.
- اضبط اسم النموذج على
Product Agentورقم التعريف علىproduct-agent. - اضبط النموذج على
gemini-3.1-flash-lite(أو أحدث إصدار متاح). - من الرمز الأولي المقدَّم لهذا الدرس التطبيقي حول الترميز، انسخ محتوى
product-agent.prompt(ابحث عن هذا الملف في الدليل الجذر). بعد ذلك، الصِق هذا المحتوى في حقل الطلب وتعليمات النظام (اختيارية) في نموذج طلب الخادم في وحدة تحكّم Firebase. يقدّم هذا المحتوى تعليمات آمنة للنموذج حول كيفية التصرّف كـ "مشغّل قوي" والرجوع إلى قائمة المنتجات. - في حقل إدخال الاختبار، حدِّد مخطط الإدخال على النحو التالي تمامًا:
{ "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" } } } } } } - انقر على حفظ النموذج لحفظ نموذج
product-agentونشره.
6. استدعاء نموذج الذكاء الاصطناعي
بعد تحديد النموذج بشكل آمن على الخادم، ما عليك سوى استدعائه من الواجهة الأمامية لتطبيقك.
- في أداة تعديل الرموز، ارجع إلى
src/firebase.ts. - أسفل عملية التهيئة، استخدِم
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، ما يؤدي إلى حظر برامج التتبّع والعملاء غير المصرّح لهم.
- في Google Cloud Console، انتقِل إلى الأمان > الدفاع ضد الاحتيال.
- انقر على إنشاء مفتاح واملأ الحقول التالية:
- اسم العرض:
Codelab Key - نوع التطبيق: الويب
- قائمة النطاقات: أضِف
localhostو127.0.0.1ليتم السماح لخادم Vite المحلي بتقديم الطلبات.
- اسم العرض:
- انقر على إنشاء مفتاح لتسجيل المفتاح.
- في أعلى صفحة "تفاصيل مفتاح Fraud Defense"، انسخ معرّف مفتاح الموقع الإلكتروني إلى الحافظة.
- في "وحدة تحكّم Firebase"، انتقِل إلى الأمان > فحص التطبيقات.
- انقر على علامة التبويب التطبيقات، ووسِّع تطبيق الويب (
Rugged Web)، ثم انقر على موفّر reCAPTCHA Enterprise. - في حقل مفتاح الموقع الإلكتروني في reCAPTCHA Enterprise، ألصِق رقم تعريف مفتاح الموقع الإلكتروني من صفحة "تفاصيل مفتاح Fraud Defense"، ثم انقر على حفظ.
- في محرّر الرموز، افتح
src/firebase.tsمرة أخرى. - أضِف عمليات الاستيراد التالية في الأعلى:
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check"; - أضِف عملية تهيئة فحص التطبيقات مباشرةً بعد طلب
initializeApp(firebaseConfig)، والصِق معرّف مفتاح الموقع الإلكتروني الذي نسخته:// Initialize App Check const appCheck = initializeAppCheck(app, { provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'), isTokenAutoRefreshEnabled: true }); - عدِّل طلبات البحث التي تستخدم وظيفة
getAI()لاستخدام هذه الرموز المميزة. أجرِ التغيير التالي: من خلال ضبط قيمةconst ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });useLimitedUseAppCheckTokensعلى "صحيح"، يمكنك التأكّد من تطبيق الرموز المميزة القصيرة الأمد للمساعدة في الحدّ من إساءة الاستخدام التي قد يتلقّاها الخادم الخلفي.
8. تشغيل التطبيق
بعد إعداد Firebase وربط التطبيق المصغّر لدردشة الدعم، حان الوقت لتشغيل التطبيق.
- في الوحدة الطرفية، شغِّل خادم تطوير Vite:
npm run dev - افتح عنوان URL المحلي المقدَّم (عادةً
http://localhost:5173/). - انقر على زرّ الإجراء الرئيسي (FAB) الدعم التكتيكي في أسفل يسار الصفحة.
- جرِّب طرح أسئلة حول المنتجات، مثل:
- أبحث عن غطاء مضادة لعوامل الطقس
- قبعة التزلج التي اشتريتها تتضمّن عيوبًا، ماذا يمكنني أن أفعل؟
- استمر في رفض العروض لتفعيل منطق "ميزانية التهدئة" في الذكاء الاصطناعي.
9. (اختياري) تنظيف الموارد من الدرس التطبيقي حول الترميز
لتجنُّب الرسوم المحتملة على حساب الفوترة في Google Cloud، يمكنك حذف الموارد التي تم إنشاؤها أثناء استخدام هذا الدرس العملي.
- في "وحدة تحكّم Firebase"، انتقِل إلى الإعدادات > علامة التبويب الإعدادات العامة.
- تأكَّد من أنّ المشروع الذي تعرضه هو المشروع الذي استخدمته في هذا الدرس العملي. إذا لم يكن مشروعك هو مشروع الدرس العملي، يمكنك استخدام القائمة المنسدلة لاختيار المشروع في أعلى يمين الصفحة لتغيير المشاريع.
- انتقِل إلى أسفل الصفحة، ثم انقر على حذف المشروع.
- اتّبِع التعليمات الظاهرة على الشاشة لتأكيد الحذف.
10. تهانينا!
🎊 اكتملت المهمة! لقد دمجت بنجاح وكيل دعم عملاء قويًا مستندًا إلى نماذج الذكاء الاصطناعي.
الإنجازات التي حققتها:
- إعداد Firebase وواجهة Agent Platform الخلفية على تطبيق عميل
- إعداد نموذج آمن لطلب من جهة الخادم باستخدام Handlebars ومخططات إدخال صارمة لتحديد السلوك المعقّد للوكيل
- استدعاء نموذج لغوي كبير بشكل ديناميكي مع تمرير سجلّ المحادثات ومعرّفات المنتجات السياقية بشكل آمن بدون الكشف عن منطق الطلب الداخلي للعميل
ما هي الخطوات التالية؟
- فحص التطبيقات من Firebase: يمكنك تأمين نقاط نهاية الذكاء الاصطناعي من إساءة الاستخدام.