Cómo entrenar YOLO de segmentación con MIDV500 para documentos de identidad
En esta guía práctica aprenderás todo el flujo para entrenar un modelo YOLO de segmentación que detecte documentos de identidad con el dataset MIDV500 y la librería ultralytics. Cubriremos la descarga del dataset, su conversión al formato YOLO, verificación visual de anotaciones, entrenamiento, exportación a ONNX y la creación de una aplicación de escritorio con interfaz gráfica para detección y rectificación de documentos. Si tu empresa necesita aplicaciones a medida, software a medida o soluciones de inteligencia artificial, en Q2BSTUDIO te acompañamos de extremo a extremo con un equipo experto en ciberseguridad, servicios cloud AWS y Azure, inteligencia de negocio y agentes IA. Descubre más sobre nuestras soluciones de IA en Q2BSTUDIO Inteligencia Artificial y sobre desarrollo multiplataforma en desarrollo de aplicaciones a medida.
Qué vas a lograr
1 Descargar y preparar MIDV500 para segmentación de documentos. 2 Convertir las anotaciones JSON a formato YOLO de segmentación. 3 Verificar visualmente las máscaras con un visor de dataset en PySide6. 4 Entrenar YOLO11-seg con ultralytics usando GPU o CPU. 5 Exportar el mejor modelo a ONNX y probar inferencia. 6 Crear una GUI para detectar y rectificar documentos.
Dataset MIDV500
MIDV500 es un conjunto amplio de imágenes y vídeos de documentos de identidad de múltiples países, ideal para tareas de detección, segmentación y reconocimiento. Puedes consultar la referencia en GitHub en MIDV500 dataset.
Instalación rápida del descargador pip install midv500
Descarga con Python ejemplo simple import midv500 luego dataset_dir = midv500_data y finalmente midv500.download_dataset(dataset_dir, all). Tras la descarga, verifica que existan carpetas por tipo de documento con subdirectorios images, ground_truth y videos.
Conversión de anotaciones a formato YOLO
MIDV500 utiliza anotaciones JSON con polígonos o cuadriláteros. Para entrenar segmentación con YOLO debemos convertirlas a etiquetas YOLO con coordenadas normalizadas. Requisitos pip install ultralytics opencv-python numpy tqdm pyyaml pillow. Crea un script que recorra todas las imágenes, localice su JSON asociado en ground_truth, ordene los puntos como TL TR BR BL, normalice por ancho y alto y guarde etiquetas con la clase 0 document en labels train y val. Genera además el archivo doc.yaml con path absoluto, y con train images train y val images val, names document y nc 1.
Ejecución de la conversión ejemplo python prep_midv500_to_yolov11seg.py. Al finalizar deberías tener dataset images train, dataset images val y dataset labels train y val, además del doc.yaml para entrenamiento.
Verificación visual de anotaciones
Antes de entrenar, valida que las etiquetas se hayan generado correctamente. Instala el visor pip install PySide6 y crea un pequeño visualizador que cargue imágenes de dataset images train y dataset images val, busque su etiqueta homónima en dataset labels y dibuje el polígono sobre la imagen. Úsalo para revisar casos aleatorios y corregir problemas si fuese necesario. Ejecuta python dataset_viewer.py.
Entrenamiento con YOLO segmentation
Instala ultralytics pip install ultralytics. Descarga un checkpoint base de segmentación si no lo tienes y entrena con un comando típico yolo task=segment mode=train model=yolo11s-seg.pt data=dataset doc.yaml imgsz=640 epochs=20 batch=16 device=0 patience=5. Si prefieres CPU usa device=cpu y ajusta batch más bajo. También puedes crear un script en Python que genere un doc.yaml temporal con path absoluto y lance el entrenamiento, además de exportar posteriormente el mejor modelo.
Comandos alternativos útiles
Entrenamiento GPU yolo task=segment mode=train model=yolo11s-seg.pt data=dataset doc.yaml imgsz=640 epochs=30 batch=16 device=0 amp=True. Entrenamiento CPU yolo task=segment mode=train model=yolo11s-seg.pt data=dataset doc.yaml imgsz=640 epochs=30 batch=8 device=cpu. Reanudar desde checkpoint yolo task=segment mode=train model=runs segment train weights last.pt resume=True.
Parámetros clave
model modelo YOLO de segmentación preentrenado. data ruta al YAML del dataset. epochs número de iteraciones. imgsz resolución de entrada recomendada 640. batch tamaño de lote ajustado a la memoria GPU. device 0 para GPU o cpu para CPU. amp mixed precision para acelerar y ahorrar memoria.
Exportación a ONNX
Tras el entrenamiento, exporta el mejor modelo a ONNX para despliegue y optimización en producción yolo export model=runs segment train weights best.pt format=onnx opset=12. También puedes simplificar el grafo yolo export model=runs segment train weights best.pt format=onnx opset=12 simplify=True.
Prueba rápida de inferencia con ONNX
Carga el modelo ONNX con ultralytics YOLO, infiere sobre una imagen de prueba y extrae la máscara más grande. Después, aproxima el polígono a un cuadrilátero ordenado y aplica una transformación de perspectiva para rectificar el documento. Guarda dos resultados detect_overlay.jpg con el contorno detectado y document_warped.jpg con el recorte rectificado. Este paso valida que el modelo exportado funciona correctamente fuera de PyTorch.
Aplicación GUI de escritorio
Con PySide6 puedes construir una aplicación sencilla que permita arrastrar y soltar una imagen, ejecutar la detección y mostrar dos paneles lado a lado el original con el polígono y el documento rectificado. La clase de detección puede intentar cargar primero runs segment train weights best.pt en PyTorch y si no existe, usar runs segment train weights best.onnx. Una vez detectado el polígono, ordénalo TL TR BR BL, calcula la homografía y muestra el resultado. Dependencias pip install PySide6 y ejecución python document_detector_gui.py.
Buenas prácticas para resultados sólidos
1 Mezcla imágenes de varios países y condiciones de iluminación del MIDV500 para mayor robustez. 2 Ajusta el tamaño de lote y epochs a tu hardware, aplica early stopping y valida periódicamente. 3 Mantén la resolución de inferencia 640 para un equilibrio entre precisión y velocidad, y prueba con 960 si tu GPU lo permite. 4 Exporta a ONNX y ensaya en onnxruntime para asegurar portabilidad. 5 Versiona tu doc.yaml y mantén rutas absolutas en entornos de producción.
Recursos de referencia
Repositorio MIDV500 en GitHub ver dataset. Paquete ultralytics en PyPI ver librería. Un ejemplo de código público similar al flujo descrito puede encontrarse en repositorios comunitarios y en documentación oficial de ultralytics.
Q2BSTUDIO, tu aliado para llevarlo a producción
En Q2BSTUDIO somos especialistas en aplicaciones a medida y software a medida con despliegue seguro y escalable. Diseñamos soluciones de inteligencia artificial e ia para empresas, incluyendo agentes IA, visión por computador y NLP, y las integramos con servicios cloud AWS y Azure, pipelines de datos y servicios inteligencia de negocio con power bi. Si quieres transformar este prototipo en una solución empresarial con autenticación, auditoría, CI CD, observabilidad y ciberseguridad avanzada, contáctanos. Conoce más sobre nuestros servicios de IA en nuestra landing de Inteligencia Artificial y sobre cómo creamos aplicaciones multiplataforma en software y apps a medida.
Palabras clave de interés aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.
