# Recetas de entrenamiento de Ornith (anexo de investigación)

Estado: **NOT RUN** para modelos, GPU, hosts remotos y entrenadores. Se
comprobaron el validador JSONL, las máscaras de respuesta y el modo de
planificación con datos ficticios. No se instaló un entorno GPU.

Este anexo es deliberadamente más estrecho que `work/atlas-v46/datasets.md`:
fija entrypoints upstream de entrenamiento y entrega un flujo seguro de
destilación de respuestas. No afirma que un 3090 pueda entrenar ninguno de los
checkpoints. Para ese hardware sólo es válido un smoke test escalonado con
memoria, rendimiento, pérdida y contrato end-to-end observados.

## Qué está soportado realmente por upstream

La familia base es Qwen3.5. La documentación de Transformers describe una
arquitectura multimodal híbrida 3:1, con atención lineal/completa, y clases
separadas para modelos densos y MoE. Esto es contexto arquitectónico, no prueba
de que una revisión concreta de Ornith sea entrenable en todas las bibliotecas.
Carga la revisión exacta de Ornith, enumera sus módulos y ejecuta un
forward/backward de un batch antes de elegir targets de LoRA.

TRL expone las CLI `trl sft` y `trl distillation` (esta última experimental);
su entrenador SFT admite mensajes conversacionales, PEFT y pérdida sólo sobre
assistant, pero esa máscara requiere una plantilla de chat compatible. PEFT
admite `target_modules` normales y, para tensores `nn.Parameter` fusionados de
expertos MoE, `target_parameters`; su documentación advierte que los adapters
de expertos pueden añadir coste en inferencia hasta fusionarlos. BitsAndBytes
documenta QLoRA de 4 bits como entrenamiento de parámetros adicionales, no de
los pesos cuantizados completos.

La guía específica de Qwen3.5 de Unsloth impone una restricción importante:
desaconseja QLoRA de 4 bits para Qwen3.5 denso y MoE por diferencias de
cuantización inusuales, y recomienda LoRA BF16 para MoE. Sus cifras publicadas
de VRAM son mínimos reportados por el proveedor para su propio stack, no una
promesa para Ornith, Transformers, PEFT ni un 3090. Por eso la primera corrida
de Ornith debe ser LoRA BF16 con secuencia muy corta, no una conversión ciega a
4 bits.

## Secuencia recomendada: maestro 35B-A3B → alumno 9B

1. **Congelar contrato y holdout.** Crea splits train/eval por tarea antes de
   generar datos del maestro. Mantén en holdout los schemas de herramientas,
   casos de no llamada, argumentos malformados, errores, reintentos y parada.
   Divide por familia de tarea/herramienta, no por turno. Nunca expongas
   chain-of-thought privado; conserva sólo llamadas observables, resultados de
   herramientas y respuestas finales.
2. **Generar y verificar externamente las filas del maestro.** Registra ID y
   revisión inmutable del modelo, tarea/prompt, parámetros de muestreo y
   veredicto del checker. Conserva sólo filas con `quality_pass=true`. El
   checker debe validar schema JSON/de herramientas, `call_id` y tests de código;
   la confianza del maestro no es una prueba.
3. **Primero, destilación de respuesta.** Los modelos 35B-A3B y 9B tienen
   clases de modelo distintas; aquí NO se ha establecido equivalencia entre sus
   tokenizers. Entrena el 9B con la respuesta observable validada del maestro y
   el tokenizer del alumno. No copies token IDs ni apliques matching KL/logit
   hasta demostrar compatibilidad de vocabularios, tokens especiales y
   alineación de posiciones. Empieza con SFT, no con KL on-policy.
4. **Smoke test del adapter del alumno.** Prepara una prueba LoRA BF16 de una
   muestra, hasta 256 tokens, batch 1, acumulación de gradiente 1,
   checkpointing activado y un paso de optimizador. Registra memoria libre de la
   GPU antes/después de cargar y el pico forward/backward/optimizer. Después
   ejecuta el mismo canary de contrato contra base y adapter.
5. **Escalar una variable cada vez.** Aumenta longitud, muestras, rank o targets
   sólo cuando la corrida previa sea reproducible. Conserva un eval congelado y
   compara tasa de llamadas válidas, precisión de no llamada, validez de
   argumentos/schema, recuperación de errores, calidad en español y latencia;
   no sólo la pérdida de entrenamiento.

Esta dirección es una propuesta para estudiar un alumno más pequeño, no una
mejora de utilidad o velocidad ya medida. Otras direcciones también pueden ser
útiles si el maestro aporta respuestas verificadas; el tamaño por sí solo no
determina la calidad de los ejemplos.

