定義機器學習 Studio 的自訂 R 模組（傳統版）

發行項
11/29/2017

適用於： 適用。機器學習 Studio（傳統版）不適用。 Azure 機器學習

重要

Machine Learning 工作室 (傳統) 的支援將於 2024 年 8 月 31 日結束。建議您在該日期之前轉換成 Azure Machine Learning。

自 2021 年 12 月 1 日起，您將無法建立新的 Machine Learning 工作室 (傳統) 資源。在 2024 年 8 月 31 日之前，您可以繼續使用現有的 Machine Learning 工作室 (傳統) 資源。

請參閱將機器學習專案從 ML 工作室 (傳統) 移至 Azure Machine Learning 的相關資訊。
深入了解 Azure Machine Learning

ML 工作室 (傳統) 文件即將淘汰，未來將不再更新。

本主題描述如何撰寫及部署自定義 R Studio（傳統版）。它說明什麼是自定義 R 模組，以及用來定義這些模組的檔案。它說明如何建構定義模組的檔案，以及如何在機器學習工作區中註冊模組以進行部署。接著會更詳細地說明自定義模組定義中使用的元素和屬性。也會討論如何使用輔助功能和檔案和多個輸出。

自定義模組是使用者定義的模組，可上傳至您的工作區，並在機器學習 Studio （傳統）實驗中執行。 自定義 R 模組是執行使用者定義 R 函式的自訂模組。 R 是統計運算和圖形的程式設計語言，可供統計人員和數據科學家廣泛用於實作演算法。目前，R 是自定義模組中唯一支援的語言，但會排程未來版本的其他語言支援。

自定義模組在機器學習 Studio（傳統版）中具有一流的狀態，也就是說，它們可以和任何其他模塊一樣使用。這些模組可以與其他模組一起執行，這些模組包含在已發佈的實驗或視覺效果中。您可以控制模組所實作的演算法、要使用的輸入和輸出埠、模型化參數和其他各種運行時間行為。包含自定義模組的實驗也可以發佈至 Azure AI 資源庫，以便輕鬆共用。

自定義 R 模組中的檔案

自訂 R 模組是由包含至少兩個檔案的.zip檔案所定義：

實作模組所公開 R 函式的來源檔案
描述自訂模組介面的 XML 定義檔

其他輔助檔案也可以包含在.zip檔案中，提供可從自定義模組存取的功能。在快速入門範例之後，XML 定義檔中 Elements 的 Reference 區段的 Arguments 部分會討論這個選項。

快速入門範例：定義、封裝及註冊自定義 R 模組

此範例說明如何建構自定義 R 模組所需的檔案、將它們封裝成 zip 檔案，然後在機器學習工作區中註冊模組。您可以從下載CustomAddRows.zip檔案下載範例 zip 套件和範例檔案。

原始程序檔

請考慮自定義新增數據列模組的範例，該模組會修改用來串連兩個數據集（數據框架）的數據列（觀察）的標準實作。標準 [新增數據列] 模組會使用 rbind 演算法，將第二個輸入數據集的數據列附加至第一個輸入數據集的結尾。自定義 CustomAddRows 函式同樣接受兩個數據集，但也接受布爾交換參數做為額外的輸入。如果 swap 參數設定為 FALSE，則會傳回與標準實作相同的數據集。但是，如果 swap 參數為 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為機器學習 Studio （傳統）模組，必須建立 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>

請務必注意，XML 檔案中 Input 和 Arg 元素的 id 屬性值必須完全符合 CustomAddRows.R 檔案中 R 程式代碼的函式參數名稱：（dataset1、dataset2 和範例中的 swap）。同樣地，Language 元素的 entryPoint 屬性值必須完全符合 R 腳本中的函式名稱：（範例中的 CustomAddRows）。

相反地，Output 元素的 id 屬性不會對應至 R 腳本中的任何變數。需要一個以上的輸出時，只要從 R 函式傳回清單，結果會以與 Output 元素相同的順序宣告在 XML 檔案中。

封裝並註冊模組

將這兩個檔案儲存為 CustomAddRows.R 並CustomAddRows.xml，然後將這兩個檔案壓縮成CustomAddRows.zip檔案。

若要在機器學習工作區中註冊它們，請移至機器學習 Studio 中的工作區（傳統版），單擊底部的 [+新增] 按鈕，然後選擇 [模組 -> 從 ZIP 套件] 上傳新的 [自定義新增數據列] 模組。

上傳 Zip

自訂新增數據列模組現在已可供機器學習實驗存取。

XML 定義檔中的元素

模組元素

