Important
Windows ML 執行時 API 目前仍處於實驗階段,尚未支援用於生產環境。 嘗試此 API 的應用程式不應被發佈到 Microsoft Store。
Windows ML 執行時 API 是專為 Windows 打造的原生本地 AI 推論框架。 使用 Windows ML Runtime API 時,你可以明確控制模型載入、硬體指派、張量擁有權、管線組合、編譯與診斷。
我們建議使用 Runtime API,以獲得 Windows 上最佳的模型推論效能,但如果您的應用程式需要在其他平台執行,或已擁有跨平台的 ONNX Runtime 程式碼,也可以透過 Windows ML 使用 ONNX Runtime。
物件如何組合
IWinMLRuntime
|-- loads --> IWinMLModel
|-- creates -> IWinMLExecutionTarget
`-- creates -> IWinMLPipelineBuilder
|-- adds/connects -> IWinMLStage
`-- Build() ------> IWinMLPipeline
IWinMLExecutionTarget -- creates --> IWinMLTensor
IWinMLStage ----------- binds -----> IWinMLTensor
IWinMLPipeline -------- Run() -----> stage outputs
每個方法回傳 HRESULT,且每個介面指標都遵循一般的 COM 參考計數。 可選能力可透過 QueryInterface 探測;若某項能力不可用,則會返回 E_NOINTERFACE。
Runtime
使用 IWinMLRuntime 建立 WinMLCreateRuntime。 用它載入模型成品、建立執行目標,以及建立管線產生器。
模型與綱要
IWinMLModel 是一個不可變且不透明的模型構件。
LoadModelFromFile 接受任何你應用程式能讀取的絕對或相對檔案路徑;模型位置是你應用程式的包裝決定。
載入時會驗證該成品是否可被識別,且在結構上可讀取。
目標相容性會在稍後於管線建構器的 Build 方法成功時才確認。
透過 IWinMLModelSchema 反映模型宣告的序數結構。 部分 ONNX 工件也會透過可選的 IWinMLOrtModelSchema 公開名稱,但執行身份仍維持位置性。
形狀與運算子
宣告的模型結構可以包含自由維度,表示為 UINT64_MAX。 具體 IWinMLTensor 的尺寸總是已確定。
ORT 支援的管線可以為自由維度綁定具體值並執行。
固定或明確有界的形狀仍是最佳化設計的核心,因為它們能讓 Build 驗證相容性、分配穩定資源,並判斷重播或裝置駐留迭代是否合法。 它們同時提供最廣泛的執行後端相容性。 這是優化與可攜性的區分,並非一刀切拒絕宣告 ONNX 結構包含自由維度的模型。
標準 ONNX 運算元同樣提升後端可攜性。 成功的模型載入並不保證每個目標都能執行所有運算子; Build 是相容性檢查。
Backends
模型檔案決定使用的後端。 你的應用程式無論如何都使用相同的執行時物件:模型、執行目標、管線建構器、階段、綁定,以及 Run。
| 模型檔案 | Backend | 硬體加速 |
|---|---|---|
.onnx、.ort |
ONNX 執行環境 | Windows 安裝並透過 Windows ML EP 目錄保持更新的執行提供者(EP) |
.gguf |
llama.cpp | llama.cpp隨應用程式部署的模組:套件內的 CPU 模組,以及 NVIDIA GPU 可選的 CUDA 模組。 CPU 和 CUDA 是 Windows ML 在此版本中唯一驗證的 llama.cpp 後端。 |
後端在階段能表達的內容上有所不同:
| 能力 | ONNX 執行環境 | llama.cpp |
|---|---|---|
| 舞台形狀 | 任何 ONNX 圖;多個階段可以在一條管線中連接 | 每個 GGUF 檔案只有一個解碼階段:令牌 ID 輸入(輸入 0),logit 輸出(輸出 0) |
| 序列狀態(KV 快取) | 使用 IWinMLStatefulStageOptions 宣告狀態張量配對;執行時負責管理它們 |
由後端擁有;無需宣告 |
| 上下文長度 |
SetSequenceCapacityHint 在 Build之前,或模型的聲明容量 |
SetSequenceCapacityHint 在 Build 之前設定 llama.cpp 上下文長度 |
| 提供者固定與 ORT 階段選項 | 支援 (WinMLRuntimeOrt.h) |
不支援; Build 傳回 HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) |
Build 之後的就業報告 |
IWinMLOrtStageDiagnostics 列出請求及選定的提供者 |
IWinMLStage::GetExecutionTarget 回報 CPU 或 GPU |
一條管道可以混用不同後端。 例如,ONNX 執行時的 Whisper 階段可以餵食 llama.cpp 上的 GGUF 語言模型。
執行目標
IWinMLExecutionTarget 是一個不可變的配置權杖,要求硬體類別,並可選擇特定介面卡。 每個後端都會在 Build 執行時解決它:
| Stage 目標 | ONNX 執行環境 | llama.cpp |
|---|---|---|
nullptr 傳給 AddModelStage |
自動放置會選擇相容的 GPU EP(若有),若無則回退至 CPU。 | 當已部署 CUDA 模組且模型適合時,會交由 CUDA 模組執行;否則會直接在 CPU 上運作。 |
CreateCpuExecutionTarget |
選擇相容的 CPU EP,基準為 ORT 的 CPU 提供者。 | 在 CPU 上執行。 |
CreateExecutionTarget 使用 GPU 類型 CreateExecutionTargetFromAdapter、或 CreateExecutionTargetFromD3D12 |
將轉接器識別碼映射到相容的 GPU EP 裝置。 如果沒有符合的供應商裝置,Build 就會失敗。 |
至少需要將部分工作轉移至 CUDA 模組。
Build在未部署 CUDA 模組時會回傳HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY),而在模型不適用時會回傳HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。 模組選擇 GPU;不會使用轉接器識別碼。 |
CreateExecutionTarget 搭配 NPU 類型或 NPU 轉接器 |
映射到相容的 NPU EP 裝置。 | 不支援; Build 返回 HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。 |
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget) |
釘選一個已註冊的 EP。 當 hardwareTarget 設為 nullptr時,執行時會將提供者與其自身的裝置配對;在擁有兩顆 GPU 的電腦上,這避免了提供者與提供者不支援的介面卡配對。 |
不支援; Build 返回 HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。 |
IWinMLRuntime::CreateExecutionTarget(kind, preference) 選擇所要求類別的轉接器,無需你自己列舉裝置,並且在有多個轉接器時由 preference 進行排序,例如一組整合式和一組獨立顯示卡:
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateExecutionTarget(
WINML_EXECUTION_TARGET_KIND_GPU,
WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
target.GetAddressOf()));
明確選擇適配器需要相容的 ONNX 執行階段提供者透過 ORT 揭露該硬體識別資訊。 如果沒有提供者裝置相符,則 Build 會失敗,而不是默默選擇其他轉接器或 CPU。
CreateExecutionTargetFromD3D12 保留呼叫者的裝置及目標上的可選佇列,但 ORT 執行僅使用配接器識別來選擇 EP。 ORT 提供者擁有其執行資源,呼叫者的指令佇列不用於 ORT 提交。
D3D12 目標仍會公開 IWinMLD3D12ExecutionTarget 到 QueryInterface。 跨階段重複使用同一明確目標表達同一適配器親和性;不同的目標會明確界定轉移邊界。
執行一個GGUF模型
- 使用
LoadModelFromFile載入檔案。.gguf擴充功能選取的是 llama.cpp。 對於分片模型,把所有分片放在同一個資料夾,然後載入第一個分片。 - 加一個模型階段,搭配 CPU、GPU 或
nullptr目標。 要設定上下文長度,從 stage 查詢IWinMLStatefulStageOptions並呼叫SetSequenceCapacityHint。 - 撥打
Build。 接著將提示的 token ID 綁定為輸入 0,請求輸出為 0,並呼叫Run。 每次後續執行會取用下一個詞元;後端則在執行間保留 KV 快取。 - 請在獨立序列之前呼叫
ResetExecutionState。
// Create the runtime and an execution target (CPU here; GPU also available).
ComPtr<IWinMLRuntime> runtime;
THROW_IF_FAILED(WinMLCreateRuntime(IID_PPV_ARGS(runtime.GetAddressOf())));
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateCpuExecutionTarget(target.GetAddressOf()));
ComPtr<IWinMLModel> model;
THROW_IF_FAILED(runtime->LoadModelFromFile(
L"C:\\models\\qwen2.5-0.5b-instruct.gguf", nullptr, model.GetAddressOf()));
ComPtr<IWinMLPipelineBuilder> builder;
THROW_IF_FAILED(runtime->CreatePipelineBuilder(builder.GetAddressOf()));
ComPtr<IWinMLStage> stage;
THROW_IF_FAILED(builder->AddModelStage(
model.Get(), target.Get(), L"decoder", stage.GetAddressOf()));
THROW_IF_FAILED(stage->RequestOutput(0));
// Set the llama.cpp context length before Build.
ComPtr<IWinMLStatefulStageOptions> stateOptions;
THROW_IF_FAILED(stage->QueryInterface(IID_PPV_ARGS(stateOptions.GetAddressOf())));
THROW_IF_FAILED(stateOptions->SetSequenceCapacityHint(4096));
ComPtr<IWinMLPipeline> pipeline;
THROW_IF_FAILED(builder->Build(pipeline.GetAddressOf()));
// Bind token IDs to input 0 and run one token at a time; the backend keeps
// the KV cache between runs.
THROW_IF_FAILED(stage->BindInput(0, tokenIdsTensor.Get()));
THROW_IF_FAILED(pipeline->Run());
ComPtr<IWinMLTensor> logits;
THROW_IF_FAILED(stage->GetOutput(0, logits.GetAddressOf()));
// Start an independent sequence on the same pipeline.
THROW_IF_FAILED(pipeline->ResetExecutionState());
分詞器和對話格式來自 GGUF 檔案,因此 GGUF 模型不需要獨立的分詞器檔案。 要跳過令牌迴圈,請使用 Text Generation API,該 API 適用於 GGUF 和 ONNX 模型。
部署 llama.cpp 後端
llama.cpp 後端是應用程式層級本機。 當專案選擇啟用時,Windows ML NuGet 套件會將執行階段的 llama.cpp 介面卡、llama.cpp 核心和 CPU 模組複製到應用程式所在目錄旁。 GPU 加速需要可選的 CUDA 模組,該模組是以與套件相同的 llama.cpp 修訂版本建置,並放在你的應用程式旁邊。
欲了解這兩個步驟,請參閱 GGUF 模型範例 與 llama.cpp樣本。
管道與階段
用單次 IWinMLPipelineBuilder 建立一條流程:
- 新增模型或處理器階段及其執行目標。
- 以序數索引連接階段連接埠。
- 呼叫一次
Build即可凍結圖表、解決放置並驗證相容性。
對於兩個模型階段,新增這兩個階段,將第一階段的輸出序數與第二階段的輸入序數連接,然後建構一次。 你的應用程式會提供模型並綁定任何外部輸入。 它不需要模型專屬的執行階段 API:嵌入、解碼器、影像預處理及其他應用程式架構都使用相同的階段與張量原語。
每個節點 IWinMLStage 擁有位置引數輸入繫結,並暴露其當前輸出張量。 輸入綁定會在多次執行之間仍會保留。 當你的應用程式提供輸出儲存空間時,請在執行前呼叫 BindOutput 方法。
可選階段功能包括已解析目標、實體化綱要、輸出資料駐留政策及序列狀態控制。 用 QueryInterface 來測試每個能力。
執行管道
IWinMLPipeline::Run 同步執行已準備的管線。 在獨立序列之間呼叫 ResetExecutionState,以清除執行時管理的狀態。
當建構的圖形與選擇後端支援時,可選擇性執行介面提供裝置時間軸提交及固定次數的迭代重播。 基本 Run 路徑仍是共同的基準。
Tensor 與鎖
IWinMLTensor 代表具型別的多維資料。 從執行目標查詢的工廠建立張量,讓張量的擺放跟著目標擺放。
工廠涵蓋原始位元組、影像資料、音訊資料、權杖 ID 以及可組合的張量處理器。 可選的張量介面可揭露可變更性、D3D12 緩衝區綁定及同步。
在存取 CPU 張量位元組前先呼叫 IWinMLTensor::Lock 。 返回 IWinMLTensorDataLock 的指標會建立 CPU 存取視窗、執行必要的映射或同步,並擁有 GetData 傳回之指標的生命週期。
編譯與外部權重
提前編譯是執行目標的一項可選功能,透過 IWinMLModelCompiler 公開。 編譯後的產物會透過一般的模型載入方法重新載入。 應用程式可以透過 IWinMLResourceMapReader 提供外部化權重。
文本工作負載
文字工作負載使用相同的執行時、目標、管線、階段及張量原語。 您的應用程式可以直接擁有模型套件的元資料、取樣、停止策略及產生的令牌累積,或使用 文本生成 API 透過相容的執行時管線協調這些操作。
IWinMLTokenizer 提供低階的編碼與解碼操作。 一個 IWinMLTokenizerDecoder 為一個序列維護獨立的增量解碼游標。 文字生成 API 新增文字生成會話、選項、串流更新、取消、完成原因及完成結果,且不改變底層執行時物件的所有權。
ONNX Runtime 相容性
WinMLRuntimeOrt.h 中的可選介面提供 ONNX 便利性:
-
IWinMLOrtCompatibility選擇已註冊的 ONNX 執行提供者。 -
IWinMLOrtModelSchema反映輸入與輸出名稱。 -
IWinMLOrtNamedBindings以名稱綁定一個由 ORT 支援的 stage。 -
IWinMLOrtStageDiagnostics在Build之後要求報告並選取提供者。
這些介面在設定時會解析名稱和提供者政策。 執行仍使用相同的位置式管線契約。
從執行時查詢 IWinMLOrtCompatibility,將 ONNX 模型階段固定至你已註冊的執行提供者,而不是讓 Build 自動選擇:
ComPtr<IWinMLOrtCompatibility> ortCompatibility;
THROW_IF_FAILED(runtime->QueryInterface(IID_PPV_ARGS(ortCompatibility.GetAddressOf())));
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(ortCompatibility->CreateExecutionTarget(
L"MyRegisteredProvider",
WINML_EXECUTION_TARGET_KIND_GPU,
/* hardwareTarget */ nullptr,
target.GetAddressOf()));
為 hardwareTarget 傳遞 nullptr 可讓執行階段將提供者與該硬體類別中其自身的裝置之一配對;改為傳遞現有的 IWinMLExecutionTarget,則會將提供者固定到該特定介面卡。
此目標不支援 .gguf 階段; Build 返回 HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。