تحسين عملية الدفع في التجارة الإلكترونية باستخدام ميزات الذكاء الاصطناعي في المتصفّح

1. مقدمة

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

في الوقت نفسه، توفّر وكلاء الذكاء الاصطناعي طريقة جديدة للمستخدمين للتفاعل مع تطبيقات الويب، ويمكن أن يساعد جعل تجربة الويب متوافقة مع الوكلاء باستخدام WebMCP في تقليل استخدام الرموز المميزة مع تقديم نتائج أكثر دقة من التنشيط التقليدي الذي يتطلّب لقطات شاشة واستخراج DOM.

في هذا الدرس التطبيقي حول الترميز، ستعمل على Mont-Royal Plein Air، وهو موقع إلكتروني للتجارة الإلكترونية خاص بمعدات الأنشطة الخارجية. ستتعرّف على كيفية إنشاء ودمج واجهات برمجة التطبيقات المضمّنة المستندة إلى الذكاء الاصطناعي وWebMCP من أجل:

1. استنتاج نية العميل من سجلّ التصفّح وإنشاء اقتراحات له ديناميكيًا باستخدام نماذج على الجهاز فقط
2. توفير أدوات يمكن أن تستخدمها برامج الوكلاء ومساعدو المتصفّح للتنقّل في الموقع الإلكتروني وفحص المنتجات والاقتراحات وإدارة سلّة تسوّق المستخدم
3. (اختياري) ترجمة موقعك الإلكتروني أثناء التنقّل باستخدام نماذج صغيرة متخصّصة على الجهاز فقط
4. (اختياري) تحويل ميزة "البحث الأساسي في الموقع الإلكتروني" إلى وكيل داخل الموقع الإلكتروني يعمل باستخدام الأدوات نفسها التي تستخدمها الوكلاء الخارجيون

أهداف الدورة التعليمية

• كيفية استخدام Prompt API وفرض إخراج JSON منظَّم منه
• كيفية تسجيل أدوات WebMCP واستراتيجيات التفكير في تركيبة الأدوات ومدى دقتها
• (اختياري) كيفية استخدام Translator API لترجمة المحتوى بسرعة باستخدام نموذج خبير على الجهاز فقط
• (اختياري) كيفية استدعاء أدوات WebMCP بنفسك

المتطلبات الأساسية

• حساب Google شخصي وGoogle Cloud
• الإصدار 150 من Google Chrome أو الإصدارات الأحدث، أو قنوات Canary أو Dev أو Beta، مع تفعيل العلامتَين #enable-webmcp-testing و#devtools-webmcp-support
• الإلمام بلغات HTML وCSS وJavaScript وTypeScript
• يجب أن تكون على دراية بمخطط JSON.

2. إعداد المشروع

حساب Google

إذا لم يكن لديك حساب Google شخصي، عليك إنشاء حساب Google.

تسجيل الدخول إلى Google Cloud Console

سجِّل الدخول إلى Google Cloud Console باستخدام حساب Google شخصي.

تفعيل الفوترة

ملاحظة: إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.

لإعداد حساب فوترة شخصي، فعِّل الفوترة في Cloud Console.

إنشاء مشروع (اختياري)

إذا لم يكن لديك مشروع حالي تريد استخدامه في هذا المختبر، يمكنك إنشاء مشروع جديد هنا.

فتح محرّر Cloud Shell

1. انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell.
2. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على تفويض للمتابعة.
3. إذا لم تظهر المحطة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
   • انقر على عرض.
   • انقر على Terminal.

إعداد مشروعك

1. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:

   gcloud config set project [PROJECT_ID]
   

   مثال: gcloud config set project lab-project-id-example

   إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، يمكنك إدراج جميع أرقام تعريف مشاريعك باستخدام gcloud projects list.

   
2. ستظهر لك الرسالة التالية: Updated property [core/project].

   إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/n)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على n، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

إعداد الحساب المحلي وحساب Workspace

1. في نافذة الوحدة الطرفية (أو نافذة Cloud Shell الطرفية)، استنسِخ مستودع المشروع وانتقِل إلى دليل المشروع:

   git clone https://github.com/GoogleChromeLabs/codelabs mont-royal
   cd mont-royal
   

2. انتقِل إلى المجلد ecommerce-ai-enhancements/starter:

   cd ecommerce-ai-enhancements/starter
   

