| # Entrenamiento | |
| Crea `modelos_entrenados/material_estado/` (material + estado) y calibra el conteo de SAM 3. | |
| ## Credenciales (una vez) | |
| | Para | Qué hacer | | |
| |---|---| | |
| | Backbone DINOv3 y SAM 3 | Aceptar la licencia en [dinov3-convnext-tiny](https://huggingface.co/facebook/dinov3-convnext-tiny-pretrain-lvd1689m) y [sam3](https://huggingface.co/facebook/sam3); después `uv run hf auth login` | | |
| | Datasets de Kaggle | Kaggle → Settings → API → *Create New Token*; guardar `kaggle.json` en `C:\Users\<usuario>\.kaggle\` | | |
| | Datasets de Roboflow | Roboflow → Settings → API Keys; `setx ROBOFLOW_API_KEY "clave"` y abrir una terminal nueva | | |
| Sin Kaggle o Roboflow el pipeline funciona igual con menos datos: esas fuentes se omiten | |
| con aviso. Sin Roboflow no hay madera ni defectos, así que la nota de estado no se valida. | |
| ## Pasos | |
| ```bash | |
| uv run python -m entrenamiento.descargar # 1. datasets → datos/crudos/ (minutos) | |
| uv run python -m entrenamiento.preparar # 2. une, limpia y reparte (minutos) | |
| uv run python -m entrenamiento.caracteristicas # 3. pasa cada foto por DINOv3 (horas en CPU, reanudable) | |
| uv run python -m entrenamiento.entrenar # 4. entrena las 2 cabezas y exporta (minutos) | |
| uv run python -m entrenamiento.evaluar_conteo # 5. mide y calibra el conteo de SAM 3 (~1 h) | |
| ``` | |
| El paso 4 escribe `modelos_entrenados/material_estado/informe.md` con las métricas sobre el | |
| conjunto de prueba (fotos que el modelo nunca vio). El paso 5 escribe | |
| `modelos_entrenados/conteo/informe.md` y el umbral elegido. | |
| ### Mejor precisión: ajuste fino completo en Colab (GPU gratis) | |
| Los pasos 3-4 dejan el backbone congelado para que se pueda entrenar sin GPU. Ajustar | |
| también el backbone suele mejorar varios puntos, sobre todo en defectos finos: | |
| ```bash | |
| uv run python -m entrenamiento.empaquetar_colab # → datos/revalora_colab.zip | |
| ``` | |
| Abre [colab_entrenamiento.ipynb](colab_entrenamiento.ipynb) en Google Colab, sube el zip y | |
| ejecuta las celdas. Descarga `material_estado.zip` y sustituye `modelos_entrenados/material_estado/`. | |
| ## Datos | |
| Las fuentes están en [fuentes.py](fuentes.py). **Solo se usan datasets con licencia que permite | |
| uso comercial** (MIT, CC0, CC BY 4.0, ODbL); la licencia se comprueba al descargar y las fuentes | |
| no comerciales se descartan. El resultado de cada fuente queda en `datos/procesados/fuentes.json` | |
| y en la tabla final del informe. | |
| | Tipo | Ejemplos | Qué enseña | | |
| |---|---|---| | |
| | Material | TrashNet, RealWaste, Garbage Classification | qué material es | | |
| | Defectos | Roboflow: madera (Kodytek), óxido, telas, cajas dañadas, vidrio roto, abolladuras | qué defectos tiene | | |
| Las etiquetas de cada dataset se traducen a nuestros defectos en [mapeo.py](mapeo.py) | |
| ("Dead_Knot" → nudo, "rust" → óxido, "non-damaged" → sin defectos...). Cada imagen solo enseña | |
| los defectos que su dataset etiqueta; el resto no cuenta. | |
| Para **añadir fotos propias** (lo que más mejora el modelo con fotos reales de la plataforma): | |
| crea una carpeta por material con las fotos dentro, añádela a `fuentes.py` como fuente de | |
| material con `origen="url"` o cópiala a `datos/crudos/<nombre>/` con un archivo `.completo`, y | |
| repite los pasos 2-4. | |
| ## Decisiones | |
| - **ConvNeXt-Tiny DINOv3** (Meta, 2025): misma red y velocidad que el ConvNeXt-Tiny original, | |
| con mejores pesos de partida. Licencia DINOv3 (uso comercial permitido, sin usos militares). | |
| - **384 px**: deja ver defectos pequeños; ~0.4 s por imagen en CPU. | |
| - **Características globales + máximo local**: el máximo conserva un defecto pequeño que el | |
| promedio diluiría. | |
| - **Reparto por grupo**: las variantes aumentadas de una misma foto (Roboflow) nunca quedan a la | |
| vez en entrenamiento y en prueba. | |
| - **Defectos sin datos suficientes** (< 30 ejemplos con y sin él) no se usan en la nota. | |