ONNX Runtime 本機部署使用完整指南

如果您與 人工智能 隨著機器學習融入你的日常生活，你遲早會遇到它。 ONNX 格式的模型 ONNX 執行時間引擎這種組合已成為穿著各種款式服裝的基石之一。 IA 從實驗室環境到 Windows、雲端、行動設備，甚至是邊緣設備上的實際應用。

在本指南中，我們將冷靜而直截了當地探討以下內容： 如何充分利用 ONNX Runtime 來處理經典模型、LLM 和電腦視覺我將詳細解釋它是什麼，它與 PyTorch 或 TensorFlow 等框架的關係，如何將其整合到 .NET 和 WinUI 應用程式中，如何利用 GPU、NPU 或 FPGA 加速，以及最有趣的實際應用案例是什麼。

ONNX是什麼？ ONNX Runtime解決了什麼問題？

ONNX（開放神經網路交換）是表示人工智慧模型的開放標準 這樣他們就可以在不同的框架之間轉換， 硬件 無需返工。可以將 ONNX 視為一個「通用翻譯器」。 神經網絡您可以使用 PyTorch 進行訓練，匯出為 ONNX 格式，然後您就可以在其他最佳化環境中執行相同的模型。

在內部，ONNX 模型被定義為靜態計算圖。其中每個節點代表一個數學運算（卷積、活化、歸一化等），邊代表資料張量的流動。該圖使用一組標準運算符，不同的執行引擎可以解釋這些運算符。

ONNX Runtime 是專為執行 ONNX 模型而設計的高效能推理引擎。它具有跨平台性，高度最佳化，允許您插入不同的執行提供程序，以利用 CPU、GPU、NPU、FPGA 或其他硬體加速器，而無需更改推理程式碼。

在實踐中， ONNX 執行時間可作為相容性和加速層。它接收一個 .onnx 文件，並使用最佳可用硬體執行該文件，應用諸如算子融合、高效內存調度和對量化模型的支援等優化措施。

在本地使用 ONNX Runtime 的優勢

ONNX Runtime 的一個優點是： 它允許您完全在本地運行人工智慧模型。無需依賴雲端服務。這非常適合對隱私、延遲或成本要求極高的場景。

第一個顯而易見的優點是： 隱私保護：您的資料絕對不會離開您的裝置。如果您需要處理醫學影像、內部文件或敏感對話，能夠在裝置上運行模型可以避免將資訊傳送給第三方，從而簡化監管合規性並降低風險。

經濟方面也值得關注，因為 在雲端服務中，推理功能無需付費。 不必擔心使用限制。模型和 ONNX Runtime 安裝完成後，您就可以在自己的硬體上進行所有想要的預測。

就使用者體驗而言， 低延遲至關重要。由於該模型不依賴網絡，因此其回應幾乎是瞬時的，這對於互動式應用程式、遊戲、編輯工具或即時控制系統來說至關重要。

最後，還有控制因素： 您可自行決定如何對模型進行版本控制、更新或替換。無需依賴外部 API。您可以將 ONNX Runtime 與現有的 C#、C++ 和其他系統整合。 蟒蛇 或其他語言，並實現整個模型部署週期的自動化。

ONNX模型及其與訓練框架的關係

ONNX格式的AI模型是 網路結構、訓練權重以及對輸入和輸出的清晰定義相結合該結構描述了層和操作，權重包含了訓練過程中學到的知識，輸入/輸出規格指示了模型支援哪些資料格式。

通常， 您可以使用 PyTorch、TensorFlow 或 Keras 等框架來訓練模型。 使用它們的原生格式（.pt、.pb、.h5 等）。一旦您對效能滿意，您就可以使用各個框架的官方工具或輔助函式庫將該模型匯出為 .onnx 格式。

關於互通性方面， ONNX 讓您在更改環境時無需重寫或重新訓練模型。例如，您可以使用 PyTorch 訓練視覺模型，然後藉助 ONNX Runtime for Mobile 在行動應用程式中使用它，或將其整合到 C++ 後端，而無需載入整個 Python 堆疊。