3. ثبِّت التبعيات باستخدام pnpm:

   pnpm install
   

4. ابدأ خادم التطوير المحلي:

   pnpm dev
   

   افتح المتصفّح وانتقِل إلى http://localhost:5173 لعرض متجر Mont-Royal Plein Air.

(اختياري) تثبيت إضافة WebMCP inspector

لتسهيل استخدام WebMCP، يمكنك تثبيت أداة فحص سياق النموذج في WebMCP. بعد تثبيت Gemini API، عليك الحصول على مفتاح API لاستخدامه:

• انتقِل إلى AI Studio.
• انقر على الزر إنشاء مفتاح واجهة برمجة تطبيقات لإنشاء مفتاح جديد لواجهة Gemini API مرتبط بالمشروع الذي أعددته في الخطوة السابقة.
• افتح "أداة فحص سياق نموذج WebMCP" (تُفتح في اللوحة الجانبية) وانقر على الزر تعديل مفتاح Gemini API.
• ألصِق مفتاح واجهة برمجة التطبيقات في النافذة المنبثقة واحفظه.

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

3- نماذج الذكاء الاصطناعي المضمَّنة على الويب

ما هي Prompt API؟

تتيح واجهة برمجة التطبيقات Prompt API لتطبيقات الويب الوصول مباشرةً إلى نموذج لغوي صغير ومتعدّد الوسائط يعمل بالكامل على جهاز المستخدم. لأنّ الاستنتاج يتم تنفيذه محليًا:

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

في Chrome، يمكن الوصول إلى Prompt API من خلال واجهة LanguageModel العامة.

// 1. Set your expected inputs and outputs. This is multimodal, so you can
// include other types here, too
const languages = {
   expectedInputs: [{type: "text", languages: ["en"]}],
   expectedOutputs: [{type: "text", languages: ["en"]}],
}

// 2. Check availability. Always pass in your expected inputs and outputs,
// as some models may only support some inputs and outputs
const availability = await LanguageModel.availability(languages);
// 'available', 'downloading', or 'unavailable'

// 3. Create an isolated session with system prompt and language constraints
const session = await LanguageModel.create({
  ...languages,
  // Optional: add initial context to your session, like a system prompt
  initialPrompts: [
   {
      role: 'system',
      content: 'You are an expert outdoors sales assistant...'
   }
  ]
});

// 4. Define your expected output as JSON Schema
const schema = {
   //...
}

// 5. Prompt the model (supports plain text or structured models)
const result = await session.prompt('Recommend a 3-season tent footprint.', {
  responseConstraint: schema,
});

أفضل الممارسات المتعلّقة بإدارة الذاكرة:

• يمكنك clone() جلسة، ونسخ حالة قدرة استيعاب الكاملة، واستخدام النسخ بشكل مستقل، ما يقلّل من الوقت المستغرَق في بدء جلسة جديدة.
• بعد الانتهاء من استخدام جلسة، عليك destroy() لإتاحة الموارد

التمرين 1: الاقتراحات المستندة إلى رحلة المستخدم

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

لتحقيق ذلك، عليك إنشاء مسار توصية من ثلاث مراحل:

1. أداة تحديد رحلة المستخدم: باستخدام Prompt API، يمكنك تحليل المخطط الزمني للتصفّح حسب التسلسل الزمني للعميل في محاولة لاستنتاج النية الحقيقية للمستخدم في خوض مغامرة.
2. طلب البحث عن المنتج: من هذا الغرض، ستُرسل طلب بيانات من واجهة برمجة التطبيقات إلى خادم خلفي مزيّف للمنتجات للحصول على سلع ذات صلة.
3. اقتراح المنتجات: ستعيد هذه المنتجات إلى Product API لترتيبها، ما يؤدي إلى عرض خمسة منتجات متوافقة مع ما يشاهده المستخدم.

المهمة 1.1: بدء استخدام Prompt API

بدلاً من تهيئة Prompt API بشكل فردي في كل مرة تريد استخدامها، يمكنك تجميع الطلبات في ملف واحد، وتخزين عملية الإنشاء حسب طلب النظام لتقليل وقت بدء تشغيل الطلبات المتعددة إلى الوكيل نفسه.

انتقِل إلى الملف src/ai/prompt-api.ts وافحص getPromptSession() في الأسطر من 27 إلى 58:

