Conceptos de la API de Windows ML Runtime

Importante

La API de tiempo de ejecución de ML de Windows es actualmente experimental y no se admite para su uso en entornos de producción. Las aplicaciones que estén probando esta API no deben publicarse en el Microsoft Store.

La API de tiempo de ejecución de ML de Windows es un marco de inferencia de IA local nativo creado específicamente para Windows. Con la API de tiempo de ejecución de ML de Windows, tiene control explícito sobre la carga del modelo, la selección de ubicación de hardware, la propiedad del tensor, la composición de canalización, la compilación y los diagnósticos.

Se recomienda usar la Runtime API para obtener el mejor rendimiento de inferencia de modelos en Windows, pero si la aplicación necesita ejecutarse en otras plataformas, o si ya tiene código funcional de ONNX Runtime multiplataforma, también puede usar ONNX Runtime a través de Windows ML.

Cómo encajan los objetos

IWinMLRuntime
  |-- loads --> IWinMLModel
  |-- creates -> IWinMLExecutionTarget
  `-- creates -> IWinMLPipelineBuilder
                   |-- adds/connects -> IWinMLStage
                   `-- Build() ------> IWinMLPipeline

IWinMLExecutionTarget -- creates --> IWinMLTensor
IWinMLStage ----------- binds -----> IWinMLTensor
IWinMLPipeline -------- Run() -----> stage outputs

Cada método devuelve HRESULTy cada puntero de interfaz sigue el recuento normal de referencias COM. Las funcionalidades opcionales se detectan con QueryInterface; una funcionalidad no disponible devuelve E_NOINTERFACE.

Runtime

Cree IWinMLRuntime con WinMLCreateRuntime. Úsalo para cargar artefactos de modelos, crear destinos de ejecución y crear generadores de pipelines.

Modelos y esquemas

IWinMLModel es un artefacto de modelo inmutable y opaco. LoadModelFromFile acepta cualquier ruta de acceso de archivo absoluta o relativa que la aplicación pueda leer; la ubicación del modelo es la decisión de empaquetado de la aplicación.

Al cargar se comprueba que el artefacto se reconoce y se puede leer estructuralmente. La compatibilidad de destino queda establecida más adelante, cuando el método Build del generador de canalizaciones se ejecuta correctamente.

Refleje el esquema ordinal declarado de un modelo mediante IWinMLModelSchema. Algunos artefactos de ONNX también exponen nombres a través del elemento opcional IWinMLOrtModelSchema, pero la identidad de ejecución sigue siendo posicional.

Formas y operadores

Un esquema de modelo declarado puede contener dimensiones libres, representadas por UINT64_MAX. Una IWinMLTensor concreta siempre tiene dimensiones resueltas. Las canalizaciones respaldadas por ORT pueden enlazar y ejecutar valores concretos para una dimensión libre.

Las formas fijas o delimitadas explícitamente siguen siendo el centro del diseño optimizado, ya que permiten a Build validar la compatibilidad, asignar recursos estables y determinar si la repetición o la iteración residente en el dispositivo son válidas. Además, proporcionan la mayor compatibilidad entre los distintos backends de ejecución. Se trata de una distinción de optimización y portabilidad, no un rechazo general de los modelos cuyo esquema ONNX declarado contiene dimensiones libres.

Los operadores ONNX estándar también mejoran la portabilidad de back-end. Una carga correcta del modelo no garantiza que cada destino pueda ejecutar cada operador; Build es la comprobación de compatibilidad.

Backends

El archivo de modelo selecciona el back-end. La aplicación usa los mismos objetos runtime de cualquier manera: modelo, destino de ejecución, generador de canalizaciones, fases, enlaces y Run.

Archivo de modelo Backend Aceleración de hardware
.onnx, .ort ONNX Runtime Proveedores de ejecución (EPs) que Windows instala y mantiene actualizados a través del catálogo de WINDOWS ML EP
.gguf llama.cpp módulos de llama.cpp implementados con la aplicación: un módulo de CPU en el paquete y un módulo CUDA opcional para GPU NVIDIA. CPU y CUDA son los únicos backends de llama.cpp que Windows ML valida para esta versión.

Los back-end difieren en lo que una etapa puede expresar:

Capacidad ONNX Runtime llama.cpp
Forma del escenario Cualquier gráfico ONNX; varias fases se pueden conectar en una canalización Una etapa de decodificación por archivo GGUF: ID de tokens en (entrada 0), logits en salida (salida 0)
Estado de la secuencia (KV cache) Declarar pares de tensor de estado con IWinMLStatefulStageOptions; el runtime los administra. Gestionado por el backend; nada que declarar
Longitud del contexto SetSequenceCapacityHint antes de Build, o la capacidad declarada del modelo SetSequenceCapacityHint antes de Build establece la longitud del contexto de llama.cpp
Fijación de proveedores y opciones de la etapa ORT Compatible (WinMLRuntimeOrt.h) No compatible; Build devuelve HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
Informe de colocación tras Build IWinMLOrtStageDiagnostics nombra los proveedores solicitados y seleccionados IWinMLStage::GetExecutionTarget indica si se utiliza CPU o GPU

