File size: 3,927 Bytes
a294091
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# 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.