AgentOps: مراقبة وكلاء الذكاء الاصطناعي وحوكمتهم باستخدام IBM Telemetry عبر watsonx Orchestrate

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

يوفر هذا البرنامج التعليمي دليلًا خطوة بخطوة لإعداد IBM Telemetry واستخدامه مع watsonx Orchestrate Developer Edition لمراقبة وكلاء الذكاء الاصطناعي وحوكمتهم. ستتعرَّف على كيفية تمكين إمكانات قابلية الملاحظة لوكلاء الذكاء الاصطناعي وتحليل سلوكهم بعمق، بدءًا من استدعاءات النماذج اللغوية الكبيرة (LLMs) الفردية وحتى مهام سير العمل متعددة الخطوات بالكامل.

بنهاية هذا البرنامج التعليمي، ستتمكن مما يلي:

• تثبيت watsonx Developer Edition وتكوينه محليًا.
• تمكين IBM Telemetry للحصول على قابلية ملاحظة شاملة لوكلاء الذكاء الاصطناعي.
• استيراد وكيل ذكاء اصطناعي مُهيأ مسبقًا واختباره مع تكامل الأدوات الخارجية.
• تحليل سلوك الوكيل من خلال التتبُّعات والمهام وعمليات الامتدادات (Span) ومهام سير العمل التفصيلية.
• تصحيح المشكلات وتحسين أداء الوكلاء باستخدام التحليلات المتقدمة.

يُعَد IBM Telemetry إطار المراقبة الأصلي في watsonx Orchestrate، حيث يلتقط معلومات تفصيلية حول كيفية تنفيذ وكلاء الذكاء الاصطناعي للطلبات. ويسجل كل خطوة في دورة حياة الوكيل، بدءًا من قرارات التوجيه وبناء المطالبات، مرورًا باستدعاءات النماذج اللغوية الكبيرة (LLMs) واستدعاءات الأدوات، ما يوفر رؤية شاملة لسلوك الوكيل.

وباستخدام IBM Telemetry، يمكنك تتبُّع مؤشرات الأداء ومراقبة تكلفة استخدام النماذج اللغوية الكبيرة (LLMs) وتحديد الأخطاء والتأكد من أن وكلاءك يعملون كما هو مخطط لهم. يوفر IBM Telemetry قابلية ملاحظة على مستوى المؤسسات، مصممة لبيئات الإنتاج وأنظمة الذكاء الاصطناعي واسعة النطاق.

قبل أن تبدأ، تأكَّد من تثبيت المتطلبات الأساسية التالية وتكوينها على نظامك:

• Python 3.8 أو أحدث (تحقق باستخدام python --version).
• ذاكرة وصول عشوائي (RAM) لا تقل عن 16 جيجابايت.
• watsonx Orchestrate Developer Edition من خلال watsonx Orchestrate ADK.

يتضمن هذا الدليل خطوات تثبيت ADK.

• حساب watsonx Orchestrate (تتوفر نسخة تجريبية مجانية لمدة 30 يومًا إذا لم يكن لديك حساب).
• مفتاح watsonx Orchestrate API الذي يتم إنشاؤه من لوحة تحكم IBM Cloud.

سيتم توضيح خطوات المصادقة لاحقًا في هذا الدليل.

للبدء، انسخ مستودع GitHub باستخدام عنوان HTTPS التالي: https://github.com/IBM/ibmdotcom-tutorials.git. للاطِّلاع على خطوات تفصيلية حول كيفية استنساخ مستودع، راجِع وثائق GitHub.

افتح المستودع في بيئة التطوير المتكاملة (IDE) التي تفضلها (مثل Visual Studio Code) ثم انتقِل إلى مجلد مشروع هذا البرنامج التعليمي: wxo-agentops. سيكون هذا الدليل هو مساحة العمل التي ستستخدمها أثناء متابعة البرنامج التعليمي.

يُعَد IBM watsonx Orchestrate Agent Development Kit (ADK) أداة لسطر الأوامر (CLI) تعمل على تبسيط عمليات تثبيت watsonx Orchestrate Developer Edition وتكوينه وإدارته.

ولاستخدام ADK، يجب ربطه ببيئة watsonx Orchestrate موجودة بالفعل. إذا لم يكن لديك حساب watsonx Orchestrate بعد، فيمكنك التسجيل للحصول على نسخة تجريبية مجانية لمدة 30 يومًا. أما إذا كان لديك حساب بالفعل، فيمكنك استخدامه لتوفير بيانات اعتماد البيئة المطلوبة لـ ADK.

سترشدك الخطوات التالية خلال عملية التثبيت باستخدام بيئة Python افتراضية، وهي الطريقة الموصى بها للحفاظ على عزل التبعيات. وللاطِّلاع على طرق تثبيت بديلة وتعليمات أكثر تفصيلًا، راجِع وثائق بدء استخدام ADK.

