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

تعرف على كيفية استكشاف الأخطاء الشائعة التي قد تواجهها عند نشر نموذج إلى Azure Container Instances (ACI) وخدمة Azure Kubernetes (AKS) باستخدام Azure التعلم الآلي وحلها أو التغلب عليها.

إشعار

إذا كنت توزع نموذجاً في خدمة Azure Kubernetes (AKS)، فننصحك بتمكين Azure Monitor لهذه المجموعة. يساعدك هذا على فهم سلامة نظام المجموعة واستخدام الموارد بشكل عام. قد تجد أيضاً الموارد التالية مفيدة:

• تحقق من أحداث Resource Health التي تؤثر على مجموعة AKS الخاصة بك
• تشخيصات خدمة Azure Kubernetes

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

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

• اشتراكAzure. جرّب الإصدار المجاني أو المدفوع من «التعلم الآلي» من Azure.

• التعلم الآلي SDK من Azure.

• Azure CLI.

• ملحق CLI الإصدار 1 للتعلم الآلي من Microsoft Azure.

  هام

  تتطلب أوامر Azure CLI الواردة في هذه المقالة ملحق azure-cli-ml، أو الإصدار 1، التعلم الآلي من Microsoft Azure. سينتهي دعم ملحق الإصدار 1 في 30 سبتمبر 2025. ستتمكن من تثبيت ملحق v1 واستخدامه حتى ذلك التاريخ.

  نوصي بالانتقال إلى ملحق ml أو الإصدار 2 قبل 30 سبتمبر 2025. لمزيد من المعلومات حول ملحق v2، راجع ملحق Azure ML CLI وPython SDK v2.

خطوات نشر Docker لنماذج التعلم الآلي

عند نشر نموذج للحساب غير المحلي في التعلم الآلي من Azure، تحدث الأشياء التالية:

1. يتم إرسال Dockerfile الذي حددته في كائن البيئات في InferenceConfig إلى السحابة، بالإضافة إلى محتويات الدليل المصدر الخاص بك
2. إذا لم تتوفر صورة تم إنشاؤها مسبقًا في سجل الحاوية، يتم إنشاء صورة Docker جديدة في السحابة وتخزينها في سجل الحاوية الافتراضي لمساحة العمل.
3. يتم تنزيل صورة Docker من سجل الحاوية الخاص بك إلى هدف الحساب الخاص بك.
4. يتم تحميل مخزن Blob الافتراضي لمساحة العمل إلى هدف الحساب الخاص بك، مما يمنحك حق الوصول إلى النماذج المسجلة
5. تتم تهيئة خادم الويب الخاص بك عن طريق تشغيل دالة init() البرنامج النصي للإدراج
6. عندما يتلقى النموذج المنشور طلبا، تعالج وظيفتك run() هذا الطلب

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

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

الحصول على سجلات التوزيع

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

Azure CLI

ينطبق على:إضافة واجهة مستوى الاستدعاء ml من Azureالإصدار الأولي

للحصول على السجلات من خدمة ويب منشورة، قم بما يلي:

az ml service get-logs --verbose --workspace-name <my workspace name> --name <service name>

Python SDK

ينطبق على:Python SDK azureml v1

بافتراض أن لديك كائنا من النوع azureml.core.Workspace يسمى ws، يمكنك القيام بما يلي:

print(ws.webservices)

# Choose the webservice you are interested in

from azureml.core import Webservice

service = Webservice(ws, '<insert name of webservice>')
print(service.get_logs())

تتبع الأخطاء محليًا

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

خادم HTTP في التعلم الآلي من Azure

يسمح لك خادم الاستدلال المحلي بتصحيح أخطاء برنامج الإدخال النصي بسرعة (score.py). في حالة وجود خطأ في البرنامج النصي للنقاط الأساسية، يفشل الخادم في تهيئة النموذج أو تقديمه. بدلا من ذلك، فإنه يطرح استثناء والموقع الذي حدثت فيه المشكلات. تعرف على المزيد حول خادم HTTP لاستدلال التعلم الآلي من Microsoft Azure

1. تثبيت الحزمة azureml-inference-server-http من مُوجز pypi:

   python -m pip install azureml-inference-server-http
   

2. بدء تشغيل الخادم وإعداده score.py كبرنامج نصي للإدخال:

   azmlinfsrv --entry_script score.py
   

3. إرسال طلب تسجيل إلى الخادم من خلالcurl:

   curl -p 127.0.0.1:5001/score
   

إشعار

تعرف على الأسئلة المتداولة حول خادم Http للاستدلال على التعلم الآلي من Azure.

تعذر جدولة الحاوية

