Share via

Определение пользовательских модулей R для Студии машинного обучения Azure (классическая модель)

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ:Применимо к продукту.Студия машинного обучения (классическая) Неприменимо к продукту.Машинное обучение Azure

Важно!

Поддержка Студии машинного обучения (классической) будет прекращена 31 августа 2024 г. До этой даты рекомендуется перейти на Машинное обучение Azure.

Начиная с 1 декабря 2021 года вы не сможете создавать новые ресурсы Студии машинного обучения (классической). Существующие ресурсы Студии машинного обучения (классическая версия) можно будет использовать до 31 августа 2024 г.

Прекращается поддержка документации по Студии машинного обучения (классическая версия). В будущем она может не обновляться.

В этой статье описывается процедура создания и развертывания пользовательского модуля R в Студии (классическая модель). Здесь поясняется, что такое пользовательский R-модуль, и какие файлы используются для его создания. В этом разделе также описан способ создания файлов, определяющих модуль, и регистрации модуля для его развертывания в рабочей области Машинного обучения. Затем более подробно описываются элементы и атрибуты, используемые в определении пользовательского модуля. Кроме этого, здесь рассматриваются способы использования дополнительных функций, файлов и нескольких наборов выходных данных.

Пользовательский модуль — это определяемый пользователем модуль, который можно передать в свою рабочую область и выполнить в рамках эксперимента Студии машинного обучения (классическая модель). Пользовательский R-модуль представляет собой настраиваемый модуль, который выполняет определяемую пользователем R-функцию. R — это язык программирования, предназначенный для статистических вычислений и работы с графикой. Его широко используют специалисты по статистике, а также обработке и анализу данных для реализации алгоритмов. В настоящее время R — это единственный язык, поддерживаемый в пользовательских модулях, но в следующих выпусках планируется добавить поддержку и других языков.

Пользовательские модули принадлежат к группе первоклассных модулей в Студии машинного обучения (классическая модель) в том смысле, что их можно использовать наравне с любыми другими модулями. Их можно выполнять с другими модулями, включенными в опубликованный эксперимент или визуализации. Вы можете управлять алгоритмом, реализуемым модулем, используемыми портами ввода и вывода, параметрами моделирования и другими параметрами, определяющими поведение во время выполнения. Эксперимент с пользовательскими модулями также можно опубликовать в коллекции решений ИИ Azure, чтобы упростить его совместное использование.

Файлы в пользовательском R-модуле

Пользовательский R-модуль создается на основе ZIP-файла, содержащего как минимум два файла:

  • исходный файл , который реализует R-функцию, предоставляемую модулем;
  • XML-файл определения , описывающий интерфейс пользовательского модуля.

В ZIP-файл также можно включить дополнительные вспомогательные файлы, обеспечивающие функциональные возможности, доступ к которым можно получить из пользовательского модуля. Эта возможность описана в подразделе Аргументы в справочном разделе Элементы в XML-файле определения после примера быстрого запуска.

Пример быстрого запуска: определение, создание пакета и регистрация пользовательского R-модуля

В этом примере показано, как создать файлы, необходимые для пользовательского R-модуля, упаковать их в ZIP-файл и затем зарегистрировать модуль в рабочей области Машинного обучения. Пример ZIP-пакета и файлов можно скачать на странице скачивания файла CustomAddRows.zip.

Исходный файл

Рассмотрим пример модуля Custom Add Rows (Добавление пользовательских строк), который изменяет стандартную реализацию модуля Add Rows (Добавление строк), используемого для объединения строк (наблюдений) из двух наборов данных (кадров данных). Стандартный модуль Add Rows (Добавление строк) добавляет строки второго входного набора данных в конец первого входного набора данных, используя алгоритм rbind. Настраиваемая функция CustomAddRows подобным образом принимает в качестве входных данных два набора данных, а также дополнительный логический параметр переноса значений. Если для параметра переноса задано значение FALSE, она возвращает тот же набор данных, что и при стандартной реализации. Если же для параметра переноса задано значение TRUE, функция добавляет строки из первого входного набора данных в конец второго набора данных. Файл CustomAddRows.R, содержащий реализацию функции R CustomAddRows , предоставляемой модулем Добавление пользовательских строк , содержит следующий код на языке R.

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) 
{
    if (swap)
    {
        return (rbind(dataset2, dataset1));
    }
    else
    {
        return (rbind(dataset1, dataset2));
    } 
}

XML-файл определения

Чтобы предоставить эту функцию CustomAddRows в качестве модуля Студии машинного обучения (классическая модель), необходимо создать XML-файл определения, чтобы задать вид и поведение модуля Добавление пользовательских строк.