Module 元素是用來在 XML 檔案中定義自定義模組。多個模組可以使用多個模組元素，在一個 XML 檔案中定義。工作區中的每個模組都必須有唯一的名稱。使用與現有自定義模組相同的名稱註冊自定義模組，並將現有的模組取代為新的模組。不過，自定義模組可以註冊為與現有機器學習 Studio （傳統）模組相同的名稱。如果是，它們會出現在 模組調色盤的 [自定義 ] 類別中。

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

在 Module 元素內，您可以指定兩個額外的選擇性元素：

內嵌至模組的 Owner 元素
Description 元素，其中包含模組快速說明中顯示的文字，以及當您將滑鼠停留在機器學習 UI 中的模組上方時。

Module 元素中的字元限制規則：

Module 元素中 name 屬性的值長度不得超過 64 個字元。
Description 元素的內容長度不得超過 128 個字元。
Owner 元素的內容長度不得超過 32 個字元。

模組的結果可以是確定性或非決定性。** 根據預設，所有模組都會被視為具決定性。也就是說，假設有一組不變更的輸入參數和數據，模組應該傳回相同的結果 eacRAND 或函式執行時間。鑒於此行為，機器學習 Studio（傳統版）只會在參數或輸入數據變更時重新執行標示為具決定性的模組。傳回快取的結果也提供更快速的實驗執行。

有些函式不具決定性，例如 RAND 或傳回目前日期或時間的函式。如果您的模組使用非決定性函式，您可以將選擇性 isDeterministic 屬性設定為 FALSE，以指定模組為不具決定性。這可確保只要執行實驗，模組就會重新執行，即使模組輸入和參數未變更也一樣。

語言定義

XML 定義檔中的 Language 元素是用來指定自定義模組語言。目前，R 是唯一支持的語言。 sourceFile 屬性的值必須是 R 檔案的名稱，其中包含執行模組時要呼叫的函式。此檔案必須是 zip 套件的一部分。 entryPoint 屬性的值是所呼叫的函式名稱，而且必須符合原始程式檔中定義的有效函式。

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

連接埠

自訂模組的輸入和輸出埠是在 XML 定義檔之 Ports 區段的子元素中指定。這些項目的順序會決定使用者所經歷的版面配置（UX）。 XML 檔案的 Ports 元素中列出的第一個子輸入或輸出會成為機器學習 UX 中最左邊的輸入埠。 每個輸入和輸出埠可能都有選擇性的 Description 子元素，指定當您將滑鼠游標暫留在機器學習 UI 中的埠上方時所顯示的文字。

連接埠規則：

每個輸入和輸出埠的數目上限為8。

輸入元素

輸入埠可讓您將數據傳遞至 R 函式和工作區。 輸入埠支援的數據類型如下所示：

DataTable： 此類型會以 data.frame 的形式傳遞至 R 函式。事實上，機器學習所支援且與 DataTable 相容的任何類型（例如 CSV 檔案或 ARFF 檔案）都會自動轉換成 data.frame。

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

與每個 DataTable 輸入埠相關聯的 id 屬性必須具有唯一值，而且此值必須符合 R 函式中對應的具名參數。未在實驗中傳遞為輸入的選擇性 DataTable 埠，如果輸入未連接，則會忽略 NULL 傳遞給 R 函式的值，並忽略選擇性 zip 埠。 dataTable 和 Zip 類型的 isOptional 屬性都是選擇性的，預設為 false。

Zip： 自定義模組可以接受 zip 檔案作為輸入。此輸入已解壓縮至函式的 R 工作目錄

<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 工作目錄。

輸入規則：

Input 元素的 id 屬性值必須是有效的 R 變數名稱。
Input 元素的 id 屬性值不得超過 64 個字元。
Input 元素之 name 屬性的值不得超過 64 個字元。
Description 元素的內容不得超過 128 個字元
Input 元素之 type 屬性的值必須是 Zip 或 DataTable。
Input 元素的isOptional 屬性值並非必要專案（且在未指定時預設為 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 定義檔中指定適當的輸出埠，而且需要以清單傳回物件。輸出物件會從左至右指派給輸出埠，以反映對象在傳回清單中的順序。

例如，如果您想要修改自定義新增數據列模組，以輸出原始的兩個數據集：dataset1 和 dataset2，除了新的聯結數據集、數據集、數據集（依序從左至右，例如：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 元素：

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

輸出規則：

Output 元素的 id 屬性值必須是有效的 R 變數名稱。
Output 元素的 id 屬性值不得超過 32 個字元。
Output 元素之 name 屬性的值不得超過 64 個字元。
Output 元素之 type 屬性的值必須是 [視覺效果]。

引數