عند نشر خدمة إلى هدف حساب خدمة Azure Kubernetes، يحاول Azure التعلم الآلي جدولة الخدمة بالمقدار المطلوب من الموارد. إذا لم تكن هناك عقد متوفرة في نظام المجموعة بالمقدار المناسب من الموارد بعد 5 دقائق، فسيفشل النشر. رسالة الفشل هي Couldn't Schedule because the kubernetes cluster didn't have available resources after trying for 00:05:00. يمكنك معالجة هذا الخطأ إما عن طريق إضافة المزيد من العقد، أو تغيير SKU للعقد الخاصة بك، أو تغيير متطلبات الموارد للخدمة الخاصة بك.

عادة ما تشير رسالة الخطأ إلى المورد الذي تحتاج إلى المزيد منه - على سبيل المثال، إذا رأيت رسالة خطأ تشير إلى 0/3 nodes are available: 3 Insufficient nvidia.com/gpu هذا يعني أن الخدمة تتطلب GPUs وهناك ثلاث عقد في نظام المجموعة لا تحتوي على GPUs المتوفرة. يمكن معالجة ذلك عن طريق إضافة المزيد من العقد إذا كنت تستخدم وحدة GPU SKU، أو التبديل إلى وحدة SKU ممكنة لـ GPU إذا لم تكن أو تغيير البيئة الخاصة بك لعدم طلب GPUs.

فشل تشغيل الخدمة

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

استخدم المعلومات الموجودة في مقالة فحص سجل Docker.

فشل تشغيل الحاوية azureml-fe-aci

عند نشر خدمة إلى هدف حساب مثيل حاوية Azure، يحاول Azure التعلم الآلي إنشاء حاوية أمامية لها اسم azureml-fe-aci لطلب الاستدلال. إذا azureml-fe-aci تعطل، يمكنك مشاهدة السجلات عن طريق تشغيل az container logs --name MyContainerGroup --resource-group MyResourceGroup --subscription MySubscription --container-name azureml-fe-aci. يمكنك اتباع رسالة الخطأ في السجلات لإجراء الإصلاح.

الفشل الأكثر شيوعا لـ azureml-fe-aci هو أن شهادة SSL المتوفرة أو المفتاح غير صالح.

فشل الدالة: get_model_path()

في كثير من الأحيان، في الدالة init() في البرنامج النصي لتسجيل النقاط، يتم استدعاء الدالة Model.get_model_path() لتحديد موقع ملف نموذج أو مجلد من ملفات النموذج في الحاوية. إذا تعذر العثور على ملف النموذج أو المجلد، فستفشل الوظيفة. أسهل طريقة لتصحيح هذا الخطأ هي تشغيل التعليمات البرمجية لـ Python أدناه في حاوية shell:

ينطبق على:Python SDK azureml v1

from azureml.core.model import Model
import logging
logging.basicConfig(level=logging.DEBUG)
print(Model.get_model_path(model_name='my-best-model'))

يطبع هذا المثال المسار المحلي (بالنسبة إلى /var/azureml-app) في الحاوية حيث يتوقع البرنامج النصي لتسجيل الدرجات العثور على ملف النموذج أو المجلد. ثم يمكنك التحقق مما إذا كان الملف أو المجلد هو بالفعل المكان المتوقع أن يكون فيه.

قد يؤدي تعيين مستوى التسجيل إلى DEBUG إلى تسجيل معلومات إضافية، مما قد يكون مفيدا في تحديد الفشل.

فشل الدالة: run(input_data)

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

def run(input_data):
    try:
        data = json.loads(input_data)['data']
        data = np.array(data)
        result = model.predict(data)
        return json.dumps({"result": result.tolist()})
    except Exception as e:
        result = str(e)
        # return error message back to the client
        return json.dumps({"error": result})

ملاحظة: يجب إرجاع رسائل الخطأ من run(input_data) المكالمة يجب أن تتم لغرض تصحيح الأخطاء فقط. لأسباب تتعلق بالأمان، يجب عدم إرجاع رسائل الخطأ بهذه الطريقة في بيئة إنتاج.

رمز حالة 502 HTTP

يشير رمز الحالة 502 إلى أن الخدمة قد ألقت استثناءً أو تعطلت في run()طريقة الملف score.py. استخدم المعلومات الواردة في هذه المقالة لتصحيح أخطاء الملف.

رمز حالة HTTP 503

تدعم عمليات توزيع Azure Kubernetes Service التحجيم التلقائي، والذي يسمح بإضافة النسخ المتماثلة لدعم التحميل الإضافي. تم تصميم التحجيم التلقائي للتعامل مع التغييرات التدريجية في التحميل. إذا تلقيت طفرات كبيرة في الطلبات في الثانية، فقد يتلقى العملاء رمز حالة HTTP 503. على الرغم من أن التحجيم التلقائي يتفاعل بسرعة، إلا أن AKS يستغرق قدرًا كبيرًا من الوقت لإنشاء حاويات إضافية.

