Share via

بنية CLI (v2) الأساسية لـ YAML

  • مقالة

ينطبق على:ملحق CLI للتعلم الآلي من Microsoft Azure v2 (الحالي)

يحتوي كل كيان التعلم الآلي من Microsoft Azure على تمثيل YAML مخطط. يمكنك إنشاء كيان جديد من ملف تكوين YAML باستخدام ملحق .yml أو .yaml.

تقدم هذه المقالة نظرة عامة على مفاهيم بناء الجملة الأساسية التي ستواجهها أثناء تكوين ملفات YAML هذه.

الرجوع إلى كيان Azure التعلم الآلي

يوفر Azure التعلم الآلي بناء جملة مرجعيا (يتكون من اختصار وتنسيق طويل) للإشارة إلى كيان Azure التعلم الآلي موجود عند تكوين ملف YAML. على سبيل المثال، يمكنك الرجوع إلى بيئة مسجلة موجودة في مساحة العمل لاستخدامها كبيئة لوظيفة.

الرجوع إلى أصل Azure التعلم الآلي

هناك خياران للإشارة إلى أصل Azure التعلم الآلي (البيئات والنماذج والبيانات والمكونات):

  • الرجوع إلى إصدار صريح من أصل:

    • بناء جملة الاختصار: azureml:<asset_name>:<asset_version>
    • بناء جملة Longhand، والذي يتضمن معرف مورد Azure Resource Manager (ARM) للأصل:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • الرجوع إلى أحدث إصدار من أصل:

    في بعض السيناريوهات، قد ترغب في الإشارة إلى أحدث إصدار من أحد الأصول دون الحاجة إلى البحث بوضوح عن سلسلة الإصدار الفعلية نفسها وتحديدها. يتم تعريف أحدث إصدار على أنه أحدث إصدار تم إنشاؤه (المعروف أيضاً باسم الأحدث) من أصل تحت اسم معين.

    يمكنك الرجوع إلى أحدث إصدار باستخدام بناء الجملة التالي: azureml:<asset_name>@latest. سيقوم Azure التعلم الآلي بحل المرجع إلى إصدار أصل صريح في مساحة العمل.

الرجوع إلى مورد Azure التعلم الآلي

للإشارة إلى مورد Azure التعلم الآلي (مثل الحساب)، يمكنك استخدام أي من بناء الجمل التالية:

  • بناء جملة الاختصار: azureml:<resource_name>
  • بناء جملة Longhand، والذي يتضمن معرف مورد ARM للمورد:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI لمرجع بيانات Azure التعلم الآلي

يوفر Azure التعلم الآلي تنسيق URI لمرجع بيانات ملائم للإشارة إلى البيانات في خدمة تخزين Azure. يمكن استخدام هذا للسيناريوهات التي تحتاج فيها إلى تحديد موقع تخزين سحابي في ملف YAML، مثل إنشاء نموذج Azure التعلم الآلي من ملف (ملفات) في التخزين، أو الإشارة إلى البيانات لتمريرها كمدخل إلى وظيفة.

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

يتكون التنسيق من مخزن بيانات في مساحة العمل الحالية والمسار على مخزن البيانات إلى الملف أو المجلد الذي تريد الإشارة إليه:

azureml://datastores/<datastore-name>/paths/<path-on-datastore>/

على سبيل المثال:

  • azureml://datastores/workspaceblobstore/paths/example-data/
  • azureml://datastores/workspaceblobstore/paths/example-data/iris.csv

بالإضافة إلى URI لمرجع بيانات Azure التعلم الآلي، يدعم Azure التعلم الآلي أيضا بروتوكولات URI للتخزين المباشر التالية: httpsو abfsswasbsو adlبالإضافة إلى عناوين URL العامة http وhttps.

بناء جملة التعبير لتكوين وظائف ومكونات Azure التعلم الآلي

تسمح ملفات YAML للمهمة والمكون v2 باستخدام التعبيرات للربط بالسياقات لسيناريوهات مختلفة. تستخدم حالة الاستخدام الأساسية تعبيراً لقيمة قد لا تكون معروفة في وقت تأليف التكوين، ولكن يجب حلها في وقت التشغيل.

استخدم بناء الجملة التالي لإخبار Azure التعلم الآلي بتقييم تعبير بدلا من معاملته كسلسلة:

${{ <expression> }}

تتم تغطية السيناريوهات المدعومة أدناه.

وضع معلمات command مع inputs و outputs سياقات الوظيفة

يمكنك تحديد القيم الحرفية ومسارات URI وأصول بيانات Azure التعلم الآلي المسجلة كمدخلات لوظيفة. command يمكن بعد ذلك وضع معلمات مع مراجع لتلك الإدخالات (الإدخالات) باستخدام بناء الجملة${{inputs.<input_name>}}. سيتم حل المراجع إلى المدخلات الحرفية إلى القيمة الحرفية في وقت التشغيل، بينما سيتم حل المراجع إلى مدخلات البيانات إلى مسار التنزيل أو مسار التحميل (اعتماداً على mode المحدد).

وبالمثل، يمكن أيضاً الرجوع إلى المخرجات إلى الوظيفة في command. لكل إخراج مسمى محدد في outputs القاموس، سيقوم Azure التعلم الآلي بإنشاء موقع إخراج للنظام على مخزن البيانات الافتراضي حيث يمكنك كتابة الملفات إليه. يعتمد موقع الإخراج لكل إخراج مسمى على المسار المعتم التالي: <default-datastore>/azureml/<job-name>/<output_name>/. سيؤدي وضع معلمات command مع ${{outputs.<output_name>}} بناء الجملة إلى حل هذا المرجع إلى المسار الذي أنشأه النظام، بحيث يمكن للبرنامج النصي الخاص بك كتابة الملفات إلى هذا الموقع من الوظيفة.

في المثال أدناه لملف YAML لمهمة أمر، command يتم وضع معلمات مع إدخالين، وإدخال حرفي وإدخال بيانات، وإخراج واحد. في وقت التشغيل، ${{inputs.learning_rate}} سيتم حل التعبير إلى 0.01، و ${{inputs.iris}}سيتم حل التعبير إلى مسار تنزيل iris.csv الملف. ${{outputs.model_dir}} سيتم حل إلى مسار التحميل لموقع الإخراج الذي أنشأه النظام والمطابق model_dir للإخراج.

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
compute: azureml:cpu-cluster
inputs:
  learning_rate: 0.01
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
outputs:
  model_dir:

وضع معلمات command مع search_space سياق مهمة المسح

ستستخدم أيضاً بناء جملة التعبير هذا عند إجراء ضبط المعلمات الفائقة عبر مهمة مسح، نظراً لأن القيم الفعلية للمعلمات الفائقة غير معروفة أثناء وقت تأليف الوظيفة. عند تشغيل مهمة مسح، سيقوم Azure التعلم الآلي بتحديد قيم المعلمات الفائقة لكل إصدار تجريبي استنادا search_spaceإلى . للوصول إلى هذه القيم في البرنامج النصي للتدريب الخاص بك، يجب تمريرها عبر وسيطات سطر الأوامر الخاصة بالبرنامج النصي. للقيام بذلك، استخدم ${{search_space.<hyperparameter>}} بناء الجملة في trial.command.

في المثال أدناه لملف YAML لمهمة المسح، سيتم حل المراجع ${{search_space.learning_rate}} و ${{search_space.boosting}} في trial.command قيم hyperparameter الفعلية المحددة لكل إصدار تجريبي عند إرسال مهمة الإصدار التجريبي للتنفيذ.

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
sampling_algorithm:
  type: random
search_space:
  learning_rate:
    type: uniform
    min_value: 0.01
    max_value: 0.9
  boosting:
    type: choice
    values: ["gbdt", "dart"]
objective:
  goal: minimize
  primary_metric: test-multi_logloss
trial:
  code: ./src
  command: >-
    python train.py 
    --training-data ${{inputs.iris}}
    --lr ${{search_space.learning_rate}}
    --boosting ${{search_space.boosting}}
  environment: azureml:AzureML-Minimal@latest
inputs:
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

ربط المدخلات والمخرجات بين الخطوات في وظيفة المسارات

تُستخدم التعبيرات أيضاً لربط المدخلات والمخرجات بين الخطوات في وظيفة المسارات. على سبيل المثال، يمكنك ربط إدخال وظيفة واحدة (الوظيفة ب) في مسار لإخراج وظيفة أخرى (الوظيفة أ). سيشير هذا الاستخدام إلى Azure التعلم الآلي تدفق التبعية للرسم البياني للبنية الأساسية لبرنامج ربط العمليات التجارية، وسيتم تنفيذ المهمة B بعد المهمة A، نظرا لأن إخراج الوظيفة A مطلوب كمدخل للوظيفة B.