其他數據可以透過 Arguments 元素中 定義的模塊參數傳遞至 R 函 式。選取模組時，這些參數會出現在機器學習 UI 的最右邊屬性窗格中。自變數可以是任何支援的型別，也可以在需要時建立自定義列舉。與 Ports 元素類似，Arguments 元素可以有選擇性的 Description 元素，指定當您將滑鼠停留在參數名稱上方時出現的文字。模組的選擇性屬性，例如 defaultValue、minValue 和 maxValue，都可以新增至任何自變數作為 Properties 元素的屬性。 Properties 元素的有效屬性取決於自變數類型，並在下一節中以支援的自變數類型來描述。 isOptional 屬性設定為 「true」 的自變數不需要使用者輸入值。如果未將值提供給自變數，則自變數不會傳遞至進入點函式。選擇性的進入點函式自變數必須由函式明確處理，例如在進入點函式定義中指派 NULL 的預設值。如果使用者提供值，選擇性自變數只會強制執行其他自變數條件約束，也就是最小值或最大值。如同輸入和輸出，每個參數都有與其相關聯的唯一標識符值非常重要。在我們的快速入門範例中，相關聯的標識碼/參數已交換。

Arg 元素

模組參數是使用 XML 定義檔之 Arguments 區段的 Arg 子項目來定義。如同 Ports 區段中的子元素，Arguments 區段中的參數順序會定義 UX 中遇到的配置。參數會以 XML 檔案中定義的相同順序，從上到下出現在 UI 中。此處列出參數機器學習支援的類型。

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>

選擇性屬性： 預設值 和 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 - 比對 Type DataTable 的 Input 元素識別碼。
選擇性屬性：
- allowedTypes - 篩選您可以從中挑選的數據行類型。有效值包括：
  - 數值
  - 布林值
  - 類別
  - String
  - 標籤
  - 功能
  - 分數
  - 全部
- default - 資料列選擇器的有效預設選取範圍包括：
  - 無
  - NumericFeature
  - NumericLabel
  - NumericScore
  - NumericAll
  - BooleanFeature
  - BooleanLabel
  - BooleanScore
  - BooleanAll
  - CategoricalFeature
  - CategoricalLabel
  - 類別目錄核心
  - CategoricalAll
  - StringFeature
  - StringLabel
  - StringScore
  - StringAll
  - AllLabel
  - AllFeature
  - AllScore
  - 全部

DropDown：使用者指定的列舉式（下拉式清單）清單。下拉式清單專案是使用 Item 元素在 Properties 元素內指定。 每個專案的標識碼必須是唯一的，而且是有效的 R 變數。 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 - 預設屬性的值必須與其中一個項目元素中的標識碼值對應。

輔助檔案

放置在自定義模組 ZIP 檔案中的任何檔案，都可供運行時間使用。任何存在的目錄結構都保留下來。這表示檔案來源在本機和機器學習 Studio （傳統）執行中的運作方式相同。

注意

請注意，所有檔案都會擷取到 'src' 目錄，因此所有路徑都應該有 'src/' 前置詞。

例如，假設您想要從數據集中移除具有 NA 的任何數據列，並移除任何重複的數據列，再將它輸出至 CustomAddRows，而且您已經撰寫在檔案 RemoveDupNARows.R 中執行該作業的 R 函式：

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

您可以在 CustomAddRows 函式中，將輔助檔案 RemoveDupNARows.R 來源：

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

接下來，將包含 'CustomAddRows.R'、'CustomAddRows.xml' 和 'RemoveDupNARows.R' 的 zip 檔案上傳為自定義 R 模組。

執行環境

R 文稿的執行環境會使用與 執行 R 腳本 模組相同的 R 版本，而且可以使用相同的預設套件。您也可以將其他 R 套件加入自訂模組 zip 套件中，以將其他 R 套件新增至您的自訂模組。只要在 R 腳本中載入它們，就如同您在自己的 R 環境中一樣。

執行環境 的限制包括：

非持續性文件系統：當自定義模組執行時寫入的檔案不會在相同模組的多個執行之間保存。
沒有網路存取

共用方式為

定義機器學習 Studio 的自訂 R 模組（傳統版）

自定義 R 模組中的檔案

快速入門範例：定義、封裝及註冊自定義 R 模組

原始程序檔

XML 定義檔

封裝並註冊模組

XML 定義檔中的元素

模組元素

語言定義

連接埠

輸入元素

輸出元素

引數

Arg 元素

輔助檔案

執行環境

其他資源

共用方式為

定義 機器學習 Studio 的自訂 R 模組（傳統版）

自定義 R 模組中的檔案

快速入門範例：定義、封裝及註冊自定義 R 模組

原始程序檔

XML 定義檔

封裝並註冊模組

XML 定義檔中的元素

模組元素

語言定義

連接埠

輸入元素

輸出元素

引數

Arg 元素

輔助檔案

執行環境

其他資源

定義機器學習 Studio 的自訂 R 模組（傳統版）