Definování vlastních modulů R pro Machine Learning Studio (classic)

Článek
11/29/2017

PLATÍ PRO: Platí pro. Machine Learning Studio (Classic) Nevztahuje se na. Azure Machine Learning

Důležité

Podpora studia Machine Learning (Classic) skončí 31. srpna 2024. Doporučujeme do tohoto data přejít na službu Azure Machine Learning.

Od 1. prosince 2021 nebude možné vytvářet nové prostředky studia Machine Learning (Classic). Do 31. srpna 2024 můžete pokračovat v používání stávajících prostředků studia Machine Learning (Classic).

Přečtěte si informace o přesunu projektů strojového učení ze sady ML Studio (classic) do služby Azure Machine Learning.
Další informace o službě Azure Machine Learning

Dokumentace ke studiu ML (Classic) se vyřazuje z provozu a v budoucnu se nemusí aktualizovat.

Toto téma popisuje, jak vytvořit a nasadit vlastní R Studio (classic). Vysvětluje, jaké vlastní moduly R jsou a jaké soubory se používají k jejich definování. Ukazuje, jak sestavit soubory, které definují modul a jak ho zaregistrovat pro nasazení v pracovním prostoru Machine Learning. Prvky a atributy použité v definici vlastního modulu se pak podrobněji popisují. Popisuje se také použití pomocných funkcí a souborů a více výstupů.

Vlastní modul je uživatelem definovaný modul, který se dá nahrát do pracovního prostoru a spustit jako součást experimentu Machine Learning Studio (classic). Vlastní modul R je vlastní modul , který spouští uživatelem definovanou funkci R. R je programovací jazyk pro statistické výpočty a grafiku, který běžně používají statistici a datoví vědci k implementaci algoritmů. V současné době je jazyk R jediným jazykem podporovaným ve vlastních modulech, ale podpora dalších jazyků je naplánovaná pro budoucí verze.

Vlastní moduly mají v nástroji Machine Learning Studio stav první třídy (klasické) v tom smyslu, že je lze použít stejně jako jakýkoli jiný modul. Dají se spouštět s dalšími moduly, které jsou zahrnuté v publikovaných experimentech nebo ve vizualizacích. Máte kontrolu nad algoritmem implementovaným modulem, vstupními a výstupními porty, které se mají použít, parametry modelování a další různá chování modulu runtime. Experiment, který obsahuje vlastní moduly, lze také publikovat do galerie Azure AI pro snadné sdílení.

Soubory ve vlastním modulu R

Vlastní modul R je definován souborem .zip, který obsahuje minimálně dva soubory:

Zdrojový soubor, který implementuje funkci R vystavenou modulem
Definiční soubor XML, který popisuje rozhraní vlastního modulu

Další pomocné soubory lze také zahrnout do souboru .zip, který poskytuje funkce, ke kterým lze získat přístup z vlastního modulu. Tato možnost je popsána v části Argumenty referenční části Elementy v definičním souboru XML podle příkladu rychlého startu.

Příklad rychlého startu: definování, zabalení a registrace vlastního modulu R

Tento příklad ukazuje, jak sestavit soubory vyžadované vlastním modulem R, zabalit je do souboru ZIP a pak ho zaregistrovat v pracovním prostoru Machine Learning. Ukázkový balíček ZIP a ukázkové soubory lze stáhnout ze souboru Download CustomAddRows.zip.

Zdrojový soubor

Představte si příklad modulu Vlastní přidání řádků , který upravuje standardní implementaci modulu Přidat řádky sloužící ke zřetězení řádků (pozorování) ze dvou datových sad (datových rámců). Standardní modul Přidat řádky připojí řádky druhé vstupní datové sady na konec první vstupní datové sady pomocí rbind algoritmu. Přizpůsobená CustomAddRows funkce podobně přijímá dvě datové sady, ale také přijímá logický parametr prohození jako další vstup. Pokud je parametr prohození nastaven na HODNOTU FALSE, vrátí stejnou datovou sadu jako standardní implementace. Pokud je ale parametr prohození pravda, funkce místo toho připojí řádky první vstupní datové sady na konec druhé datové sady. Soubor CustomAddRows.R, který obsahuje implementaci funkce R CustomAddRows vystavené modulem Custom Add Rows , má následující kód R.

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