تستند قرارات التوسع/التقليص إلى استخدام النسخ المتماثلة للحاوية الحالية. عدد النسخ المتماثلة المشغولة (معالجة طلب) مقسوما على العدد الإجمالي للنسخ المتماثلة الحالية هو الاستخدام الحالي. إذا تجاوز autoscale_target_utilizationهذا الرقم، فسيتم إنشاء المزيد من النسخ المتماثلة. إذا كان أقل، فسيتم تقليل النسخ المتماثلة. قرارات إضافة النسخ المتماثلة حريصة وسريعة (حوالي ثانية واحدة). قرارات إزالة النسخ المتماثلة متحفظة (حوالي دقيقة واحدة). بشكل افتراضي، يتم تعيين استخدام هدف التحجيم التلقائي إلى 70٪، ما يعني أن الخدمة يمكنها التعامل مع الارتفاعات في الطلبات في الثانية (RPS) التي تصل إلى 30٪.

هناك أمران يمكن أن يساعدا في منع رموز الحالة 503:

تلميح

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

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

  هام

  لا يؤدي هذا التغيير إلى إنشاء النسخ المتماثلة بشكل أسرع. بدلا من ذلك، يتم إنشاؤها عند حد استخدام أقل. بدلا من الانتظار حتى يتم استخدام الخدمة بنسبة 70٪، يؤدي تغيير القيمة إلى 30٪ إلى إنشاء النسخ المتماثلة عند حدوث استخدام 30٪.

  إذا كانت خدمة الويب تستخدم بالفعل الحد الأقصى الحالي للنسخ المتماثلة ولا تزال ترى رموز حالة 503، فقم بزيادة قيمة autoscale_max_replicas لزيادة الحد الأقصى لعدد النسخ المتماثلة.

• تغيير الحد الأدنى لعدد النسخ المتماثلة. توفر زيادة الحد الأدنى من النسخ المتماثلة تجمعا أكبر للتعامل مع الارتفاعات الواردة.

  لزيادة الحد الأدنى لعدد النسخ المتماثلة، قم بتعيين autoscale_min_replicas إلى قيمة أعلى. يمكنك حساب النسخ المتماثلة المطلوبة باستخدام التعليمات البرمجية التالية، واستبدال القيم بقيم خاصة بمشروعك:

  from math import ceil
  # target requests per second
  targetRps = 20
  # time to process the request (in seconds)
  reqTime = 10
  # Maximum requests per container
  maxReqPerContainer = 1
  # target_utilization. 70% in this example
  targetUtilization = .7
  
  concurrentRequests = targetRps * reqTime / targetUtilization
  
  # Number of container replicas
  replicas = ceil(concurrentRequests / maxReqPerContainer)
  

  إشعار

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

لمزيد من المعلومات حول إعداد autoscale_target_utilizationو autoscale_max_replicasو autoscale_min_replicas ل، راجع مرجع الوحدة النمطية AksWebservice.

رمز حالة HTTP 504

يشير رمز الحالة 504 إلى انتهاء مهلة الطلب. المهلة الافتراضية هي دقيقة واحدة.

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

رسائل خطأ أخرى

اتخذ هذه الإجراءات للأخطاء التالية:

خطأ	نوع الحل
خطأ تعارض 409	عندما تكون عملية قيد التقدم بالفعل، تستجيب أي عملية جديدة على نفس خدمة الويب هذه بخطأ تعارض 409. على سبيل المثال، إذا كانت عملية إنشاء أو تحديث خدمة ويب قيد التقدم وإذا قمت بتشغيل عملية حذف جديدة، فإنها تطرح خطأ.
فشل إنشاء الصور عند نشر خدمة الويب	إضافة "pynacl==1.2.1" كتبعية pip إلى ملف Conda لتكوين الصورة
['DaskOnBatch:context_managers.DaskOnBatch', 'setup.py']' died with <Signals.SIGKILL: 9>	قم بتغيير SKU للأجهزة الظاهرية المستخدمة في النشر الخاص بك إلى وحدة تحتوي على ذاكرة إضافية.
فشل FPGA	لا يمكنك نشر النماذج على FPGAs حتى يتم طلب الحصة النسبية ل FPGA والموافقة عليها. لطلب الوصول، املأ نموذج طلب الحصة النسبية: https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR2nac9-PZhBDnNSV2ITz0LNUN0U5S0hXRkNITk85QURTWk9ZUUFUWkkyTC4u

تصحيح الأخطاء المتقدم

قد تحتاج إلى تصحيح التعليمات البرمجية Python المضمنة في نشر النموذج بشكل تفاعلي. على سبيل المثال، إذا فشل البرنامج النصي للإدخل ولا يمكن تحديد السبب بتسجيل إضافي. باستخدام Visual Studio Code وتصحيح الأخطاء، يمكنك إرفاق التعليمات البرمجية التي تعمل داخل حاوية Docker.

لمزيد من المعلومات، تفضل بزيارة دليل التصحيح التفاعلي في VS Code.

منتدى مستخدم نشر النموذج

الخطوات التالية

معرفة المزيد بشأن التوزيع:

• طريقة التوزيع ومكانه
• طريقة تشغيل التجارب وتتبع الأخطاء محليًا