此外，ONNX 標準 它支援量化算子和不同的算子集（算子集）。這樣一來，就可以更輕鬆地將相同型號適應不同的精度等級（例如，從 float32 到 int8）以及隨著新硬體功能的出現而不斷改進。

ONNX 執行時間及其執行提供者的工作原理

ONNX運作時的核心是 一個優化的推理引擎，用於解釋 ONNX 圖 並決定如何以最高效的方式執行每項操作。為此，它依賴所謂的執行提供程序，這些程序是針對不同類型硬體的專用模組。

最常用的服務提供者之一是 Windows 上的 DirectML這樣您就可以利用GPU和NPU的效能。 透過統一的 API，使用 DirectML 提供程序，您的應用程式無需更改程式碼即可在各種顯示卡和整合加速器上運行相同的 ONNX 模型。

ONNX 運作時也與 專用加速器，例如 Xilinx U250 FPGA透過諸如 Vitis AI 之類的庫。在這種情況下，微軟和賽靈思合作，使 ONNX Runtime 能夠在這些 FPGA 上運行模型，從而充分利用其並行化能力。

另一個關鍵要素是與…的整合 Windows ML 和 Windows 執行提供者目錄AI Dev Gallery 等應用程式使用此目錄來確保已認證的供應商已註冊並準備就緒，從而自動選擇設備上可用的 CPU、GPU 或 NPU 的最佳組合。

最後，ONNX Runtime 也被用作後端。 關鍵生產環境，例如 Bing 語義精確圖像搜索在需要極高性能和穩定性的場景下，其優化圖和記憶體管理的能力對於每天處理數百萬次推理至關重要。

用 C# 建立一個使用 ONNX 執行時間的 WinUI 應用程式

ONNX Runtime 在 Windows 中的應用的一個非常典型的例子是： 使用 C# 和 WinUI 3 建立一個桌面應用程式 載入 ONNX 影像分類模型（例如 ResNet-50），執行 GPU 加速推理，並將預測結果顯示給使用者。

第一步是準備開發環境： 您需要一台已啟用開發者模式的Windows裝置。 並且已安裝 Visual Studio 2022 或更高版本，並安裝了「.NET 桌面應用程式開發」工作負載。這樣，您就擁有了處理打包的 WinUI 專案所需的一切。

在 Visual Studio 中，您必須建立一個新的專案類型 使用 C# 建立一個“空的、打包的應用程式（桌面版 WinUI 3）”這類範例的常用名稱可能是 ONNXWinUIExample 之類的，不過你可以隨意命名，只要保持結構清晰即可。

在此基礎上，我們的想法是為該項目增添內容。 允許您使用 ONNX 執行時間、處理映像以及與 DirectX 通訊的 NuGet 依賴項這是透過解決方案中的 NuGet 套件管理器完成的，方法是搜尋套件並選擇最新的穩定版本。

NuGet 套件和介面配置

對於這個在 Windows 系統上加速進行影像分類的範例，需要安裝的基本軟體包有： Microsoft.ML.OnnxRuntime.DirectML、SixLabors.ImageSharp 與 SharpDX.DXGI它們分別涵蓋工作流程中的特定部分。

埃爾帕克特 Microsoft.ML.OnnxRuntime.DirectML 增加了透過 DirectML 將 ONNX Runtime 與 GPU 結合使用的支援。它允許您在設備的圖形硬體上高效運行 ONNX 模型，而無需處理底層管理。

書店 SixLabors.ImageSharp 提供用於在 .NET 中載入、調整大小和處理影像的高階實用程式。我們使用它來將使用者選擇的影像轉換為分類模型期望的歸一化張量（例如，RGB 中的 224×224 像素）。

就其本身而言， SharpDX.DXGI 從 C# 公開 DirectX 功能 並且允許我們在將 DirectML 設定為執行提供者時，選擇特定的圖形適配器（例如第一個可用的 GPU）與 ONNX 執行時間推理會話關聯。

安裝完軟體包後，建議… 將相應的 using 指令新增至 MainWindow.xaml.cs 檔案中 方便引用 OnnxRuntime、Tensors、SharpDX 和 ImageSharp 命名空間。這樣，主視窗中的程式碼就可以直接使用所有這些 API。