أنشئ بيئة Python افتراضية جديدة داخل مجلد مشروعك:

تُنشئ هذه الخطوة مجلدًا باسم .venv يحتوي على بيئة Python افتراضية معزولة.

يختلف أمر التفعيل باختلاف نظام التشغيل.

macOS وLinux

Windows

بمجرد التفعيل، ستغير المطالبة في الوحدة الطرفية (Terminal) لتُشير إلى أنك تعمل داخل البيئة الافتراضية، وعادةً ما يظهر (.venv ) في بداية المطالبة.

بعد تفعيل البيئة الافتراضية، ثبِّت ADK باستخدام pip:

يقوم هذا الأمر بتنزيل ADK وتثبيته مع جميع تبعياته. قد تستغرق عملية التثبيت بضع دقائق حتى تكتمل.

ملاحظة: إذا كان لديك إصدار أقدم من ADK مثبتًا (>2.0)، فشغِّل الأمر pip install --upgrade ibm-watsonx-orchestrate. قد تحتاج أيضًا إلى تنفيذ خطوات استكشاف الأخطاء وإصلاحها الواردة في الخطوة 4 ب.

يستخدم ADK ملف .env لمصادقة بيانات اعتماد المستخدم وتكوين watsonx Orchestrate Developer Edition. تعتمد متغيرات البيئة التي تحتاج إليها على طريقة المصادقة التي اخترتها. يستخدم هذا البرنامج التعليمي طريقة حساب watsonx Orchestrate، وهي أبسط طريقة للبدء.

للاطِّلاع على طرق مصادقة بديلة وتعليمات تفصيلية حول التكوين، راجِع وثائق تكوين ملف البيئة.

داخل دليل wxo-agentops، أنشئ ملف .env من خلال نسخ القالب المرفق.

افتح ملف .env في محرر النصوص، ثم قم بتكوين الحقلين الأساسيين التاليين:

• WO_INSTANCE : يمثل URL هذا عنوان مثيل watsonx Orchestrate الخاص بك. يمكنك العثور عليه بتسجيل الدخول إلى حساب watsonx Orchestrate والانتقال إلى تفاصيل المثيل. انقر على أيقونة الملف الشخصي > Settings، ثم افتح علامة التبويب API details. وللحصول على تعليمات تفصيلية حول البدء باستخدام واجهة برمجة التطبيقات (API)، راجِع وثائق watsonx Orchestrate.

يتَّبع عنوان URL التنسيق التالي:

انسخ عنوان URL الخاص بمثيل الخدمة وألصِقه لاستبدال القيمة الافتراضية في ملف .env. تعتمد المنطقة (على سبيل المثال، us-south) على موقعك الجغرافي.

• WO_API_KEY : هذا المفتاح هو مفتاح واجهة برمجة التطبيقات (API) الخاص بـ watsonx Orchestrate، ويُستخدم لمصادقة الاتصال بخدمات IBM Cloud. يمكنك إنشاء هذا المفتاح أو استرجاعه من لوحة معلومات حسابك في IBM Cloud. استبدِل <your-api-key> بمفتاح واجهة برمجة التطبيقات الفعلي الخاص بك. للاطِّلاع على خطوات إنشاء مفتاح واجهة برمجة التطبيقات بالتفصيل، راجِع دليل البدء.

احرص على الحفاظ على سرية مفتاح واجهة برمجة التطبيقات، ولا تقم بإضافته إلى نظام التحكم في الإصدارات.يجب أن يكون ملف .env مُدرجًا بالفعل في ملف .gitignore لمنع كشفه عن طريق الخطأ.

بعد ذلك، ستكون جاهزًا لتثبيت watsonx Orchestrate Developer Edition، الذي سيشغِّل مثيلًا محليًا لخادم watsonx Orchestrate على جهازك. تعمل هذه الخطوة أيضًا على تمكين IBM Telemetry، ما يمنحك وصولًا مباشرًا إلى ميزات قابلية الملاحظة.

فهم أمر التثبيت

يوفر ADK أمرًا واحدًا يتولى تنفيذ عملية التثبيت بالكامل:

لنلقِ نظرة على ما يفعله هذا الأمر:

• orchestrate server start : تهيئة خادم watsonx Orchestrate Developer Edition وتشغيله.
• -e <path-.env-file> : الإشارة إلى ملف التكوين الذي يحتوي على بيانات الاعتماد.
• --with-ibm-telemetry : تمكين إطار عمل قابلية الملاحظة الأصلي IBM Telemetry.

نفِّذ الأمر من داخل مجلد wxo-agentops:

يشغِّل الأمر التالي خادم watsonx Orchestrate Developer Edition من خلال تهيئة بيئة الخادم: orchestrate server start -e <path-.env-file>. تؤدي إضافة الخيار --with-ibm-telemetry إلى تمكين IBM Telemetry، وهو إطار العمل الأصلي لقابلية الملاحظة.