Definiční soubor XML

Pokud chcete tuto CustomAddRows funkci zveřejnit jako modul Machine Learning Studio (classic), musí být vytvořen definiční soubor XML, který určuje, jak má modul Vlastní přidat řádky vypadat a chovat.

<!-- 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>

Je důležité si uvědomit, že hodnota atributů ID elementů Input a Arg v souboru XML musí odpovídat názvům parametrů funkce kódu R v souboru CustomAddRows.R PRÁVĚ: (datová sada1, datová sada2 a prohození v příkladu). Podobně hodnota atributu entryPoint elementu Language musí odpovídat názvu funkce ve skriptu R PŘESNĚ: (CustomAddRows v příkladu).

Naproti tomu atribut ID pro výstupní prvek neodpovídá žádným proměnným ve skriptu jazyka R. Pokud je požadován více než jeden výstup, jednoduše vrátí seznam z funkce R s výsledky umístěnými ve stejném pořadí jako výstupní prvky jsou deklarovány v souboru XML.

Zabalení a registrace modulu

Uložte tyto dva soubory jako CustomAddRows.R a CustomAddRows.xml a potom tyto dva soubory zazipujte do souboru CustomAddRows.zip.

Pokud je chcete zaregistrovat v pracovním prostoru Machine Learning, přejděte do svého pracovního prostoru v nástroji Machine Learning Studio (classic), klikněte na tlačítko +NOVÝ v dolní části a zvolte MODUL –> FROM ZIP PACKAGE a nahrajte nový modul Vlastní přidat řádky .

Nahrát zip

Modul Vlastní přidat řádky je teď připravený k přístupu k experimentům ve službě Machine Learning.

Prvky v definičním souboru XML

Prvky modulu

Element Module slouží k definování vlastního modulu v souboru XML. V jednom souboru XML lze definovat více modulů pomocí více prvků modulu . Každý modul v pracovním prostoru musí mít jedinečný název. Zaregistrujte vlastní modul se stejným názvem jako existující vlastní modul a nahradí stávající modul novým modulem. Vlastní moduly se ale dají zaregistrovat se stejným názvem jako existující modul Machine Learning Studio (classic). Pokud ano, zobrazí se v kategorii Vlastní paleta modulů.

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

V elementu Module můžete zadat dva další volitelné prvky:

Element Owner , který je vložen do modulu
Prvek popisu, který obsahuje text, který se zobrazí v rychlé nápovědě pro modul a když na něj najedete myší v uživatelském rozhraní machine learningu.

Pravidla pro omezení znaků v elementech modulu:

Hodnota atributu name v prvku Module nesmí překročit délku 64 znaků.
Obsah prvku Description nesmí být delší než 128 znaků.
Obsah elementu Owner nesmí být delší než 32 znaků.

Výsledky modulu můžou být deterministické nebo nedeterministické.** Ve výchozím nastavení jsou všechny moduly považovány za deterministické. To znamená, že vzhledem k neměnné sadě vstupních parametrů a dat by modul měl vrátit stejné výsledky jako eacRAND nebo čas spuštění funkce. Vzhledem k tomuto chování Machine Learning Studio (Classic) znovu spustí moduly označené jako deterministické, pokud se změnil parametr nebo vstupní data. Vrácení výsledků uložených v mezipaměti také poskytuje mnohem rychlejší provádění experimentů.

Existují funkce, které nejsou deterministické, například funkce RAND nebo funkce, která vrací aktuální datum nebo čas. Pokud váš modul používá nedeterministické funkce, můžete určit, že modul není deterministický nastavením volitelného atributu isDeterministic na HODNOTU FALSE. To zajistí, že se modul znovu spustí při každém spuštění experimentu, i když se vstup modulu a parametry nezměnily.