## Recetas LoRA/QLoRA (puntos de partida, no afirmaciones)

### 9B denso

Empieza con LoRA BF16. Enumera `named_modules()` del checkpoint exacto de Ornith
y apunta sólo a proyecciones lingüísticas después de confirmar sus nombres; no
uses `all-linear` a ciegas en un modelo multimodal porque puede incluir la torre
visual. Un primer sondeo conservador es rank 8–16, alpha igual al rank, dropout
0.05, batch 1, gradient checkpointing y secuencia máxima inicial 256. Son knobs
experimentales, no valores medidos para Ornith.

QLoRA genérico (NF4 + LoRA) está documentado por Transformers/BitsAndBytes,
pero aquí no se propone como sustitución automática si BF16 no cabe. Eso
requiere una investigación de compatibilidad aparte. No mezcles un archivo GGUF, un
checkpoint BnB de 4 bits y un checkpoint Transformers original en una receta:
los loaders y las plantillas de chat difieren.

### 35B-A3B MoE

Empieza con LoRA BF16 en proyecciones ordinarias de atención/compartidas,
congelando router y expertos. Si ese smoke test es estable, prueba LoRA sobre
expertos como experimento separado mediante `target_parameters` de PEFT para los
tensores fusionados exactos y un `rank_pattern` reducido; mide entrenamiento e
inferencia posterior al merge. PEFT advierte que adapters de expertos sin
fusionar pueden materializar todos los expertos y ralentizar inferencia. No
deduzcas que un router top-k hace caber todo el modelo en VRAM: siguen contando
parámetros completos, optimizer, activaciones y ruta visual.

La advertencia de cuantización anterior también afecta al MoE. Un maestro 35B-A3B puede
servirse o generar lotes por separado, pero eso no significa que pueda
entrenarse simultáneamente con el alumno en una tarjeta de 24 GB.

## Entry points ejecutables upstream (todos NOT RUN aquí)

Estas son las superficies upstream que deben fijarse en un entorno aislado:

- [TRL CLI](https://github.com/huggingface/trl/blob/main/docs/source/clis.md):
  `trl sft --config sft.yaml`; la misma página documenta `trl distillation`.
- [TRL SFT trainer](https://huggingface.co/docs/trl/sft_trainer): usa JSONL
  conversacional y `SFTConfig(assistant_only_loss=True)` sólo después de
  verificar que la plantilla de Ornith emite markers de generación.
- [TRL distillation trainer](https://github.com/huggingface/trl/blob/main/trl/experimental/distillation/distillation_trainer.py):
  scoring experimental on-policy del maestro; fija la versión y no supongas
  soporte multimodal de Ornith a partir de un ejemplo causal-LM.
- [TRL MiniLLM trainer](https://github.com/huggingface/trl/blob/main/trl/experimental/minillm/minillm_trainer.py):
  KD experimental por logits/on-policy para causal LMs; no es una receta directa
  para dos clases multimodales de Ornith.
- [PEFT LoRA API](https://huggingface.co/docs/peft/en/package_reference/lora):
  `LoraConfig`, `target_modules`, `target_parameters` y rank patterns.
- [Transformers BitsAndBytes guide](https://huggingface.co/docs/transformers/v4.50.0/quantization/bitsandbytes):
  `BitsAndBytesConfig` y la limitación explícita de que el entrenamiento 4/8-bit
  es para parámetros adicionales.
- [Accelerate FSDP/DeepSpeed guide](https://github.com/huggingface/accelerate/blob/main/docs/source/concept_guides/fsdp_and_deepspeed.md):
  `accelerate launch --config_file ...` para sharding single-node multi-GPU.
- [Unsloth Qwen3.5 fine-tuning guide](https://unsloth.ai/docs/models/qwen3.5/fine-tune):
  ejemplos BF16 LoRA y advertencia sobre 4 bits. Sustituye el ID Qwen sólo
  después de probar compatibilidad de clase/plantilla con Ornith.
- [Microsoft MiniLLM repository](https://github.com/microsoft/LMOps/tree/main/minillm):
  implementación primaria de investigación; su rama Transformers modificada y
  supuestos causal-LM la convierten en referencia, no en comando seguro para
  Ornith.

El YAML ilustrativo anterior se eliminó durante la consolidación: no activaba
LoRA y una ruta JSONL local no es automáticamente un ID de dataset Hub. No
trates un YAML esquemático como receta ejecutable para Ornith. El archivo
`training-examples/train_lora_smoke.py` incluido proporciona un loader JSONL
local explícito, targets LoRA y un paso de optimizador. Sus comprobaciones de
plan/máscara corren offline; la carga GPU, backward y recarga del adapter siguen
en estado NOT RUN.

Si se requiere una corrida multi-GPU, usa un config de Accelerate revisado por
separado:

```bash
accelerate launch --config_file accelerate-fsdp.yaml path/to/pinned_train.py
```

El comando local de `training-examples/` prepara `train.jsonl` y `eval.jsonl`
sin red; no es un entrenador ni construye trayectorias de herramientas: el
fixture valida pares `user`/`assistant` y controles de contaminación.

## Ejemplo offline y verificación

```bash
cd training-examples
python3 prepare_distill_dataset.py \
  --input teacher_candidates.jsonl \
  --output-dir resultados-distill
python3 -m unittest -v test_prepare_distill_dataset.py
```

El validador rechaza IDs duplicados, veredictos de calidad ausentes/fallidos,
campos de razonamiento privado, splits vacíos, task keys duplicadas y solapamiento
train/eval por task key o huella de prompt normalizada. Emite filas
`messages` compatibles con OpenAI y un manifest con conteos y hashes de salida.
El fixture es sintético y pequeño; es un test de contrato, no un resultado de
calidad.

## Puertas de aceptación para ia-lab

Antes de cualquier cambio remoto, captura revisión exacta del checkpoint,
versiones de Python/Torch/Transformers/TRL/PEFT/BitsAndBytes, GPU/driver,
plantilla de chat, lista de targets y revisiones git. Ejecuta después, en orden:

1. Checks CPU-only de JSONL y enumeración de targets.
2. Forward/backward de una muestra con LoRA BF16 de 9B.
3. Generación pequeña del maestro 35B separada del entrenamiento del alumno.
4. Corrida de un paso del adapter, logs de memoria/pérdida y luego inferencia
   con adapter fusionado.
5. Holdout de contrato congelado y canary por la ruta de serving (mismo parser,
   streaming, schema de tool-call y comportamiento de parada de producción).

Un OOM, clase no soportada, markers de generación ausentes, llamada inválida o
regresión de calidad es una puerta fallida. No hay afirmación de que quepa en un
3090 hasta contar con estas mediciones.

## Resumen de riesgos y límites (menos de 1000 palabras)

- **Compatibilidad no demostrada:** que Transformers documente Qwen3.5 o que
  Ornith publique un loader no prueba que su revisión concreta admita backward,
  PEFT, pérdida sólo de assistant o multimodalidad en la versión instalada.
  Hay que fijar versiones, revisar la plantilla y ejecutar el smoke test.
- **Tokenización y destilación:** aquí no se afirma que los tokenizers sean
  distintos; sólo que la equivalencia entre 35B-A3B y 9B no está establecida.
  Por eso se recomienda respuesta observable con tokenizer del alumno y se
  bloquea KL/logit hasta verificar vocabulario, tokens especiales y posiciones.
- **Fuga de evaluación:** dividir por turno puede poner la misma tarea, schema o
  prompt en train y eval. El ejemplo sólo comprueba pares user/assistant y
  hashes/task keys; no ejecuta herramientas ni verifica calidad semántica.
  El checker externo debe validar llamadas, errores, código y holdout congelado.
- **Razonamiento privado y datos sensibles:** las salidas del maestro pueden
  incluir chain-of-thought, secretos o contenido de usuario. Deben filtrarse
  antes de publicar o entrenar; sólo deben conservarse campos observables y
  provenance suficiente para auditar.
- **Cuantización:** QLoRA genérico no equivale a soporte Qwen3.5/Ornith. La
  guía específica desaconseja 4-bit en esta familia; comparar NF4 sólo como
  experimento aislado, midiendo calidad y compatibilidad. GGUF, BnB y
  Transformers no son intercambiables por nombre.
- **MoE:** `target_parameters` puede aumentar coste y overhead, especialmente
  sin merge. Congelar router/expertos inicialmente reduce variables, pero no
  garantiza balance, calidad ni memoria.
- **Hardware:** no se infiere capacidad de un 3090 ni de una cifra de VRAM de
  terceros. Secuencia, activaciones, optimizer, visión, contexto y concurrencia
  deben medirse en ia-lab; el maestro y alumno pueden requerir corridas separadas.
- **Producción:** una pérdida menor o una respuesta textual correcta no prueba
  streaming, parser, call IDs, parada, reintentos o recuperación de errores.
  La aceptación exige comparar base/adapter en el mismo serving path y holdout.
