{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "# 07 · Una cabeza nueva y un adaptador que aprende\n\n¿Qué aprende un adaptador si casi todo el modelo está congelado? Este\nexperimento permite verlo: el encoder es un **BERT diminuto inicializado al\nazar**, y la tarea distingue dos grupos de tokens sintéticos. No reconoce\nlenguaje y no usa conocimiento preentrenado. Sirve para explorar la mecánica\nde PEFT antes de aplicarla a un modelo permitido por una tarea real.\n\nEsta referencia entrena adaptadores y cabeza.\nLa configuración conserva la cabeza nueva como entrenable. Prueba qué ocurre\nal omitir `modules_to_save` y mira sus parámetros, sin confundir un código\nque corre con una cabeza que aprende.\n\nTodo usa CPU, sin red ni archivos de modelos externos. Datos sintéticos\ngenerados con semilla fija, CC0-1.0. Requiere el entorno de estudio con\nPyTorch, Transformers, PEFT y matplotlib. 60–90 minutos de exploración, sin límite de juez.\n",
   "id": "07-s-00"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "from pathlib import Path\nimport json\nimport numpy as np\nimport torch\nfrom torch import nn\nfrom torch.utils.data import DataLoader, TensorDataset\nfrom transformers import BertConfig, BertModel\nimport matplotlib.pyplot as plt\n\ntorch.set_num_threads(1)\ntorch.manual_seed(4)\ng = torch.Generator().manual_seed(41)\ndef muestras(n, longitud):\n    y = torch.arange(n) % 2\n    ids = torch.randint(1, 24, (n, longitud), generator=g) + y[:, None] * 24\n    return ids, torch.ones_like(ids), y\ntrain = muestras(96, 5)\nval = muestras(48, 5)\nnuevo = muestras(48, 10)\nencoder = BertModel(BertConfig(vocab_size=48, hidden_size=32,\n    intermediate_size=64, num_hidden_layers=1, num_attention_heads=4,\n    hidden_dropout_prob=0., attention_probs_dropout_prob=0.))\npesos_base = [(p, p.detach().clone()) for p in encoder.parameters()]\n",
   "id": "07-s-01"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "# bloque: probado; id: clasificador_texto\nimport torch\n\nclass Clasificador(torch.nn.Module):\n    def __init__(self, encoder, n_clases):\n        super().__init__()\n        self.encoder = encoder\n        self.cabeza = torch.nn.Linear(encoder.config.hidden_size, n_clases)\n\n    def forward(self, ids, mascara):\n        h = self.encoder(input_ids=ids, attention_mask=mascara).last_hidden_state\n        m = mascara.unsqueeze(-1)\n        vector = (h * m).sum(1) / m.sum(1).clamp(min=1)     # mean pooling enmascarado\n        return self.cabeza(vector)                          # logits, sin softmax\n",
   "id": "07-s-02"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "modelo = Clasificador(encoder, n_clases=2).eval()\nwith torch.no_grad():\n    logits_sin_lora = modelo(val[0], val[1]).clone()\n",
   "id": "07-s-03"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## La actualización empieza en cero; sus factores no\n\nEn la inicialización estándar, A es aleatoria y B es cero. El producto\n`B @ A` es cero, de modo que insertar el adaptador no cambia inicialmente\nla función. Si los dos factores fueran cero, ambos gradientes serían cero.\nLa cabeza es nueva y también tiene que aprender: PEFT la conserva con\n`modules_to_save=[\"cabeza\"]`.\n",
   "id": "07-s-04"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "# bloque: probado; id: lora_cabeza\nfrom peft import LoraConfig, get_peft_model\n\nconfig = LoraConfig(r=8, lora_alpha=16, lora_dropout=0.05,\n                    target_modules=[\"query\", \"value\"],\n                    modules_to_save=[\"cabeza\"])  # la cabeza NUEVA también aprende\nmodelo = get_peft_model(modelo, config)\nmodelo.print_trainable_parameters()      # la proporción depende de la arquitectura\n",
   "id": "07-s-05"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "modelo.eval()\nwith torch.no_grad():\n    logits_iniciales = modelo(val[0], val[1])\nassert torch.allclose(logits_iniciales, logits_sin_lora, atol=1e-6)\nentrenables = {n: p for n, p in modelo.named_parameters() if p.requires_grad}\nantes = {n: p.detach().clone() for n, p in entrenables.items()}\nfor nombre, p in entrenables.items():\n    print(nombre, tuple(p.shape))\nprint(\"Entrenables:\", sum(p.numel() for p in entrenables.values()))\nprint(\"Totales:\", sum(p.numel() for p in modelo.parameters()))\n",
   "id": "07-s-06"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "EPOCAS = 20\nLR = 0.01  # tarea sintética diminuta; no trasladar este valor a un encoder grande\n",
   "id": "07-s-07"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "def medir(datos):\n    modelo.eval()\n    with torch.no_grad():\n        logits = modelo(datos[0], datos[1])\n        perdida = nn.functional.cross_entropy(logits, datos[2]).item()\n        accuracy = (logits.argmax(1) == datos[2]).float().mean().item()\n    return perdida, accuracy\n\nbaseline = medir(val)[1]\noptimizador = torch.optim.AdamW(entrenables.values(), lr=LR, weight_decay=0.)\ncargador = DataLoader(TensorDataset(*train), batch_size=24, shuffle=True,\n                     generator=torch.Generator().manual_seed(8))\nhistorial = [(*medir(train), *medir(val))]\nfor epoca in range(EPOCAS):\n    modelo.train()\n    for ids, mascara, y in cargador:\n        optimizador.zero_grad(set_to_none=True)\n        perdida = nn.functional.cross_entropy(modelo(ids, mascara), y)\n        perdida.backward()\n        optimizador.step()\n    historial.append((*medir(train), *medir(val)))\nresultado = {\"baseline\": baseline, \"validacion\": medir(val)[1],\n             \"transferencia\": medir(nuevo)[1]}\ncurvas = np.asarray(historial)\nfig, ejes = plt.subplots(1, 2, figsize=(10, 3.5))\nejes[0].plot(curvas[:, 0], label=\"train\")\nejes[0].plot(curvas[:, 2], label=\"validación\")\nejes[0].set(xlabel=\"época\", ylabel=\"cross-entropy\"); ejes[0].legend()\nejes[1].plot(curvas[:, 1], label=\"train\")\nejes[1].plot(curvas[:, 3], label=\"validación\")\nejes[1].set(xlabel=\"época\", ylabel=\"accuracy\", ylim=(0, 1.05)); ejes[1].legend()\nfig.tight_layout(); plt.show()\n",
   "id": "07-s-08"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## Ver la matriz que aprendió\n\nCada mapa tiene 32 filas y 32 columnas: una actualización de la proyección\nquery. Aunque el adaptador la representa mediante dos factores, su efecto\nse suma a la matriz completa. El factor `alpha/r` también importa.\nUna actualización distinta de cero no implica que mejore cualquier tarea.\n",
   "id": "07-s-09"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "adaptador = next(m for m in modelo.modules() if hasattr(m, \"lora_A\") and \"default\" in m.lora_A)\nA = adaptador.lora_A[\"default\"].weight.detach()\nB = adaptador.lora_B[\"default\"].weight.detach()\ndelta = (B @ A * adaptador.scaling[\"default\"]).cpu().numpy()\nfigura, eje = plt.subplots(figsize=(4.5, 4))\nlimite = max(float(np.abs(delta).max()), 1e-8)\nmapa = eje.imshow(delta, cmap=\"RdBu_r\", vmin=-limite, vmax=limite)\neje.set(title=\"Actualización LoRA de query\", xlabel=\"entrada\", ylabel=\"salida\")\nfigura.colorbar(mapa, ax=eje); figura.tight_layout(); plt.show()\ncambios = {n: float((p.detach() - antes[n]).abs().max()) for n, p in entrenables.items()}\nresultado[\"cambio_maximo_cabeza\"] = max(v for n, v in cambios.items() if \"cabeza\" in n)\nresultado[\"cambio_maximo_adaptador\"] = max(v for n, v in cambios.items() if \"lora_\" in n)\nresultado[\"encoder_base_intacto\"] = all(torch.equal(p, original) for p, original in pesos_base)\n",
   "id": "07-s-10"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## Cambiar la pregunta\n\nLa transferencia duplica la longitud y conserva la regla de tokens. Compara\nambas accuracies y luego mezcla algunos tokens del otro grupo: el problema\nya no tiene la misma señal.\n\nMira los nombres de los parámetros de la cabeza con y sin `modules_to_save`.\nUn porcentaje pequeño de parámetros entrenables no demuestra que hayas\nelegido los correctos. Después prueba r=2 y r=16 y observa tamaño de la\nactualización, tiempo y validación.\n\nPara pasar a lenguaje real necesitas una preparación separada con el encoder\npermitido, su tokenizador, datos de train y validación apropiados. Este\nnotebook no mide el beneficio del preentrenamiento ni valida una ejecución\noficial o en GPU. El learning rate del juguete tampoco calibra ese caso.\n",
   "id": "07-s-11"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "assert resultado[\"validacion\"] > resultado[\"baseline\"]\nassert resultado[\"validacion\"] >= 0.85 and resultado[\"transferencia\"] >= 0.85\nassert resultado[\"cambio_maximo_cabeza\"] > 0\nassert resultado[\"cambio_maximo_adaptador\"] > 0\nassert resultado[\"encoder_base_intacto\"]\n",
   "id": "07-s-12"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "resultado.update({\"laboratorio\": '07_lora',\n                  \"version\": 'solución de referencia',\n                  \"metrica\": 'accuracy sobre secuencias de tokens sintéticos (mayor es mejor)', \"split\": '96 train, 48 validación y 48 transferencia; generador torch con semilla 41, transferencia duplica longitud de 5 a 10'})\nPath(\"resultado.json\").write_text(json.dumps(resultado, ensure_ascii=False,\n                  indent=2, allow_nan=False) + \"\\n\", encoding=\"utf-8\")\nprint(json.dumps(resultado, ensure_ascii=False, indent=2))\n",
   "id": "07-s-13"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