شغِّل الأمر التالي لتثبيت خادم watsonx Orchestrate مع IBM Telemetry:

يُنشئ هذا الأمر حاويات داخلية يديرها ADK من أجل:

• خادم watsonx Orchestrate
• قواعد بيانات PostgreSQL وRedis
• خدمات IBM Telemetry
• التبعيات الداعمة

يُنشئ ADK تلقائيًا شبكة افتراضية تُتيح لهذه الحاويات التواصل مع بعضها عبر http://localhost:3000.

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

إذا ظهرت لك هذه الرسالة، فتهانينا! أصبحت بيئة watsonx Orchestrate المحلية لديك، مع IBM Telemetry، قيد التشغيل الآن.

إذا فشلت عملية التثبيت أو توقفت، فجرِّب الخطوات التالية:

1. إعادة تعيين الخادم:

يؤدي هذا الأمر إلى إيقاف جميع الحاويات التي أنشئت لـ watsonx Orchestrate وإزالتها، ما يمنحك بيئة نظيفة للبدء من جديد.

2. إعادة تشغيل التثبيت:

بعد إعادة التعيين، شغِّل أمر البدء مرة أخرى.

3. التحقق من سجلات الخادم وحالة الحاويات:

يمكنك عرض سجلات خدمات خادم Orchestrate للتحقق من وجود أي تحذيرات أو أخطاء.

إذا لم تنجح الخطوات السابقة، فأعِد تعيين الخادم بإزالة بيئة الخادم بالكامل باستخدام orchestrate server purge، ثم أعِد تثبيته.

بعد تثبيت خادم watsonx Orchestrate بنجاح، ستحتاج إلى تفعيل بيئتك المحلية وتشغيل واجهة الدردشة التي ستتفاعل من خلالها مع وكلاء الذكاء الاصطناعي.

يدعم watsonx Orchestrate ADK عدة بيئات، مثل المحلية والتطوير والإنتاج وغيرها. ولذلك، يجب عليك تفعيل البيئة المحلية التي أنشأتها صراحةً.

من المفترض أن تتلقى رسالة تؤكِّد أن البيئة أصبحت نشطة.

يؤدي هذا إلى تعيين البيئة المحلية كسياق افتراضي لجميع أوامر ADK اللاحقة. وبذلك، سيتم توجيه جميع الوكلاء والأدوات والإعدادات التي تعمل عليها إلى هذا المثيل المحلي.

شغِّل خدمة واجهة دردشة watsonx Orchestrate باستخدام الأمر التالي:

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

توفِّر واجهة الدردشة وسيلة سهلة للتفاعل مع وكلاء الذكاء الاصطناعي. إذا لم يفتح المتصفح تلقائيًا، فيمكنك الانتقال يدويًا إلى: http://localhost:3000/chat-lite.

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

بعد إعداد البيئة، حان الوقت لاستيراد وكيل ذكاء اصطناعي مُهيأ مسبقًا، ليوضِّح قدرات المراقبة التي يوفرها IBM Telemetry. يستخدم وكيل الطقس أداة تعتمد على واجهة برمجة تطبيقات (API) خارجية لجلب بيانات الطقس في الوقت الفعلي، ما يوفر مثالًا عمليًا يمكنك مراقبته وتحليله.

يُعَد وكيل الطقس نقطة انطلاق مثالية لأنه:

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

من الدليل الجذر للمشروع (wxo-agentops)، انتقِل إلى مجلد Weather Agent:

يحتوي هذا المجلد على ملفَي تكوين بصيغة YAML:

• get_weather.yaml : يعرِّف أداة واجهة برمجة تطبيقات الطقس.
• weather_agent.yaml : يعرِّف الوكيل الذي يستخدم هذه الأداة.

الأدوات هي قدرات قابلة لإعادة الاستخدام يمكن للوكلاء استدعاؤها لتنفيذ إجراءات محددة. استورِد أدوات get_weather أولًا:

يُشير الخيار --kind openapi إلى أن هذه الأداة تستخدم مواصفة OpenAPI لتعريف واجهتها. يجب أن تظهر رسالة تؤكد أنه تم استيراد الأداة بنجاح.

بعد ذلك، استورِد الوكيل الذي سيستخدم هذه الأداة.

يسجل هذا الأمر وكيل الطقس في بيئة watsonx Orchestrate المحلية لديك. ويتم تكوين الوكيل مسبقًا بما يلي:

• تعليمات حول كيفية تفسير بيانات الطقس.
• إذن استدعاء الأداة get_weather.
• آلية احتياطية للتعامل مع المواقع غير الصحيحة.

عُد الآن إلى المتصفح الذي تعمل فيه واجهة الدردشة. قد تحتاج إلى تحديث الصفحة حتى يظهر الوكيل الذي تم استيراده حديثًا.