export async function getPromptSession(
  systemPrompt: string = '',
  options: { signal?: AbortSignal } = {}
): Promise<LanguageModel>

1. إعادة استخدام جلسة أساسية مخزَّنة مؤقتًا تتوفّر حاليًا خريطة ذاكرة تخزين مؤقت في السطر 21، baseSessions، يتم تحديد مفتاحها من خلال طلب النظام. تؤدي إعادة استخدام النماذج الأساسية بدلاً من clone() نماذج جديدة إلى تقليل وقت بدء التشغيل والاستفادة من الإعداد الأساسي بدون أن تتداخل كل جلسة مع الأخرى. إرجاع النسخة المستنسخة، ويمكن للمتصلين التفاعل معها، بما في ذلك destroy()ها، بحرية بدون تجاهل قاعدة البيانات الأساسية المخزّنة مؤقتًا
2. رصد توفّر واجهة برمجة التطبيقات رصد الميزة إذا كانت واجهة برمجة التطبيقات متوفرة، وعرض رسالة خطأ إذا لم تكن متوفرة
3. التعريف عن طرق الدفع واللغات يمكن للنماذج المضمّنة معالجة الإدخالات المتعدّدة الوسائط. عليك تحديد الأوضاع التي تحتاج إليها واللغات التي تريد إتاحتها. يجب أن يكون كل المحتوى الذي ترسله إلى النموذج اللغوي الكبير باللغة الإنجليزية.
4. تحقَّق من مدى التوفّر قبل إنشاء أي محتوى. حتى إذا كانت واجهة برمجة التطبيقات متوفّرة، قد لا يتوفّر نموذج يستوفي متطلباتك. تحقَّق مما إذا كان هناك حساب. إذا لم يكن كذلك، سيظهر خطأ. إذا لم يتم تنزيلها بعد، أبلِغ عن مستوى التقدّم في عملية التنزيل.
5. أنشئ الجلسة. إعداد الخيارات لإنشاء جلسة جديدة في Prompt API، وطلب النظام، إذا كان متضمّنًا

المهمة 1.2: تنفيذ أداة إنشاء ملفات رحلات المستخدمين

انتقِل إلى الملف src/ai/journey-profiler.ts وافحص الدالة المستهدَفة في الأسطر من 42 إلى 100:

export async function inferJourneyProfile(
  context: ProfilerInputContext,
  catalogMap: ReadonlyMap<string, Product>
): Promise<JourneyProfile>

1. استخدِم الدالة من المهمة 1 لإنشاء جلسة طلب جديدة لاستخدامها.
2. اطلب من النموذج تنفيذ الطلب باستخدام نص الطلب المقدَّم، واستخدِم journeyProfileSchema كـ مخطط JSON للرد المنظَّم.
3. حلِّل نتائج الطلب وأزِل الفئات المستهدَفة المكرّرة.
4. استبدِل السلاسل المرمّزة بثبات بالنتائج الفعلية من طلبك.
5. يجب إيقاف الجلسة عند الانتهاء منها لتوفير مساحة في الذاكرة.

اطّلِع على src/utils/journey-helpers.ts لمعرفة كيف يتم تحويل عملية جمع السياق إلى طلب.

المهمة 1.3: تنفيذ أداة إعادة الترتيب المستندة إلى التآزر

انتقِل إلى الملف src/ai/synergy-reranker.ts وافحص الدالة المستهدَفة في الأسطر من 30 إلى 71:

export async function rankComplementaryGear(
  profile: JourneyProfile,
  candidates: readonly Product[],
  currentProduct?: Product | null,
  cartProducts?: readonly Product[],
  limit: number = 5
): Promise<readonly RecommendedItem[]>

1. استخدِم الدالة من المهمة 1 لإنشاء جلسة طلب جديدة لاستخدامها.
2. قدِّم للنموذج نص الطلب والمخطط الذي تم إنشاؤه.
3. حلِّل ناتج الطلب.
4. إرجاع قائمة الاقتراحات المجمّعة باستخدام assembleRecommendations
5. يجب إيقاف الجلسة عند الانتهاء منها لتوفير مساحة في الذاكرة.

اطّلِع على src/utils/reranker-helpers.ts وsrc/utils/recommendation-schemas.ts لمعرفة كيفية إنشاء الطلب والمخطط وكيفية تجميع الاقتراحات من نتائج الطلب.

التحقّق من مسار الاقتراحات

