Compilar y almacenar en caché modelos ONNX en Windows ML

La compilación es la etapa que convierte su modelo ONNX en el binario específico para el hardware que un proveedor de ejecución (EP) ejecuta realmente. En las NPU y las GPU, ese paso puede tardar desde unos pocos segundos hasta varios minutos en el caso de modelos grandes; y, si tu aplicación no almacena en caché el resultado, los usuarios asumen ese coste cada vez que se inicia tu aplicación.

En esta página se explica qué implica la compilación, cuándo realizar la compilación previa y cómo validar un modelo compilado almacenado en caché antes de reutilizarlo.

Prerequisites

Las API de compatibilidad del modelo compilado requieren Windows ML 2.3 o posterior. En el entorno de ejecución de ONNX ascendente, GetModelCompatibilityForEpDevices() está disponible en la versión 1.23 y GetCompatibilityInfoFromModel() está disponible en la versión 1.24.

Dos tipos de compilación

"Compilación" puede significar dos cosas diferentes. Separarlas hace que el resto de esta página sea más fácil de razonar sobre:

  • Optimización de grafos : fusión, plegado constante y trabajo de diseño que onNX Runtime realiza en la creación de la sesión. Es barato, independiente de EP y se ejecuta cada vez que creas una sesión.
  • Compilación del EP — Conversión del grafo ONNX al formato propio de un EP, seguida de su compilación a un binario específico para el hardware. Los EP de hardware (QNN, OpenVINO, VitisAI, NvTensorRtRtx, MIGraphX) lo hacen y es el paso costoso. En las NPUs, los modelos más grandes pueden tardar decenas de segundos en minutos.

Windows ML evita volver a pagar la compilación EP mediante el mecanismo EPContext de ONNX Runtime. La primera compilación serializa un binario listo para el hardware en un modelo *_ctx.onnx (o en un archivo auxiliar .bin); en sesiones posteriores se carga el binario ya generado y se omite por completo la conversión.

¿Por qué compilar previamente?

Windows ML recomienda encarecidamente la compilación previa al usar proveedores de ejecución. La compilación previa convierte un arranque en frío de varios segundos y a veces de varios minutos en un coste único, y ofrece a su aplicación:

  • Arranques en frío rápidos: las ejecuciones posteriores omiten la conversión de grafos y la compilación para el hardware.
  • Comportamiento predecible : la plataforma admite la comprobación de si un modelo compilado es óptimo para los dispositivos que selecciona la aplicación antes de crear una sesión de inferencia.
  • Menor uso de CPU y batería : deja de volver a compilar el mismo gráfico en cada lanzamiento.

Sin precompilación, la aplicación vuelve a ejecutar la conversión de EP y la compilación cada vez que se crea una sesión, y los usuarios perciben esa demora cada vez.

Cuándo compilar previamente

Compile previamente cada vez que la aplicación tenga como destino un EP de hardware. Hay dos opciones de tiempo disponibles:

Strategy Más adecuado para Ventajas y desventajas
Ahead-of-time (AOT): compilar en el momento de la compilación o la instalación y distribuir el artefacto compilado. Flotas de hardware y controladores controladas, o instaladores por dispositivo. Requiere herramientas de compilación cruzada para destinos en los que no se puede ejecutar la máquina de compilación. Valida el artefacto en el dispositivo de destino y proporciona una alternativa de recompilación.
Compile en la primera ejecución(recomendada para una distribución amplia): compruebe si hay un artefacto compilado, compárelo si falta, después almacene en caché y reutilíquelo. Aplicaciones de la Store y distribución al consumidor general para una amplia variedad de hardware. Los usuarios pagan el costo de compilación una vez, en el primer lanzamiento.

En el tutorial de Windows ML se muestra la mecánica básica de compilación en primera ejecución comprobando si existe un artefacto compilado. No es un ejemplo completo de administración de caché. Antes de reutilizar un modelo compilado existente en una aplicación, aplique la comprobación de compatibilidad descrita en este artículo. Para obtener la API de compilación en contexto, consulte Compilación de modelos.

Validar un modelo compilado antes de reutilizarlo

Un modelo compilado puede depender del EP y de la configuración del dispositivo que lo generó. El EP determina si un modelo almacenado en caché sigue siendo compatible y óptimo para un conjunto de dispositivos.

Durante la compilación, un EP puede generar una cadena de compatibilidad UTF-8 terminada en nulo que ONNX Runtime escribe en las propiedades de metadatos del modelo compilado. El formato y el contenido de la cadena están definidos por el EP. La aplicación no debe analizarla ni interpretarla.

La aplicación envía la cadena de texto y los dispositivos EP de destino a GetModelCompatibilityForEpDevices(). ONNX Runtime invoca la implementación de validación de la fábrica de EP y devuelve un estado OrtCompiledModelCompatibility. Para los contratos de origen, consulte GetModelCompatibilityForEpDevices() y ValidateCompiledModelCompatibilityInfo() en el repositorio onnx runtime.

Escenarios de comprobación de compatibilidad

Puede usar la misma API de validación en dos escenarios:

  • Valide un modelo que ya está en el dispositivo. Llame GetCompatibilityInfoFromModel() a para extraer la cadena de un archivo de modelo compilado. Si el modelo ya está en memoria, llame a GetCompatibilityInfoFromModelBytes(). A continuación, pase la cadena a GetModelCompatibilityForEpDevices().
  • Valide antes de descargar un modelo compilado. Publique la cadena opaca como metadatos ligeros junto con el modelo compilado. La aplicación puede recuperar primero la cadena, validarla con GetModelCompatibilityForEpDevices() y descargar el modelo, que puede ser grande, solo cuando el estado devuelto cumpla su política de caché o implementación.