بالنسبة لملف YAML للبنية الأساسية لبرنامج ربط العمليات التجارية، يتم تقييم inputs و outputs أقسام كل وظيفة فرعية ضمن السياق الأصلي (وظيفة البنية الأساسية لبرنامج ربط العمليات التجارية ذات المستوى الأعلى). commandمن ناحية أخرى، سيتم حل إلى السياق الحالي (الوظيفة التابعة).

هناك طريقتان لربط المدخلات والمخرجات في مهمة البنية الأساسية لبرنامج ربط العمليات التجارية:

الربط بمدخلات ومخرجات المستوى الأعلى لمهمة البنية الأساسية لبرنامج ربط العمليات التجارية

يمكنك ربط مدخلات أو مخرجات مهمة تابعة (خطوة البنية الأساسية لبرنامج ربط العمليات التجارية) بمدخلات/مخرجات مهمة البنية الأساسية لبرنامج ربط العمليات التجارية الأصل ذات المستوى الأعلى باستخدام بناء الجملة التالي: ${{parent.inputs.<input_name>}} أو ${{parent.outputs.<output_name>}}. يحل هذا المرجع إلى parent السياق؛ ومن ثم مدخلات/مخرجات المستوى الأعلى.

في المثال أدناه، يرتبط إدخال (raw_data) الخطوة prep الأولى بإدخال البنية الأساسية لبرنامج ربط العمليات التجارية من المستوى الأعلى عبر ${{parent.inputs.input_data}}. يرتبط الإخراج (model_dir) للخطوة train النهائية بإخراج مهمة البنية الأساسية لبرنامج ربط العمليات التجارية من المستوى الأعلى عبر ${{parent.outputs.trained_model}}.

الربط بمدخلات ومخرجات وظيفة تابعة أخرى (خطوة)

لربط المدخلات/المخرجات لخطوة واحدة بالمدخلات/المخرجات لخطوة أخرى، استخدم بناء الجملة التالي: ${{parent.jobs.<step_name>.inputs.<input_name>}} أو ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. مرة أخرى، يحل هذا المرجع إلى السياق الأصل، لذلك يجب أن يبدأ التعبير بـ parent.jobs.<step_name>.

في المثال أدناه، يرتبط الإدخال (training_data) للخطوة train بإخراج (clean_data) prep الخطوة عبر ${{parent.jobs.prep.outputs.clean_data}}. سيتم استخدام البيانات المعدة prep من الخطوة كبيانات تدريب train للخطوة.

من ناحية أخرى، سيتم حل مراجع السياق داخل command الخصائص إلى السياق الحالي. على سبيل المثال، ${{inputs.raw_data}} سيتم حل المرجع في prep الخطوة command إلى مدخلات السياق الحالي، وهي prep الوظيفة التابعة. سيتم إجراء البحث على prep.inputs، لذلك يجب تعريف إدخال مسمى raw_data هناك.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
inputs:
  input_data: 
    type: uri_folder
    path: https://azuremlexamples.blob.core.windows.net/datasets/cifar10/
outputs:
  trained_model:
jobs:
  prep:
    type: command
    inputs:
      raw_data: ${{parent.inputs.input_data}}
    outputs:
      clean_data:
    code: src/prep
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python prep.py 
      --raw-data ${{inputs.raw_data}} 
      --prep-data ${{outputs.clean_data}}
    compute: azureml:cpu-cluster
  train:
    type: command
    inputs: 
      training_data: ${{parent.jobs.prep.outputs.clean_data}}
      num_epochs: 1000
    outputs:
      model_dir: ${{parent.outputs.trained_model}}
    code: src/train
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python train.py 
      --epochs ${{inputs.num_epochs}}
      --training-data ${{inputs.training_data}} 
      --model-output ${{outputs.model_dir}}
    compute: azureml:gpu-cluster

وضع معلمات command مع inputs و outputs سياقات التكوين

