mlops

Ver en Git

---

Guía de MLOps

Cómo se trackean, deployean e iteran los experimentos.

---

Stack General

Developer → git push → GitLab CI → build → test → experiment
                                                      ↓
                                               MLflow tracking
                                          (params + métricas + artifacts)
                                                      ↓
                                          GitLab Model Registry
                                          (mejor modelo versionado)

Componente	Rol
Docker	Ambiente reproducible (GDAL, rasterio, geopandas, ultralytics)
GitLab CI	Pipeline automatizado de build, smoke test y experimentación
MLflow	Tracking de experimentos (params, métricas, GeoJSONs de output)
S3 (AWS)	Storage de artifacts para MLflow
Planetary Computer	Descarga de imágenes Sentinel-2 sin autenticación

---

MLflow Tracking

Cada corrida de experimento se loguea automáticamente al server de MLflow.

Parámetros Trackeados

Parámetro	Descripción
engine	Nombre del engine de detección
conf	Threshold de confianza YOLO
iou	Threshold IoU de YOLO
tile_size	Tamaño de tile de inferencia (pixels)
n_scenes	Cantidad de escenas en el composite
start_date	Fecha de inicio de búsqueda de imágenes
min_area_m2	Filtro de área mínima de campo
device	Dispositivo de cómputo
detection_mode	Estrategia de detección
Todos los postprocess_params	Configuración de post-procesamiento

Métricas Trackeadas

Métrica	Descripción
reference_coverage	Tipo recall (intersección / área referencia)
prediction_precision	Tipo precision (intersección / área predicha)
iou	Intersection over Union
n_predicted	Cantidad de polígonos predichos
n_ref	Cantidad de polígonos de referencia
elapsed_s	Tiempo de inferencia wall-clock (segundos)

Artifacts Trackeados

• GeoJSON de output con los límites de campo predichos

Ver Resultados

El server de MLflow corre en la URI definida por MLFLOW_SERVER_URI:

# Si usa file store local como fallback
mlflow ui --backend-store-uri outputs/mlruns
# Abrir http://127.0.0.1:5000

Cambiar el Backend de Tracking

# Server MLflow remoto (default)
export MLFLOW_SERVER_URI=http://10.100.2.23:5000

# SQLite (persistencia local single-user)
export MLFLOW_SERVER_URI=sqlite:///mlflow.db

---

GitLab Model Registry

El GitLab Model Registry es compatible con MLflow y hostea las versiones registradas de modelos.

Después de un sweep, la mejor corrida (mayor IoU) se registra automáticamente como una nueva versión del modelo.

Setup

1. Generá un token de acceso de proyecto/grupo/personal con scope api y rol Developer.
2. Seteá las variables de entorno:

export MLFLOW_REGISTRY_URI="https://git.auravant.com/api/v4/projects/<project_id>/ml/mlflow"
export MLFLOW_TRACKING_TOKEN="<access_token>"

3. Corré un sweep — el mejor resultado se registra automáticamente.

Dónde Ver los Resultados en GitLab

• Deploy → Model experiments — todas las corridas trackeadas
• Deploy → Model registry — versiones registradas del modelo

Consideraciones

• Los artifacts se suben con artifact_path="" (sin subdirectorios). El framework maneja esto automáticamente cuando detecta el endpoint de GitLab.
• create_model_version ignora run_id, source y run_link. Cada versión obtiene su propia corrida backing.
• Las versiones del modelo se ordenan por SemVer. La versión se deriva de CI_COMMIT_TAG, con fallback a 0.1.<pipeline_id> en CI o 0.0.<timestamp> en local.

---

Pipeline de GitLab CI

Definido en .gitlab-ci.yml con tres stages:

build → test → experiment

Stages

Job	Trigger	Qué hace
build	Push (cuando cambian Dockerfile, pyproject.toml o source)	Buildea imagen Docker, pushea al GitLab Container Registry
test	Cada push	Smoke-tests de imports, config y mlflow dentro de la imagen
sweep	Cada push (después de test)	Corre el experimento baseline, guarda el GeoJSON como artifact

Variables de CI/CD Requeridas

Seteadas automáticamente por GitLab:

Variable	Descripción
CI_REGISTRY_USER	Username del container registry
CI_REGISTRY_PASSWORD	Password del container registry
CI_REGISTRY	Hostname del container registry
CI_REGISTRY_IMAGE	Path completo de la imagen

Seteadas manualmente en Settings → CI/CD → Variables:

Variable	Requerida	Descripción
MLFLOW_TRACKING_URI	No	Endpoint MLflow de GitLab (para registro de modelos)
MLFLOW_TRACKING_TOKEN	No	Access token con scope api
MLFLOW_SERVER_URI	No	Server de tracking MLflow (default http://10.100.2.23:5000)
AWS_ACCESS_KEY_ID	Sí	Credenciales del artifact store S3
AWS_SECRET_ACCESS_KEY	Sí	Credenciales del artifact store S3
GITLAB_DEPLOY_USER	Sí	Usuario para login al registry
GITLAB_DEPLOY_SECRET	Sí	Token para login al registry

No se necesitan secrets adicionales para imágenes — Planetary Computer no requiere autenticación.

Descargar Artifacts del Pipeline

Después de una corrida del pipeline: GitLab → CI/CD → Pipelines → [job] → Download artifacts.

La carpeta outputs/ contiene los resultados de los experimentos y los GeoJSONs.

---

Agregar un Nuevo Experimento

1. Creá un archivo YAML en experiments/:

experiment_name: "mi_experimento"
engine: "delineate-anything"
aoi_wkt: "POLYGON((......))"
reference_path: "data/input/reference_output.geojson"
device: "cpu"

engine_params:
  conf: 0.05
  iou: 0.5
  tile_size: 1024
  n_scenes: 5
  start_date: "2025-01-01"

postprocess_params:
  simplify_tolerance: 10.0
  min_area_m2: 30000
  buffer_distance: -5.0
  merge_overlaps: true

2. Correlo:

python3 -m model.cli run --config experiments/mi_experimento.yaml

3. Compará contra la referencia:

python3 -m model.cli compare --result outputs/result_mi_experimento.geojson \
                             --reference data/input/reference_output.geojson

4. Mirá en la UI de MLflow para comparar con otras corridas.

---

Actualizar el Output de Referencia

Para regenerar la referencia después de cambiar la escena o el ground-truth:

python3 scripts/convert_bounds.py

Commiteá la nueva referencia para que las futuras corridas de CI comparen contra ella.