語言

用 Windows ML 用你自己的語言模型產生文字

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 文字生成範例。 範例展示了完整的執行時設定,並附帶文字生成設定,讓你了解抽象的起點,以及如何自訂底層工作流程。

也請參閱