تصحيح نقاط النهاية عبر الإنترنت محليا في Visual Studio Code

ينطبق على:ملحق ML Azure CLI v2 (الحالي)Python SDK azure-ai-ml v2 (الحالي)

تعرف على كيفية استخدام مصحح أخطاء Microsoft Visual Studio Code لاختبار نقاط النهاية عبر الإنترنت وتصحيحها محليا قبل نشرها في Azure.

تساعدك نقاط النهاية المحلية في التعلم الآلي من Microsoft Azure على اختبار وتصحيح البرنامج النصي لتسجيل النقاط وتكوين البيئة وتكوين التعليمة البرمجية ونموذج التعلم الآلي محلياً.

هام

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

لمزيد من المعلومات، راجع ⁧⁩شروط الاستخدام التكميلية لمعاينات Microsoft Azure⁧⁩.

يمكن أن يساعدك تصحيح أخطاء نقاط النهاية محلياً قبل نشرها على السحابة في اكتشاف الأخطاء في التعليمة البرمجية الخاصة بك والتكوين مسبقاً. لديك خيارات مختلفة لتصحيح أخطاء نقاط النهاية محليا باستخدام Visual Studio Code.

• خادم HTTP للاستدلال على Azure التعلم الآلي
• نقطة النهاية المحلية

يركز هذا الإرشاد على نقاط النهاية المحلية.

يوفر الجدول التالي نظرة عامة على السيناريوهات لمساعدتك في اختيار الأفضل بالنسبة لك.

السيناريو	خادم الاستدلال HTTP	نقطة النهاية المحلية
تحديث بيئة Python المحلية، دون إعادة إنشاء صورة Docker	‏‏نعم‬	لا
تحديث البرنامج النصي لتسجيل النقاط	‏‏نعم‬	‏‏نعم‬
تحديث تكوينات النشر (النشر، البيئة، التعليمة البرمجية، النموذج)	لا	‏‏نعم‬
تكامل مصحح أخطاء Visual Studio Code	‏‏نعم‬	‏‏نعم‬

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

Azure CLI

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

• Docker
• Visual Studio Code
• Azure CLI
• ملحق التعلم الآلي من Azure CLI (v2)

لمزيد من المعلومات، راجع الدليل حول كيفية إعداد النظام لنشر نقاط النهاية عبر الإنترنت.

تستند الأمثلة في هذه المقالة إلى نماذج التعليمات البرمجية الموجودة في مستودع GitHub azureml-examples . لتشغيل الأوامر محليا دون الحاجة إلى نسخ/لصق YAML والملفات الأخرى، قم باستنساخ المستودع ثم قم بتغيير الدلائل إلى azureml-examples/cli:

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

إذا لم تكن قد قمت بالفعل بتعيين الإعدادات الافتراضية لـAzure CLI، فاحفظ الإعدادات الافتراضية. لتجنب تمرير قيم الاشتراك ومساحة العمل ومجموعة الموارد عدة مرات، قم باستخدام الأوامر التالية. قم باستبدال المعلمات التالية بقيم للتكوين المحدد:

• استبدل <subscription> بمعرف اشتراك Azure الخاص بك.
• استبدل <workspace> بمساحة عمل التعلم الآلي من Azure.
• استبدل <resource-group> بمجموعة موارد Azure التي تحتوي على مساحة العمل لديك.
• استبدل <location> بمنطقة Azure التي تحتوي على مساحة العمل.

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

تلميح

بإمكانك معرفة ما الإعدادات الافتراضية الحالية باستخدام الأمر az configure -l.

Python

ينطبق على: Python SDK azure-ai-ml v2 (الحالي)

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

• Docker
• Visual Studio Code
• Azure CLI
• ملحق التعلم الآلي من Azure CLI (v2)
• Azure التعلم الآلي Python SDK (v2)
• نظام Windows الفرعي لـ Linux (WSL)

لمزيد من المعلومات، راجع الدليل حول كيفية إعداد النظام لنشر نقاط النهاية عبر الإنترنت.

