語言
Important
Windows 的 ML 執行時與文字生成 API 目前仍處於實驗階段,尚未支援於生產環境中使用。 嘗試這些 API 的應用程式不應該發佈至 Microsoft 市集。
Important
Windows 的機器學習執行時與文字生成 API 目前以 C++ 和 Python 提供;C# 目前不支援。如果你有興趣使用 C# 中的這些 API,歡迎在 Windows ML GitHub 倉庫發表問題告訴我們!
Windows ML 文字生成 API 簡化了在您自己的語言模型上執行文字生成。 它能在 Windows ML 執行階段 API 之上,幫你處理標記化、自我回歸解碼、串流輸出和取消——類似於 ONNX Runtime GenAI 在 ONNX Runtime 之上簡化這個迴圈的方式。 Windows 並未隨附這個 API 的模型;你可以選擇、打包並分發這個模型——一個 ONNX 或 GGUF 檔案,加上一個分詞器——隨您的應用程式一同封裝並散發。
Tip
如果你不需要特定模型,只想用 Microsoft 管理的模型在裝置上產生文字,那就改用現成的本地 LLM 吧。
你仍然建立底層的執行時物件——模型、執行目標和管線——並將它們傳交給會話。 API 不會隱藏硬體配置;它只是省去了自己寫代幣迴圈的需求。
支援的模型
文字生成 API 接受:
-
ONNX (
.onnx)或 ORT 格式 (.ort)模型,透過 ONNX Runtime 執行。 模型必須提供一個權杖 ID 輸入、一個 logits 輸出,以及一對固定容量狀態張量對,該張量對保存鍵值快取與序列位置。 你提供一個獨立的分詞器來源(例如,一個tokenizer.json)。 -
GGUF(
.gguf)模型,透過 llama.cpp 後端執行。 分詞器嵌入模型中,因此不需要獨立的分詞器來源。
這些範例針對 Qwen2.5-0.5B-Instruct 模型家族驗證此契約,並使用任務專屬圖匯出,將鍵/值快取與序列位置打包成單一狀態對。 其他僅依賴解碼器的語言模型,若能暴露相同的標記輸入、logit 輸出與狀態合約,也應該可行。
產生文字
文字生成工作階段封裝分詞器與有狀態的管線(擁有鍵值快取的模型)。 載入模型與分詞器,描述模型的標記輸入、logits 輸出與狀態合約,並建立會話:
// Create the runtime and an execution target (CPU here; GPU/NPU also available).
ComPtr<IWinMLRuntime> runtime;
THROW_IF_FAILED(WinMLCreateRuntime(IID_PPV_ARGS(runtime.GetAddressOf())));
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateCpuExecutionTarget(target.GetAddressOf()));
// Load your ONNX model and its tokenizer.
ComPtr<IWinMLModel> model;
THROW_IF_FAILED(runtime->LoadModelFromFile(
L"C:\\models\\qwen2.5-0.5b-instruct\\task_model.onnx",
nullptr,
model.GetAddressOf()));
ComPtr<IWinMLTokenizer> tokenizer;
THROW_IF_FAILED(WinMLCreateTokenizerFromFile(
L"C:\\models\\qwen2.5-0.5b-instruct\\tokenizer.json",
tokenizer.GetAddressOf()));
// Describe the model's token input, logits output, and KV-cache state pair.
winml::tasks::text_generation::onnx::StateTensorPair stateTensorPairs[] = {{1, 1}};
winml::tasks::text_generation::Options options;
options.values = winml::tasks::MakeTextGenerationOptions(/* maxNewTokens */ 64);
winml::tasks::text_generation::onnx::BuildTextGenerationArguments arguments;
arguments.runtime = runtime.Get();
arguments.model = model.Get();
arguments.target = target.Get();
arguments.tokenizer = tokenizer.Get();
arguments.tokenInputName = L"input_ids";
arguments.outputName = L"logits";
arguments.debugName = L"my-text-generation";
arguments.stateTensorPairs = stateTensorPairs;
arguments.sequenceCapacityHint = 128;
arguments.outputKind = WINML_TEXT_GENERATION_OUTPUT_KIND_LOGITS;
arguments.eosPolicy = WINML_TEXT_GENERATION_EOS_POLICY_TOKENIZER_DEFAULT;
arguments.options = &options;
winml::tasks::text_generation::TextGeneration textGeneration;
THROW_IF_FAILED(winml::tasks::text_generation::onnx::BuildTextGeneration(
arguments, textGeneration));
使用提示詞呼叫 GenerateText 以開始串流操作,然後從回傳的串流中拉取片段,直到串流回報完成:
ComPtr<IWinMLCancellationSource> cancellation;
THROW_IF_FAILED(textGeneration.tasks->CreateCancellationSource(
cancellation.GetAddressOf()));
ComPtr<IWinMLTextGenerationPullStream> stream;
THROW_IF_FAILED(textGeneration.session->GenerateText(
L"The sky is often",
textGeneration.options.Get(),
cancellation.Get(),
stream.GetAddressOf()));
// Pull generated text one fragment at a time until the stream completes.
WINML_TEXT_GENERATION_READ_STATUS status{};
UINT32 tokenId = 0;
LPCWSTR fragment = nullptr;
while (SUCCEEDED(stream->ReadNext(&status, &tokenId, &fragment)) &&
status == WINML_TEXT_GENERATION_READ_STATUS_UPDATE)
{
std::wprintf(L"%ls", fragment);
}
// The terminal result is the authoritative text, token counts, and finish reason.
ComPtr<IWinMLTextGenerationResult> result;
THROW_IF_FAILED(stream->GetResult(result.GetAddressOf()));
完成的結果報告如下:
- 完整產生的文字與令牌 ID
- 提示和產生的權杖數量
- 結束理由——序列結束標記、停止標記、請求的標記限制、序列容量上限、取消或錯誤
C++ 與 Python
原生 API 是透過 winml/tasks/text_generation/TextGeneration.hpp 公開,而型別化的 C++ 輔助工具則位於 WinMLTasks.h 之下。 Python 應用程式會將windowsml.tasks投影與 windowsml.runtime一起使用。
Windows ML 範例包含 C++ 與 Python 文字生成範例。 範例展示了完整的執行時設定,並附帶文字生成設定,讓你了解抽象的起點,以及如何自訂底層工作流程。
也請參閱
- Windows 上現成可用的本地大型語言模型(Phi Silica 及其他 Microsoft 管理模型)
- Windows ML 執行時 API 概述
- Windows ML 執行時 API 概念
- 用 Windows ML 用你自己的 Whisper 模型辨識語音
- Windows ML 範例
- ONNX 執行環境生成人工智慧