انقر على القائمة المنسدلة الخاصة بالوكلاء (وتوجد عادةً أعلى واجهة الدردشة)، ثم اختَر Weather_Agent من القائمة.

بعد تحديد وكيل الطقس (Weather Agent)، جرِّب طرح بعض الأسئلة لتوليد بيانات المراقبة.

أمثلة على الاستعلامات:

• "كيف هو الطقس في مدينة نيويورك؟".
• "هل يمكنك إخباري بدرجة الحرارة الحالية في لندن؟".
• "ما حالة الطقس في طوكيو؟".
• "هل تمطر الآن في سياتل؟".

سيعالج الوكيل كل طلب من خلال:

1. فهم استفسارك.
2. استخراج الموقع.
3. استدعاء الأداة get_weather باستخدام الإحداثيات المناسبة.
4. تفسير بيانات الطقس.
5. تقديم الإجابة بلغة طبيعية.

يسجِّل IBM Telemetry كل تفاعل تُجريه مع وكيل الطقس. ويشمل ذلك تسجيل:

• السياق الكامل للمحادثة.
• جميع استدعاءات النماذج اللغوية الكبيرة (LLMs) وعدد الرموز المميزة المستخدمة.
• استدعاءات الأدوات مع المدخلات والمخرجات الخاصة بها.
• قرارات التوجيه وخطوات سير العمل.
• أوقات التنفيذ ومقاييس الأداء.
• أي أخطاء أو استثناءات تحدث.
• التفاعلات مع المزوِّدين الخارجيين وأوقات استجابتهم.

في الخطوة التالية، ستستكشف بيانات القياس عن بُعد هذه بالتفصيل لفهم كيفية عمل الوكيل بدقة.

والآن نصل إلى أقوى جزء في هذا البرنامج التعليمي: استخدام IBM Telemetry للحصول على رؤية عميقة لسلوك الوكيل. يوفر IBM Telemetry عدة طرق عرض وأدوات تحليلية تُتيح لك فهم كل جانب من جوانب كيفية معالجة الوكيل للطلبات.

افتح متصفحك وانتقِل إلى الرابط التالي: https://localhost:8765/?serviceName=wxo-server. توفِّر هذه الواجهة ميزة إعادة تشغيل الجلسات، التي تُتيح لك إعادة استعراض تفاعلات الوكيل السابقة لتحليلها.

ملاحظة: يستخدم عنوان URL القيمة https، ولكن نظرًا لأن هذه بيئة تطوير محلية، فقد يعرض متصفحك تحذيرًا بشأن شهادة موقَّعة ذاتيًا (Self-signed Certificate). هذه الرسالة متوقعة، ويمكنك المتابعة بأمان في بيئة التطوير المحلية.

عند ظهور شاشة تسجيل الدخول، أدخِل أي اسم (لتمييز جلستك المحلية)، ثم انقر على Login.

سينقلك ذلك إلى لوحة معلومات IBM Telemetry الرئيسية.

تعرض لوحة المعلومات قائمة بأحدث التتبُّعات، حيث يمثل كل تتبُّع تفاعلًا واحدًا بين المستخدم والوكيل. انقر على أول تتبُّع في لوحة Trace and Group Selection لعرض تحليلات تفصيلية لأحدث محادثة أجريتها مع وكيل الطقس.

تنقلك هذه الخطوة إلى شاشة Agent Analytics، التي تمثِّل المركز الرئيسي لفهم سلوك الوكيل.

توفِّر شاشة Agent Analytics نظرة عامة على التتبُّع المحدد، وتشمل ما يلي:

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

توفِّر هذه النظرة العامة عالية المستوى فهمًا سريعًا لما إذا كان الوكيل قد عمل كما هو متوقع، ومدى كفاءة أدائه.

يُعَد قسم Tasks المكان الذي ستقضي فيه معظم وقتك عند تحليل سلوك الوكيل. فهو يعرض مخططًا زمنيًا مرئيًا، خطوة بخطوة، لكل ما قام به الوكيل أثناء معالجة الطلب، بما في ذلك كل استدعاء للنموذج اللغوي الكبير (LLM) وكل استدعاء للأدوات وقرارات التوجيه وإنشاء المخرجات.

ويتم تنظيم المهام بشكل هرمي ليعكس كيفية تنفيذ الوكيل لسير العمل فعليًا، ما يجعل من السهل فهم تسلسل العمليات والعلاقات بينها.

لنستعرض الآن مسار التنفيذ القياسي لطلب يعالجه وكيل watsonx Orchestrate. من المفترض أن يُظهر تتبُّع وكيل الطقس (Weather Agent) بنية مشابهة للمثال التالي.

يعرض سير العمل هذا دورة الحياة الكاملة لاستعلام مستخدم واحد. وفيما يلي ما تمثله كل مهمة:

• 0:_ROOT : تمثل أعلى مستوى في التتبُّع وتحتوي على جميع المهام الفرعية. ويمكن اعتبارها المجلد الذي يضم عملية تنفيذ الوكيل بالكامل. وهي تحدد وقت بداية التتبُّع ونهايته، بدءًا من لحظة وصول الطلب إلى النظام وحتى تسليم الاستجابة النهائية.

وتكتسب هذه المهمة أهمية كبيرة لأن مدتها تمثِّل إجمالي زمن الاستجابة الذي اختبره المستخدم. فإذا كانت المدة طويلة، فيمكنك تحليل المهام الفرعية لتحديد العوائق.

• 0.0:agent_style_router : تحدد مهمة التوجيه الوكيل الذي سيتولى معالجة الرسالة، كما تصنِّف الطلب وفق أسلوب المعالجة المناسب. يحلِّل جهاز التوجيه الطلب الوارد ليقرر إذا ما كان يحتاج إلى معالجة حوارية، أو تنفيذ يعتمد على الأدوات، أو توليد معزز بالاسترجاع (RAG)، أو تنسيق بين عدة وكلاء.

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

• 0.1:agent : تمثِّل سياق التنفيذ الرئيسي للوكيل الذي ينسِّق معالجة الطلب بالكامل. تجمع هذه المهمة المطالبة (Prompt) من تعليمات النظام وسجل المحادثة واستجابات الأدوات، وتطبِّق قواعد وسياسات التنسيق، ثم تُعِد المدخلات اللازمة للنموذج اللغوي الكبير (LLM). كما تحدد نوع الاستدعاء الذي سيتم إجراؤه للنموذج اللغوي الكبير.

وهنا يحدث الجانب "الذكي" من عملية التنسيق، حيث تضمن هذه المهمة تزويد النموذج اللغوي الكبير بجميع المعلومات السياقية اللازمة لاتخاذ قرارات مستنيرة.

• 0.1.0:WatsonxChatModel.chat : تمثِّل الاستدعاء الفعلي للنموذج اللغوي الكبير، حيث يتلقى المطالبة الكاملة ويقرر إذا ما كان سيستدعي أداة، أو يطلب توضيحًا، أو يقدِّم إجابة مباشرة. وتُنتج في النهاية استجابة نصية أو استدعاءات منظمة للأدوات.

هذه الخطوة هي خطوة "التفكير"، حيث يعالج النموذج المعلومات ويتخذ القرارات. كما أن استخدام الرموز المميزة وزمن الاستجابة وجودة النتائج، كلها ترتبط بهذه المهمة. وإذا كان الوكيل بطيئًا أو مرتفع التكلفة، فغالبًا ما تكون هذه المهمة هي المساهم الرئيسي في ذلك.

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

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

ملخص سير العمل الخاص بالمهام

باختصار، يمر سير العمل بالمراحل التالية:

1. يحدد جهاز التوجيه (Router) كيفية معالجة الطلب.
2. يعمل الوكيل (Agent) على تجهيز السياق ومنطق التنسيق.
3. يُنشئ النموذج اللغوي الكبير (LLM) الاستجابة أو استدعاءات الأدوات.
4. تعمل الإجابة (Answer) على تنسيق المخرجات وإظهار الاستجابة النهائية.

يتم تغليف سير العمل بالكامل داخل حاوية الطلب ROOT، ما يمنحك رؤية شاملة لتنفيذ الوكيل من البداية إلى النهاية. يمثل هذا المستوى من قابلية الملاحظة عنصرًا أساسيًا لفِرق MLOps وDevOps التي تُدير عمليات الوكلاء ومسارات المعالجة المعقدة على نطاق واسع.

تحتوي كل مهمة في هذا التسلسل الهرمي على ثلاث فئات من السمات، توفِّر بيانات تعريفية تفصيلية حول ما استهلكته المهمة وما أنتجته:

1. سمات الإدخال (Input Attributes): تعرض كل ما تلقته المهمة قبل التنفيذ، مثل الرسائل واستجابات الأدوات وتعليمات النظام والحالة الداخلية.

مثال: بالنسبة للمهمة WatsonxChatModel.chat، ستتضمن سمات الإدخال المطالبة المجمَّعة بالكامل، ما يشمل تعليمات النظام وسجل المحادثة وأي نتائج للأدوات تحتاج إلى تفسير.

2. سمات الإخراج (Output Attributes): تعرض ما أنتجته المهمة، بما في ذلك استجابات النموذج اللغوي الكبير (LLM) واستدعاءات الأدوات والقرارات.

مثال: قد تُنتج المهمة نفسها WatsonxChatModel.chat استجابة بلغة طبيعية أو استدعاءً منظَّمًا لأداة مثل get_weather(latitude=40, longitude=-74).