Una canalización puede mezclar backends. Por ejemplo, una fase de Whisper en ONNX Runtime puede alimentar un modelo de lenguaje GGUF en llama.cpp.

Destinos de ejecución

IWinMLExecutionTarget es un token de colocación inmutable que solicita una clase de hardware y, opcionalmente, un adaptador específico. Cada back-end lo resuelve cuando Build se ejecuta:

Destino de la etapa ONNX Runtime llama.cpp
nullptr se pasó a AddModelStage La colocación automática selecciona un EP de GPU compatible cuando está disponible, con la CPU como alternativa. Se descarga al módulo CUDA cuando hay uno implementado y el modelo se adapta; de lo contrario, se ejecuta en la CPU.
CreateCpuExecutionTarget Selecciona un EP de CPU compatible, con el proveedor de CPU de ORT como línea base. Se ejecuta en la CPU.
CreateExecutionTarget con el tipo de GPU, CreateExecutionTargetFromAdapter, o CreateExecutionTargetFromD3D12 Asigna la identidad del adaptador a un dispositivo GPU EP compatible. Si no coincide ningún dispositivo del proveedor, Build falla. Requiere al menos la delegación parcial al módulo CUDA. Build devuelve HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) cuando no está desplegado ningún módulo CUDA y HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) cuando el modelo no se ajusta. El módulo elige la GPU; no se usa la identidad del adaptador.
CreateExecutionTarget con el tipo NPU o un adaptador NPU Se asigna a un dispositivo EP de NPU compatible. No compatible; Build devuelve HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget) Asigna un EP registrado. Con hardwareTarget establecido en nullptr, el Integration Runtime empareja el proveedor con uno de sus propios dispositivos; en un PC con dos GPU, esto evita emparejar el proveedor con un adaptador que no admite. No compatible; Build devuelve HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

IWinMLRuntime::CreateExecutionTarget(kind, preference) elige un adaptador de la clase solicitada sin necesidad de enumerar los dispositivos usted mismo y preference clasifica los adaptadores cuando hay más de uno, por ejemplo, una GPU integrada y discreta:

ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_GPU,
    WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
    target.GetAddressOf()));

La selección explícita del adaptador requiere un proveedor en tiempo de ejecución de ONNX compatible para exponer esa identidad de hardware a través de ORT. Si ningún dispositivo proveedor coincide, Build falla en lugar de seleccionar silenciosamente otro adaptador o la CPU.

CreateExecutionTargetFromD3D12 conserva el dispositivo del llamante y la cola opcional en el destino, pero la ejecución de ORT solo usa la identidad del adaptador para la selección de EP. El proveedor ORT posee sus recursos de ejecución y la cola de comandos de quien llama no se usa para el envío de ORT.

Un destino D3D12 sigue exponiendo IWinMLD3D12ExecutionTarget a QueryInterface. La reutilización de un destino explícito en todas las etapas expresa la afinidad con el mismo adaptador; los destinos distintos hacen explícitos los límites de transferencia.

Ejecutar un modelo GGUF

  1. Cargue el archivo con LoadModelFromFile. La .gguf extensión selecciona llama.cpp. Para un modelo particionado, mantenga todas las particiones en una carpeta y cargue la primera partición.
  2. Añade una etapa de modelo con un destino CPU, GPU o nullptr. Para establecer la longitud del contexto, consulte IWinMLStatefulStageOptions desde el stage y llame a SetSequenceCapacityHint.
  3. Llame a Build. A continuación, enlace los identificadores de token del prompt a la entrada 0, solicite la salida 0 y llame a Run. Cada ejecución posterior toma el siguiente token; el back-end mantiene la caché de KV entre ejecuciones.
  4. Llama a ResetExecutionState antes de una secuencia independiente.
// 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());

El tokenizador y el formato de conversación proceden del archivo GGUF, por lo que un modelo GGUF no necesita archivos de tokenizador independientes. Para omitir el bucle de token, use Text Generation API, que funciona con modelos GGUF y ONNX.

Despliega el backend de llama.cpp

El back-end de llama.cpp es local de la aplicación. Cuando un proyecto se inscribe, el paquete NuGet de Windows ML copia el adaptador llama.cpp del tiempo de ejecución, el núcleo llama.cpp y el módulo de CPU junto a tu aplicación. La aceleración de GPU necesita el módulo CUDA opcional, creado para la misma revisión llama.cpp que el paquete y colocado junto a la aplicación.

Para ver un tutorial de ambos pasos, consulte los ejemplos de modelos de GGUF y los ejemplos de llama.cpp.