يمكن العثور على الأمثلة في هذه المقالة في دفتر ملاحظات Jupyter المسمى Debug online endpoints محليا في Visual Studio Code داخل مستودع azureml-examples . لتشغيل التعليمات البرمجية محليا، قم باستنساخ المستودع ثم قم بتغيير الدلائل إلى sdk/endpoints/online/managed للدليل الأصلي لدفتر الملاحظات.

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples
cd sdk/python/endpoints/online/managed

افتح دفتر ملاحظات Jupyter واستورد الوحدات النمطية المطلوبة:

from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Model,
    CodeConfiguration,
    Environment,
)
from azure.identity import DefaultAzureCredential

إعداد متغيرات لمساحة العمل ونقطة النهاية:

subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace_name = "<AML_WORKSPACE_NAME>"

endpoint_name = "<ENDPOINT_NAME>"

تشغيل حاوية التطوير

Azure CLI

تستخدم نقاط النهاية المحلية Azure التعلم الآلي حاويات تطوير Docker وVisual Studio Code (حاويات التطوير) لإنشاء بيئة تصحيح الأخطاء المحلية وتكوينها. باستخدام حاويات التطوير، يمكنك الاستفادة من ميزات Visual Studio Code من داخل حاوية Docker. لمزيد من المعلومات حول حاويات التطوير، راجع Create a development container.

لتتبع أخطاء نقاط النهاية عبر الإنترنت محليا في Visual Studio Code، استخدم العلامة --vscode-debug عند الإنشاء أو التحديث ونشر Azure التعلم الآلي عبر الإنترنت. يستخدم الأمر التالي مثال نشر من أمثلة المستودع:

az ml online-deployment create --file endpoints/online/managed/sample/blue-deployment.yml --local --vscode-debug

هام

في نظام Windows الفرعي لـ Linux (WSL)، ستحتاج إلى تحديث متغير بيئة PATH لتضمين المسار إلى Visual Studio Code القابل للتنفيذ أو استخدام تبادل WSL. لمزيد من المعلومات، راجع Windows interoperability with Linux.

تم إنشاء صورة Docker محلياً. تظهر أي أخطاء تكوين بيئة أو ملف النموذج في هذه المرحلة من العملية.

إشعار

في المرة الأولى التي تقوم فيها بتشغيل حاوية تطوير جديدة أو محدثة، قد يستغرق الأمر عدة دقائق.

بمجرد إنشاء الصورة بنجاح، تفتح حاوية التطوير الخاصة بك في نافذة Visual Studio Code.

ستستخدم بعض ملحقات Visual Studio Code لتصحيح عمليات التوزيع في حاوية التطوير. يقوم التعلم الآلي من Microsoft Azure تلقائياً بتثبيت هذه الملحقات في حاوية التطوير الخاصة بك.

• تصحيح الاستدلال
• Pylance
• Jupyter
• Python

هام

قبل بدء جلسة تصحيح الأخطاء، تأكد من انتهاء تثبيت ملحقات Visual Studio Code في حاوية التطوير الخاصة بك.

Python

تستخدم نقاط النهاية المحلية Azure التعلم الآلي حاويات تطوير Docker وVisual Studio Code (حاويات التطوير) لإنشاء بيئة تصحيح الأخطاء المحلية وتكوينها. باستخدام حاويات التطوير، يمكنك الاستفادة من ميزات Visual Studio Code من داخل حاوية Docker. لمزيد من المعلومات حول حاويات التطوير، راجع Create a development container.

الحصول على مؤشر إلى مساحة العمل:

credential = DefaultAzureCredential()
ml_client = MLClient(
    credential,
    subscription_id=subscription_id,
    resource_group_name=resource_group,
    workspace_name=workspace_name,
)

لتصحيح نقاط النهاية عبر الإنترنت محليا في Visual Studio Code، قم بتعيين vscode-debug local و عند إنشاء أو تحديث توزيع Azure التعلم الآلي عبر الإنترنت. تعكس التعليمات البرمجية التالية مثالا للتوزيع من مستودع الأمثلة:

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=endpoint_name,
    model=Model(path="../model-1/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-1/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-1/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=1,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    deployment, local=True, vscode_debug=True
).result()

هام

