Upload 8 files

README.md

@@ -0,0 +1,107 @@
+---
+language:
+  - es
+library_name: pytorch
+pipeline_tag: tabular-regression
+tags:
+  - machine-learning
+  - regression
+  - linear-regression
+  - safetensors
+  - educational-example
+license: mit
+---
+
+# Regresión lineal con PyTorch: precio de una casa
+
+## Descripción del modelo
+
+Este modelo es un ejemplo pedagógico del Seminario de Actualización (IFTS N.º 18). Muestra cómo se entrena una regresión lineal con el ciclo explícito de PyTorch y cómo se publican los pesos en formato **safetensors**.
+
+Predice el precio de una casa, en miles de US$, a partir de su superficie y de si tiene balcón y ascensor. Resuelve el mismo problema que el ejemplo de scikit-learn.
+
+## Objetivo
+
+Predecir una variable numérica continua: el precio estimado de una casa.
+
+## Datos de entrenamiento
+
+- **Dataset:** sintético, generado en `train.py`. Es el mismo de la Clase 10, con la misma semilla, y no son casas reales.
+- **Cantidad de registros:** 200. Se usan 160 para entrenar y 40 para evaluar.
+- **Variables de entrada (X):** `m2` (de 35 a 120), `balcon` (0 o 1), `ascensor` (0 o 1).
+- **Variable objetivo (y):** `precio`, en miles de US$.
+- **Preprocesamiento:** las entradas se normalizan restando la media y dividiendo por el desvío, ambos calculados con los datos de entrenamiento. Esos valores están en `config.json`.
+
+## Entrenamiento
+
+- **Tipo de aprendizaje:** supervisado.
+- **Problema:** regresión.
+- **Arquitectura:** una capa `torch.nn.Linear(3, 1)`, es decir, tres pesos y un bias. Está definida en `modelo.py`.
+- **Función de pérdida:** error cuadrático medio (`MSELoss`).
+- **Optimizador:** descenso por gradiente (`SGD`), con tasa de aprendizaje 0,1.
+- **Épocas:** 500. La pérdida se estabiliza antes de la época 100.
+- **Biblioteca:** PyTorch.
+
+**Parámetros aprendidos.** Son los que guarda `model.safetensors`:
+
+| Parámetro | Valor |
+|---|---|
+| `lineal.weight` | [35,157 · 4,351 · 5,992] |
+| `lineal.bias` | 147,769 |
+
+**Por qué los pesos no se parecen a los de scikit-learn.** Están en la escala de las entradas **normalizadas**. Si se divide cada peso por el desvío de su variable, se vuelve a la escala original. Por ejemplo, 35,157 / 23,398 ≈ 1,503 para `m2`, que es el mismo peso que encontró scikit-learn.
+
+## Evaluación
+
+Se evaluó sobre 40 casas que el modelo no vio durante el entrenamiento.
+
+| Métrica | Resultado |
+|---|---|
+| MAE | 3,08 miles de US$ |
+| R² | 0,989 |
+
+## Archivos
+
+| Archivo | Qué es |
+|---|---|
+| `model.safetensors` | **solo los pesos** (`state_dict`) |
+| `config.json` | las entradas, la salida y la normalización que hay que aplicar antes de predecir |
+| `modelo.py` | la clase del modelo: PyTorch no la guarda en el archivo de pesos |
+| `train.py` | el código que lo entrenó |
+| `predict.py` | cómo cargarlo y usarlo |
+| `requirements.txt` | las dependencias |
+| `README.md` | esta Model Card |
+
+## Cómo utilizar el modelo
+
+```python
+import json
+import numpy as np
+import torch
+from safetensors.torch import load_file
+from modelo import RegresionLineal
+
+config = json.load(open("config.json"))
+media = np.array(config["normalizacion"]["media"], dtype="float32")
+desvio = np.array(config["normalizacion"]["desvio"], dtype="float32")
+
+modelo = RegresionLineal(n_entradas=3)              # 1. el modelo vacío
+modelo.load_state_dict(load_file("model.safetensors"))  # 2. se le cargan los pesos
+modelo.eval()
+
+casa = np.array([[80, 1, 0]], dtype="float32")
+with torch.no_grad():
+    print(modelo(torch.tensor((casa - media) / desvio)))  # tensor([[148.5]])
+```
+
+## Limitaciones
+
+- Tiene fines exclusivamente educativos. Los datos son sintéticos y no representan precios reales.
+- Solo conoce casas de 35 a 120 m².
+- **Si se olvida la normalización, las predicciones dan cualquier cosa.** Los pesos solos no alcanzan: hace falta `config.json`.
+- Para cargar los pesos hace falta la misma arquitectura (`modelo.py`). Si cambia la clase, `load_state_dict` falla.
+- A diferencia de pickle o joblib, **safetensors no ejecuta código al cargarse**: solo contiene números.
+
+## Autoría
+
+Modelo desarrollado con fines educativos para el IFTS N.º 18. Docente: Cynthia M. Villagra.