1. افتح Chrome http://localhost:5173/catalog/tent-mont-tremblant-3p.
2. انتقِل للأسفل إلى قسم محتوى يهمّك.
3. لاحظ كيف يتم تعديل البطاقات الخمس المصاحبة لعرض مجموعات الأدوات الذكية (مثل آثار الأقدام على الأرض، ووسادات النوم، والأوتاد الخفيفة) بدلاً من المنتجات العشوائية.
4. افتح "وحدة تحكّم أدوات مطوّري البرامج في Chrome" لفحص مدة التنفيذ في الوقت الفعلي لكلتا خطوتَي الاستنتاج.

(اختياري) المهمة 1.4: استكشاف المزيد من نماذج الذكاء الاصطناعي المضمَّنة

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

انتقِل إلى الملف: src/ai/translator.ts

افحص الدالة المستهدَفة createTranslator في الأسطر من 29 إلى 45:

export async function createTranslator(
  targetLang: SupportedLanguage
): Promise<Translator | null>

1. تحقَّق من توفّر واجهة برمجة التطبيقات Translator API وتأكَّد من أنّ اللغة المستهدَفة ليست الإنجليزية (يكون المحتوى باللغة الإنجليزية تلقائيًا).
2. أنشئ زوجًا من اللغات، من الإنجليزية إلى اللغة المستهدَفة، وتحقّق مما إذا كان هذا الزوج متاحًا.
3. إنشاء خيارات للمترجم وإرفاق شاشة عرض لمستوى تقدّم تنزيل النموذج
4. لعرض أداة الترجمة التي تمّت تهيئتها

بعد ذلك، افحص الدالة المستهدَفة translate في الأسطر من 50 إلى 58:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

5. تحقَّق ممّا إذا كان هناك مترجم متاح مع تمرير getCachedTranslator في targetLang. إذا لم يكن هناك أي نص، أعِد النص النظيف.
6. إذا كان هناك نص، استخدِم أداة الترجمة لترجمة النص النظيف.

انتقِل إلى الملف: src/ai/translator.ts

افحص الدالة المستهدَفة render في السطر 204:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

7. تفعيل مكوّن "أداة اختيار اللغة"

اطّلِع على src/utils/translator-helpers.ts لمعرفة طريقة عمل ذاكرة التخزين المؤقت للترجمة والاشتراك.

4. استخدام WebMCP لتحسين تجربة الموظف

ما هي WebMCP؟

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

تساعد WebMCP في حلّ هذه المشكلة من خلال السماح للمطوّرين بتوفير أدوات مباشرةً للوكلاء للتفاعل مع الصفحة التي يتصفّحونها. يمكن للوكلاء الذين يتيحون استخدام هذه الأدوات الاستفادة منها تمامًا مثل أداة في حزمة الترميز، مع إدخالات وعائدات منظَّمة وواضحة تحدّدها أنت.

// Register a tool directly on document.modelContext
document.modelContext.registerTool({
  name: 'get_product_specs',
  title: 'Get Product Specs',
  description: 'Retrieve technical specifications for the active product.',
  inputSchema: {
    type: 'object',
    properties: {
      // ...
    },
  },
  annotations: {
    readOnlyHint: true, // Informs the agent this tool causes no side-effects
  },
  execute: async (input) => {
    return {
      weight: '1.8 kg',
      capacity: '3 persons',
      seasons: '3-season',
    };
  },
});

عندما يتصل موظّف الدعم بصفحة الويب، يرسل طلب بحث إلى document.modelContext.getTools(). تتيح كل أداة مسجّلة ما يلي:

• ‫name: معرّف الأداة الآلية الذي تستخدمه البرامج عند تنفيذ الأدوات (مثل 'get_product_specs').
• ‫title: تصنيف العرض القابل للقراءة من قِبل الإنسان والذي تستخدمه واجهات المفتشين والوكلاء (مثل 'Get Product Specs').
• ‫description: وصف بنص عادي يوضّح للنموذج وظيفة الأداة ومتى يجب استدعاؤها. هذه هي الطريقة التي يحدّد بها الوكيل ما إذا كان عليه استدعاء الأداة، لذا يجب أن يكون الوصف واضحًا.
• inputSchema: مخطط JSON الذي يحدّد الوسيطات المقبولة.
• annotations: تلميحات السلوك، مثل { readOnlyHint: true } للأدوات التي لا يمكن تعديلها ولا تتسبّب في أي آثار جانبية للحالة.
• ‫execute: دالة غير متزامنة يتم تنفيذها عند استدعاء الأداة.

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

