--- description: OneAI 文件 tags: 案例教學, 聯合學習 --- [OneAI 文件](/s/user-guide) # 案例教學 - 部署 NVIDIA FLARE Federated Learning [TOC] ## 前言 聯合學習（Federated Learning，簡稱 FL），又稱「聯邦式學習」或「聯盟學習」，聯合學習可以讓多個參與者能夠在不共享資料的情況下共同構建一個通用的、強大的機器學習模型，從而解決資料的隱私、安全、法規及地域性等問題，以模型共享取代資料共享的方式，藉由不同來源的大量資料及分散式訓練取得最佳的 AI 模型。聯合學習技術已應用於多個領域，包括醫療、電信、物聯網和製藥。 NVIDIA FLARE™ （NVIDIA Federated Learning Application Runtime Environment）是一個與領域無關、開源且可擴展的聯合學習 SDK。此 SDK 讓研究人員和資料科學家可以將現有的機器學習和深度學習工作流程調整為分散式典範，並使平台開發人員可以針對分散式多方協作，打造安全、保護隱私的產品。 <center><img src="/uploads/upload_68113190912dafd4db7a21f653ff5276.png" ></center> <center>NVIDIA FLARE 聯合學習示意圖</center> <center><a href="https://developer.nvidia.com/flare">（圖片來源：NVIDIA）</a></center> <br><br> ## 0. 開始使用 TWCC OneAI 提供 GPU 運算資源管理及多種工具，預載常用的 AI 訓練框架，只要透過本範例教學的指引即可快速完成部署與連線，協助您如何輕鬆入門使用 TWCC OneAI 部署 NVIDIA FLARE 聯合學習，快速開發人工智慧模型。 本教學將使用 OneAI 的「**容器服務**」和「**儲存服務**」 部署 NVIDIA FLARE [Hello PyTorch](https://github.com/NVIDIA/NVFlare/tree/2.1.3/examples/hello-pt) 範例的聯合學習環境，範例中 FL Server 負責人在 TWCC OneAI 租用一個計畫部署 FL Server；其他家醫院或機構在 OneAI 租用各自的計畫部署 FL Client 加入聯合學習訓練，在此將部署 NVIDIA 組織中的 Site1 和 Site2 兩個 FL Client；FL Admin 可以由聯盟中的首席資料科學家擔任，在 OneAI 上租用另一個計畫部署 FL Admin，不同計畫間各自獨立，彼此不共享資料。為了方便體驗，本範例可以在同一個 OneAI 計畫中操作。 <center><img src="/uploads/upload_bd9938e3f3fa0fc2ed65d3c838727aa7.png" alt="NVIDIA Clara Train 聯合學習部署架構"></center> <center>聯合學習部署架構</center> <br><br> 主要步驟如下： 1. [**Provision**](#1-Provision) 在此階段，計畫主持人規劃參與者的角色、權限及產生安裝包。 2. [**部署 FL Server**](#2-部署-FL-Server) 在此階段，我們將部署 FL Server，FL Server 協調聯合學習訓練，為 FL Client 和 FL Admin 連接的主要樞紐。 3. [**部署 FL Client**](#3-部署-FL-Client) 在此階段，我們將部署 2 個 FL Client，分別為 Site1 和 Site2，以及準備每個 FL Client 的訓練資料集。 4. [**部署 FL Admin**](#4-部署-FL-Admin) 在此階段，我們會部署 FL Admin，透過 FL Admin 工具連線到 FL Server 及 FL Client 進行聯合學習的操作。 5. [**執行聯合學習訓練**](#5-執行聯合學習訓練) 在此階段，我們會執行聯合學習訓練，並取得各個 FL Client 的訓練結果及最佳模型。 :::warning :warning: **注意事項** 1. 開始本範例前請先對 [**NVIDIA FLARE**](https://nvflare.readthedocs.io/en/main/index.html) 有基本瞭解。 2. 本範例基於 [**NVIDIA FLARE 2.1 Examples**](https://github.com/NVIDIA/NVFlare/tree/2.1.3/examples/hello-pt) 範例程式、資料集和模型，使用前請詳閱 NVIDIA 的授權條款。 ::: <br> ## 1. Provision Provision 階段是計畫主持人規劃參與者的角色、權限及產生安裝包，本章節將使用 NVIDIA FLARE 內建的 project.yml 透過 Provision 工具程式產生每個站點的安裝包，請依照下列步驟操作。 ### 1.1 預建 FL Server 容器 因為在 Provision 階段需設定 FL Server 所需的 fed_learn_port 和 admin_port 的服務埠，故開始 Provision 前我們先預建一個 FL Server 容器，以取得 FL Server 的兩個對外服務埠。 從 OneAI 服務列表選擇「**容器服務**」，進入容器服務管理頁面後，點擊「**+建立**」，新增一個容器服務。 1. **基本資訊** 請依序輸入 **名稱**，例如：**`federated-learning-server`**、**描述**，**映像檔** 請選擇 `nvidia-official-images:PyTorch-21.02-py3`。 :::info :bulb:**提示：** 建議依所使用的開發框架，選擇系統提供的映像檔。 | 開發框架| 映像檔 | ------------ | -------- | | TensorFlow | nvidia-official-images:TensorFlow-21.02-tf1-py3 | | TensorFlow 2| nvidia-official-images:TensorFlow-21.02-tf2-py3 | | PyTorch | nvidia-official-images:PyTorch-21.02-py3 | | MONAI | nvidia-official-images:PyTorch-21.02-py3 | | Numpy | nvidia-official-images:PyTorch-21.02-py3 | :::  2. **硬體設定** 選擇硬體規格，可以不用配置 GPU。 3. **儲存設定** 此步驟暫不需設定，可先清除預設的設定。 4. **網路設定** 此步驟我們會先預產生兩個 FL Server 需要的對外服務埠，若所選取的映像檔有預設的容器連接埠，可先删除，再依下列圖示新增兩個容器連接埠。 * **fed_learn_port**  * **admin_port**  * 新增後好容器連接埠後的設定畫面如下。  5. **變數設定** 此步驟暫不需設定，可先清除預設的設定或直接到下一步。 6. **檢閱 + 建立** 最後，確認填寫的資訊，就可按下「**建立**」。 **FL Server** 容器建立後，會出現在容器服務列表中，當容器服務的狀態變成 **`Ready`** 後，在連接埠下方可以看見系統為 **網路設定** 步驟中新增的容器連接埠 `8002` 及 `8003` 自動產生的對外埠 **`8002:31767`** 和 **`8003:31768`**，在接下來的步驟中會使用到這兩個對外埠。  ### 1.2 建立 Provision 安裝包存放空間 本步驟將建立存放 Provision 安裝包的空間。 1. **建立儲存體** 從 OneAI 服務列表選擇「**儲存服務**」，進入儲存服務管理頁面，接著點擊「**+建立**」，新增儲存體 **`federated-learning-packages`**。  2. **檢視儲存體** 完成儲存體的建立後，回到儲存服務管理頁面，此時會看到剛剛新增的儲存體已建立完成。  ### 1.3 建立 Provision 容器　 從 OneAI 服務列表選擇「**容器服務**」，進入容器服務管理頁面後，點擊「**+建立**」，新增一個容器服務。 1. **基本資訊** 請依序輸入 **名稱**，例如：**`federated-learning-provision`**、**描述**，**映像檔** 請選擇支援 Python 3.8 執行環境，例如：`clara:v4.0`。  2. **硬體設定** 選擇硬體規格，可以不用配置 GPU。 3. **儲存設定** 這個階段需掛載存放安裝包的儲存體，請點擊「**新增**」並設定存放安裝包的儲存體。 **workspace**：**`federated-learning-packages`**。  4. **網路設定** 此步驟無需設定。 5. **變數設定** * **命令** 請貼上以下指令： ```= echo "cd /workspace" >> /root/.bashrc &&git clone https://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@github.com/asus-ocis/fl-script.git /fl-script &&sleep 1 &&/bin/bash /fl-script/nvflare21.sh ```  6. **檢閱 + 建立** 最後，確認填寫的資訊，就可按下「**建立**」。 ### 1.4 修改 Provision 配置檔 **Provision** 容器建立後，會出現在容器服務列表中，當容器服務的狀態變成 **`Ready`** 後，請進入該容器服務的詳細資料頁面，點選上方「**終端機**」頁籤連線該容器，連線成功後再輸入 provision 指令，並依本範例的環境設定，修改 Provision 配置檔：project.yml。 執行 provision 指令時，如果 project.xml 不存在，會詢問是否要自動產生，請輸入 `ｙ` 確認。 ``` # provision Path list (sys.path) for python codes loading: ['/opt/conda/bin', '/workspace', '/opt/nvidia/medical', '/opt/conda/lib/python38.zip', '/opt/conda/lib/python3.8', '/opt/conda/lib/python3.8/lib-dynload', '/opt/conda/lib/python3.8/site-packages', '/opt/monai', '/workspace/.'] No project.yml found in current folder. Is it OK to generate one at /workspace/project.yml for you? (y/N) y /workspace/project.yml was created. Please edit it to fit your FL configuration. ``` 接著執行以下命令編輯 project.yml，修改配置檔內容。 ```= # nano project.yml ``` 修改處如下： * **name**：FL Server 的完整網域名稱（FQDN），本範例設定為 **`federated.oneai.twcc.ai`**。請注意：因本範例將 FL Server 部署於 OneAI，故需設定為 OneAI 為聯合學習特別建立的 **`federated.oneai.twcc.ai`**。 * **fed_learn_port**：配置檔中預設為 **`8002`**，請修改成您的 FL Server 容器服務埠 `8002` 對應的對外服務埠，例如本範例為 `31767` （如下圖）。 * **admin_port**：配置檔中預設為 **`8003`**，請修改成您的 FL Server 容器服務埠 `8003` 對應的對外服務埠，例如本範例為 `31768` （如下圖）。請注意 admin_port 不能跟 fed_learn_port 相同。 * **enable_byoc**：因為本範例使用自定的程式，所以在配置檔中的 enable_byoc 設定需要全部設置為 true。 * **關閉 HA 相關設定**：配置檔中預設有第二台 FL Server，因為本範例不會開啟 HA 功能，所以需修改 HA 的相關設定。 * **設定將安裝包打包成 zip 檔**：配置檔中預設沒有此設定，請新增將安裝包打包成 zip 檔的設定以方便下載。  :::info :bulb:**提示：關於 FL Server** 本範例使用的 FL Server FQDN 為 **`federated.oneai.twcc.ai`**，這是 OneAI 為聯合學習提供的 FL Server 服務網址．您可以依照本範例教學，體驗在 OneAI 上部署及執行聯合學習訓練，或是設定成其他的 FL Server FQDN。 ::: ```yaml= .... # change overseer.example.com to the FQDN of the overseer - name: overseer.example.com type: overseer org: nvidia protocol: https api_root: /api/v1 port: 8443 # change example.com to the FQDN of the server - name: federated.oneai.twcc.ai <--- 修改 FL Server 的 Domain type: server org: nvidia fed_learn_port: 31767 <--- 修改 fed_learn_port admin_port: 31768 <--- 修改 admin_port，不可與 fed_learn_port 相同 # enable_byoc loads python codes in app. Default is false. enable_byoc: true components: <<: *svr_comps # - name: example2.com <--- 請整個註解掉第二台 FL server設定，因為本範例不使用HA # type: server # org: nvidia # fed_learn_port: 8002 # admin_port: 8003 # enable_byoc loads python codes in app. Default is false. # enable_byoc: true # components: # <<: *svr_comps - name: site-1 type: client org: nvidia enable_byoc: true components: <<: *cln_comps - name: site-2 type: client org: nvidia enable_byoc: true <--- 修改為 true，因為需要執行自定的程式 components: <<: *cln_comps ... ... ... overseer_agent: path: nvflare.ha.dummy_overseer_agent.DummyOverseerAgent <--- 修改為 DummyOverseerAgent, 用以關掉 HA 功能 overseer_exists: false <--- 修改為 false，用以關掉 HA 功能 args: sp_end_point: federated.oneai.twcc.ai:31767:31768 <--- 設定 FL server 的 end point ... ... ... - path: nvflare.lighter.impl.workspace.DistributionBuilder <--- 新增此 3 列，將安裝包打包成 zip 檔 args: zip_password: true ``` :::info :bulb:**提示：關於 FL Client 和 Admin Client** 本範例僅需修改 FL Server 的設定，如果您想修改 FL Client 和 Admin Client，可自行修改 project.yml 中 fl_clients 和 admin_clients 的設定，請參考下列說明，更多資訊請參見 NVIDIA FLARE 的 [**Project yaml file 說明文件**](https://nvflare.readthedocs.io/en/main/programming_guide/provisioning_system.html?highlight=project.yml#project-yaml-file)。 <br> ```yaml= ... participants: <-- 這裡定義所有參與者角色與組織，像是 server、 client 和 admin # change example.com to the FQDN of the server - name: federated.oneai.twcc.ai type: server <-- 根據 type 這裡定義 server org: nvidia fed_learn_port: 31767 admin_port: 31768 # enable_byoc loads python codes in app. Default is false. enable_byoc: true - name: site1 type: client <-- 根據 type 這裡定義 client org: nvidia enable_byoc: true - name: site2 type: client <-- 根據 type 這裡定義 client org: nvidia enable_byoc: true - name: admin@nvidia.com type: admin <-- 根據 type 這裡定義 admin org: nvidia roles: - super <-- 這裡定義 admin 權限 ... ``` ::: :::info :bulb:**提示：關於角色與權限** NVIDIA FLARE 的角色權限定義在 project.yml 的 authz_policy 欄位裡，本範例使用預設的角色與權限設定，更多資訊請參見 NVIDIA FLARE 的 [**Federated Learning Authorization 說明文件**](https://nvflare.readthedocs.io/en/main/user_guide/authorization.html?highlight=right)。 ::: ### 1.5 執行 Provision 工具產生安裝包 接下來請執行 **`provision`** 命令產生安裝包及密碼。 ``` # provision ``` 執行成功後，請將畫面上提供的密碼記下來。  接著從 OneAI 服務列表選擇「**儲存服務**」，進入儲存服務管理頁面，選擇 **`federated-learning-packages`**，將會看到執行 provision 所產生的安裝包，如下圖所示：   本範例將會使用到以下的安裝包，在實際情境中，每個聯盟的成員只會收到自己的安裝包和解壓縮的密碼。 * federated.oneai.twcc.ai.zip * site1.zip * site2.zip * admin@nvidia.com.zip ## 2. 部署 FL Server FL Server 將協調聯合學習訓練並成為所有 FL Client 和 Admin 連接的主要樞紐，本章節將介紹如何使用 **OneAI 容器服務** 部署 FL Server。 ### 2.1 上傳 FL Server 安裝包 首先，請解壓安裝包 federated.oneai.twcc.ai.zip，密碼就是在執行 provision 命令後畫面列表中 federated.oneai.twcc.ai.zip 左邊的 Password。  解開後目錄結構如下： ```= ./startup ├── authorization.json ├── fed_server.json ├── log.config ├── readme.txt ├── rootCA.pem ├── server.crt ├── server.key ├── server.pfx ├── signature.json ├── start.sh ├── stop_fl.sh └── sub_start.sh ``` 解開安裝包後請依以下步驟檢查安裝包的資訊： 1. 確認 FL Server 資訊。 開啟 **fed_server.json**，確認此檔案中 **`target`** 設定的 FL Server 的 Domain Name 和 Port 是否正確，例如： ```json= ... "service": { "target": "federated.oneai.twcc.ai:31767", ... ``` 2. 檢查安裝包檔案是否有異常，以防止拿到來路不明的檔案。 檢查無誤後，接著將此安裝包上傳至 OneAI 的「**儲存服務**」中。 1. **建立儲存體** 從 OneAI 服務列表選擇「**儲存服務**」，進入儲存服務管理頁面，接著點擊「**+建立**」，新增儲存體 **`federated-learning-server-startkit`**，用來存放 Server 安裝包。  2. **檢視儲存體** 完成儲存體的建立後，回到儲存服務管理頁面，此時會看到剛剛新增的儲存體已建立完成。 3. **上傳 FL Server 安裝包** 點擊建立好的儲存體，然後上傳整個 FL Server 安裝包目錄 **startup**。（請參閱 [**儲存服務說明文件**](/s/storage)）。  ### 2.2 修改 FL Server 容器 從 OneAI 服務列表選擇「**容器服務**」，進入容器服務管理頁面後，點擊剛建立的 **`federated-learning-server`** 容器服務。  進入「**容器服務詳細資料**」頁面後，點擊上方的 **停止** 圖示停止容器服務。  進入容器服務詳細資料頁面後，點擊上方的 **編輯** 圖示。  接著依下列步驟修改 FL Server 的容器服務設定。 1. **基本資訊** 此步驟無需修改。 2. **硬體設定** 此步驟無需修改。 3. **儲存設定** 此步驟將掛載存放 FL Server 安裝包的儲存體，請點擊「**新增**」並設定存放安裝包的儲存體。 * **workspace**：**`federated-learning-server-startkit`**。  4. **網路設定** 在此我們需將之前建立的容器連接埠修改成與系統自動分配的對外埠一致。 :::info :bulb:**提示：** 因為 FL Server 的 Listen Port 要與 FL Client 的連接埠一致。 ::: 點擊列表右側的 **編輯** 圖示。  將容器連接埠 `8002` 改成下方的 **對外埠**，如下圖。  修改好後點擊「**儲存設定**」。  重覆同樣步驟，將修改容器連接埠 `8003` 改成對應的對外埠，修改完後請確認 **容器連接埠** 是否與 **對外埠** 一致。  5. **變數設定** * **環境變數** 此步驟可依您的需求，自行選擇是否要設定下列變數。 * **START**：設定是否要自動自動執行 **`start.sh`**，數值設定為 **`AUTO`** 時，將會在容器啟動後自動執行 **`start.sh`** 啟動 FL Server，如不想自動啟動 FL Server 請不要設定 START 變數。 * **命令** 請貼上以下指令： ```= echo "cd /workspace" >> /root/.bashrc &&git clone https://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@github.com/asus-ocis/fl-script.git /fl-script &&sleep 1 &&/bin/bash /fl-script/nvflare21.sh ```  6. **檢閱 + 建立** 最後，確認填寫的資訊，就可按下建立。 修改完成後，請點擊上方的 **啟動** 圖示，重新啟動容器服務。 ### 2.3 啟動 FL Server 如果您在 **變數設定** 有設定 **START:AUTO**，在 **容器服務** 建立好後，系統將自動執行 **./startup/start.sh** 啟動 FL Server。當容器服務的狀態顯示為 **`Ready`** 後，請進入該容器服務的詳細資料頁面，點選上方「**終端機**」頁籤，執行以下命令查看 log 檔。 ```= cat /workspace/log.txt ``` :::info :bulb:**提示** 如果您在 **變數設定** 步驟沒有設定 START:AUTO，進入「**終端機**」頁面後，請先手動執行啟動命令 **`./startup/start.sh`**。 ::: 看到下列訊息，表示 FL Server 成功啟動。 ```= 2022-07-15 04:07:10,061 - FederatedServer - INFO - starting secure server at federated.oneai.twcc.ai:31767 2022-07-15 04:07:10,068 - FederatedServer - INFO - Got the primary sp: federated.oneai.twcc.ai fl_port: 31767 SSID: ebc6125d-0a56-4688-9b08-355fe9e4d61a. Turning to hot. deployed FL server trainer. 2022-07-15 04:07:10,080 - FedAdminServer - INFO - Starting Admin Server federated.oneai.twcc.ai on Port 31768 2022-07-15 04:07:10,080 - root - INFO - Server started ``` 最後請確認您的工作相關軟體是否已安裝完成。 ## 3. 部署 FL Client 在本範例中有 2 個 Client，分別為 site1 和 site2，以下說明如何部署 site1 的安裝包和資料集。接著，請依此類推，完成 site2 的部署。 ### 3.1 上傳 FL Client 安裝包 首先在本地端解壓縮 site1 的安裝包 site1.zip，解壓縮後目錄結構如下： ```= ./startup ├── client.crt ├── client.key ├── client.pfx ├── fed_client.json ├── log.config ├── readme.txt ├── rootCA.pem ├── signature.json ├── start.sh ├── stop_fl.sh └── sub_start.sh ``` 解開安裝包後請依以下步驟檢查安裝包的資訊： 1. 確認 FL Server 資訊。 開啟 **fed_client.json**，確認此檔案中 **`sp_end_point`** 設定的 FL Server 的 Domain Name 和 Port 是否正確。 ```json= ... "overseer_agent": "sp_end_point": "federated.oneai.twcc.ai:31767:31768" ... ``` 2. 檢查安裝包檔案是否有異常，以防止拿到來路不明的檔案。 檢查無誤後，接著將此安裝包上傳至 OneAI 的「**儲存服務**」中。 1. **建立儲存體** 從 OneAI 服務列表選擇「**儲存服務**」，進入儲存服務管理頁面，接著點擊「**+建立**」，新增儲存體 `federated-learning-site1-startkit` 以用來存放 site1 的安裝包檔案。  2. **檢視儲存體** 完成儲存體的建立後，回到儲存服務管理頁面，此時會看到剛剛新增的儲存體已建立完成。 3. **上傳 FL Client 安裝包** 點擊建立好的儲存體，然後上傳整個 site1 安裝包目錄 **startup**。（請參閱 [**儲存服務說明文件**](/s/storage)）。  ### 3.2 準備訓練資料集儲存體 接著請建立一個存放訓練資料集的儲存體，例如：`federated-learning-site1-dataset`，本範例使用的 NVIDIA PyTorch 範例會自動將 Cifar10 資料集存放於此。 ### 3.3 建立 FL Client 容器 從 OneAI 服務列表選擇「**容器服務**」，進入容器服務管理頁面後，點擊「**+建立**」，新增一個容器服務。 1. 基本資訊 請依序輸入 **名稱**，例如：**`federated-learning-site1`**、**描述**，**映像檔** 請選擇 `nvidia-official-images:PyTorch-21.02-py3`。 :::info :bulb:**提示：** 建議依所使用的開發框架，選擇系統提供的映像檔。 | 開發框架| 映像檔 | ------------ | -------- | | TensorFlow | nvidia-official-images:TensorFlow-21.02-tf1-py3 | | TensorFlow 2| nvidia-official-images:TensorFlow-21.02-tf2-py3 | | PyTorch | nvidia-official-images:PyTorch-21.02-py3 | | MONAI | nvidia-official-images:PyTorch-21.02-py3 | | Numpy | nvidia-official-images:PyTorch-21.02-py3 | :::  2. **硬體設定** FL Client 需執行 FL 訓練任務，請選擇至少有 1 張 GPU，記憶體 25 GB 的硬體選項。 3. **儲存設定** 此步驟須掛載的儲存體有兩個，請點擊「**新增**」並設定以下內容： * **workspace**：存放 Client 安裝包的儲存體，請選擇 **`federated-learning-site1-startkit`**。 * **data**：存放訓練資料集的儲存體，請選擇 **`federated-learning-site1-dataset`**。  4. **網路設定** 此步驟無需設定。 5. **變數設定** * **環境變數** * **`START`** 設定是否自動執行 **`start.sh`**，數值設定為 **`AUTO`**，將會在 FL Client 容器啟動後自動執行 **`start.sh`**，並自動加入 FL Server。 * **命令** 請貼上以下指令： ```= echo "cd /workspace" >> /root/.bashrc &&git clone https://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@github.com/asus-ocis/fl-script.git /fl-script &&sleep 1 &&/bin/bash /fl-script/nvflare21.sh ```  :::info :bulb:**提示** 如果您的 FL Server 不是公開的，可以透過設定 **`FLSERVER`** 和 **`FLSERVERIP`** 環境變數，讓系統自動修改 /etc/hosts。 * **`FLSERVER`** 設定您的 FL Server Domain Name（非對外公開），系統會自動修改 /etc/hosts。例如 `myflserver.com`（需與 **fed_client.json** 的 "sp_end_point" 欄位一致）。 設定 FL Server 的 IP，需與 **`FLSERVER`** 搭配使用，例如 `203.145.220.166`。 ::: 6. **檢閱 + 建立** 最後，確認填寫的資訊，就可按下「**建立**」。 ### 3.4 啟動 FL Client 如果您在 **變數設定** 有設定 **START:AUTO**，系統將自動執行 **./startup/start.sh**，當 FL Client 容器服務的狀態顯示為 **`Ready`** 後，請進入該容器服務的詳細資料頁面，點選上方「**終端機**」頁籤，執行以下命令查看 log 檔。 ```= cat /workspace/log.txt ``` :::info :bulb:**提示** 如果您在 **變數設定** 步驟沒有設定 START:AUTO，進入「**終端機**」頁面後，請先手動執行啟動命令 **`./startup/start.sh`**。 ::: 當 FL Client 成功連接 FL Server 後，將會出現如以下的資訊： ```= ... 2022-07-15 06:50:01,348 - FederatedClient - INFO - Got the new primary SP: federated.oneai.twcc.ai:30718 2022-07-15 06:50:02,514 - FederatedClient - INFO - Successfully registered client:site-1 for project example_project. Token:ac664158-37a7-4169-9a61-32bdb36e2ef3 SSID:ebc6125d-0a56-4688-9b08-355fe9e4d61a ``` ### 3.5 部署其他 FL Client 請重覆 site1 的部署步驟，使用 site2.zip 安裝包部署並啟動。 ## 4. 部署 FL Admin FL Admin 是聯合學習的控制核心，負責監督及調控整個深度學習模型訓練過程。當 FL Server 和 FL Clients 啟動後，就可以透過 FL Admin 管理及運行聯合學習。此章節將說明如何部署 FL Admin 並使用 Admin Tool 操作聯合學習。 ### 4.1 上傳 FL Admin 安裝包 首先在本地端解壓縮安裝包 admin@nvidia.com.zip，解開後目錄結構如下： ```= startup/ ├── client.crt ├── client.key ├── client.pfx ├── fed_admin.json ├── fl_admin.sh ├── readme.txt └── rootCA.pem ``` 解開安裝包後請依以下步驟檢查安裝包的資訊： 1. 確認 FL Server 資訊。 開啟 **fed_admin.json**，確認此檔案中 **`sp_end_point`** 設定的 FL Server 的 Domain Name 和 Port 是否正確。 ```json= ... "overseer_agent": "sp_end_point": "federated.oneai.twcc.ai:31767:31768" ... ``` 2. 檢查安裝包檔案是否有異常，以防止拿到來路不明的檔案。 檢查無誤後，接著將此安裝包上傳至 OneAI 的「**儲存服務**」中。 1. **建立儲存體** 從 OneAI 服務列表選擇「**儲存服務**」，進入儲存服務管理頁面，接著點擊「**+建立**」，新增一個名稱為 `federated-learning-admin-startkit` 的儲存體，用來存放 Admin 安裝包。  2. **檢視儲存體** 完成儲存體的建立後，回到儲存服務管理頁面，此時會看到剛剛新增的儲存體已建立完成。 3. **上傳 FL Admin 安裝包** 點擊建立好的儲存體，然後上傳整個 Admin 安裝包目錄 **startup**。（請參閱 [**儲存服務說明文件**](/s/storage)）。  ### 4.2 建立 FL Admin 容器 從 OneAI 服務列表選擇「**容器服務**」，進入容器服務管理頁面後，點擊「**+建立**」，新增一個容器服務。 1. **基本資訊** 請依序輸入 **名稱**，例如：**`federated-learning-admin`**、**描述**，**映像檔** 請選擇支援 Python 3.8 執行環境，例如：`clara:v4.0`。  2. **硬體設定** 選擇硬體規格，可以不用配置 GPU。 3. **儲存設定** 此步驟須掛載存放安裝包的空間，請點擊「**新增**」並設定存放安裝包的儲存體。 * **workspace**：存放 Admin 安裝包的儲存體，請選擇 `federated-learning-admin-startkit`。  4. **網路設定** 此步驟無需設定。 5. **變數設定** * **環境變數** 本範例使用的 FL Server 無需設定環境變數。 * **命令** 請貼上以下指令： ``` echo "cd /workspace" >> /root/.bashrc &&git clone https://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@github.com/asus-ocis/fl-script.git /fl-script &&sleep 1 &&/bin/bash /fl-script/nvflare21.sh ```  :::info :bulb:**提示** 如果您的 FL Server 不是公開的，可以透過設定 **`FLSERVER`** 和 **`FLSERVERIP`** 環境變數，讓系統自動修改 /etc/hosts。 * **`FLSERVER`** 設定您的 FL Server Domain Name（非對外公開），系統會自動修改 /etc/hosts。例如 **`myflserver.com`**。（需與 **fed_admin.json** 的 "sp_end_point" 欄位一致）。 * **`FLSERVERIP`** 設定 FL Server 的 IP，需與 **`FLSERVER`** 搭配使用，例如 `203.145.220.166`。 ::: 6. **檢閱 + 建立** 最後，確認填寫的資訊，就可按下「**建立**」。 ### 4.3 啟動 FL Admin Admin 容器服務建立後，請進入該容器服務的詳細資料頁面，點選 上方「**終端機**」頁籤，執行 **`/startup/fl_admin.sh`** 命令啟動 FL Admin Server。 ```= # ./startup/fl_admin.sh ``` 畫面出現 **`User Name:`** 提示後請輸入 **`admin@nvidia.com`** 並按下 Enter 鍵登入。 ```= # ./startup/fl_admin.sh User Name: admin@nvidia.com Waiting for token from successful login... Got primary SP federated.oneai.twcc.ai:31767:31768 from overseer. Host: federated.oneai.twcc.ai Admin_port: 31768 SSID: ebc6125d-0a56-4688-9b08-355fe9e4d61a Type ? to list commands; type "? cmdName" to show usage of a command. > ``` ### 4.4 確認連線狀態 執行 **`check_status server`** 命令查詢 FL Server 的狀態。  執行 **`check_status client`** 命令查詢 FL Client 的連線狀態。確認 FL Server 和 FL Client 已連線成功後，即可開始準備進行聯合學習訓練。  ## 5. 執行聯合學習訓練 此章節將說明如何準備訓練程式及執行聯合學習的訓練。 ### 5.1 準備訓練程式 本教學將使用 NVIDIA 提供的 Hello PyTorch 範例程式進行執行聯合學習訓練，請先下載 [**hello-py**](https://github.com/NVIDIA/NVFlare/tree/2.1.3/examples/hello-pt)，並修改下列程式以符合本範例的測試環境。 :::info :bulb:**提示：** 詳細 custom code 說明請參考 [**NVIDIA FLARE 文件說明**](https://nvflare.readthedocs.io/en/main/user_guide/application.html?highlight=custom#custom-code)。 ::: 1. 請修改檔案 hello-py/custom/cifar10trainer.py 的部分內容： ```json= ... def __init__( self, data_path="/data", <--這裡請設定 "/data" ... ``` 2. 請修改檔案 hello-py/custom/cifar10validator.py 的部分內容： ```json= ... def __init__(self, data_path="/data", validate_task_name=AppConstants.TASK_VALIDATION): <--這裡請設定 data_path="/data" ... ``` 修改完後，請到「**儲存服務**」的 **`federated-learning-admin-startkit`** 儲存體的 **transfer** 目錄，並將 **hello-py** 上傳至 **transfer** 目錄下，如下圖所示：  ### 5.2 執行訓練任務 接著我們可以透過 submit_job 指令來執行訓練任務，請執行 **`submit_job hello-pt`** 啟動訓練，執行後會得到一個訓練任務編號，請記下此訓練任務編號方便後續查詢。  訓練任啟動後可執行 **`check_status server`** 和 **`check_status client`** 命令來檢查 FL Server 與 FL Client 的狀態，若狀態顯示為 **`started`**，即表示訓練任務已開始執行。   ### 5.3 查看訓練狀態 訓練任務執行一段時間後可以執行 **`list_jobs`** 命令取得所有訓練任務狀態。  ### 5.4 取得訓練結果 當訓練任務顯示為完成狀態，即可執行 **`download_job <job_id>`** 命令下載訓練任務結果。  訓練完成後的模型（global model）可從下載路徑中取得，例如： 6592e357-0b8b-400e-b04d-275349eb138c/workspace/app_server/FL_global_model.pt。