في نظام Windows الفرعي لـ Linux (WSL)، ستحتاج إلى تحديث متغير بيئة PATH لتضمين المسار إلى Visual Studio Code القابل للتنفيذ أو استخدام تبادل WSL. لمزيد من المعلومات، راجع Windows interoperability with Linux.

تم إنشاء صورة Docker محلياً. تظهر أي أخطاء تكوين بيئة أو ملف النموذج في هذه المرحلة من العملية.

إشعار

قد يستغرق تشغيل حاوية تطوير جديدة أو محدثة عدة دقائق للمرة الأولى.

بمجرد إنشاء الصورة بنجاح، تفتح حاوية التطوير الخاصة بك في نافذة Visual Studio Code.

ستستخدم بعض ملحقات Visual Studio Code لتصحيح عمليات التوزيع في حاوية التطوير. يقوم التعلم الآلي من Microsoft Azure تلقائياً بتثبيت هذه الملحقات في حاوية التطوير الخاصة بك.

• تصحيح الاستدلال
• Pylance
• Jupyter
• Python

هام

قبل بدء جلسة تصحيح الأخطاء، تأكد من انتهاء تثبيت ملحقات Visual Studio Code في حاوية التطوير الخاصة بك.

بدء جلسة التصحيح

بمجرد إعداد البيئة الخاصة بك، استخدم مصحح أخطاء Visual Studio Code لاختبار وتصحيح التوزيع محليا.

1. افتح البرنامج النصي لتسجيل النقاط في Visual Studio Code.

   تلميح

   يوجد البرنامج النصي score.py المستخدم بواسطة نقطة النهاية التي تم نشرها سابقا في azureml-samples/cli/endpoints/online/managed/sample/score.py في المستودع الذي نسخته. ومع ذلك، فإن الخطوات الواردة في هذا الإرشاد تعمل مع أي برنامج نصي لتسجيل النقاط.

2. عيّن نقطة توقف في أي مكان في برنامجك النصي لتسجيل النقاط.

   • لتصحيح سلوك بدء التشغيل، ضع نقطة (نقاط) التوقف داخل دالة init.
   • لتصحيح سلوك تسجيل النقاط، ضع نقطة (نقاط) التوقف داخل دالة run.

3. حدد طريقة عرض وظيفة التعليمات البرمجية Visual Studio.

4. في القائمة المنسدلة Run and Debug ، حدد AzureML: Debug Local Endpoint لبدء تصحيح أخطاء نقطة النهاية محليا.

   في قسم Breakpoints في طريقة العرض "Run" ، تحقق مما يلي:

   • الاستثناءات البارزة لم يتم فحصها
   • الاستثناءات غير المحددةلم يتم فحصها

   

5. حدد أيقونة التشغيل بجوار القائمة المنسدلة Run and Debug لبدء جلسة تصحيح الأخطاء.

   في هذه المرحلة، يتم اكتشاف أي نقاط توقف في دالة init الخاصة بك. استخدم إجراءات التصحيح للدخول إلى التعليمة البرمجية الخاصة بك. لمزيد من المعلومات حول إجراءات التصحيح، راجع debug actions guide.

لمزيد من المعلومات حول مصحح أخطاء Visual Studio Code، راجع تصحيح الأخطاء.

تصحيح نقطة النهاية الخاصة بك

Azure CLI

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

استخدم الأمر mlextensioninvoke لتقديم طلب إلى نقطة النهاية المحلية الخاصة بك.

az ml online-endpoint invoke --name <ENDPOINT-NAME> --request-file <REQUEST-FILE> --local

في هذه الحالة، يعتبر <REQUEST-FILE> هو ملف JSON يحتوي على نماذج بيانات الإدخال للنموذج لعمل توقعات مماثلة لملف JSON التالي:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

تلميح

عنوان URI لتسجيل النقاط هو العنوان الذي تستمع فيه نقطة النهاية للطلبات. استخدم الملحق ml للحصول على URI لتسجيل النقاط.

az ml online-endpoint show --name <ENDPOINT-NAME> --local

يجب أن يبدو الإخراج مشابهًا لما يلي:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

