ONNX Format Guide

Specification

ONNX (Open Neural Network Exchange) es un formato estándar abierto para representar modelos de machine learning. Desarrollado originalmente por Microsoft y Facebook en 2017 y ahora gobernado por la Linux Foundation, ONNX define un conjunto común de operadores, tipos de datos y un formato de grafo de cómputo que permite que modelos entrenados en un framework se desplieguen en otro. El formato usa Protocol Buffers (protobuf) para serialización y soporta una amplia gama de arquitecturas de modelos incluyendo redes neuronales convolucionales, redes recurrentes, transformers y modelos clásicos de ML.

Un modelo ONNX se representa como un grafo acíclico dirigido (DAG) donde los nodos representan operaciones (convolución, multiplicación de matrices, funciones de activación, etc.), las aristas representan tensores que fluyen entre operaciones, y el grafo tiene entradas y salidas definidas. El conjunto de operadores (opset) de ONNX es versionado, permitiendo que los modelos especifiquen qué versión de las definiciones de operadores requieren. A partir del opset 21, ONNX define más de 200 operadores que cubren operaciones de redes neuronales, funciones matemáticas, manipulación de tensores y flujo de control.

El formato incluye un sistema extensible de metadatos para documentación del modelo, información de entrenamiento y propiedades personalizadas. ONNX también soporta tipos de datos cuantizados (INT8, UINT8) y representaciones de precisión mixta, permitiendo la optimización de modelos para despliegue en dispositivos con recursos limitados. El ONNX Model Zoo proporciona una colección de modelos pre-entrenados en formato ONNX que cubren clasificación de imágenes, detección de objetos, NLP, reconocimiento de voz y otras tareas comunes.

When to Use ONNX

ONNX es la opción correcta cuando necesitas despliegue de modelos multiplataforma — entrenar en PyTorch o TensorFlow y desplegar en diferentes entornos de hardware o runtime. ONNX Runtime (ORT) proporciona inferencia optimizada en CPUs (x86, ARM), GPUs (NVIDIA, AMD, Intel), NPUs y aceleradores especializados. Si tu objetivo de despliegue incluye aplicaciones Windows (vía DirectML), dispositivos móviles (vía ONNX Runtime Mobile), navegadores web (vía ONNX Runtime Web/WebAssembly) o dispositivos de borde, ONNX proporciona un formato de modelo único que funciona en todos ellos.

Elige ONNX cuando el rendimiento de inferencia sea crítico y quieras beneficiarte de las extensas optimizaciones de grafo de ONNX Runtime incluyendo fusión de operadores, eliminación de constantes, optimización de layout y cuantización. ONNX Runtime se posiciona consistentemente entre los motores de inferencia más rápidos en diversas arquitecturas de modelos y plataformas de hardware. Es particularmente fuerte para modelos encoder de tipo transformer (BERT, RoBERTa, DeBERTa) usados en tareas de clasificación, NER y embeddings.

ONNX es menos adecuado para modelos generativos de lenguaje muy grandes (más de 7B parámetros) donde motores de inferencia especializados como vLLM, TensorRT-LLM o llama.cpp proporcionan mejor rendimiento a través de técnicas como batching continuo, PagedAttention y decodificación especulativa. ONNX también tiene una brecha de conversión — no todas las operaciones de PyTorch son soportadas por el exportador de ONNX, particularmente flujo de control dinámico y ciertos operadores personalizados, lo que puede requerir soluciones alternativas durante la exportación.

Schema / Structure

// ONNX Model structure (simplified from onnx.proto3)
message ModelProto {
  int64 ir_version = 1;           // IR version (currently 9)
  repeated OperatorSetIdProto opset_import = 8;
  string producer_name = 2;       // e.g., "pytorch"
  string producer_version = 3;
  string domain = 4;
  int64 model_version = 5;
  string doc_string = 6;
  GraphProto graph = 7;           // The computation graph
  repeated StringStringEntryProto metadata_props = 14;
}

message GraphProto {
  string name = 1;
  repeated NodeProto node = 2;      // Operations in the graph
  repeated TensorProto initializer = 5; // Pretrained weights
  repeated ValueInfoProto input = 11;
  repeated ValueInfoProto output = 12;
}

message NodeProto {
  repeated string input = 1;
  repeated string output = 2;
  string op_type = 4;              // e.g., "Conv", "MatMul", "Relu"
  repeated AttributeProto attribute = 5;
}

Example Data

import torch
import onnx
import onnxruntime as ort
from transformers import AutoTokenizer, AutoModelForSequenceClassification

# Export a HuggingFace model to ONNX
model_name = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
model.eval()

dummy_input = tokenizer("This is a test", return_tensors="pt")
torch.onnx.export(
    model,
    (dummy_input["input_ids"], dummy_input["attention_mask"]),
    "sentiment_model.onnx",
    input_names=["input_ids", "attention_mask"],
    output_names=["logits"],
    dynamic_axes={"input_ids": {0: "batch", 1: "seq"},
                  "attention_mask": {0: "batch", 1: "seq"},
                  "logits": {0: "batch"}},
    opset_version=17,
)

# Run inference with ONNX Runtime
session = ort.InferenceSession("sentiment_model.onnx")
inputs = tokenizer("Great product, highly recommend!", return_tensors="np")
outputs = session.run(None, dict(inputs))
print(f"Logits: {outputs[0]}")  # [[negative_score, positive_score]]