Canalizaciones y etapas

Crea una canalización con el comando de un solo paso IWinMLPipelineBuilder:

  1. Agregue etapas del modelo o del procesador con sus destinos de ejecución.
  2. Conecta los puertos de las etapas por índice ordinal.
  3. Llama a Build una vez para congelar el grafo, resolver la ubicación y validar la compatibilidad.

Para dos fases del modelo, agregue ambas fases, conecte el ordinal de salida de la primera fase al ordinal de entrada de la segunda fase y compile una vez. La aplicación proporciona los modelos y enlaza cualquier entrada externa. No necesita una API en tiempo de ejecución específica del modelo: embedding, decodificador, preprocesamiento de imágenes y otras arquitecturas de aplicación usan la misma etapa y primitivas de tensores.

Cada uno IWinMLStage posee asociaciones de entrada posicionales y expone sus tensores de salida actuales. Las asignaciones de entrada persisten entre ejecuciones. Llama a BindOutput antes de una ejecución cuando tu aplicación proporcione almacenamiento de salida.

Entre las funcionalidades de fase opcional se incluyen el destino resuelto, el esquema materializado, la directiva de residencia de salida y el control de estado de secuencia. Se usa QueryInterface para probar cada funcionalidad.

Ejecución de canalización

IWinMLPipeline::Run ejecuta el pipeline preparado de forma sincrónica. Llame a ResetExecutionState entre secuencias independientes para borrar el estado administrado en tiempo de ejecución.

Las interfaces de ejecución opcionales proporcionan envío a la línea temporal del dispositivo y reproducción iterativa de recuento fijo cuando el grafo construido y el back-end seleccionado los admiten. La ruta de acceso básica Run sigue siendo la línea base común.

Tensores y bloqueos

IWinMLTensor representa datos tipados y multidimensionales. Crea tensores a partir de una fábrica consultada desde el destino de ejecución, de modo que la ubicación de los tensores siga la ubicación del destino.

Las fábricas abarcan bytes sin procesar, datos de imagen, datos de audio, ID de tokens y procesadores de tensores componibles. Las interfaces de tensor opcionales exponen la mutación, los enlaces de búfer D3D12 y la sincronización.

Llame a IWinMLTensor::Lock antes de acceder a bytes de tensor en la CPU. El valor devuelto por IWinMLTensorDataLock establece la ventana de acceso a la CPU, realiza la asignación o sincronización necesarias y controla el tiempo de vida del puntero devuelto por GetData.

Compilación y ponderaciones externas

La compilación AOT es una funcionalidad opcional de un destino de ejecución, expuesta a través de IWinMLModelCompiler. Los artefactos compilados se vuelven a cargar a través de los métodos normales de carga de modelos. Las aplicaciones pueden proporcionar ponderaciones externalizadas a través de IWinMLResourceMapReader.

Cargas de trabajo de texto

Las cargas de trabajo de texto usan el mismo entorno de ejecución, destino, canalización, fase y primitivos de tensor. La aplicación puede poseer directamente metadatos del paquete de modelos, muestreo, política de parada y acumulación de tokens generados, o bien usar Text Generation API para coordinar esas operaciones a través de una canalización en tiempo de ejecución compatible.

IWinMLTokenizer proporciona operaciones de codificación y descodificación de bajo nivel. Un IWinMLTokenizerDecoder mantiene un cursor de descodificación incremental independiente para una secuencia. Text Generation API agrega sesiones de generación de texto, opciones, actualizaciones de streaming, cancelación, motivos de finalización y resultados completados sin cambiar la propiedad de los objetos Runtime subyacentes.

Compatibilidad con ONNX Runtime

Las interfaces opcionales de WinMLRuntimeOrt.h ofrecen funciones prácticas de ONNX:

  • IWinMLOrtCompatibility selecciona un proveedor de ejecución de ONNX Runtime ya registrado.
  • IWinMLOrtModelSchema refleja los nombres de entrada y salida.
  • IWinMLOrtNamedBindings enlaza una fase respaldada por ORT por nombre.
  • IWinMLOrtStageDiagnostics informa de los proveedores solicitados y seleccionados después de Build.

Estas interfaces resuelven nombres y directiva del proveedor durante la instalación. La ejecución sigue usando el mismo contrato de pipeline posicional.

Consulta IWinMLOrtCompatibility desde el tiempo de ejecución para asociar una etapa de modelo ONNX a un proveedor de ejecución que ya hayas registrado, en lugar de dejar que Build elija uno automáticamente:

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()));

Pasar nullptr para hardwareTarget permite al runtime emparejar el proveedor con uno de sus propios dispositivos de esa clase de hardware; pase un existente IWinMLExecutionTarget para anclar el proveedor a ese adaptador específico en su lugar. Este destino no es compatible con las etapas .gguf; Build devuelve HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Consulte también

  • Se actualizó por última vez el