اختبر، ونشر، ودمج الوكلاء

مكتمل

‏‫ملاحظة‬

راجع علامة التبويب النص والصور لمزيد من التفاصيل!

الاختبار، والنشر، والنشر هي خطوات حاسمة في الانتقال من التطوير إلى الإنتاج. يوفر Microsoft Foundry قدرات شاملة للتحقق من سلوك الوكلاء، ونشرها في مشروع Foundry الخاص بك، ونشر الوكلاء كنقاط نهاية قابلة للاستدعاء يمكن للمستهلكين والتطبيقات الخارجية استخدامها.

استراتيجيات اختبار الوكلاء

تضمن الاختبارات الدقيقة سلوك وكلائك بشكل موثوق عبر سيناريوهات متنوعة قبل الوصول إلى المستخدمين. توفر كل من بوابة Foundry وامتداد تعليمة Visual Studio برمجية ملاعب للاختبار التفاعلي.

استخدام الملعب بفعالية:

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

تسجيل نتائج الاختبارات لتتبع التحسينات واكتشاف الانحدارات.

نشر الوكلاء إلى مشروعك

يدعم Microsoft Foundry نشر الوكلاء من البوابة أو كود Visual Studio. النشر يحفظ تكوين الوكيل الخاص بك في مشروع Foundry الخاص بك حتى تتمكن من الاختبار والتكرار.

النشر من بوابة Foundry

1. انتقل إلى وكيلك في بوابة Foundry
2. تحقق من أن التكوين ونتائج الاختبار مرضية
3. اختر الحفظ من صفحة الوكيل
4. تأكيد الإصدار وإعدادات النشر

النشر من تعليمة Visual Studio برمجية

1. افتح وكيلك في مجموعة أدوات الذكاء الاصطناعي
2. اختر خيار الحفظ إلى المصنع لدفع تغييرات التكوين
3. بالنسبة للوكلاء المستضافين، افتح قائمة +Build في أدوات المطورين واختر Deploy to Microsoft Foundry
4. اختر تكوين الحاوية الخاص بك وتأكد

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

وكلاء النشر إلى نقطة نهاية

النشر ينقل وكيلا من مساحة عمل مشروعك إلى مورد Azure مدار يسمى تطبيق الوكيل. هذه الخطوة هي التي تجعل وكيلك قابلا للاتصال خارجيا عبر نقطة نهاية مستقرة.

ما الذي يخلقه النشر

عندما تنشر نسخة وكيل، تقوم Foundry بإنشاء ما يلي:

• تطبيق الوكيل - مورد Azure له عنوان استدعاء خاص به، وسياسة مصادقة، وهوية وكيل إنترا.
• النشر - نسخة تشغيل لإصدار وكيل معين داخل التطبيق، مع إدارة دورة حياة التشغيل/الإيقاف.

الفرق الرئيسي بين النشر والنشر هو النطاق. النشر يبقي الوكيل ضمن مشروعك. النشر يخلق نقطة نهاية مخصصة يمكن للمستهلكين الخارجيين الاتصال بها دون الحاجة للوصول إلى مشروع Foundry الخاص بك.

النشر من بوابة Foundry

1. في البوابة، اختر النسخة التي تريد نشرها في الوكيل
2. اختر النشر لإنشاء تطبيق الوكيل والنشر

النشر من كود فيجوال ستوديو

1. افتح لوحة الأوامر (Ctrl+Shift+P) وشغل Microsoft Foundry: نشر الوكيل المستضاف للوكلاء المستضافين
2. اختر إعداد مساحة العمل والحاوية المستهدفة
3. تأكيد ونشر

بعد النشر، يظهر الوكيل في قسم الوكلاء المستضافين (المعاينة) في عرض شجرة التوسعات لمجموعة أدوات الذكاء الاصطناعي.

نقطة نهاية تطبيق الوكيل

الوكلاء المنشورون يعرضون نقطة نهاية مستقرة باستخدام بروتوكول واجهة برمجة التطبيقات Responses:

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

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

المصادقة والهوية

تستخدم تطبيقات الوكيل معرف Microsoft Entra للمصادقة. يجب أن يكون لدى المتصلين دور مستخدم الذكاء الاصطناعي في Azure على مورد تطبيق الوكيل. مصادقة مفاتيح API غير مدعومة لتطبيقات الوكلاء.

مهم

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

التحقق من نقطة النهاية

بعد النشر، تحقق من أن النقطة النهائية تعمل:

1. الحصول على رمز مميز للوصول:

   az account get-access-token --resource https://ai.azure.com
   

2. اتصل بنقطة نهاية تطبيق الوكيل:

   curl -X POST \
     "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"input":"Say hello"}'
   

إذا استلمت 403 Forbidden، تأكد من أن المتصل لديه دور مستخدم Azure AI في مورد تطبيق الوكيل.

تحديث الوكلاء المنشورين

لإطلاق نسخة وكيل جديدة:

1. قم بإجراء تغييرات في بيئة التطوير الخاصة بك واختبر جيدا
2. في بوابة Foundry، اختر نشر التحديثات من ملعب الوكلاء
3. يقوم تطبيق الوكيل بتوجيه 100% من حركة المرور تلقائيا إلى النسخة الجديدة

يبقى عنوان URL نقطة النهاية دون تغيير، لذا تستمر التكاملات الحالية في العمل.

توليد كود التكامل

يقوم امتداد Microsoft Foundry VS Code بإنشاء كود تكامل نموذجي لربط تطبيقك بوكيل منشور:

1. اختر وكيلك المنتشرة في عرض My Resources
2. اختر رمز العرض
3. اختر مجلدك
4. يقوم الامتداد بتوليد كود للمصادقة، والاتصال، وإرسال الرسائل، ومعالجة الردود

أنماط التكامل

تشمل الأنماط الشائعة لدمج الوكلاء المنشورين:

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

اعتبارات الإنتاج

يتطلب تشغيل الوكلاء في الإنتاج اهتماما بعدة مجالات تشغيلية:

• المراقبة - تتبع أوقات الاستجابة، معدلات نجاح استدعاء الأدوات، أنماط الأخطاء، واستهلاك الرموز باستخدام دمج Application Insights مع التطبيقات.
• الأمان - استخدم الهويات المدارة للمصادقة، وتطبيق الوصول ذو الامتيازات الأقل، وتحديد سياسات الاحتفاظ بالبيانات.
• إدارة التكاليف - مراقبة استخدام الرموز، وتحديد حدود طول الاستجابة، وتنفيذ تحديد المعدل لمنع الارتفاعات المفاجئة.
• معالجة الأخطاء - تنفيذ منطق إعادة المحاولة مع ارتداد أسي للأعطال المؤقتة. تعامل مع تحديد السعر باستخدام استراتيجيات التراجع. تحقق من صحة المدخلات قبل إرسالها إلى الوكلاء.
• إدارة المحادثات - تدعم نقاط نهاية تطبيق الوكيل حاليا فقط واجهة برمجة التطبيقات Responses بدون حالة. قم بتخزين سجل المحادثات في عميلك لتجارب متعددة الأدوار.