新增 ONNX 模型並建立簡單接口

下一步驟是 將 ONNX 模型包含在專案本身中常見的做法是在專案內建立一個名為「model」的資料夾，並將下載的 .onnx 檔案複製到該資料夾中，例如從 GitHub 上的官方 ONNX 模型儲存庫下載 ResNet50 v2 模型 (resnet50-v2-7.onnx)。

在 Visual Studio 解決方案資源管理器中，建議這樣做： 配置模型檔案的「複製到輸出目錄」屬性 這樣，在編譯應用程式時就會自動複製該模型。 「如果版本較新則複製」選項通常足以確保模型與執行檔同時存在。

範例的使用者介面可以非常簡單： 一個用於從磁碟中選擇照片的按鈕，一個用於顯示照片的圖像控件，以及一個用於列出預測結果的文字區塊。所有這些都可以用三列網格進行組織，使每個元素都佔據其應有的空間。

在 MainWindow.xaml 檔案中，您可以將初始模板產生的 StackPanel 替換為 一個三列的網格：第一列是按鈕，第二列是圖像，第三列是文字結果。該按鈕將觸發一個點擊事件，該事件將負責整個推理流程。

為了讓體驗更加舒適，這樣做很有幫助。 調整影像控制項以限制顯示影像的最大寬度。 （例如，300 像素），這樣就不會破壞設計，並且保持 TextBlock 頂部對齊，以便用戶無需滾動即可閱讀預測內容。

使用 DirectML 初始化 ONNX 執行時間會話

介面定義完成後，就必須準備好推理引擎。通常在主視窗類別中聲明它。 一個類型為 InferenceSession 的私有欄位和一個模型資料夾的基本路徑這樣一來，會話只需初始化一次，即可在後續推理中重複使用。

InitModel 輔助函數負責處理 建立 SharpDX 的 Factory1 實例以取得圖形適配器 （通常是第一個，索引 0），並使用該設備標識符配置 ONNX Runtime SessionOptions 對象，其中指示將 DirectML 執行提供者與該設備一起使用。

採用同樣的方法， 透過傳遞 .onnx 檔案的完整路徑和會話選項來建立 InferenceSession。為了除錯，通常也會設定日誌的嚴重程度（例如，ORT_LOGGING_LEVEL_INFO），這有助於了解出現問題時內部發生了什麼。

重要的是 InitModel 首先檢查會話是否已建立如果私有欄位 _inferenceSession 不為空，則無需重複初始化。這可以避免重複載入模型，節省時間和資源，並且僅在首次使用時產生初始成本。

有了這種結構，您的應用程式已經具備了 設定為在選定的圖形適配器上使用 DirectML 的 ONNX 執行時間引擎準備接收輸入張量，並在可用時返回硬體加速的模型輸出。

使用 ImageSharp 載入和預處理影像

推理流程通常從按鈕點擊處理程序開始。此處理程序用於 使用 FileOpenPicker 控制項允許使用者選擇映像 從檔案系統中，將副檔名限制為常見的格式，例如 .jpg、.jpeg、.png 或 .gif。

選定圖像後，您可以 立即在介面影像控制項中顯示 使用 BitmapImage 並將其來源設定為檔案流。這樣使用者就可以看到將要產生預測結果的圖像。

為了準備模型輸入，SixLabors.ImageSharp 就派上了用場，它允許 以圖像方式開啟圖像並將其調整為模型所需的尺寸通常情況下，通用分類 ResNet 類型模型的像素尺寸為 224×224 像素。

這時通常會應用 使用裁剪模式調整影像大小，使其達到適當程度。保持寬高比並在必要時進行裁剪後，資料將以與初始檢測相同的格式儲存在記憶體流中。此步驟可確保所有輸入資料的大小相同。

預處理的最後一步是歸一化： 創建了一個 DenseTensor形狀 （批次為 1，三個 RGB 通道，高度和寬度），影像逐行掃描，分別使用通常的平均值和標準差（255* 和 255*）對每個通道進行歸一化。

配置輸入並運行推理