<!-- Defined a module using an R Script -->
<Module name="Custom Add Rows">
    <Owner>Microsoft Corporation</Owner>
    <Description>Appends one dataset to another. Dataset 2 is concatenated to Dataset 1 when Swap is FALSE, and vice versa when Swap is TRUE.</Description>

<!-- Specify the base language, script file and R function to use for this module. -->        
    <Language name="R" 
        sourceFile="CustomAddRows.R" 
        entryPoint="CustomAddRows" />  

<!-- Define module input and output ports -->
<!-- Note: The values of the id attributes in the Input and Arg elements must match the parameter names in the R Function CustomAddRows defined in CustomAddRows.R. -->
    <Ports>
        <Input id="dataset1" name="Dataset 1" type="DataTable">
            <Description>First input dataset</Description>
        </Input>
        <Input id="dataset2" name="Dataset 2" type="DataTable">
            <Description>Second input dataset</Description>
        </Input>
        <Output id="dataset" name="Dataset" type="DataTable">
            <Description>The combined dataset</Description>
        </Output>
    </Ports>

<!-- Define module parameters -->
    <Arguments>
        <Arg id="swap" name="Swap" type="bool" >
            <Description>Swap input datasets.</Description>
        </Arg>
    </Arguments>
</Module>

Обратите внимание, что значение атрибутов id элементов Input и Arg в XML-файле должно ПОЛНОСТЬЮ совпадать с именами параметров функций кода R в файле CustomAddRows.R (в данном примере это dataset1, dataset2 и swap). Аналогичным образом значение атрибута entryPoint элемента Language должно ПОЛНОСТЬЮ соответствовать имени функции в R-скрипте (в данном примере это CustomAddRows).

И наоборот, атрибут id элемента Output не соответствует каким-либо переменным в R-скрипте. Если требуется несколько наборов выходных данных, следует просто вернуть список из функции R с результатами, размещенными в том же порядке , в котором выходные данные заявлены в XML-файле.

Создание пакета и регистрация модуля

Сохраните эти два файла как CustomAddRows.R и CustomAddRows.xml, а затем поместите их в архивный файл CustomAddRows.zip.

Чтобы зарегистрировать их в рабочей области машинного обучения, перейдите в свою рабочую область в Студии машинного обучения (классическая модель), нажмите кнопку +Создать в нижней части страницы и выберите Модуль-> Из ZIP-пакета, чтобы передать новый пользовательский модуль Добавление пользовательских строк.

Передача ZIP-файла

Теперь модуль Добавление пользовательских строк доступен из экспериментов Машинного обучения.

Элементы в XML-файле определения

Элементы «Модуль»

Элемент Модуль используется для определения пользовательского модуля в XML-файле. С помощью нескольких элементов модуль в одном XML-файле можно определить несколько модулей. Каждый модуль в рабочей области должен иметь уникальное имя. Если зарегистрировать пользовательский модуль с таким же именем, как у имеющегося пользовательского модуля, существующий модуль заменится на новый. При этом пользовательский модуль можно зарегистрировать с таким же именем, как у имеющегося модуля Студии машинного обучения (классическая модель). Он появится в категории пользовательских на палитре модулей.

<Module name="Custom Add Rows" isDeterministic="false"> 
    <Owner>Microsoft Corporation</Owner>
    <Description>Appends one dataset to another...</Description>/>

В элементе Module можно указать два дополнительных необязательных элемента:

  • элемент Owner , внедренный в модуль;
  • элемент Description , содержащий текст, отображающийся в экспресс-справке для модуля и при наведении на модуль в пользовательском интерфейсе машинного обучения.

Правила по ограничению количества символов в элементах Module:

  • Значение атрибута name в элементе Module не должно превышать 64 символа.
  • Содержимое элемента Описание не должно превышать 128 символов.
  • Содержимое элемента Владелец не должно превышать 32 символа.

Результаты модуля могут быть детерминированными или недетерминированными.** По умолчанию все модули считаются детерминированными. Другими словами, при прочих равных входных параметрах и данных модуль должен выдать одни и те же результаты при каждом выполнении. Это означает, что Студия машинного обучения (классическая модель) повторяет выполнение только модулей, помеченных как детерминированные, если параметр или входные данные были изменены. При возвращении кэшированных результатов эксперименты можно проводить гораздо быстрее.