Definice jazyka

Element Language v definičním souboru XML slouží k určení vlastního jazyka modulu. V současné době je R jediným podporovaným jazykem. Hodnota atributu sourceFile musí být název souboru R, který obsahuje funkci pro volání při spuštění modulu. Tento soubor musí být součástí balíčku ZIP. Hodnota atributu entryPoint je název volané funkce a musí odpovídat platné funkci definované ve zdrojovém souboru.

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

Porty

Vstupní a výstupní porty pro vlastní modul se zadávají v podřízených prvcích oddílu Porty v definičním souboru XML. Pořadí těchto prvků určuje rozložení, které uživatelé zaznamenali (UX). První podřízený vstup nebo výstup uvedený v elementu Porty souboru XML se stane levým vstupním portem v uživatelském prostředí Machine Learning. Každý vstupní a výstupní port může mít volitelný podřízený prvek Popis , který určuje text zobrazený při najetí myší na port v uživatelském rozhraní machine learningu.

Pravidla portů:

Maximální počet vstupních a výstupních portů je pro každý z nich 8.

Vstupní prvky

Vstupní porty umožňují předávat data do funkce a pracovního prostoru jazyka R. Datové typy podporované pro vstupní porty jsou následující:

DataTable: Tento typ se předává do funkce R jako data.frame. Ve skutečnosti se všechny typy (například soubory CSV nebo soubory ARFF) podporované službou Machine Learning a kompatibilní s DataTable automaticky převedou na data.frame.

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

Atribut ID přidružený ke každému vstupnímu portu DataTable musí mít jedinečnou hodnotu a tato hodnota se musí shodovat s odpovídajícím pojmenovaným parametrem ve vaší funkci R. Volitelné porty DataTable , které nejsou předány jako vstup v experimentu, mají hodnotu NULL předanou funkci R a volitelné porty ZIP jsou ignorovány, pokud vstup není připojený. Atribut isOptional je volitelný pro typy DataTable i Zip a ve výchozím nastavení je false .

Zip: Vlastní moduly můžou jako vstup přijmout soubor ZIP. Tento vstup se rozbalí do pracovního adresáře jazyka R vaší funkce.

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

U vlastních modulů jazyka R nemusí ID portu ZIP odpovídat žádným parametrům funkce R. Důvodem je to, že soubor ZIP se automaticky extrahuje do pracovního adresáře jazyka R.

Vstupní pravidla:

Hodnota atributu ID elementu Input musí být platný název proměnné jazyka R.
Hodnota atributu ID elementu Input nesmí být delší než 64 znaků.
Hodnota atributu name elementu Input nesmí být delší než 64 znaků.
Obsah prvku Description nesmí být delší než 128 znaků.
Hodnota atributu typu elementu Input musí být Zip nebo DataTable.
Hodnota isOptional atribut Input element není vyžadován (a je false ve výchozím nastavení, pokud není zadán); ale pokud je zadána, musí být true nebo false.

Výstupní prvky

Standardní výstupní porty: Výstupní porty se mapují na návratové hodnoty z funkce R, které pak můžou používat následné moduly. DataTable je aktuálně podporovaný jediný standardní typ výstupního portu. (Podpora pro Studenti a transformace jsou připravované.) Výstup tabulky DataTable je definován takto:

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

Pro výstupy ve vlastních modulech jazyka R nemusí hodnota atributu ID odpovídat ničemu ve skriptu jazyka R, ale musí být jedinečná. Pro výstup jednoho modulu musí být návratová hodnota z funkce R data.frame. Aby bylo možné vypsat více než jeden objekt podporovaného datového typu, musí být v definičním souboru XML zadány příslušné výstupní porty a objekty musí být vráceny jako seznam. Výstupní objekty jsou přiřazeny k výstupním portům zleva doprava, což odpovídá pořadí, ve kterém jsou objekty umístěny do vráceného seznamu.