影像張量填充完畢後，需要… 將其連結到 OrtValue，以便 ONNX 運行時可以使用它。理想情況下，應使用 OrtValue.CreateTensorValueFromMemory 從記憶體中建立此值，並使用 DenseTensor 緩衝區，從而避免額外的資料複製。

字典的構造方式如下： 關鍵在於模型輸入名稱（例如，「data」），其值為 OrtValue。 新建立的字典隨後被傳遞給推理會話，以指示哪些張量應作為圖的輸入。

在做出推斷之前，建議… 如果尚未初始化會話，請呼叫 InitModel 函數初始化會話。這樣可以確保模型位於記憶體中，並配置了適當的執行提供者（在本例中為 DirectML）。

要運行模型，您需要調用 _inferenceSession.Run 傳遞一些 RunOptions、輸入字典和輸出名稱集合。結果是一個唯讀的 OrtValues 集合，其中包含模型的輸出張量。

此程序將所有執行邏輯封裝在 ONNX 運行時中，以便： 您無需擔心內部 CPU 或 GPU 調度細節。你的程式碼仍然相對簡單：準備輸入，呼叫 Run，並收集輸出。

後製、softmax 和預測選擇

分類模型的輸出通常是 一個logits向量，即每個可能類別的未歸一化值。在本例中，logits 是透過 GetTensorDataAsSpan 從結果的第一個 OrtValue 中取得的。並將其轉換為數組，以便使用 LINQ 對其進行操作。

為了將這些logits轉換為易於理解的機率，請應用以下方法。 softmax 函數計算每個值的指數並將其歸一化，使其總和為 1。這樣，向量中的每個索引都代表了模型對圖像屬於該類別的置信度。

下一步是將這些機率與…進行交叉比對 一個標籤圖，其中包含按相同順序排列的每個類別的人類名稱。 這是用於訓練模型的資料。輸出數組的索引必須與 LabelMap 中標籤的索引完全一致。

為了清晰地向用戶呈現訊息，通常是 以置信度降序排列標籤集，保留最有可能的 10 個標籤。每個物件都由一個輔助物件表示，該物件包含標籤和相關的機率。

最後，對這份預測清單進行回顧， 在介面的 TextBlock 中建構並顯示一個文字字串。包括每個標籤及其置信度。這樣，使用者可以快速查看模型認為所選影像中最有可能出現的物體。

輔助類別：預測和標籤映射

為了以更簡潔的方式處理結果，我們創建了一個名為“ 預測，具有兩個屬性：標籤和置信度當需要將機率以及類別名稱投影到一系列類型化的結果上時，可以使用此類。

為了獲得更大的靈活性，Label 屬性可以是 object 類型，儘管在實際應用中… 它通常用作字串，內容為模型傳回的類別名稱。置信度是一個浮點數，它儲存了 softmax 計算出的機率。

另一方面， 靜態類別 LabelMap，帶有一個名為 Labels 的公共字串數組此陣列包含用於訓練模型的所有標籤，順序與訓練期間使用的順序完全一致，並且編碼在 ONNX 檔案中。

對於 ImageNet 類型的模型而言， 標籤清單非常龐大，通常包含數百上千個類別。 （例如，「丁鯛」、「金魚」、「大白鯊」等）。通常的做法是直接從 ONNX Runtime 儲存庫中的範例取得此列表，以避免索引不符。

透過結合預測和標籤映射， 後處理程式碼已大大簡化。機率值經過迭代，與其標籤關聯，並按置信度排序，最終結果清晰易讀，易於在使用者介面中顯示。

在 AI 開發圖庫中使用 LLM 實現 ONNX 運行時

除了視覺模型之外，ONNX Runtime 還 它透過 ONNX Runtime GenAI 格式支援大型語言模型 (LLM)。微軟提供了一款名為 AI Dev Gallery 的 Windows 應用程序，可在 Microsoft Store 中找到，它允許您以互動方式測試這些 ONNX LLM 模型。

該應用程序包括 文字生成、聊天、摘要、情緒分析、內容審核及其他場景範例它們都基於 GenAI 格式的 LLM。您可以載入預先轉換的模型，也可以從常用框架轉換自己的模型。