Mantenga los metadatos de compatibilidad remota emparejados con el artefacto compilado exacto que lo generó. Si cambia el artefacto, actualice la cadena de compatibilidad asociada.

En cualquier escenario:

  1. Llame a GetEpDevices() para enumerar los dispositivos EP disponibles y, a continuación, aplique la misma directiva de EP o de dispositivo que use para configurar la sesión de inferencia.
  2. Obtenga la cadena de compatibilidad del modelo local o de los metadatos asociados a un modelo remoto.
  3. Pase la cadena y el grupo de dispositivos coincidente a GetModelCompatibilityForEpDevices().
  4. Aplique la directiva de caché o de descarga al estado devuelto. Los ejemplos de ml de Windows usan una directiva conservadora y aceptan el modelo compilado solo para EP_SUPPORTED_OPTIMAL.

GetCompatibilityInfoFromModel() analiza el ONNX ModelProto completo desde el disco. Use el patrón de metadatos remotos cuando necesite tomar una decisión de compatibilidad antes de descargar el propio modelo.

Las API devuelven un OrtCompiledModelCompatibility valor:

Situación Meaning Acción recomendada
EP_SUPPORTED_OPTIMAL El modelo compilado es compatible y es óptimo para los dispositivos EP. Vuelva a usar el modelo compilado.
EP_SUPPORTED_PREFER_RECOMPILATION El modelo compilado es compatible, pero el EP recomienda recompilarlo para obtener un mejor rendimiento. El modelo puede ejecutarse, pero una directiva de caché solo óptima lo recompila.
EP_UNSUPPORTED El modelo compilado no es compatible con los dispositivos EP actuales. No cargue el modelo compilado. Vuelva a compilar o use el modelo original.
EP_NOT_APPLICABLE El EP no proporcionó una determinación de compatibilidad para los dispositivos suministrados. Este es también el valor predeterminado cuando el EP no implementa la validación de compatibilidad. No trate este estado como evidencia de que la memoria caché es compatible. Use el modelo original a menos que la aplicación tenga otra directiva de validación.

En una directiva de caché solo óptima, trate los metadatos de compatibilidad que faltan para el EP preferido como un error de caché. Si la evaluación de compatibilidad devuelve un error, use el modelo original para esa ejecución y no promueva un artefacto recién compilado porque la aplicación no puede validarlo.

Entre los eventos que pueden requerir una nueva entrada de caché se incluyen:

  • Se instala un nuevo EP.
  • El controlador de GPU o NPU se actualiza.
  • El hardware del usuario cambia.
  • El modelo ONNX de origen cambia.
  • Tu aplicación cambia la configuración de ONNX Runtime, EP o compilación utilizada para generar el artefacto.

Las API de compatibilidad validan un artefacto compilado existente en dispositivos EP; no determinan si el artefacto se generó a partir del modelo de origen actual. Incluya una versión del modelo de origen o un hash en la clave de caché e invalide la memoria caché cuando cambien las entradas de compilación.

Si tu aplicación se distribuye en una variedad de dispositivos, almacena los artefactos compilados en una ubicación de caché local para que cada dispositivo genere y reutilice su propio binario.

Comprobación de compatibilidad básica

Las siguientes funciones auxiliares comprueban un modelo compilado para un EP. Antes de llamar a un asistente, aplique la misma directiva ep o de dispositivo que use para configurar la sesión de inferencia. La recopilación de dispositivos debe no estar vacía y contener dispositivos del mismo EP.

static bool IsCompiledModelOptimal(
    OrtEnv ortEnv,
    string compiledModelPath,
    string epName,
    IReadOnlyList<OrtEpDevice> epDevices)
{
    string compatibilityInfo =
        ortEnv.GetCompatibilityInfoFromModel(compiledModelPath, epName);

    return !string.IsNullOrWhiteSpace(compatibilityInfo) &&
        ortEnv.GetModelCompatibilityForEpDevices(
            epDevices,
            compatibilityInfo) ==
        OrtCompiledModelCompatibility.EP_SUPPORTED_OPTIMAL;
}

Use la comprobación antes de la creación de la sesión:

  • Si el resultado cumple la directiva de compatibilidad de la aplicación, use el modelo compilado.
  • De lo contrario, use o vuelva a compilar el modelo original.

Los ejemplos de Windows ML usan una política conservadora y solo aceptan EP_SUPPORTED_OPTIMAL. La aplicación determina cómo almacenar, actualizar y reemplazar modelos compilados.

Compilar modelos

Antes de usar un modelo ONNX en una sesión de inferencia, a menudo debe compilarse en una representación optimizada que se pueda ejecutar de forma eficaz en el hardware subyacente del dispositivo.

A partir de ONNX Runtime 1.22, hay nuevas API que encapsulan mejor los pasos de compilación. Hay más detalles disponibles en la documentación de compilación de ONNX Runtime (consulte OrtCompileApi struct).

// Prepare compilation options
OrtModelCompilationOptions compileOptions = new(sessionOptions);
compileOptions.SetInputModelPath(modelPath);
compileOptions.SetOutputModelPath(compiledModelPath);

// Compile the model
compileOptions.CompileModel();

Note

La compilación puede tardar varios minutos en completarse. Para que cualquier interfaz de usuario siga respondiendo, considere la posibilidad de hacerlo como una operación en segundo plano en la aplicación o alertar al usuario de que se está preparando un modelo.

Consulte también

  • Se actualizó por última vez el