Pokud například chcete upravit modul Vlastní přidání řádků tak, aby výstupem původních dvou datových sad, datové sady1 a datové sady2, kromě nové připojené datové sady, datové sady (v pořadí zleva doprava, jako: datová sada, datová sada1, datová sada2), pak definujte výstupní porty v souboru CustomAddRows.xml následujícím způsobem:

<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>

A vrátí seznam objektů v seznamu ve správném pořadí v 'CustomAddRows.R':

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

Výstup vizualizace: Můžete také zadat výstupní port typu Vizualizace, který zobrazuje výstup z grafického zařízení R a výstupu konzoly. Tento port není součástí výstupu funkce R a nezasahuje do pořadí ostatních typů výstupních portů. Pokud chcete přidat port vizualizace do vlastních modulů, přidejte výstupní prvek s hodnotou Visualization pro jeho atribut typu :

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

Výstupní pravidla:

Hodnota atributu ID výstupního prvku musí být platný název proměnné R.
Hodnota atributu ID výstupního prvku nesmí být delší než 32 znaků.
Hodnota atributu name prvku Output nesmí být delší než 64 znaků.
Hodnota atributu typu výstupního prvku musí být Visualization.

Argumenty

Další data lze předat funkci R prostřednictvím parametrů modulu, které jsou definovány v elementu Arguments . Tyto parametry se zobrazí v podokně vlastností úplně vpravo v uživatelském rozhraní služby Machine Learning, když je vybraný modul. Argumenty můžou být některé z podporovaných typů nebo v případě potřeby můžete vytvořit vlastní výčet. Podobně jako u elementů Porty mohou argumenty obsahovat volitelný element Popis, který určuje text, který se zobrazí při najetí myší na název parametru. Volitelné vlastnosti modulu, například defaultValue, minValue a maxValue, lze přidat do libovolného argumentu jako atributy do elementu Properties . Platné vlastnosti prvku Properties závisí na typu argumentu a jsou popsány s podporovanými typy argumentů v další části. Argumenty s isOptional vlastnost nastavená na true nevyžadují, aby uživatel zadal hodnotu. Pokud argument nezadá hodnotu, nepředá se do funkce vstupního bodu. Argumenty funkce vstupního bodu, které jsou volitelné, musí funkce explicitně zpracovat, například přiřazenou výchozí hodnotu NULL v definici funkce vstupního bodu. Nepovinný argument bude vynucovat pouze ostatní omezení argumentu, tj. minimální nebo maximální hodnotu, pokud uživatel poskytne hodnotu. Stejně jako u vstupů a výstupů je důležité, aby každý z parametrů měl přidružené jedinečné hodnoty ID. V našem příkladu rychlého startu došlo ke prohození přidruženého ID/parametru.

Arg – element

Parametr modulu je definován pomocí podřízeného elementu Arg oddílu Arguments souboru definice XML. Stejně jako u podřízených prvků v části Porty definuje pořadí parametrů v oddílu Argumenty rozložení zjištěné v uživatelském prostředí. Parametry se zobrazí shora dolů v uživatelském rozhraní ve stejném pořadí, v jakém jsou definovány v souboru XML. Tady jsou uvedené typy podporované službou Machine Learning pro parametry.

int – celočíselná hodnota (32bitový) parametr typu.

<Arg id="intValue1" name="Int Param" type="int">
    <Properties min="0" max="100" default="0" />
    <Description>Integer Parameter</Description>
</Arg>

Volitelné vlastnosti: min, max, výchozí a isOptional

double – dvojitý parametr typu.

<Arg id="doubleValue1" name="Double Param" type="double">
    <Properties min="0.000" max="0.999" default="0.3" />
    <Description>Double Parameter</Description>
</Arg>

Volitelné vlastnosti: min, max, výchozí a isOptional