目前支援轉換為 ONNX Runtime GenAI 格式的模型包括： 深度搜尋 R1 Distill Qwen 1.5B、Phi 3.5 Mini、Qwen 2.5-1.5B 和 Llama 3.2 1B主要用於「指導」或「提示」等變體。這些模型非常適合聊天任務和本地文字生成。

AI開發者畫廊本身 它與 Visual Studio Code 的 AI Toolkit 擴充功能整合。這樣您就可以直接從模型選擇器啟動轉換工具。如果您尚未安裝該擴展，可以在 VS Code 應用程式商店中搜尋“AI Toolkit”，安裝後即可使用它將您的 LLM 檔案轉換為 GenAI 格式。

轉換或下載模型後，只需 返回 AI 開發圖庫模型選擇器，選擇自訂模型選項卡，然後從磁碟新增檔案。從那裡，您可以在互動式範例中選擇您的 LLM，並查看其在不同文字任務中的表現。

與 Microsoft.Extensions.AI 和 WinML 集成

在 AI 開發畫廊介面下方，以 GenAI 格式執行 LLM 由以下方式管理： 客戶端 OnnxRuntimeGenAIChatClient它充當 ONNX Runtime 和 Microsoft.Extensions.AI 聊天抽象之間的橋樑。

此客戶端相容以下介面： IChatClient 和 ChatMessage 等類型這使得使用該模型的程式碼能夠處理高級訊息，而無需處理張量和底層細節。因此，同一個應用程式只需進行極少的變更即可切換後端（例如，從雲端服務切換到本機 ONNX 模型）。

以下操作在 OnnxRuntimeGenAIChatClientFactory 中執行 Windows ML (WinML) 執行提供者註冊表 使用 ExecutionProviderCatalog.GetDefault 和非同步呼叫來保護和註冊經過認證的供應商，然後再建立聊天用戶端。

建立 OnnxRuntimeGenAIChatClient 時， 傳遞到 ONNX 模型的路徑和提示模板（LlmPromptTemplate）。 它定義了系統、使用者和助手角色的格式，以及指示在哪裡停止文字產生的停止序列。

一切準備就緒後，該應用程式即可運行。 接收訊息，呼叫 GetStreamingResponseAsync，並將回應逐步轉儲到介面中。利用 WinML 和 ONNX Runtime 提供的硬體加速，透過本機 ONNX 模型實現流暢的聊天體驗。

將YOLO模型匯出為ONNX格式並部署

除了微軟的例子之外，ONNX 生態系統在 Ultralytics 等第三方函式庫中也非常流行。 將 YOLO 模型轉換為 ONNX 只需幾行程式碼。這為在不同類型的設備中部署相同的物體偵測器打開了大門。

透過 Ultralytics API，您可以 載入預先訓練的 YOLO 模型（例如 yolo11n.pt），並使用 format="onnx" 選項匯出。流程將架構和權重轉換為 ONNX 標準，並產生一個可直接使用的 .onnx 檔案。

一旦您將模型轉換為 ONNX 格式，就可以進行後續操作了。 將其整合到行動應用程式、網頁應用程式或其他應用程式中 物聯網 使用 ONNX 運行時及其特定變體在行動裝置上，ONNX Runtime for Mobile 提供了一個精簡優化的版本，以減少資源消耗；而在… 邊緣和物聯網 採用針對小型記憶體設備最佳化的版本。

在工業環境中，向 ONNX 的轉換簡化了 將電腦視覺模型整合到原有的 C++ 或 C# 系統中無需嵌入 Python 解釋器。這簡化了維護工作，並降低了部署要求，尤其是在每個依賴項至關重要的系統中。

與使用原生框架格式相比，依賴 ONNX 它能減少從實驗室原型到生產解決方案的過渡過程中的摩擦。這樣可以避免代價高昂的重寫，並讓您充分利用 ONNX Runtime、TensorRT 或其他與此格式相容的引擎的最佳化。

ONNX 運作時被放置在 對於那些希望在本地運行 AI 模型、利用硬體加速以及在不同框架和平台之間保持靈活性的用戶來說，這是一個關鍵組件。無論是在桌面應用、行動應用、雲端或邊緣設備上。