La gestión de proyectos de inteligencia artificial, especialmente aquellos que involucran modelos grandes y un equipo de desarrollo, puede volverse caótica rápidamente. La falta de un sistema robusto de control de versiones para los archivos de modelos, configuraciones y código puede llevar a la confusión, la pérdida de progreso y una colaboración ineficiente. Este artículo describe un flujo de trabajo colaborativo integral para proyectos de detección de móviles en tiempo real, aprovechando Git y Git LFS para una gestión de versiones eficaz tanto del código como de los artefactos del modelo.

Por Qué los Proyectos de IA Necesitan Control de Versiones

Los proyectos de IA difieren de los proyectos de software tradicionales en su complejidad multidimensional. No solo el código fuente requiere control de versiones, sino también los pesos del modelo, los archivos de configuración y las versiones del conjunto de datos. Ignorar la gestión de versiones para estos componentes puede resultar en problemas significativos, como:

• Pérdida de Artefactos: Los archivos de modelos que representan horas de entrenamiento pueden sobrescribirse o perderse fácilmente en carpetas compartidas, lo que requiere un reentrenamiento costoso.
• Falta de Reproducibilidad: Sin un registro claro de qué código, configuración y datos produjeron un modelo específico, reproducir resultados o depurar problemas se vuelve extremadamente difícil.
• Colaboración Ineficiente: Los equipos luchan por rastrear quién hizo qué cambio, qué versión del modelo está asociada con qué iteración de código y cómo integrar los esfuerzos de manera coherente.

Git, diseñado principalmente para la gestión de archivos de texto, sobresale en el control de versiones de código y configuraciones. Para los archivos de modelo grandes, se requieren estrategias adicionales, pero el principio subyacente sigue siendo el mismo: cada cambio significativo debe ser un punto de control rastreable.

Estructura del Proyecto e Inicialización del Repositorio Git

Una estructura de proyecto bien organizada es crucial para la gestión. Aquí hay una estructura recomendada para un proyecto de detección de móviles:

phone_detection_project/
├── .gitignore          # Archivos a ignorar por Git
├── README.md           # Documentación del proyecto
├── requirements.txt    # Dependencias de Python
├── configs/            # Archivos de configuración
│   ├── train_config.yaml
│   └── inference_config.yaml
├── data/               # Datos (sin subir datos crudos/grandes)
│   ├── README.md
│   └── preprocess.py   # Script de preprocesamiento de datos
├── src/                # Código fuente
│   ├── model/          # Definiciones del modelo
│   ├── dataset/        # Carga de datos
│   ├── train.py        # Script de entrenamiento
│   └── infer.py        # Script de inferencia
├── experiments/        # Registro de experimentos y almacenamiento de modelos
│   ├── exp_20240501_lighting/
│   │   ├── config.yaml         # Copia de configuración del experimento
│   │   ├── train.log          # Registro de entrenamiento
│   │   └── checkpoints/       # Puntos de control del modelo (gestionados por LFS)
│   └── exp_20240505_backbone/
└── scripts/            # Scripts de utilidad
    ├── evaluate.py
    └── export_to_onnx.py

Para inicializar el repositorio Git:

# 1. Inicializar un nuevo repositorio Git
git init

# 2. Configurar nombre y correo electrónico (si es la primera vez)
git config user.name "Tu Nombre"
git config user.email "tu.email@example.com"

# 3. Crear y configurar el archivo .gitignore
# Es crucial para excluir archivos grandes y no necesarios.

Contenido recomendado para .gitignore:

# Ignorar entornos virtuales de Python
venv/
.env/

# Ignorar archivos generados por IDEs
.vscode/
.idea/
*.swp
*.swo