bool – logický parametr reprezentovaný zaškrtávacím políčkem v uživatelském prostředí.

<Arg id="boolValue1" name="Boolean Param" type="bool">
    <Properties default="true" />
    <Description>Boolean Parameter</Description>
</Arg>

Volitelné vlastnosti: výchozí – nepravda, pokud není nastavená

string: standardní řetězec

<Arg id="stringValue1" name="My string Param" type="string">
    <Properties isOptional="true" />
    <Description>String Parameter 1</Description>
</Arg>

Volitelné vlastnosti: výchozí a isOptional

ColumnPicker: parametr výběru sloupce. Tento typ se v uživatelském prostředí vykreslí jako volič sloupců. Element Property se zde používá k určení ID portu, ze kterého jsou vybrané sloupce, kde cílový typ portu musí být DataTable. Výsledek výběru sloupce se předá funkci R jako seznam řetězců obsahujících názvy vybraných sloupců.

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

Požadované vlastnosti: portId – odpovídá ID vstupního prvku s typem DataTable.
Volitelné vlastnosti:
- allowedTypes – Filtruje typy sloupců, ze kterých můžete vybírat. Mezi platné hodnoty patří:
  - Číslo
  - Logická hodnota
  - Kategorické
  - String
  - Popisek
  - Funkce
  - Skóre
  - Všechny
- default – Platné výchozí výběry pro výběr sloupců zahrnují:
  - Nic
  - NumericFeature
  - NumericLabel
  - NumericScore
  - NumericAll
  - BooleanFeature
  - Logická hodnotaLabel
  - BooleanScore
  - Logická hodnotaAll
  - CategoricalFeature
  - Kategorickálabel
  - KategorickéScore
  - KategoricalAll
  - StringFeature
  - StringLabel
  - StringScore
  - StringAll
  - AllLabel
  - AllFeature
  - AllScore
  - Všechny

Rozevírací seznam: seznam zadaný uživatelem (rozevírací seznam). Položky rozevíracího seznamu jsou zadány v elementu Properties pomocí elementu Item . ID každé položky musí být jedinečné a platná proměnná jazyka R. Hodnota názvu položky slouží jak jako text, který vidíte, tak jako hodnota předaná do funkce 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>

Volitelné vlastnosti:
- default – Hodnota výchozí vlastnosti musí odpovídat hodnotě ID z jednoho z elementů Item .

Pomocné soubory

Všechny soubory, které jsou umístěné v souboru ZIP vašeho vlastního modulu, budou k dispozici pro použití během doby provádění. Zachovají se všechny adresářové struktury. To znamená, že model file sourcing funguje stejně místně a při provádění nástroje Machine Learning Studio (classic).

Poznámka:

Všimněte si, že všechny soubory se extrahují do adresáře src, takže všechny cesty by měly mít předponu src/.

Řekněme například, že chcete odebrat všechny řádky s NA z datové sady, a také odebrat všechny duplicitní řádky, před výstupem do CustomAddRows a už jste napsali funkci R, která to dělá v souboru RemoveDupNARows.R:

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

Pomocný soubor RemoveDupNARows.R můžete zdrojovat ve funkci 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)
}

Dále nahrajte soubor ZIP obsahující customAddRows.R, CustomAddRows.xml a RemoveDupNARows.R jako vlastní modul R.

Spouštěcí prostředí

Spouštěcí prostředí skriptu R používá stejnou verzi jazyka R jako modul Execute R Script a může používat stejné výchozí balíčky. Do vlastního modulu můžete také přidat další balíčky R tak, že je zahrnete do balíčku ZIP vlastního modulu. Stačí je načíst do skriptu R stejně jako ve vlastním prostředí R.

Omezení spouštěcího prostředí zahrnují:

Systém souborů, který není trvalý: Soubory zapsané při spuštění vlastního modulu se nezachovají napříč několika spuštěními stejného modulu.
Žádný síťový přístup

Sdílet prostřednictvím