3. السمات العامة (General Attributes): توفِّر بيانات Telemetry الوصفية، مثل استخدام الرموز المميزة ومعلومات التوقيت والمعرِّفات الفريدة ومعلومات النموذج.

مثال: قد ترى أن إحدى المهام استخدمت 450 رمز إدخال (Input Tokens) و120 رمز إخراج (Output Tokens)، واستغرقت 1.2 ثانية للتنفيذ، واعتمدت على النموذج ibm/granite-3.1-8b-instruct model.

كيفية استخدام سمات المهام

تُتيح لك هذه السمات، مجتمعةً، فهم ما شاهده النموذج والقرارات التي اتخذها وكيفية استجابته.

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

تتضمن كل مهمة مقاييس مرتبطة بالأداء والتكلفة تلخِّص كيفية تنفيذها. وتوفِّر هذه المقاييس بيانات كمية حول أداء الوكيل.

تشمل المقاييس الرئيسية ما يلي:

• إجمالي وقت التنفيذ: المدة التي استغرقتها المهمة من البداية حتى النهاية.
• عدد استدعاءات النموذج اللغوي الكبير (LLM): عدد مرات استدعاء النموذج اللغوي.
• عدد استدعاءات الأدوات: عدد مرات استدعاء الأدوات الخارجية.
• استخدام الرموز المميزة: رموز الإدخال ورموز الإخراج وإجمالي الرموز المميزة المستهلكة.
• تقديرات التكلفة: تقديرات تقريبية للتكلفة استنادًا إلى استخدام الرموز المميزة (عند توفُّر بيانات التسعير).
• توزيع المهام الفرعية: كيفية توزيع العمل بين المهام الفرعية.

تساعدك هذه المقاييس على تحسين الأداء وتصحيح سلوك الوكيل. كما تساعد على تحديد المهام البطيئة التي يمكن تنفيذها بالتوازي أو الاستفادة من التخزين المؤقت (Caching) لتحسينها. وتُعَد هذه الرؤية ضرورية لتخطيط السعة؛ لأنها تساعدك على فهم الموارد المطلوبة للتوسع، بالإضافة إلى تتبُّع استهلاك الرموز المميزة للتحكم في النفقات.

على سبيل المثال، إذا لاحظت أن أحد التتبُّعات استغرق 8 ثوانٍ، بينما لم تستغرق استدعاءات النموذج اللغوي الكبير سوى 0.5 ثانية، فهذا يعني أن سبب التأخير يقع في مكان آخر، وغالبًا ما يكون في تنفيذ الأدوات أو زمن استجابة الشبكة.

بينما تعرض المهام سير العمل المنطقي الذي ينفِّذه الوكيل، تمثِّل الامتدادات (Spans) العمليات الداخلية التي ينفِّذها النظام أثناء التنفيذ. وبالنقر على علامة التبويب Spans، يمكنك الاطِّلاع على ما تقوم به المنصة داخليًا لمعالجة كل طلب.

توفِّر الامتدادات (Spans) رؤية تفصيلية لخطوات التنفيذ منخفضة المستوى التي يسجلها إطار عمل التنسيق، وهو في هذه الحالة LangGraph، وهو إطار عمل مفتوح المصدر يعمل داخل wxo-server. ويمثل كل امتداد (Span) عملية مستقلة، مثل:

• توجيه الطلب إلى الوكيل المناسب (agent_style_router).
• استدعاء الوكيل وتهيئة سياق عمله (agent.task).
• إنشاء المطالبات (Prompts) والسياق بالاعتماد على القوالب (ChatPromptTemplate.task).
• استدعاء النموذج اللغوي الكبير (LLM) باستخدام المطالبة المجمَّعة (WatsonxChatModel.chat).
• إرجاع النتائج إلى المستخدم (answer.task).

بينما تعرض المهام الخطوات المنطقية لتنفيذ الوكيل (أي ما الذي يحاول الوكيل إنجازه)، تعرض الامتدادات (Spans) الخطوات التقنية التي ينفِّذها النظام (أي كيف ينجز النظام ذلك). ويمنحك هذا المنظور المزدوج فهمًا عالي المستوى، إلى جانب القدرة على تصحيح المشكلات على المستوى الفني.

مثال: قد تحتوي مهمة واحدة مثل 0.1:agent على عدة امتدادات (Spans) تمثِّل استعلامات قاعدة البيانات، وعمليات البحث في الذاكرة المؤقتة (Cache)، وتحميل التكوينات. تتم هذه العمليات خلف الكواليس لدعم تنفيذ الوكيل.

يتضمن كل امتداد علامات (Tags) توفِّر بيانات وصفية وسياقًا إضافيًا. وتُعَد هذه العلامات ضرورية لعمليات التصفية وتصحيح الأخطاء وتحليل أداء الوكيل.

تشمل علامات الامتدادات (Spans) الشائعة ما يلي:

• تعريف الوكيل: agent_id.agent_name
• تتبُّع الجلسة: thread_id، session_id.conversation_id
• سياق مهام سير العمل: step_number، workflow_path.parent_span_id
• بيانات الأداء: token_count، duration_ms.model_name
• تفاصيل الطلب: tool_calls، input_preview.output_preview

تُستخدم الامتدادات في: تتبُّع أسباب التأخير وفهم حالات الفشل من خلال تحديد العنصر الداخلي الذي تعطَّل وتحليل الأنماط عبر تصفية الامتدادات باستخدام العلامات لاكتشاف التوجُّهات والربط بين الامتدادات عبر عدة تتبُّعات باستخدام معرِّفات الجلسات.

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

توفر علامة التبويب Workflows تصورًا هرميًا يُعرَف باسم Runnables Tree، يعرض البنية الكاملة لتنفيذ سير عمل الوكيل. وتُعَد هذه الرؤية مفيدة بشكل خاص لفهم الأنظمة متعددة الوكلاء وأنماط التنفيذ المتداخلة.

في إطار عمل watsonx Orchestrate، تُعَد الوحدة القابلة للتشغيل (Runnable) وحدة عمل أو مهمة قابلة للتنفيذ. ويمكن أن تكون الوحدات القابلة للتشغيل:

• عمليات بسيطة: مثل استدعاء واحد لنموذج لغوي كبير (LLM) أو لأداة.
• مهام سير عمل مركَّبة: تضم عدة وحدات قابلة للتشغيل مترابطة.
• فروع شرطية: مسارات تنفيذ مختلفة تعتمد على شروط محددة.
• عمليات تنفيذ متوازية: عدة وحدات قابلة للتشغيل تعمل في الوقت نفسه.

تعرض Runnables Tree العلاقات بين العناصر الرئيسية والفرعية، ما يجعل من السهل معرفة ما يلي:

• المهام التي تؤدي إلى تشغيل مهام أخرى، من خلال تتبُّع سلسلة التنفيذ.
• الفرق بين التنفيذ المتوازي والتنفيذ التسلسلي، لفهم تزامن سير العمل.
• منطق التفرع، وكيف تؤدي القرارات إلى مسارات تنفيذ مختلفة.
• عمق سير العمل، ومدى تعقيد منطق الوكيل.

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

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

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

يمكنك التفاعل مع الشجرة من خلال:

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

وتجعل هذه الطريقة المرئية تصحيح أخطاء مهام سير العمل أسهل بكثير من محاولة تتبُّع سجلات النصوص أو بيانات التتبُّع فقط.

توفِّر علامة التبويب Eval (Evaluation) طريقة عرض مخصصة لضمان الجودة والمراقبة، حيث تقيس مدى صحة وموثوقية تنفيذ الوكيل. وفي هذه المرحلة، تنتقل من مجرد معرفة ما الذي حدث إلى تقييم مدى جودة ما حدث.

تعرض علامة التبويب Eval نتائج التقييم التي تقيس الجودة من خلال ضوابط الحماية، وتشمل ما يلي:

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

تساعد التقييمات على مراقبة الموثوقية من خلال قياس مدى اتساق الوكيل في إنتاج نتائج صحيحة واكتشاف الحالات التي تؤدي فيها التغييرات إلى تراجع أداء الوكيل وتحديد أولويات التحسين وتعزيز الثقة في الوكيل من خلال التحقق من صحة أدائه قبل نشره في بيئة الإنتاج.

كما يمكنك الاستفادة من نتائج التقييم في إعداد التنبيهات وتتبُّع التحسينات بمرور الوقت واكتشاف الأنماط المتكررة واستخدام الملاحظات لتوجيه عملية التطوير وتحسين المطالبات أو الأدوات.

إذا لاحظت أن 15% من استعلامات الطقس تفشل في التقييم، فيمكنك فحص تلك التتبُّعات المحددة لمعرفة إذا ما كانت المشكلة ناتجة عن سوء معالجة المدخلات، أو فشل واجهات برمجة التطبيقات (APIs)، أو تنسيق غير صحيح للاستجابة.

توفِّر علامة التبويب Issues عرضًا مركزيًا لجميع المشكلات التي حدثت أثناء تنفيذ سير العمل. ويُعَد هذا التبويب نقطة البداية الأولى عند تصحيح أعطال الوكيل أو السلوك غير المتوقع.

تعرض علامة التبويب Issues مشكلات مثل:

• فشل استدعاءات واجهات برمجة التطبيقات (API Calls): عندما تُظهر الخدمات الخارجية أخطاءً.
• فشل تنفيذ الأدوات: عندما تتعطل الأدوات أو تتجاوز المهلة الزمنية.
• المدخلات المفقودة: عندما لا تتوفر البيانات المطلوبة عند الحاجة إليها.
• استثناءات النماذج: أخطاء النموذج اللغوي الكبير (LLM)، مثل تجاوز حد الرموز المميزة أو استخدام مدخلات غير صالحة.
• أخطاء التحقق من الصحة: عندما لا تتوافق البيانات مع التنسيق المتوقع.
• أخطاء انتهاء المهلة: عندما تتجاوز العمليات الزمن المسموح به.
• أخطاء وقت التشغيل غير المعالجة: الاستثناءات غير المتوقعة في تعليمات الوكيل البرمجية.