المهمة 2.1: أدوات الاقتراحات والمنتجات

تبدأ بتسجيل أداة للسماح للوكلاء باسترداد الاقتراحات التي أنشأتها للتو في التمرين السابق.

انتقِل إلى الملف: src/components/product/ForYouSection.ts

فحص registerWebMCPTools() في الأسطر من 71 إلى 94:

private registerWebMCPTools(): void

1. تحقَّق مما إذا كانت WebMCP متاحة.
2. إذا كان الأمر كذلك، سجِّل الأداة.

• اختَر عنوانًا ووصفًا يجذبان الوكيل لاختيار الأداة، مع مراعاة هندسة الطلبات هنا.
• لا يوجد إدخال، لذا ما عليك سوى تضمين مخطط JSON فارغ.
• هذه أداة للقراءة فقط.
• في دالة التنفيذ، استخدِم recommendationStore للحصول على المجموعة الحالية من الاقتراحات، ثمّ أرجِع معرّف المنتج الحالي ومجموعة اقتراحات المنتجات.
• أضِف إشارة إلغاء والتقِطها كي لا تؤدي إلى حدوث خطأ. يضمن ذلك إزالة الأداة بشكل صحيح عند إلغاء تحميل المكوّن.

انتقِل إلى الملف: src/views/ProductView.ts

3. كرِّر العملية نفسها لتسجيل أداة get_current_product، ولكن هذه المرة سيتم عرض المنتج الكامل بالإضافة إلى الاقتراحات.

ملاحظة: يتم تسجيل الأداة على مستوى المكوّن، لذا عند تجميع المكوّنات معًا لإنشاء صفحة، يتم تضمين أدواتها معها.

المهمة 2.2: أدوات درج سلة التسوّق

انتقِل إلى الملف: src/components/cart/CartDrawer.ts

فحص registerWebMCPTools() في الأسطر من 83 إلى 114:

private registerWebMCPTools(): void

1. سجِّل أداة view_cart باتّباع الخطوات التالية:

• يجب أن تكون inputSchema عبارة عن عنصر يتضمّن خيارًا منطقيًا واحدًا، وهو openDrawer.
• يجب أن يكون متاحًا للقراءة فقط.
• قراءة الإدخال كجزء من وظيفة execute، وتحديد ما إذا كان سيتم عرض سلة التسوّق أو إخفاؤها، وإعادة تحميل recommendationStore، ثم عرض ملخّص سلة التسوّق

2. سجِّل أداة manage_cart باتّباع الخطوات التالية:

• يجب أن يكون inputSchema عنصرًا يتضمّن items، وهو عبارة عن مصفوفة من العناصر التي تتضمّن التعداد action productID وadd وremove وupdate، بالإضافة إلى العدد الصحيح quantity.
• يجب أن تنقل الدالة execute العناصر إلى this.updateCart

المهمة 2.3: أداة تبديل اللغة

يمكنك الاستفادة بشكل أكبر من WebMCP من خلال توفير أداة لغوية للجهات الخارجية.

انتقِل إلى الملف: src/components/navigation/LanguagePicker.ts

فحص registerWebMCPTools() في الأسطر من 61 إلى 63:

private registerWebMCPTools(): void

1. تسجيل أداة switch_language:
   • يجب أن تتضمّن السمة inputSchema سمة language تكون عبارة عن قيمة محدّدة مسبقًا من SUPPORTED_LANGUAGE_CODES.
   • يجب أن تستدعي الدالة execute الدالة this.switchLanguage مع اللغة المقدَّمة.

المهمة 2.4: أدوات التنقّل في المتجر

يمكنك السماح للوكلاء المستقلين بالتنقّل في المتجر أو الانتقال إلى صفحات المنتجات أو تصفّح الفئات أو بدء عمليات البحث.

انتقِل إلى الملف: src/components/navigation/SiteHeader.ts

فحص registerWebMCPTools() في الأسطر من 155 إلى 171:

private registerWebMCPTools(): void

1. تحقَّق مما إذا كانت WebMCP متاحة.
2. تسجيل أداة search:
   • يستخدِم مخطط الإدخال سلسلة query.
   • في execute، اتّصِل بالرقم this.search(input?.query).
