使用 AI Toolkit for VS Code 轉換模型

模型轉換是一套整合式開發環境，旨在協助開發人員與 AI 工程師在 Windows 本地平台上轉換、量化、最佳化並評估預先構建的機器學習模型。它提供了一種簡化的端對端體驗，可將來源（如 Hugging Face）的模型進行轉換與最佳化，並啟用基於 NPU、GPU 與 CPU 的本地裝置推論。

先決條件

• 安裝最新版本的 Visual Studio Code。
• 安裝 AI Toolkit VS Code 擴充功能。如需更多資訊，請參閱 安裝 AI Toolkit。

建立專案

在模型轉換中建立專案，是進行機器學習模型轉換、最佳化、量化與評估的第一步。

1. 開啟 AI Toolkit 檢視，並選擇 Models > Conversion 以啟動模型轉換。

2. 選擇 New Model Project 以開始新的專案。

   

3. 選擇基礎模型

   • Hugging Face Model：從支援的模型清單中，選擇帶有預定義配方的基礎模型。
   • Model Template：如果模型未包含在基礎模型中，請選擇空白範本以使用自訂配方（進階場景）。

   

4. 輸入專案詳細資料：一個唯一的 Project Folder（專案資料夾）與 Project Name（專案名稱）。

   系統會在您選擇的儲存位置中，建立一個以該專案名稱命名的新資料夾，用於存放專案檔案。

支援的模型

模型轉換目前支援的清單不斷擴大，包括 PyTorch 格式的熱門 Hugging Face 模型。詳細的模型清單，請參考：模型清單 (Model List)

(選擇性) 將模型加入至現有專案

1. 開啟模型專案。

2. 選擇 Models > Conversion，然後在右側面板選擇 Add Models。

   

3. 選擇基礎模型或範本，然後選擇 Add。

   系統會在目前的專案資料夾中，建立一個包含新模型檔案的資料夾。

(選擇性) 建立新的模型專案

1. 開啟模型專案。

2. 選擇 Models > Conversion，然後在右側面板選擇 New Project。

   

3. 或者，關閉目前的模型專案並從頭 建立新專案。

(選擇性) 刪除模型專案

1. 開啟模型專案並選擇 Models > Conversion。

2. 在右上角的檢視畫面中，選擇省略號 (...) 然後選擇 Delete，即可刪除目前選取的模型專案。

   

執行工作流程

執行模型轉換中的工作流程是核心步驟，其將預先構建的機器學習模型轉換為最佳化且已量化的 ONNX 模型。

1. 在 VS Code 中選擇 File > Open Folder 以開啟模型專案資料夾。

2. 檢視工作流程設定

   1. 選擇 Models > Conversion。
   2. 選擇工作流程範本以檢視轉換配方。

   

   轉換 (Conversion)

   工作流程將始終執行轉換步驟，將模型轉換為 ONNX 格式。此步驟無法停用。

   量化 (Quantization)

   此區段可讓您設定量化參數。

   重要

   Hugging Face 合規警示：量化過程中需要校準資料集。您可能會在繼續之前被要求接受授權條款。若您錯過了通知，執行程序將會暫停等待您的輸入。請確保通知已啟用，且您已接受所需的授權。

   • Activation Type (啟用類型)：這是用於表示神經網路中每一層中間輸出（啟用）的資料類型。

   • Weight Type (權重類型)：這是用於表示模型學習參數（權重）的資料類型。

   • Quantization Dataset (量化資料集)：用於量化的校準資料集。

     若您的工作流程使用了需要在 Hugging Face 上批准授權合約的資料集（例如 ImageNet-1k），您將會在繼續前被要求於資料集頁面上接受條款。這是法律合規所必需的。

     1. 選擇 HuggingFace Access Token 按鈕以取得您的 Hugging Face 存取權杖。

        

     2. 選擇 Open 以開啟 Hugging Face 網站。

        

     3. 在 Hugging Face 入口網站取得您的權杖，並將其貼上至 Quick Pick 中。按下 Enter。

        

   • Quantization Dataset Split (量化資料集分割)：資料集可能具有不同的分割區，例如驗證集、訓練集與測試集。

   • Quantization Dataset Size (量化資料集大小)：用於量化模型的資料數量。

   如需更多關於啟用與權重類型的資訊，請參閱 資料類型選擇。

   您也可以停用此區段。在這種情況下，工作流程將僅把模型轉換為 ONNX 格式，而不對模型進行量化。

   評估

   在此區段中，您需要選擇用於評估的執行提供者 (Execution Provider, EP)，而不論模型是在哪個平台上轉換的。

   • Evaluate on (評估於)：您想要評估模型所在的目標裝置。可能的值為：
     • Qualcomm NPU：使用此選項需要相容的 Qualcomm 裝置。
     • AMD NPU：使用此選項需要具備支援 AMD NPU 的裝置。
     • Intel CPU/GPU/NPU：使用此選項需要具備支援 Intel CPU/GPU/NPU 的裝置。
     • NVIDIA TRT for RTX：使用此選項需要具備支援 TensorRT for RTX 之 Nvidia GPU 的裝置。
     • DirectML：使用此選項需要具備支援 DirectML 之 GPU 的裝置。
     • CPU：任何 CPU 皆可運作。
   • Evaluation Dataset (評估資料集)：用於評估的資料集。
   • Evaluation Dataset Split (評估資料集分割)：資料集可能具有不同的分割區，例如驗證集、訓練集與測試集。
   • Evaluation Dataset Size (評估資料集大小)：用於評估模型的資料數量。

   您也可以停用此區段。在這種情況下，工作流程將僅把模型轉換為 ONNX 格式，而不對模型進行評估。