Существуют недетерминированные функции, например RAND или функция, возвращающая текущую дату и время. Если в модуле используется недетерминированная функция, можно указать, что модуль является недетерминированным, установив для необязательного атрибута isDeterministic значение false. Таким образом модуль будет выполняться повторно при каждом выполнении эксперимента, даже если входные данные и параметры модуля не менялись.

Определение языка

Элемент Language в XML-файле определения используется для указания языка пользовательского модуля. В настоящее время R — единственный поддерживаемый язык. Значением атрибута sourceFile должно быть имя R-файла, который содержит функции вызова при выполнении модуля. Этот файл должен быть в составе ZIP-пакета. Значением атрибута entryPoint является имя вызываемой функции. Оно должно совпадать с допустимой функцией, определенной в исходном файле.

<Language name="R" sourceFile="CustomAddRows.R" entryPoint="CustomAddRows" />

порты;

Входные и выходные порты для пользовательского модуля указываются в дочерних элементах раздела Порты в XML-файле определения. От того, в каком порядке заданы эти элементы, зависит структура (UX), которая будет отображаться для пользователей. Первым дочерним входом или выходом в элементе Ports XML-файла будет крайний слева порт входа в интерфейсе машинного обучения. Каждый порт входа и выхода может иметь необязательный дочерний элемент Description , задающий текст, отображаемый при наведении курсора мыши на порт в пользовательском интерфейсе машинного обучения.

Правила портов:

  • Максимальное число портов входа и выхода — по 8 для каждого.

Элементы ввода

Порты входа позволяют передавать данные в функцию R и в рабочую область. Ниже приведены типы данных , которые поддерживаются для портов входа.

DataTable: этот тип передается R-функции в формате data.frame. Фактически все типы (например, CSV-файлы или ARFF-файлы), которые поддерживаются машинным обучением и которые совместимы с DataTable , автоматически преобразуются в формат data.frame.

<Input id="dataset1" name="Input 1" type="DataTable" isOptional="false">
    <Description>Input Dataset 1</Description>
</Input>

Атрибут id, привязанный к каждому порту входа DataTable, должен иметь уникальное значение, которое должно совпадать с соответствующим именем параметра в функции R. Необязательные порты DataTable, которые не передаются в качестве входных в эксперименте, имеют значение null, передаваемое в функцию R, а необязательные ZIP-порты игнорируются, если вход не подключен. Атрибут isOptional необязательный для типов DataTable и Zip, и для него по умолчанию задано значение false.

Zip — пользовательские модули могут принимать в качестве входных данных ZIP-файл. Эти входные данные распаковываются в рабочий каталог функции.

<Input id="zippedData" name="Zip Input" type="Zip" IsOptional="false">
    <Description>Zip files to be extracted to the R working directory.</Description>
</Input>

Для пользовательских модулей R идентификатор ZIP-порта не должен соответствовать параметрам функции R. Это связано с тем, что ZIP-файл автоматически извлекается в рабочий каталог R.

Правила входных данных:

  • Значением атрибута id элемента Input должно быть допустимое имя переменной R.
  • Значение атрибута id элемента Input не должно превышать 64 символа.
  • Значение атрибута name элемента Input не должно превышать 64 символа.
  • Содержимое элемента Описание не должно превышать 128 символов.
  • Значение атрибута type элемента Input должно быть Zip или DataTable.
  • Значение атрибута isOptional элемента Input не является обязательным (по умолчанию false, если значение не указано). Если значение указано, оно должно быть true или false.

Выходные элементы

Стандартные выходные порты сопоставляются со значениями, выдаваемыми функцией R, что потом может использоваться последующими модулями. DataTable — пока единственный поддерживаемый стандартный выходной порт. (Поддержка для Учеников и Преобразований будет добавлена позже.) Выходные данные DataTable определены следующим образом:

<Output id="dataset" name="Dataset" type="DataTable">
    <Description>Combined dataset</Description>
</Output>

Что касается выходов в пользовательских модулях R, значение атрибута id не обязательно должно соответствовать скрипту R, но оно должно быть уникальным. Что касается выхода одного модуля, значение, выдаваемое функцией R, должно быть data.frame. Для вывода нескольких объектов поддерживаемого типа данных необходимо указать соответствующие порты в XML-файле определения, а объекты необходимо возвратить в виде списка. Выходные объекты назначаются портам вывода слева направо, в том порядке, в котором объекты размещены в возвращенном списке.

Например, если требуется изменить модуль Custom Add Rows (Добавление пользовательских строк) для вывода двух оригинальных наборов данных dataset1 и dataset2 в дополнение к новым присоединенным наборам данных dataset (слева направо: dataset, dataset1, dataset2), то необходимо определить выходные порты в файле CustomAddRows.xml следующим образом:

<Ports> 
    <Output id="dataset" name="Dataset Out" type="DataTable"> 
        <Description>New Dataset</Description> 
    </Output> 
    <Output id="dataset1_out" name="Dataset 1 Out" type="DataTable"> 
        <Description>First Dataset</Description> 
    </Output> 
    <Output id="dataset2_out" name="Dataset 2 Out" type="DataTable"> 
        <Description>Second Dataset</Description> 
    </Output> 
    <Input id="dataset1" name="Dataset 1" type="DataTable"> 
        <Description>First Input Table</Description>
    </Input> 
    <Input id="dataset2" name="Dataset 2" type="DataTable"> 
        <Description>Second Input Table</Description> 
    </Input> 
</Ports>

Затем возвратите список объектов в виде списка с правильным порядком в файле "CustomAddRows.R":

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) { 
    if (swap) { dataset <- rbind(dataset2, dataset1)) } 
    else { dataset <- rbind(dataset1, dataset2)) 
    } 
    return (list(dataset, dataset1, dataset2)) 
}

Выход визуализации. Вы можете также указать выходной порт типа Визуализация, отображающий выходные данные от графического устройства и консоли выходных данных R. Этот порт не является частью выходных данных функции R и не влияет на порядок других типов выходных портов. Для добавления порта визуализации в пользовательские модули добавьте элемент Output со значением Visualization для его атрибута type:

<Output id="deviceOutput" name="View Port" type="Visualization">
    <Description>View the R console graphics device output.</Description>
</Output>

Правила выходных данных:

  • Значением атрибута id элемента Output должно быть допустимое имя переменной R.
  • Значение атрибута id элемента Output не должно превышать 32 символа.
  • Значение атрибута name элемента Output не должно превышать 64 символа.
  • Значением атрибута type элемента Output должно быть Visualization.

Аргументы

Дополнительные данные могут передаваться в функцию R через параметры модуля, которые определяются в элементе Аргументы. Эти параметры отображаются в правой части панели свойств в пользовательском интерфейсе машинного обучения при выборе модуля. Аргументы могут быть любого поддерживаемого типа. При необходимости можно создать пользовательскую нумерацию. Как и элементы Ports, элементы Arguments могут иметь необязательный элемент Description, который задает текст, отображаемый при наведении указателя мыши на имя параметра. Дополнительные свойства для модуля, например defaultValue, minValue и maxValue, можно добавить к любому аргументу в виде атрибутов для элемента Properties. Допустимые свойства для элемента Properties зависят от типа аргумента. Они описаны в следующем разделе, где также приведены типы поддерживаемых аргументов. Пользователям не нужно вводить значения для аргументов, свойство isOptional которых имеет значение true. Если для аргумента значение не указано, он не передается в функцию точки входа. Аргументы функции точки входа, которые не являются обязательными, необходимо явным образом обрабатывать с помощью функции, например назначать значение по умолчанию null в определении функции точки входа. Необязательный аргумент будет обеспечивать применение других ограничений аргументов, например min или max, если это значение указано пользователем. Как и в случае с портами ввода и вывода, крайне важно, чтобы с каждым параметром было связано уникальное значение идентификатора. В нашем примере краткого руководства привязанным идентификатором или параметром был swap.

Элемент Arg

Параметр модуля определяется с помощью дочернего элемента Arg в разделе Arguments XML-файла определения. Как и в случае с дочерними элементами в разделе Ports, от порядка параметров в разделе Arguments зависит схема размещения элементов в UX. Параметры отображаются сверху вниз в пользовательском интерфейсе в том же порядке, в котором они определены в XML-файле. Здесь перечислены типы, поддерживаемые для параметров в машинном обучении.

int — параметр целочисленного типа (32-разрядная версия).

<Arg id="intValue1" name="Int Param" type="int">
    <Properties min="0" max="100" default="0" />
    <Description>Integer Parameter</Description>
</Arg>
  • Необязательные свойства: min, max, default и isOptional.

double — параметр типа double.

<Arg id="doubleValue1" name="Double Param" type="double">
    <Properties min="0.000" max="0.999" default="0.3" />
    <Description>Double Parameter</Description>
</Arg>
  • Необязательные свойства: min, max, default и isOptional.

bool — логический параметр, который представлен в UX в виде флажка.

<Arg id="boolValue1" name="Boolean Param" type="bool">
    <Properties default="true" />
    <Description>Boolean Parameter</Description>