3. تسجيل أداة go_to_catalog:
   • يقبل مخطط الإدخال السمتَين الاختياريتَين activity (تعداد ACTIVITIES) وcategory (تعداد PRODUCT_CATEGORIES).
   • في execute، اتّصِل بالرقم this.goToCatalog(input?.activity, input?.category).
4. تسجيل أداة get_categories_and_activities:
   • أداة للقراءة فقط بدون مَعلمات إدخال
   • في execute، اتّصِل بالرقم this.getCategoriesAndActivities().
5. تسجيل أداة go_to_product:
   • يتطلّب مخطط الإدخال سلسلة productId.
   • في execute، اتّصِل بالرقم this.goToProduct(input?.productId).

التحقّق باستخدام أداة فحص WebMCP

1. أعِد تحميل http://localhost:5173/catalog/tent-mont-tremblant-3p في Chrome وانتقِل إلى صفحة منتج.
2. افتح "أدوات مطوّري البرامج في Chrome" > "التطبيق" > WebMCP.
3. من المفترض أن تظهر أدوات WebMCP: get_recommendations وget_current_product وview_cart وmanage_cart وswitch_language وsearch وgo_to_catalog وget_categories_and_activities وgo_to_product.
4. انقر على أحدها للاطّلاع على تفاصيله ومَعلماته.
5. اختَر أداة تتضمّن مَعلمات، ثم اختَر بعض المَعلمات وانقر على تشغيل الأداة للاطّلاع على طريقة عملها.
6. (اختياري) إذا ثبّت WebMCP Model Context Tool Inspector وأعددته، افتحه، وسيتم فتحه في اللوحة الجانبية في Chrome. استخدِم واجهة المحادثة لطلب إجراء معيّن من الوكيل، على أن يكون هذا الإجراء من المفترض أن يستدعي إحدى أدواتك، وذلك لمعرفة كيفية استجابة الوكيل.

5- (اختياري) إنشاء وكيل داخل الموقع

استدعاء أدوات WebMCP داخل الصفحة

لا تقتصر أدوات WebMCP على إضافات المتصفّح الخارجية أو برامج التتبّع الآلية التابعة لجهات خارجية، بل يمكن لتطبيقك الخاص استدعاؤها مباشرةً. من خلال طلب البحث من document.modelContext.getTools()، يمكن لرمزك من جهة العميل اكتشاف الأدوات وتنفيذها بشكلٍ ديناميكي.

يمكنك استخدام هذه الميزة لإنشاء مساعد تسوّق مستند إلى الذكاء الاصطناعي على الموقع الإلكتروني، ما يؤدي إلى تحويل شريط البحث إلى أداة لاكتشاف المنتجات استنادًا إلى الإدخال باللغة الطبيعية. بدلاً من كتابة رمز إلزامي مخصّص لتنسيق العديد من فلاتر الأوجه، يمكن لشريط البحث إرسال طلبات بحث باللغة الطبيعية إلى Prompt API، التي تحدّد أدوات WebMCP التي سيتم استدعاؤها على الصفحة.

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

لاكتشاف أداة WebMCP واستدعائها من JavaScript، اتّبِع الخطوات التالية:

// getTools() returns a Promise — it must be awaited.
const tools = await document.modelContext.getTools();
const tool = tools.find(t => t.name === 'list_items');

const json = await document.modelContext.executeTool(tool, args);
const result = JSON.parse(json); // executeTool resolves with a DOMString

المهمة 3.1: أدوات الفلاتر في الشريط الجانبي

اعرض كل جزء من الشريط الجانبي للكتالوج على WebMCP حتى يتمكّن العملاء (ومساعد البحث داخل الصفحة) من تفعيل الفلاتر وإيقافها آليًا.

يوفّر كل مكوّن من مكوّنات التصميم المتعدّد الأوجه في src/components/facets/ طريقة مساعدة في فئته ومخطط إدخال تم تصديره في src/utils/filter-schemas.ts:

1. في src/components/facets/ActivityFacet.ts:
   • سجِّل بطاقة "activity_filter" باستخدام activityFilterSchema.
   • في execute، اتّصِل بالرقم this.filterActivity(input?.activity, input?.selected).
2. في src/components/facets/CategoryFacet.ts:
   • سجِّل بطاقة "category_filter" باستخدام categoryFilterSchema.
   • في execute، اتّصِل بالرقم this.filterCategory(input?.category, input?.selected).