على غرار command وظيفة ما، command يمكن أيضاً تحديد معلمات للمكون مع مراجع للسياقين inputs و outputs. في هذه الحالة، يكون المرجع إلى مدخلات المكون ومخرجاته. عند تشغيل المكون في وظيفة، سيقوم Azure التعلم الآلي بحل هذه المراجع إلى قيم الإدخال والإخراج لوقت تشغيل الوظيفة المحددة لإدخالات المكون المعني ومخرجاته. فيما يلي مثال على استخدام بناء جملة السياق لمواصفات YAML لمكون أمر.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_data_component_cli
display_name: train_data
description: A example train component
tags:
  author: azureml-sdk-team
version: 9
type: command
inputs:
  training_data: 
    type: uri_folder
  max_epocs:
    type: integer
    optional: true
  learning_rate: 
    type: number
    default: 0.01
    optional: true
  learning_rate_schedule: 
    type: string
    default: time-based
    optional: true
outputs:
  model_output:
    type: uri_folder
code: ./train_src
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  $[[--max_epocs ${{inputs.max_epocs}}]]
  $[[--learning_rate ${{inputs.learning_rate}}]]
  $[[--learning_rate_schedule ${{inputs.learning_rate_schedule}}]]
  --model_output ${{outputs.model_output}}

تعريف المدخلات الاختيارية في سطر الأوامر

عند تعيين الإدخال على أنه optional = true، تحتاج إلى استخدام $[[]] لاحتضان سطر الأوامر مع المدخلات. على سبيل المثال$[[--input1 ${{inputs.input1}}]. قد يحتوي سطر الأوامر في وقت التشغيل على مدخلات مختلفة.

  • إذا كنت تستخدم المعلمات المطلوبة training_datamodel_output فقط، فسيبدو سطر الأوامر كما يلي:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

إذا لم يتم تحديد أي قيمة في وقت التشغيل، learning_ratelearning_rate_schedule وسوف تستخدم القيمة الافتراضية.

  • إذا كانت جميع المدخلات/المخرجات توفر قيما أثناء وقت التشغيل، فسيبدو سطر الأوامر كما يلي:
python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

تعبيرات مسار الإخراج

يمكن استخدام التعبيرات التالية في مسار إخراج وظيفتك:

هام

يتم حل التعبيرات التالية على جانب الخادم ، وليس من جانب العميل . بالنسبة للوظائف المجدولة حيث يختلف وقت إنشاء الوظيفة ووقت إرسال الوظيفة، يتم حل التعبيرات عند إرسال الوظيفة. نظرا لحل هذه التعبيرات على جانب الخادم، فإنها تستخدم الحالة الحالية لمساحة العمل، وليس حالة مساحة العمل عند إنشاء المهمة المجدولة. على سبيل المثال، إذا قمت بتغيير مخزن البيانات الافتراضي لمساحة العمل بعد إنشاء مهمة مجدولة، يتم حل التعبير ${{default_datastore}} إلى مخزن البيانات الافتراضي الجديد، وليس مخزن البيانات الافتراضي عند إنشاء المهمة المجدولة.

تعبير ‏‏الوصف Scope
${{default_datastore}} إذا تم تكوين مخزن البيانات الافتراضي للبنية الأساسية لبرنامج ربط العمليات التجارية، يتم حله كاسم مخزن بيانات افتراضي للبنية الأساسية لبرنامج ربط العمليات التجارية؛ وإلا يتم حلها كاسم مخزن بيانات افتراضي لمساحة العمل.

يمكن التحكم في مخزن البيانات الافتراضي للبنية الأساسية لبرنامج ربط العمليات التجارية باستخدام pipeline_job.settings.default_datastore.		 يعمل لجميع الوظائف.

تحتوي مهام البنية الأساسية لبرنامج ربط العمليات التجارية على مخزن بيانات افتراضي للبنية الأساسية لبرنامج ربط العمليات التجارية قابل للتكوين.
${{name}} اسم الوظيفة. بالنسبة للبنية الأساسية لبرنامج ربط العمليات التجارية، إنه اسم مهمة الخطوة، وليس اسم مهمة البنية الأساسية لبرنامج ربط العمليات التجارية. يعمل لجميع الوظائف
${{output_name}} اسم إخراج الوظيفة يعمل لجميع الوظائف

على سبيل المثال، إذا azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} تم استخدام كمسار الإخراج، في وقت التشغيل يتم حله كمسار ل azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

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