3. 選擇 Run 以執行工作流程。

   系統會使用工作流程名稱與時間戳記（例如 bert_qdq_2025-05-06_20-45-00）自動產生預設的作業名稱，以便於追蹤。

   作業執行期間，您可以透過選擇狀態指示器，或在 History 面板的 Action 下的三點選單中選擇 Stop Running，來取消作業。

   Hugging Face 合規警示：量化過程中需要校準資料集。您可能會在繼續之前被要求接受授權條款。若您錯過了通知，執行程序將會暫停等待您的輸入。請確保已啟用通知，且您已接受所需的授權。

4. (選擇性) 在雲端執行模型轉換

   當您的本地機器運算或儲存容量不足時，雲端轉換 (Cloud Conversion) 可讓您在雲端執行模型轉換與量化。使用雲端轉換需要 Azure 訂閱。

   1. 從右上角的下拉式選單中選擇 Run with Cloud。請注意，Evaluation 區段將會被停用，因為雲端環境沒有用於推論的目標處理器。

      

   2. AI Toolkit 會先檢查是否已準備好雲端轉換所需的 Azure 資源。若有需要，系統會提示您輸入 Azure 訂閱與資源群組，以進行 Azure 資源佈建。

      

   3. 佈建完成後，佈建設定會儲存於您工作區根目錄下的 model_lab.workspace.provision.config。此資訊會被快取，以便重複使用 Azure 資源並加速雲端轉換流程。若您想要使用新資源，請刪除此檔案並再次執行雲端轉換。

   4. 系統會觸發一個 Azure Container App (ACA) 作業來執行雲端轉換。對於執行中的作業，您可以：

      • 選擇狀態連結以瀏覽至 Azure ACA 作業執行歷程頁面。
      • 選擇 logs 以瀏覽至 Azure Log Analytics。
      • 選擇重新整理按鈕以取得目前的作業狀態。

      

重新評估提示

模型轉換完成後，您可以使用重新評估功能再次執行評估，而無需重新進行模型轉換。

前往 History 面板並找到模型執行作業。選擇 Action 下的三點選單以 Re-evaluate (重新評估) 模型。

您可以選擇不同的 EP 或資料集進行重新評估。

失敗作業提示

如果您的作業被取消或失敗，您可以選擇作業名稱來調整工作流程並再次執行作業。為避免意外覆寫，每次執行都會建立一個新的歷史資料夾，其中包含各自的設定與結果。

檢視結果

Conversion 中的 History 面板是您追蹤、檢視與管理所有工作流程執行作業的中心儀表板。每次執行模型轉換與評估時，History 面板都會建立一個新項目，確保完整的可追蹤性與可重現性。

• 找到您想要檢視的工作流程執行紀錄。每個執行紀錄都列有狀態指示器（例如 Succeeded, Cancelled）。

• 選擇執行紀錄名稱以檢視轉換設定。

• 選擇狀態指示器下方的 logs 以檢視記錄與詳細執行結果。

• 模型轉換成功後，您可以在 Metrics 下方檢視評估結果。準確度 (accuracy)、延遲 (latency) 與吞吐量 (throughput) 等指標會顯示在每次執行紀錄旁。

  

• 您可以選擇 Action 下的三點選單，與已轉換的模型互動。

  

複製已轉換的模型路徑

• 從下拉式選單選擇 Copy model path。輸出的已轉換模型路徑（如 c:/{workspace}/{model_project}/history/{workflow}/model/model.onnx）將會複製到剪貼簿供您參考。對於 LLM 模型，系統會改為複製輸出資料夾路徑。

使用範例 Notebook 進行模型推論

• 從下拉式選單選擇 Inference in Sample。
• 選擇 Python 環境。
• 系統將會提示您選擇 Python 虛擬環境。預設執行階段為：C:\Users\{user_name}\.aitk\bin\model_lab_runtime\Python-WCR-win32-x64-3.12.9。
• 請注意，預設執行階段包含所需的一切，否則請手動安裝 requirements.txt。