# Ignorar datasets y archivos de modelo grandes
data/raw/
data/processed/
experiments/*/checkpoints/  # Ignorar puntos de control del modelo

# Ignorar logs y salidas de entrenamiento (opcional)
*.log
output/
__pycache__/
*.py[cod]

Después de crear estos archivos, ejecuta:

git add .
git commit -m "Commit inicial: Estructura base del proyecto"

Gestión de Modelos y Pesos: Estrategias Clave

Gestionar archivos de modelo grandes (cientos de MB o GB) directamente en Git es ineficiente. Se recomiendan las siguientes estrategias:

Estrategia 1: Uso de Git LFS (Large File Storage)

Git LFS es una extensión de Git que gestiona archivos grandes almacenándolos en un servidor remoto separado, mientras que el repositorio Git solo contiene punteros a estos archivos. Esto permite mantener la familiaridad de las operaciones de Git.

Instalación y Configuración:

# 1. Instalar Git LFS (usando gestores de paquetes como brew, apt, etc.)
# Ejemplo para macOS:
brew install git-lfs

# 2. Habilitar LFS en el repositorio
git lfs install

# 3. Especificar los tipos de archivo a rastrear por LFS
git lfs track "*.pt"
git lfs track "*.pth"
git lfs track "*.h5"
git lfs track "*.bin"
git lfs track "*.onnx"

# 4. Añadir y commitear el archivo .gitattributes generado por LFS
git add .gitattributes
git commit -m "Configurar Git LFS para rastrear archivos de modelo"

Uso: Después de la configuración, al añadir un archivo de modelo con git add, Git LFS interceptará automáticamente el archivo. Al hacer git commit y git push, el archivo se subirá al servidor LFS, manteniendo el repositorio Git ligero.

Ventajas: Integración fluida, fácil de usar para el equipo. Desventajas: Las plataformas de alojamiento suelen tener límites de almacenamiento LFS, pudiendo requerir costos adicionales.

Estrategia 2: Registro de Modelos + Punteros Ligeros

Una alternativa es gestionar los modelos externamente y usar Git solo para almacenar metadatos y punteros.

1. Almacenamiento Centralizado de Modelos: Utilizar un servicio de almacenamiento en la nube (S3, GCS, Azure Blob Storage), un NAS o un registro de modelos dedicado (MLflow, DVC).
2. Gestión de "Inventario" de Modelos en Git: Mantener un archivo en Git (p. ej., model_registry.json) que registre los detalles de cada versión del modelo.

// Ejemplo de model_registry.json
{
  "phone_detection_v1.0": {
    "experiment_id": "exp_20240501_lighting",
    "git_commit": "a1b2c3d4e5f67890", // Versión del código de entrenamiento
    "config_file": "configs/train_config_v1.yaml",
    "model_path": "s3://our-model-bucket/phone_detection/exp_20240501/best_model.pth",
    "metrics": {"mAP": 0.965, "inference_time_ms": 45},
    "created_at": "2024-05-01 15:30:00"
  },
  // ... más versiones
}

Ventajas: Desacoplado de la infraestructura de Git, escalable para grandes volúmenes de modelos, control de costos. Desventajas: Requiere scripts personalizados para la recuperación y validación de modelos; menor automatización nativa.

Para la mayoría de los equipos, Git LFS ofrece un buen equilibrio entre faiclidad de uso y funcionalidad.

Normas de Colaboración y Flujo de Trabajo

Un flujo de trabajo claro previene conflictos y asegura la coherencia.

Estrategia de Ramificación: Versión Simplificada de Git Flow

• main: Rama principal, solo código estable y desplegable.
• develop: Rama de integración para desarrollo diario. Las ramas de características se fusionan aquí.
• feature/*: Ramas para nuevas características o experimentos (p. ej., feature/new-backbone).
• experiment/*: Ramas para experimentos de alto reisgo o temporales.
• release/*: Ramas para preparar lanzamientos, desde develop, para pruebas finales y correcciones.

Flujo de Trabajo de Ejemplo (Nueva Característica):

# 1. Crear una nueva rama de característica desde develop
git checkout develop
git pull origin develop
git checkout -b feature/try-mobilenetv3

# 2. Desarrollar, entrenar y probar en la rama feature/try-mobilenetv3
# ... (modificaciones de código, entrenamiento, etc.)

# 3. Commitear cambios (archivos de código y punteros LFS)
git add .
git commit -m "feat: Experimentar con MobileNetV3 como backbone"
git push origin feature/try-mobilenetv3

# 4. Crear una Solicitud de Integración (Pull Request) para fusionar en develop.
# 5. Realizar revisión de código.
# 6. Fusionar la rama tras la aprobación.

Normas de Mensajes de Commit

Adoptar la convención de Conventional Commits mejora la legibilidad del historial y permite la generación automática de registros de cambios.

Formato: <tipo>[opcional scope]: <descripción>

Tipos comunes: feat, fix, docs, style, refactor, test, chore.

Ejemplos:

• git commit -m "feat(model): Incorporar módulo de atención para mejorar detección de objetivos pequeños"
• git commit -m "fix(infer): Corregir orden de canales de color en preprocesamiento de imágenes"

Integración Continua y Prácticas de Automatización

Automatizar el entrenamiento, las pruebas y el despliegue reduce errores y acelera el ciclo de desarrollo. Aquí se muestra un ejemplo de configuración .gitlab-ci.yml:

# .gitlab-ci.yml
stages:
  - test
  - train
  - deploy

# Etapa 1: Pruebas unitarias
unit-test:
  stage: test
  image: python:3.9-slim
  before_script:
    - pip install -r requirements.txt
  script:
    - python -m pytest tests/unit/ -v

# Etapa 2: Validación del flujo de entrenamiento (entrenamiento corto con datos mínimos)
train-validation:
  stage: train
  image: pytorch/pytorch:latest
  before_script:
    - pip install -r requirements.txt
  script:
    - python src/train.py --config configs/ci_test_config.yaml --epochs 1
  artifacts:
    paths:
      - experiments/ci_test_run/
    expire_in: 1 week

# Etapa 3: Evaluación y empaquetado (solo en la rama main)
evaluate-and-package:
  stage: deploy
  image: pytorch/pytorch:latest
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - python scripts/evaluate.py --model experiments/latest/best_model.pth --data data/test/
    - python scripts/export_to_onnx.py --model experiments/latest/best_model.pth --output model.onnx
    - echo "Desplegando model.onnx al entorno de producción..."

Esta canalización automatiza:

1. Pruebas unitarias para la corrección del código.
2. Validación del flujo de entrenamiento para asegurar que el proceso de entrenamiento funcione.
3. Evaluación y empaquetado del modelo en la rama principal, preparando para el despliegue.

Conclusión

Implementar un flujo de trabajo robusto para proyectos de IA, que incluya una estructura de proyecto clara, control de versiones para código y modelos (usando Git y Git LFS), normas de colaboración definidas y automatización de CI/CD, es fundamental para la eficiencia y la reproducibilidad. Este enfoque sistemático transforma la gestión de proyectos de IA de un desafío caótico a un proceso manejable y confiable.