</Arg>
  • Необязательные свойства: по умолчанию — значение false (если не задано).

string— стандартная строка

<Arg id="stringValue1" name="My string Param" type="string">
    <Properties isOptional="true" />
    <Description>String Parameter 1</Description>
</Arg>
  • Необязательные свойства: default и isOptional.

ColumnPicker — параметр выбора столбца. Этот тип воспроизводится в UX в виде средства выбора столбца. Элемент Property используется для указания идентификатора порта, из которого будут выбираться столбцы. При этом тип порта назначения должен быть DataTable. Результат выбора столбца передается функции R в виде списка строк, содержащих имена выбранных столбцов.

<Arg id="colset" name="Column set" type="ColumnPicker">      
    <Properties portId="datasetIn1" allowedTypes="Numeric" default="NumericAll"/>
    <Description>Column set</Description>
</Arg>

  • Необходимые свойства: portId — совпадает с идентификатором элемента входных данных типа DataTable.

  • Необязательные свойства:

    • allowedTypes фильтрует типы столбцов для выбора. Допустимые значения:

      • Числовой
      • Логический
      • категориальные;
      • Строка
      • Метка
      • Компонент
      • Оценка
      • Все

    • по умолчанию — варианты выбора по умолчанию, допустимые для выбора столбца:

      • Нет
      • NumericFeature
      • NumericLabel
      • NumericScore
      • NumericAll
      • BooleanFeature
      • BooleanLabel
      • BooleanScore
      • BooleanAll
      • CategoricalFeature
      • CategoricalLabel
      • CategoricalScore
      • CategoricalAll
      • StringFeature
      • StringLabel
      • StringScore
      • StringAll
      • AllLabel
      • AllFeature
      • AllScore
      • Все

DropDown— указанный пользователем пронумерованный (раскрывающийся) список. Раскрывающийся список элементов, заданных в элементе Properties с помощью элемента Item. Элемент id для каждого параметра Item должен быть уникальной и допустимой переменной R. Значение элемента name параметра Item выступает в качестве отображаемого текста и значения, передаваемого в функцию R.

<Arg id="color" name="Color" type="DropDown">
    <Properties default="red">
        <Item id="red" name="Red Value"/>
        <Item id="green" name="Green Value"/>
        <Item id="blue" name="Blue Value"/>
    </Properties>
    <Description>Select a color.</Description>
</Arg>
  • Необязательные свойства:
    • default — значение свойства по умолчанию должно соответствовать значению идентификатора от одного из элементов Item.

Вспомогательные файлы

Любой файл, помещенный в ZIP-файл пользовательского модуля, будет доступен для использования во время выполнения. Вся структура каталогов сохраняется. Это означает, что вызов файлов работает как локально, так и при выполнении в Студии машинном обучении (классическая модель).

Примечание

Обратите внимание, что все файлы извлекаются в каталог "src"', поэтому все пути должны иметь префикс "src/".

Предположим, например, что из набора данных необходимо удалить все повторяющиеся строки и строки, в которых частично отсутствуют данные, перед выводом в функцию CustomAddRows, и вы уже написали R-функцию, которая выполняет это действие в файле RemoveDupNARows.R:

RemoveDupNARows <- function(dataFrame) {
    #Remove Duplicate Rows:
    dataFrame <- unique(dataFrame)
    #Remove Rows with NAs:
    finalDataFrame <- dataFrame[complete.cases(dataFrame),]
    return(finalDataFrame)
}

Вы можете вызвать вспомогательный файл RemoveDupNARows.R из функции CustomAddRows:

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) {
    source("src/RemoveDupNARows.R")
        if (swap) { 
            dataset <- rbind(dataset2, dataset1))
        } else { 
            dataset <- rbind(dataset1, dataset2)) 
        } 
    dataset <- removeDupNARows(dataset)
    return (dataset)
}

Затем передайте ZIP-файл, содержащий "CustomAddRows.R", "CustomAddRows.xml" и "RemoveDupNARows.R", в качестве пользовательского модуля R.

Среда выполнения

В среде выполнения R-скрипта используется та же версия R, что и в модуле Выполнение R-скрипта , и могут использоваться те же пакеты по умолчанию. В пользовательский модуль также можно добавить дополнительные пакеты R, включая их в ZIP-пакет. Просто загрузите их в R-скрипт так же, как в среду R.

Ограничения среды выполнения включают:

  • Несохраняемая файловая система. Файлы, записанные при выполнении пользовательского модуля, не сохраняются между несколькими запусками одного и того же модуля.
  • Нет доступа к сети