3. في src/components/facets/ConditionFacet.ts:
   • سجِّل بطاقة "condition_filter" باستخدام conditionFilterSchema.
   • في execute، اتّصِل بالرقم this.filterCondition(input?.condition, input?.selected).
4. في src/components/facets/PriceFacet.ts:
   • سجِّل بطاقة "price_filter" باستخدام priceFilterSchema.
   • في execute، اتّصِل بالرقم this.filterPrice(input?.priceRange || input?.bracket, input?.selected).
5. في src/components/facets/WeightFacet.ts:
   • سجِّل بطاقة "weight_filter" باستخدام weightFilterSchema.
   • في execute، اتّصِل بالرقم this.filterWeight(input?.weightRange || input?.bracket, input?.selected).
6. في src/components/facets/RatingFacet.ts:
   • سجِّل بطاقة "rating_filter" باستخدام ratingFilterSchema.
   • في execute، اتّصِل بالرقم this.filterRating(input?.minRating || input?.rating, input?.selected).
7. في src/components/facets/SearchFacet.ts:
   • سجِّل بطاقة "keyword_filter" باستخدام keywordFilterSchema.
   • في execute، اتّصِل بالرقم this.updateKeyword(input?.keyword).

تذكَّر التحقّق من توفّر WebMCP وإدخال { signal: this.signal } مع .catch(() => {}) كما تعلّمت في الخطوة 2.

المهمة 3.2: أدوات عرض الكتالوج

يمكنك الآن تسجيل أدوات بطاقة البيانات على مستوى الكتالوج وإعادة ضبط الفلتر والبحث الدلالي على document.modelContext.

انتقِل إلى الملف: src/views/CatalogView.ts

فحص registerWebMCPTools() في الأسطر من 125 إلى 140:

private registerWebMCPTools(): void

1. تحقَّق مما إذا كان WebMCP متاحًا.
2. تسجيل أداة list_items:
   • لا يتطلّب أي مَعلمات إدخال وهو للقراءة فقط.
   • يجب أن تستدعي الدالة execute الدالة this.getItemsSummary().
3. تسجيل أداة reset_filters:
   • لا تتطلّب أي مَعلمات إدخال.
   • يجب أن تستدعي الدالة execute الدالة this.resetFilters().
4. تسجيل أداة semantic_catalog_filter:
   • استخدم semanticCatalogFilterSchema.
   • يجب أن تستدعي الدالة execute الدالة interpretAndApplySemanticFilter(input.query).

المهمة 3.3: تنسيق وكيل الفلتر الدلالي

حان الوقت الآن لربط كل ذلك. تحوّل هذه المهمة البحث إلى مسار دلالي يشغّل أداة semantic_catalog_filter:

انتقِل إلى الملف: src/ai/catalog-semantic-filter.ts

فحص prewarmSemanticFilterSession() في الأسطر من 84 إلى 88:

export async function prewarmSemanticFilterSession(): Promise<void>

1. تحقَّق مما إذا كان warmSession موجودًا من قبل، وإذا كان الأمر كذلك، ارجع مبكرًا.
2. يمكنك تسخين جلسة Prompt API مسبقًا باستخدام SEMANTIC_FILTER_SYSTEM_PROMPT من خلال getPromptSession() وتخزينها في warmSession. يمكنك تضمينها في كتلة try/catch حتى يظلّ بإمكانك الرجوع إلى الإصدار السابق من ميزة البحث بسلاسة في حال تعذّر التسخين المسبق.

فحص inferSearchFacets() في الأسطر من 93 إلى 134:

async function inferSearchFacets(
  searchTerm: string,
  cachedJourney: JourneyProfile | null
): Promise<{ parsed: SemanticFilterResponse; cacheHit: boolean }>

3. يمكنك طلب الجلسة المُسخّنة مسبقًا من warmSession إذا كانت متاحة (وإعادة ضبط warmSession إلى null)، أو إنشاء جلسة جديدة باستخدام getPromptSession(SEMANTIC_FILTER_SYSTEM_PROMPT).
4. قدِّم الطلب إلى النموذج باستخدام promptText، مع استخدام semanticFilterSchema كـ responseConstraint.
5. حلِّل ملف JSON الذي تم إرجاعه، وخزِّن النتيجة التي تم تحليلها في ذاكرة التخزين المؤقت الثابتة باستخدام cacheKey، وأنهِ الجلسة في كتلة finally.