في لقطة الشاشة أعلاه، يمكنك ملاحظة Tool Error حدث عندما أعادت واجهة برمجة تطبيقات الطقس رمز الخطأ 424 (Failed Dependency) أو 404 (Not Found). وتعرض علامة التبويب Issues ما يلي:

1. نوع الخطأ: Tool Error
2. الأداة المتأثرة: get_weather
3. استجابة الخطأ: الاستجابة الكاملة لواجهة برمجة التطبيقات التي توضِّح سبب الفشل.
4. رابط مباشر: انقر عليه للانتقال مباشرةً إلى المهمة التي وقع فيها الخطأ.

يسهِّل هذا الأسلوب فهم سبب المشكلة دون الحاجة إلى البحث في السجلات أو بيانات التتبُّع.

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

توفِّر علامة التبويب Trajectory عرضًا زمنيًا على هيئة محادثة يوضِّح التفاعل بين المستخدم والوكيل، بالإضافة إلى أي أدوات يستدعيها الوكيل أثناء التنفيذ. ويُعَد هذا العرض بالغ الأهمية لفهم السياق الكامل وتدفق سلوك الوكيل.

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

لنستعرض مسار تنفيذ وكيل الطقس (Weather Agent) الظاهر في لقطة الشاشة:

1. استعلام المستخدم

تبدأ المحادثة بطلب واضح ومحدد يتعلق بحالة الطقس في مدينة نيويورك.

2. استدعاء الوكيل للأداة

يدرك الوكيل أنه يحتاج إلى بيانات خارجية، فيستدعي أداة الطقس.

يوضِّح هذا المثال أن الوكيل حدَّد الإحداثيات التقريبية لمدينة نيويورك بصورة صحيحة وأنشأ طلب واجهة برمجة التطبيقات (API) بالتنسيق المناسب وعيَّن الخيار الصحيح للحصول على بيانات الطقس الحالية.

يعرض IBM Telemetry هذه النتيجة بصيغة JSON الخام، بالإضافة إلى عرض شجري منسق وقابل للتوسيع.

3. إظهار الأداة للبيانات

تُعيد واجهة برمجة تطبيقات الطقس بيانات طقس منظمة.

يوضِّح هذا المثال أن الأداة نجحت في استرجاع البيانات والاستجابة تتَّبع المخطط (Schema) المتوقع وجميع الحقول المطلوبة موجودة. ويُعَد فحص الاستجابة الخام للأداة أمرًا بالغ الأهمية عند تصحيح المشكلات التي يُسيء فيها الوكيل تفسير مخرجات الأدوات.

4. تلخيص الوكيل للنتيجة

أخيرًا، يعالج الوكيل البيانات المنظمة ويقدِّم استجابة طبيعية للمستخدم.

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

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

تهانينا! لقد نجحت في إعداد IBM Telemetry مع watsonx Orchestrate، وتعرَّفت على كيفية مراقبة سلوك وكلاء الذكاء الاصطناعي وتحليله بعمق. يوفر IBM Telemetry مستويات متعددة من الرؤية تمنحك قابلية مراقبة شاملة لكيفية تفكير وكلاء الذكاء الاصطناعي لديك واتخاذهم للقرارات وتنفيذهم للإجراءات. وتُعَد القدرات التي استعرضتها ضرورية للإدارة الفعَّالة لدورة حياة عمليات الوكلاء في بيئات الإنتاج، أو عند دمجها مع أطر عمل أخرى للوكلاء داخل بيئتك.

إذا واجهت أي مشكلات أو كانت لديك أسئلة، فراجِع الوثائق. يتناول دليل استكشاف الأخطاء وإصلاحها معظم المشكلات الشائعة. ويمكنك أيضًا مراجعة قسم مشكلات GitHub لمعرفة إذا ما كان آخرون قد واجهوا مشكلات مماثلة.

لقد أدَّت مراقبة الوكلاء من خلال منصات مثل IBM Telemetry إلى إنشاء منظومة متكاملة لـ AgentOps، وأصبح عنصرًا أساسيًا مع تزايد تعقيد الوكلاء المستقلين وتوليهم مهام تتضمن التكامل مع SDKs والأدوات وواجهات برمجة التطبيقات الخارجية. وتُتيح لك الرؤية التي اكتسبتها حول سلوك الوكلاء إنشاء أنظمة ذكاء اصطناعي أكثر موثوقية وكفاءة وجديرة بالثقة.