Descripción general 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 Microsoft Store.

Importante

La API de tiempo de ejecución de Windows ML está disponible actualmente en C++ y Python; Actualmente no se admite C#. Háganos saber si está interesado en usar estas API de C# publicando un problema en el repositorio de GitHub de Windows ML.

La API de tiempo de ejecución de ML de Windows es un marco de inferencia de IA local nativo de C/C++ creado específicamente para Windows. Con la API Windows ML Runtime, puede cargar un modelo, elegir un destino de ejecución de CPU, GPU o NPU (incluido un adaptador DXCore específico o un dispositivo D3D12), enlazar tensores a ese destino, componer el modelo y las fases del procesador en una canalización, compilar la canalización y ejecutarla para generar tensores de salida.

Las API opcionales de generación de texto y reconocimiento de voz combinan estos mismos objetos de tiempo de ejecución en flujos de trabajo de nivel superior basados en un modelo que proporciona tu aplicación: consulta Generar texto con tu propio modelo de lenguaje mediante Windows ML y Reconocer voz con tu propio modelo de Whisper mediante Windows ML.

RUNTIME API frente a ONNX Runtime

Si su aplicación solo tiene como destino Windows (y usted está dispuesto a usar API que actualmente son experimentales), use Runtime API. Proporciona control explícito sobre la selección de hardware (incluido un adaptador DXCore específico o un dispositivo D3D12), la residencia de tensores, la ubicación en canalizaciones de varias etapas y la compilación.

De lo contrario, si la aplicación necesita ejecutarse en otras plataformas o ya tiene código de sesión multiplataforma de ONNX Runtime que funciona, use las API de ONNX Runtime incluidas en Windows ML en su lugar.

Modelo de objetos básico

Concepto API principal Description
Runtime IWinMLRuntime Interfaz devuelta por WinMLCreateRuntime; carga archivos de modelo, crea destinos de ejecución y genera generadores de canalizaciones.
Modelo IWinMLModel Artefacto de modelo inmutable y opaco cargado desde un archivo o búfer. Refleje su esquema declarado mediante IWinMLModelSchema.
Destino de ejecución IWinMLExecutionTarget Token de colocación de CPU, GPU o NPU que se usa para construir etapas y crear tensores.
Generador de canalizaciones IWinMLPipelineBuilder Agrega fases de modelo y procesador, las conecta y compila una canalización preparada.
Pipeline IWinMLPipeline Gráfico preparado y ejecutable inmediatamente que ejecuta tensores enlazados y genera tensores de salida.
Stage IWinMLStage Un paso en la canalización que posee enlaces de entrada y salida posicionales y su destino de ejecución resuelto.
Tensor IWinMLTensor Datos multidimensionales tipados enlazados a entradas y salidas de etapa.
Generación de texto/reconocimiento de voz Windows ML Text Generation and Speech Recognition APIs Flujo de trabajo de nivel superior compuesto por objetos Runtime propiedad del código que realiza la llamada, con sesiones, flujos y resultados con tipo.

Elija un back-end y un destino de ejecución

LoadModelFromFile selecciona el back-end según la extensión de archivo del artefacto del modelo. La aplicación usa los mismos objetos runtime ( modelo, destino de ejecución, generador de canalizaciones, fases, enlaces y Run ), independientemente del back-end que cargue el archivo.

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 ML EP de Windows
.gguf llama.cpp Un módulo de CPU local de la aplicación, además de un módulo CUDA opcional para GPU de NVIDIA que se implementa junto con la aplicación. CPU y CUDA son los únicos backends de llama.cpp que Windows ML valida para esta versión.

Un destino de ejecución representa una clase de hardware —CPU, GPU o NPU— creada con IWinMLRuntime. Reutilizar un destino para crear etapas y crear tensores: la reutilización de un destino expresa la afinidad de mismo destino, mientras que el uso de destinos distintos hace explícitos los límites de transferencia entre destinos. Cuando se ejecuta el método Build del generador de canalizaciones, el tiempo de ejecución coloca cada etapa en el backend de ejecución correspondiente a su destino y garantiza la compatibilidad entre el destino y el backend.

Para una clase de hardware sin enumerar los dispositivos usted mismo, llame a CreateExecutionTarget con un WINML_EXECUTION_TARGET_KIND y un WINML_EXECUTION_TARGET_PREFERENCE que clasifica a los candidatos de esa clase, como una GPU integrada frente a una GPU discreta. Trate ERROR_NOT_FOUND y ERROR_NOT_SUPPORTED por igual y retroceda a otra clase:

ComPtr<IWinMLExecutionTarget> target;
HRESULT hr = runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_NPU,
    WINML_EXECUTION_TARGET_PREFERENCE_EFFICIENCY,
    target.GetAddressOf());
if (hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
    hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
{
    THROW_IF_FAILED(runtime->CreateExecutionTarget(
        WINML_EXECUTION_TARGET_KIND_GPU,
        WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
        target.GetAddressOf()));
}
else
{
    THROW_IF_FAILED(hr);
}

CreateCpuExecutionTarget es equivalente a solicitar el tipo de CPU. CreateExecutionTargetFromAdapter y CreateExecutionTargetFromD3D12 enlazan un destino a un adaptador DXCore específico o un dispositivo D3D12 en lugar de permitir que el runtime elija uno. Para los modelos ONNX que dependen de un proveedor de ejecución instalado (EP), una superficie de compatibilidad opcional de ONNX Runtime le permite fijar un proveedor que ya ha registrado. Cada back-end resuelve estos destinos de forma diferente; por ejemplo, el back-end de llama.cpp usado por los modelos .gguf requiere al menos un offload parcial a la GPU para respetar un destino de GPU y no admite destinos de NPU ni anclaje de proveedores. Para obtener la matriz de resolución de destino completa por back-end y para ver un tutorial sobre cómo ejecutar un modelo GGUF, consulte Conceptos de la API de Windows ML Runtime.

Pasos siguientes

  • Se actualizó por última vez el