فحص applyFacetsViaWebMCP() في الأسطر من 139 إلى 270:

async function applyFacetsViaWebMCP(
  searchTerm: string,
  parsed: SemanticFilterResponse
): Promise<{ appliedFilters: SemanticFilterResult['appliedFilters']; toolsExecuted: string[] }>

6. استكشاف الأدوات المسجَّلة على document.modelContext باستخدام await document.modelContext.getTools()
7. يمكنك إعادة ضبط الفلاتر للبدء من جديد عن طريق الاتصال بالرقم await executeFacet('reset_filters', {}).
8. تطبيق الأوجه النشطة بشكلٍ متزامن باستخدام await Promise.all(facetTasks)

فحص interpretAndApplySemanticFilter() في الأسطر من 272 إلى 316:

export async function interpretAndApplySemanticFilter(
  searchTerm: string
): Promise<SemanticFilterResult>

9. استنتاج تصنيفات البحث من خلال استدعاء inferSearchFacets(searchTerm, cachedJourney)
10. طبِّق التصنيفات المستنتَجة على الكتالوج باستخدام applyFacetsViaWebMCP(searchTerm, parsed).

التأكّد من صحة معلومات الوكيل على الصفحة

1. الانتقال إلى http://localhost:5173/catalog
2. في شريط البحث العلوي، أدخِل: "lightweight 3 season tent for wet hikes"
3. شاهِد كيف تحلّل Prompt API الطلب، وتستدعي activity_filter (رحلات المشي لمسافات طويلة) وcategory_filter (خيام) وcondition_filter (مبلّلة)، وتضيّق نطاق الكتالوج على الفور ليقتصر على المعدات المطابقة بدون الحاجة إلى النقر يدويًا على مربعات الاختيار.

6. ما تعلّمته

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

ما تم إنشاؤه:

• On-device Prompt API: تمّ تركيب المخططات الزمنية لتصفّح المستخدمين باستخدام LanguageModel لإنشاء سياق JourneyProfile في الوقت الفعلي، وتمّ إنشاء محرّك rankComplementaryGear تآزري باستخدام مخططات JSON المنظَّمة (responseConstraint).
• أدوات WebMCP: أدوات مسجّلة نمطية ومغلّفة في جميع مكونات واجهة المستخدم (get_recommendations وget_current_product وview_cart وmanage_cart) من خلال document.modelContext
• بنية التوجيه إلى الوكيل: تم اختبار تنفيذ الأداة والتحقّق منه باستخدام إضافة Chrome WebMCP Inspector.
• وكيل في الصفحة على الموقع الإلكتروني: أدوات منسَّقة من جهة العميل مباشرةً في المتصفّح لتفعيل البحث في قائمة المنتجات بلغة طبيعية ومتعددة الأوجه من شريط البحث في رأس الموقع الإلكتروني
• نماذج الذكاء الاصطناعي المتخصّصة على الجهاز فقط: استكشفنا الترجمة الديناميكية على الجهاز فقط باستخدام Translator.

الخلاصات المقتطفة الرئيسية:

1. زمن استجابة معدوم ومستوى عالٍ من الخصوصية: تعمل النماذج على الجهاز فقط، مثل Gemini Nano، على إلغاء مفاتيح واجهة برمجة التطبيقات السحابية وزمن استجابة الشبكة ومخاوف استخراج البيانات.
2. النتائج المنظَّمة ضرورية: يؤدي استخدام مخططات JSON مع responseConstraint إلى تحويل عملية إنشاء النصوص الإبداعية إلى منطق تطبيق موثوق وآمن من حيث النوع.
3. تجهّز WebMCP الويب لوكلاء الذكاء الاصطناعي: يتيح تسجيل الأدوات مباشرةً في DOM لكلّ من الميزات المساعدة الداخلية ووكلاء المتصفّح المستقلين الخارجيين تنفيذ إجراءات مؤكَّدة ومحدَّدة.
4. السماح للنموذج بالاقتراح وليس التنفيذ: من خلال حصر النموذج في enum من أدواتك المسجّلة وإرسال النتيجة بنفسك، يمكنك إبقاء السلوك المستند إلى الوكلاء قابلاً للتدقيق ومنعه من ابتكار إجراءات.