يمكن العثور على URI لتسجيل النقاط في خاصية scoring_uri.

في هذه المرحلة، يتم اكتشاف أي نقاط توقف في دالة run الخاصة بك. استخدم إجراءات التصحيح للدخول إلى التعليمة البرمجية الخاصة بك. لمزيد من المعلومات حول إجراءات التصحيح، راجع debug actions guide.

Python

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

استخدم الأسلوب الموجود invoke على الكائن الخاص بك MLClient لتقديم طلب إلى نقطة النهاية المحلية.

endpoint = ml_client.online_endpoints.get(name=endpoint_name, local=True)

request_file_path = "../model-1/sample-request.json"

ml_client.online_endpoints.invoke(endpoint_name, request_file_path, local=True)

في هذه الحالة، يعتبر <REQUEST-FILE> هو ملف JSON يحتوي على نماذج بيانات الإدخال للنموذج لعمل توقعات مماثلة لملف JSON التالي:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

تلميح

عنوان URI لتسجيل النقاط هو العنوان الذي تستمع فيه نقطة النهاية للطلبات. يقوم as_dict أسلوب كائنات نقطة النهاية بإرجاع معلومات مشابهة ل show في Azure CLI. يمكن الحصول على كائن نقطة النهاية من خلال .get.

print(endpoint)

يجب أن يبدو الإخراج مشابهًا لما يلي:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

يمكن العثور على URI لتسجيل النقاط في scoring_uri المفتاح.

في هذه المرحلة، يتم اكتشاف أي نقاط توقف في دالة run الخاصة بك. استخدم إجراءات التصحيح للدخول إلى التعليمة البرمجية الخاصة بك. لمزيد من المعلومات حول إجراءات التصحيح، راجع debug actions guide.

تحرير نقطة النهاية الخاصة بك

Azure CLI

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

لتطبيق التغييرات على التعليمة البرمجية الخاصة بك:

1. تحديث التعليمات البرمجية الخاصة بك.
2. أعد تشغيل جلسة التصحيح باستخدام الأمر Developer: Reload Window في لوحة الأوامر. لمزيد من المعلومات، راجع command palette documentation.

إشعار

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

لمزيد من التغييرات الشاملة التي تتضمن تحديثات لبيئتك وتكوين نقطة النهاية، استخدم الأمر ml extension update. يؤدي القيام بذلك إلى إعادة إنشاء صورة كاملة مع تغييراتك.

az ml online-deployment update --file <DEPLOYMENT-YAML-SPECIFICATION-FILE> --local --vscode-debug

بمجرد إنشاء الصورة المحدثة وتشغيل حاوية التطوير الخاصة بك، استخدم مصحح أخطاء Visual Studio Code لاختبار نقطة النهاية المحدثة واستكشاف الأخطاء وإصلاحها.

Python

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

لتطبيق التغييرات على التعليمة البرمجية الخاصة بك:

1. تحديث التعليمات البرمجية الخاصة بك.
2. أعد تشغيل جلسة التصحيح باستخدام الأمر Developer: Reload Window في لوحة الأوامر. لمزيد من المعلومات، راجع command palette documentation.

إشعار

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

لمزيد من التغييرات الشاملة التي تتضمن تحديثات للبيئة وتكوين نقطة النهاية، استخدم الوحدة/الأسلوب الخاص بكMLClientonline_deployments.update. يؤدي القيام بذلك إلى إعادة إنشاء صورة كاملة مع تغييراتك.

new_deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name=endpoint_name,
    model=Model(path="../model-2/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-2/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-2/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=2,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    new_deployment, local=True, vscode_debug=True
).result()

بمجرد إنشاء الصورة المحدثة وتشغيل حاوية التطوير الخاصة بك، استخدم مصحح أخطاء Visual Studio Code لاختبار نقطة النهاية المحدثة واستكشاف الأخطاء وإصلاحها.

المحتوى ذو الصلة

• نشر نموذج التعلم الآلي وتسجيله باستخدام نقطة نهاية عبر الإنترنت
• استكشاف أخطاء توزيع نقاط النهاية وتسجيلها عبر الإنترنت وإصلاحها