config.json

@@ -0,0 +1,21 @@
+{
+  "arquitectura": "RegresionLineal (torch.nn.Linear)",
+  "entradas": [
+    "m2",
+    "balcon",
+    "ascensor"
+  ],
+  "salida": "precio (miles de US$)",
+  "normalizacion": {
+    "media": [
+      78.51875305175781,
+      0.46875,
+      0.512499988079071
+    ],
+    "desvio": [
+      23.397640228271484,
+      0.4990224838256836,
+      0.4998437762260437
+    ]
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4f87d90c7f81d67c5ce4da4e585bad567d702ff36ebffe9e3e8747fb0f9e93ea
+size 160

modelo.py

@@ -0,0 +1,16 @@
+"""Arquitectura del modelo. La usan train.py y predict.py.
+
+PyTorch no guarda la clase dentro del archivo de pesos: para cargar model.safetensors
+hay que volver a crear el mismo modelo vacío y después cargarle los pesos.
+"""
+
+import torch
+
+
+class RegresionLineal(torch.nn.Module):
+    def __init__(self, n_entradas=3):
+        super().__init__()
+        self.lineal = torch.nn.Linear(n_entradas, 1)  # pesos (w) y bias (b)
+
+    def forward(self, x):
+        return self.lineal(x)

predict.py

@@ -0,0 +1,34 @@
+"""Carga model.safetensors + config.json y predice el precio de casas nuevas.
+
+Uso:
+    python predict.py
+"""
+
+import json
+from pathlib import Path
+
+import numpy as np
+import torch
+from safetensors.torch import load_file
+
+from modelo import RegresionLineal
+
+CARPETA = Path(__file__).parent
+
+# 1. Leer la configuración (entradas y normalización)
+config = json.loads((CARPETA / "config.json").read_text(encoding="utf-8"))
+media = np.array(config["normalizacion"]["media"], dtype="float32")
+desvio = np.array(config["normalizacion"]["desvio"], dtype="float32")
+
+# 2. Crear el modelo vacío y cargarle los pesos entrenados
+modelo = RegresionLineal(n_entradas=len(config["entradas"]))
+modelo.load_state_dict(load_file(CARPETA / "model.safetensors"))
+modelo.eval()
+
+# 3. Predecir: las entradas se normalizan igual que en el entrenamiento
+casas_nuevas = np.array([[50, 0, 0], [80, 1, 0], [110, 1, 1]], dtype="float32")
+with torch.no_grad():
+    precios = modelo(torch.tensor((casas_nuevas - media) / desvio)).numpy().ravel()
+
+for casa, precio in zip(casas_nuevas, precios):
+    print(f"{dict(zip(config['entradas'], casa.astype(int).tolist()))} -> {precio:.1f} miles de US$")

predict_hub.py

@@ -0,0 +1,41 @@
+"""Descarga el modelo desde Hugging Face Hub y predice EN ESTA PC (o en el servidor donde corra).
+
+En PyTorch del Hub se bajan los pesos y la configuración, pero la arquitectura
+(la clase RegresionLineal) tiene que estar en tu código: por eso se importa modelo.py.
+
+Uso:
+    python predict_hub.py tu-usuario/regresion-casas-pytorch
+"""
+
+import json
+import sys
+
+import numpy as np
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+from modelo import RegresionLineal
+
+REPO_ID = sys.argv[1] if len(sys.argv) > 1 else "TU-USUARIO/regresion-casas-pytorch"
+
+# 1. Bajar los dos archivos que hacen falta
+ruta_pesos = hf_hub_download(repo_id=REPO_ID, filename="model.safetensors")
+ruta_config = hf_hub_download(repo_id=REPO_ID, filename="config.json")
+
+# 2. Armar el modelo vacío, cargarle los pesos y leer la normalización
+with open(ruta_config, encoding="utf-8") as f:
+    config = json.load(f)
+media = np.array(config["normalizacion"]["media"], dtype="float32")
+desvio = np.array(config["normalizacion"]["desvio"], dtype="float32")
+
+modelo = RegresionLineal(n_entradas=len(config["entradas"]))
+modelo.load_state_dict(load_file(ruta_pesos))
+modelo.eval()
+
+# 3. Predecir
+casas_nuevas = np.array([[50, 0, 0], [80, 1, 0], [110, 1, 1]], dtype="float32")
+with torch.no_grad():
+    precios = modelo(torch.tensor((casas_nuevas - media) / desvio)).numpy().ravel()
+for casa, precio in zip(casas_nuevas, precios):
+    print(f"{dict(zip(config['entradas'], casa.astype(int).tolist()))} -> {precio:.1f} miles de US$")

requirements.txt

@@ -0,0 +1,6 @@
+torch>=2.1
+safetensors
+numpy
+pandas
+scikit-learn  # solo lo usa train.py, para separar train/test y medir
+huggingface_hub  # para descargar el modelo desde el Hub o publicarlo

train.py

@@ -0,0 +1,83 @@
+"""Entrena una regresión lineal con PyTorch y la exporta a model.safetensors + config.json.
+
+Mismo problema que el ejemplo 01: precio de una casa a partir de m², balcón y ascensor.
+
+Diferencia importante con scikit-learn: PyTorch guarda solo los pesos (state_dict).
+La clase del modelo y la normalización de las entradas no viajan en el archivo de pesos,
+así que la normalización se guarda aparte, en config.json.
+
+Uso:
+    python train.py
+"""
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+from safetensors.torch import save_file
+from sklearn.metrics import mean_absolute_error, r2_score
+from sklearn.model_selection import train_test_split
+
+from modelo import RegresionLineal
+
+CARPETA = Path(__file__).parent
+ENTRADAS = ["m2", "balcon", "ascensor"]
+torch.manual_seed(42)
+
+
+def generar_casas(n=200, semilla=42):
+    """Dataset sintético de la Clase 10 (misma semilla, mismos datos)."""
+    rng = np.random.default_rng(semilla)
+    m2 = rng.integers(35, 121, n)
+    balcon = rng.integers(0, 2, n)
+    ascensor = rng.integers(0, 2, n)
+    precio = 1.5 * m2 + 8 * balcon + 12 * ascensor + 20 + rng.normal(0, 4, n)
+    return pd.DataFrame({"m2": m2, "balcon": balcon, "ascensor": ascensor, "precio": precio.round(1)})
+
+
+# 1. Datos
+casas = generar_casas()
+X = casas[ENTRADAS].to_numpy(dtype="float32")
+y = casas["precio"].to_numpy(dtype="float32").reshape(-1, 1)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+# Normalización: se calcula SOLO con los datos de entrenamiento y se guarda para predecir
+media = X_train.mean(axis=0)
+desvio = X_train.std(axis=0)
+X_train_t = torch.tensor((X_train - media) / desvio)
+y_train_t = torch.tensor(y_train)
+
+# 2. Modelo, función de pérdida y optimizador
+modelo = RegresionLineal(n_entradas=len(ENTRADAS))
+perdida_fn = torch.nn.MSELoss()
+optimizador = torch.optim.SGD(modelo.parameters(), lr=0.1)
+
+# 3. El ciclo de entrenamiento
+for epoca in range(500):
+    prediccion = modelo(X_train_t)             # el modelo predice
+    perdida = perdida_fn(prediccion, y_train_t)  # la pérdida mide el error
+    optimizador.zero_grad()
+    perdida.backward()                         # se calculan los gradientes
+    optimizador.step()                         # el optimizador corrige pesos y bias
+    if epoca % 100 == 0:
+        print(f"época {epoca:3d} · pérdida (MSE) {perdida.item():.2f}")
+
+# 4. Evaluación con datos que el modelo no vio
+modelo.eval()
+with torch.no_grad():
+    pred_test = modelo(torch.tensor((X_test - media) / desvio)).numpy()
+print(f"MAE en test: {mean_absolute_error(y_test, pred_test):.2f} miles de US$")
+print(f"R² en test:  {r2_score(y_test, pred_test):.3f}")
+
+# 5. Exportación: pesos en safetensors, todo lo demás en config.json
+save_file(modelo.state_dict(), CARPETA / "model.safetensors")
+config = {
+    "arquitectura": "RegresionLineal (torch.nn.Linear)",
+    "entradas": ENTRADAS,
+    "salida": "precio (miles de US$)",
+    "normalizacion": {"media": media.tolist(), "desvio": desvio.tolist()},
+}
+(CARPETA / "config.json").write_text(json.dumps(config, indent=2, ensure_ascii=False), encoding="utf-8")
+print("Modelo guardado en model.safetensors + config.json")