# 如何使用 Faust-cudf 及 Faust 功能
Faust 是一個自動進行參數最佳化的 python 套件。透過此套件，使用者只需要對原程式碼做些微調整，再新增參數調教與最佳化流程之定義，即可輕鬆執行參數最佳化，尤其在機器學習、深度學習之超參數（hyperparameter）調教相當有幫助。
本環境已佈署於 Kubeflow jupyterhub 中，使用者可選擇以下 image
harbor.registry.com/kubeflow-images-public/faust-cudf:0.0.2
此環境同時包含 Keras 及 XGBoost，並安裝於 Python 3.6。關於 Jupyterhub 之使用方法請參閱相關說明書。
# 準備您的基本模型：Keras 執行實例
在以下說明文件中我們以 Keras MNIST 做為範例，利用 Faust 調教模型學習速度（learning rate）讓模型訓練在六個 epochs 內達到最佳的測試準確度。
# 原始程式碼（mnist_cnn.py）
開發人員首先準備欲進行參數調教的模型及訓練過程所需的資料集，並進行以下四個步驟。針對以下四步驟在 Keras MNIST 範例如下圖所示。
# 定義調教的參數（tunerKeras.json）
我們使用 JSON 格式定義各參數之調教值域，在本範例中我們對於 learning_rate 變數進行調教，數值區間為10ିହ至1.0，並以對數比例調整。
使用者指定該參數之名稱，並設定不同的參數種類，Faust 允許以下數值種類。
- “Type”: “Real”
“Bound”: [X:Y] “Distribution”: “log-uniform” 此類設定實數型參數，參數值域為 X 至 Y 之間，並包含 X 及 Y。Distribution 選項為選 擇性定義，若定義 Distribution 選項為 log-uniform 則調教區間以對數比例進行；若無定 義，則預設調教區間為線性。
- “Type”: “Integer”
“Bound”: [X:Y] 此類設定整數型參數，參數值域為 X 至 Y 之間，並包含 X 及 Y。調教區間為線性。
- “Type”: “Categorical”
“Categories”: [“A”, “B”, “C”] 此類設定分類型參數，參數種類列於 Categories，並以字串陣列型式表達。
JSON 定義完成後，將其檔案儲存。
# 設定參數最佳化流程（testKeras.py）
完成模型訓練主程式及調教參數定義後，使用者即可定義最佳化流程。對於一般應用之參數最佳化，使用者可由下圖範例進行調用。
使用者首先透過以下指令引入 FaustSession
from FaustAI.opt_main import FaustSession其次使用者透過 FaustSession 定義最佳化流程之基本資訊，包含軟硬體使用設置。此為必要指令。
FaustSession(entryFile, numRounds, settingJSONFile, n_concurrent=1, optfor=’maximum’, n_gpu_pw=1)
- entryFile: 指定欲進行最佳化之目標程式檔，該檔為 1.1.1 中已調整完成之程式。
- numRounds: 欲進行最佳化之回合數。
- settingJSONFile: 標明參數最佳化區間之 JSON 格式檔，如 1.1.2 所述。
- n_concurrent: 每一回合可以同時訓練多少個參數不同的模型。若最佳化流程完整
結束，則會產生的模型數量為(numRounds × n_concurrent)。以上圖為例，8 個回合搭配每回合 8 個平行測試全部完畢將產生 64 個模型。預設為 1。
- optfor: 計分之最佳化目標，可為’maximum’或’minimum’。
- n_gpu_pw: 每一測試所使用的 GPU 數量，預設為 1。如果該機器有 N 個 GPU，
則 N ≥ n_concurrent × n_gpu_pw。
- FaustSession.setEarlyStopper([[criteriaName, LargerOrLower, Value], …]) 定義最佳化流程提前結束之條件。使用者將定義包裝成為 list，每個 list element 為包含三個 element 的 sublist。
- criteriaName: 條件對象名稱，目前支援’Score’，即最佳化計分。
- LargerOrLower: 比較規則，目前支援’>’, ‘<’, ‘=’
- Value: 比較值。
在此範例中，如果產生得分超過 0.99 之模型，則立刻離開最佳化流程以節省時間。由於前面已指定測試資料集準確度做為得分依據，該定義相當於讓最佳化流程在獲得測試準確度超過 99%的模型時結束。此為選擇性指令。
- FaustSession.setSpaceDimensions()
此指令將 JSON 定義檔內容匯入 FaustSession 中。此為必要指令。
- FaustSession.fit()
開始進行參數最佳化流程。
- FaustSession.view()
流程結束後，此指令顯示參數最佳化結果以及模型列表。使用者可透過此列表尋找所需的模型。
使用者將以上檔案準備完成後，即可在指令行執行以下指令，執行入口檔為 1.1.3 所存取之流程定義程式。以下為本範例之指令行執行方法
python3.6 testKeras.py
本 Keras MNIST 範例之執行列表如下，可發現在第二回合（step_1）時有多個同時測試的 model 達到提前結束的條件（Score > 0.99），這些測試都採用 learning rate 為 1.0 的參數。使用者由此可同時獲得以下重要資訊。
- 本最佳化流程提供建議的參數設定，可用於日後類似資料訓練，提高長期機器學習應用之效率。
- 產生的模型檔可直接用於其他資料之預測。
- 使用者可選用多個模型進行額外處理，可用於多模型組合學習和判斷（ensembles）。
# 使用 Jupyter Notebook 範例
除了在一般 Python 程式中調用 Faust 以外，本雲端平台所設置的 Faust 容器亦提供 Jupyter Notebook 範例，使用者可直接在 FaustExample/Keras_MNIST_CNN 中進入 Test_Keras_MNIST.ipynb 執行，同時提供詳細說明。
# XGBoost 執行實例
Faust 之一大優勢即不受限於特定機器學習框架，除了前面所述之 Keras，本範例提供XGBoost 之使用方法，除了直接調用 FaustAI.opt_main 中的 FaustSession 以外，亦可直接使用 wrapper。
本 wrapper 的調用方法為與前文範例幾乎相同，差別在於調用函數的名稱如下
from FaustAI.opt_xgboost import FaustXGB
除此之外，FaustXGB 不提供單模型多 GPU 功能；換言之，調用 FaustXGB 時沒有n_gpu_pw 參數。使用方法可參考 Jupyter Notebook 中所附之範例，使用者可直接在FaustExample/XGB_Otto 中進入 Test_XGBoost_Otto.ipynb 執行。
本範例提供兩種
