# Atlas Ornith v4.6 — datasets, PEFT, evaluación y destilación

Estado de este capítulo: investigación documental y diseño de recetas. No se descargaron datasets ni pesos, no se entrenó nada y no se modificó ningún runtime. Fecha de verificación de enlaces y metadatos: 2026-09-23.

[TOC]

## 1. Decisión de diseño

El dataset no arregla por sí solo el contrato de Codex/OpenCode. Antes de entrenar, fijar y probar el contrato observable: plantilla de chat, nombres y esquema de herramientas, serialización de `tool_calls`, `call_id`, política de reintentos, streaming, parada, errores y evaluación end-to-end. Un SFT que sólo memoriza texto puede empeorar la decisión «no llamar a una herramienta» o producir JSON correcto pero incompatible con el parser.

Mantener dos líneas de experimento independientes:

| Línea | Base | Objetivo inicial | Lo que no se debe mezclar |
|---|---|---|---|
| Densa | `ornith-ai/Ornith-1.5-9B` | contrato de herramientas, programación y español | supuestos de MoE, pesos de expertos, resultados de 35B |
| MoE | `ornith-ai/Ornith-1.5-35B-A3B` | tool-use y/o destilación con presupuesto controlado | targets de una arquitectura densa, cifras de VRAM de 9B |

Las tarjetas oficiales describen ambos como `Qwen3_5*ForConditionalGeneration`, con visión y texto. El `config.json` del 9B reporta `Qwen3_5ForConditionalGeneration`, 32 capas, `hidden_size=4096`, mezcla 3:1 de atención lineal/full y contexto máximo configurado de 262144. El 35B-A3B reporta `Qwen3_5MoeForConditionalGeneration`, 40 capas, `hidden_size=2048`, 256 expertos, top-8 y el mismo contexto configurado. Son hechos de configuración, no una garantía de entrenamiento estable a esa longitud.

## 2. Auditoría de los adjuntos locales solicitados

Se inspeccionaron exclusivamente estos cuatro paths (sin búsqueda masiva de `Downloads`):

- `/Users/lomelidev/Downloads/atlas_ornith_v4_4_pre_audio_auditoria_y_fuentes.json`
- `/Users/lomelidev/Downloads/atlas_ornith_v4_4_pre_audio_canonico_r2.json`
- `/Users/lomelidev/Downloads/atlas_ornith_v4_4_pre_audio_canonico_r3.json`
- `/Users/lomelidev/Downloads/atlas_ornith_v4_4_pre_audio_canonico_r3_1.json`

Resultado: no contienen un inventario de datasets de entrenamiento/evaluación ni filas JSONL entregadas por el agente. Contienen corpus y auditoría de vídeos/fuentes, con material bruto separado de las selecciones. No se reabre ni se altera aquí aquella decisión de corpus canónico. En la matriz, L6 se llama `L6_datasets_y_tool_use`, pero su fuente primaria es documentación de function calling, no un dataset. Los campos `datasets` presentes en R3/R3.1 son banderas booleanas (`false`), no referencias ni datos. Esta inspección de cuatro adjuntos no descarta que exista otra entrega en una tarea o archivo diferente.

Por tanto, no atribuyo al agente la entrega de BFCL, Codeforces, Alpaca-ES ni ningún otro dataset. El catálogo siguiente es investigación adicional y cada ficha separa fuente primaria, comunidad, licencia declarada y nivel de confianza.

## 3. Datasets recuperados de nuestra conversación anterior

La búsqueda histórica recuperó estos nombres que no estaban en los cuatro adjuntos locales. Se verificaron contra sus tarjetas/repositorios oficiales sin descargar datos. Esto corrige el alcance del catálogo: **los adjuntos siguen sin contener un inventario ni filas JSONL entregadas por el agente**, pero sí existe ahora una lista histórica verificable. Las licencias son las declaradas por la fuente; cuando los repositorios subyacentes tienen licencias adicionales, no se las simplifica a la licencia de la tarjeta.

| dataset oficial | uso recomendado | tamaño/formato/idioma observado | licencia y cautelas |
|---|---|---|---|
| [`nvidia/OpenCodeInstruct`](https://huggingface.co/datasets/nvidia/OpenCodeInstruct) | **training SFT de código**; separar por `domain` y filtrar por tests antes de mezclar | 5,000,000 filas `train`, Parquet; inglés; `input/output`, juicio, unit tests y estado de ejecución | Tarjeta NVIDIA: CC BY 4.0. Es sintético/híbrido y la tarjeta pide revisar si la licencia sirve al uso concreto. |
| [`SWE-Gym/SWE-Gym`](https://huggingface.co/datasets/SWE-Gym/SWE-Gym) | **training/trajectory generation** para agentes SWE: tareas reales, checkout ejecutable y verificación; no usar como holdout de SWE-bench | alrededor de 2.4k tareas de 11 repositorios Python según el repo del proyecto; Parquet en Hub; inglés | La tarjeta HF declara MIT, mientras el repositorio oficial del proyecto declara Apache-2.0. Las licencias de repositorios, imágenes y dependencias de cada tarea requieren auditoría separada; no asumir una licencia única. |
| [`SWE-bench/SWE-smith-py`](https://huggingface.co/datasets/SWE-bench/SWE-smith-py) / [`SWE-bench/SWE-smith-go`](https://huggingface.co/datasets/SWE-bench/SWE-smith-go) | **training de agentes/verificadores** o generación de trayectorias; mantener `patch`, `test_patch` y cualquier evaluación fuera del input si se quiere medir sin fuga | `train`; 50,908 Python y 8,210 Go en las tarjetas consultadas; Parquet; inglés; issue, patch, tests, repositorio e imagen ejecutable | Tarjetas declaran MIT. Los repositorios fuente, imágenes y dependencias tienen procedencia propia; auditar antes de redistribuir. No confundir con un split de evaluación de SWE-bench. |
| [`princeton-nlp/SWE-bench`](https://huggingface.co/datasets/princeton-nlp/SWE-bench) y [`SWE-bench/SWE-bench_Verified`](https://huggingface.co/datasets/SWE-bench/SWE-bench_Verified) | **holdout/evaluación**, no training: ejecutar el harness oficial con Docker; Verified es un conjunto de 500 problemas | SWE-bench `test` de 2,294 filas observado; Verified `test` de 500; Parquet; inglés; issue, repositorio, commits, patch y tests | El repositorio oficial SWE-bench declara MIT. Los repositorios evaluados, imágenes y contenido de terceros conservan sus propios términos. Preservar la revisión del benchmark y no entrenar con `patch`/`test_patch`. |
| [`ByteDance-Seed/Code-Contests-Plus`](https://huggingface.co/datasets/ByteDance-Seed/Code-Contests-Plus) | **training de programación/verificación** o evaluación aislada de soluciones; no es dataset multi-turn de herramientas | 11,690 problemas y más de 13M soluciones correctas/incorrectas; `default` y configs `1x`–`5x`, split `train`; Parquet; lenguaje de problemas/soluciones variable | Tarjeta y README declaran CC BY 4.0. Los casos 1x–5x son distintos niveles de tests, no holdouts; reservar una configuración/problemas propios si se mide generalización. |
| [`AmazonScience/SWE-PolyBench`](https://huggingface.co/datasets/AmazonScience/SWE-PolyBench) | **evaluación reservada** de agentes a nivel repositorio; no incorporarlo al training Atlas | CSV; 4 lenguajes (Python, Java, JavaScript, TypeScript); repo oficial anuncia 2,110 full, 500 sampled y 382 Verified; `test`/predictions + Docker evaluator | MIT declarado. La fuente oficial recomienda su evaluador y distingue full/PB500/PBv; conservar la revisión porque la tarjeta puede mostrar conteos distintos después de actualizaciones. |
| [`bigcode/the-stack-v2`](https://huggingface.co/datasets/bigcode/the-stack-v2) | **pretraining de código**, no SFT ni benchmark de agentes; considerar sólo después del contrato de procedencia | 600+ lenguajes; dataset principal contiene SWHIDs/metadatos y la documentación describe escala de decenas de TB; acceso condicionado | No es una licencia única: la tarjeta exige aceptar términos, acuerdo para descargas masivas y cumplir las licencias originales de cada repositorio, con provenance/removals. No llamar “permissive” al conjunto completo ni redistribuirlo sin revisión legal. |

Regla práctica: `OpenCodeInstruct`, SWE-Gym, SWE-smith y Code-Contests+ son candidatos de **training** (con filtrado y separación de tests); SWE-bench y SWE-PolyBench son **evaluación/holdout**; The Stack v2 es **pretraining/procedencia**, no una solución directa para tool use. Ninguno por sí solo arregla el contrato de herramientas o el comportamiento de Codex/OpenCode.

## 4. Catálogo para entrenamiento (no holdout)

Las cantidades son las publicadas por la tarjeta o por la vista de Dataset Viewer; cuando la vista está deshabilitada se conserva esa limitación. No descargar sin revisar licencia, procedencia y contaminación con el holdout.

### Programación

#### [open-r1/codeforces](https://huggingface.co/datasets/open-r1/codeforces)

- **Uso:** problemas de programación competitiva; opción `verifiable-prompts` ofrece prompt y lenguaje para generación de código. Adecuado para una mezcla pequeña de Python/C++ con verificación ejecutable, no para aprender el contrato de herramientas.
- **Licencia/procedencia:** CC-BY-4.0 declarada en la tarjeta; problemas y tests provienen de Codeforces y otros concursos, con atribución requerida.
- **Formato/tamaño:** Parquet; tarjeta indica unas 10k entradas. Configuraciones `default`, `verifiable`, `verifiable-prompts`; `train` y `test`. Los tests generados grandes son un artefacto separado (la tarjeta advierte ~110 GB), no parte de esta receta.
- **Regla:** entrenar sólo `train`; reservar `test` como holdout de código. Deduplicar por `id`/aliases y por hash de enunciado. El split `test` contiene problemas de finales de 2024/inicios de 2025 según la tarjeta; no usarlo para crear prompts.
- **Limitación:** principalmente inglés; comprobar idioma real antes de mezclar en el lote español.

#### [open-r1/verifiable-coding-problems-python](https://huggingface.co/datasets/open-r1/verifiable-coding-problems-python)

- **Uso:** SFT de generación de Python donde cada fila incluye enunciado, solución de referencia y casos de verificación.
- **Licencia/procedencia:** verificar la tarjeta y las licencias de los datos fuente antes de redistribuir; no asumir que “verificable” equivale a permiso irrestricto.
- **Formato/tamaño:** Parquet, un split `train`, repositorio de aproximadamente 2.69 GB según Hub; columnas observadas por Dataset Viewer: `source`, `task_type`, `problem_statement`, `gold_standard_solution`, `problem_id`, `metadata`, `verification_info`.
- **Regla:** usar una fracción train para SFT y generar un holdout propio por `problem_id`/URL antes de ver respuestas; ejecutar el checker fuera del modelo. No incorporar `gold_standard_solution` en el prompt de entrada.

### Herramientas, agentes y multi-turn

#### [tuandunghcmut/toolace](https://huggingface.co/datasets/tuandunghcmut/toolace) (conversión comunitaria de [Team-ACE/ToolACE](https://huggingface.co/datasets/Team-ACE/ToolACE))

- **Uso:** conversaciones multi-turn de tool use en formato uniforme; buen candidato para enseñar roles `user/assistant/tool` y llamadas secuenciales.
- **Licencia/procedencia:** Apache-2.0 declarada por la conversión; el card atribuye el original a Team-ACE y unas 11,300 conversaciones sintetizadas. Revisar ambos avisos antes de publicar un derivado.
- **Formato/tamaño:** Parquet, inglés, 10k–100k; columnas `messages` y `tools_json`, ambas descritas como JSON string.
- **Regla:** parsear JSON, validar que cada `tool_call_id` tenga un resultado, eliminar cadenas de razonamiento privadas y separar 90/10 por conversación, no por turno. No usar el mismo API/tool schema en train y eval si se pretende medir generalización.
- **Limitación:** el Dataset Viewer respondió 401 durante esta auditoría; el tamaño procede de la tarjeta y no se afirma lectura de filas privadas.

#### [product-science/xlam-function-calling-60k-raw](https://huggingface.co/datasets/product-science/xlam-function-calling-60k-raw) (derivado de Salesforce xLAM)

- **Uso:** 60k ejemplos de function calling, útiles para single-turn, múltiples funciones y argumentos estructurados; no es multi-turn completo.
- **Licencia/procedencia:** Apache-2.0 en la copia derivada; el original `Salesforce/xlam-function-calling-60k` declara CC-BY-4.0 y acceso con aceptación. Tratar la copia como derivado y conservar atribución a APIGen/Salesforce.
- **Formato/tamaño:** Parquet; `train` 57k y `test` aproximadamente 3k según tarjeta; columnas `query`, `id`, `answers`, `tools` observadas en Viewer. La fuente original es JSON y está gated.
- **Regla:** usar `train` sólo para enseñar llamada, argumentos y abstención. El `test` se reserva; no mezclarlo con BFCL si se publicará una cifra única sin declarar contaminación de familias.

#### [tuandunghcmut/xlam-function-calling-60k](https://huggingface.co/datasets/tuandunghcmut/xlam-function-calling-60k) (conversión OpenAI-compatible)

- **Uso:** alternativa práctica al raw: `messages` y `tools_json` en una sola fila, lista para adaptar al chat template.
- **Licencia/procedencia:** la tarjeta atribuye a `Salesforce/xlam-function-calling-60k`; revisar CC-BY-4.0 del original y la licencia de la conversión.
- **Formato/tamaño:** Parquet, 60k filas, un split `train`; `messages` y `tools_json` son JSON strings.
- **Regla:** usar sólo si se necesita una conversión ya normalizada; no contarla como dataset independiente junto con `product-science/xlam-function-calling-60k-raw`.

#### [ToolMind, conversión comunitaria](https://huggingface.co/datasets/AmanPriyanshu/tool-reasoning-sft-TOOLS-ToolMind-data-cleaned-rectified)

- **Uso:** corpus grande de trayectorias multi-turn con llamadas validadas; sólo después de auditar el origen de cada componente.
- **Licencia/procedencia:** Apache-2.0 declarada por la tarjeta comunitaria; la tarjeta dice combinar 128k trayectorias sintéticas y 152k instancias aumentadas de seis datasets. Es una afirmación del publicador, no validación primaria de cada fuente.
- **Formato/tamaño:** Parquet, inglés, 280k filas, `train`.
- **Regla:** no es mi primera receta por riesgo de duplicación y trazas de razonamiento explícitas. Si se usa, filtrar a salidas observables, registrar origen por fila y excluir cualquier ejemplo que reaparezca en un benchmark.

### Español y multilingüe

#### [pinzhenchen/alpaca-cleaned-es](https://huggingface.co/datasets/pinzhenchen/alpaca-cleaned-es)

- **Uso:** SFT general en español (instrucción, entrada opcional y salida).
- **Licencia/procedencia:** CC-BY-NC-4.0 declarada; traducción automática de `yahma/alpaca-cleaned`. No usar para un producto comercial sin aclarar la cláusula NC.
- **Formato/tamaño:** JSON; 51,760 filas; columnas `instruction`, `input`, `output`, observadas en Viewer. La tarjeta advierte errores de traducción en código, tareas cruzadas y corrección gramatical.
- **Regla:** usar como pequeño componente de estilo lingüístico, no como fuente de verdad técnica. Filtrar código defectuoso y validar manualmente una muestra.

#### [HiTZ/alpaca_mt](https://huggingface.co/datasets/HiTZ/alpaca_mt)

- **Uso:** instruction tuning multilingüe; la tarjeta incluye español y otras lenguas ibéricas.
- **Licencia/procedencia:** CC-BY-NC-4.0; traducción con NLLB-200 3.3B desde Alpaca. Revisar cláusula NC y atribución.
- **Formato/tamaño:** formato de dataset con columnas Alpaca (`instruction`, `input`, `output`, `text`); split por idioma, 52,002 ejemplos para `es` según la tarjeta.
- **Limitación:** Viewer deshabilitado porque el repositorio requiere código arbitrario; no ejecutar `trust_remote_code` sin revisión de seguridad. Es preferible convertir en un entorno aislado antes de cualquier uso.

#### [OpenAssistant/oasst1](https://huggingface.co/datasets/OpenAssistant/oasst1)

- **Uso:** conversaciones humanas multi-turn y preferencias, con español entre muchos idiomas; útil para construir estilo de diálogo, no específicamente tool use.
- **Licencia/procedencia:** Apache-2.0 declarada; proyecto OpenAssistant y paper enlazado.
- **Formato/tamaño:** Parquet y artefactos JSONL; `train` observado con 84.4k mensajes y `validation` separado. Cada fila contiene `message_id`, `parent_id`, `text`, `role`, `lang`, revisiones y árbol de conversación.
- **Regla:** reconstruir árboles por `message_tree_id`, filtrar `lang=es`, `deleted=false`, `review_result=true` y deduplicar por `message_id`. No convertir mensajes sueltos en multi-turn sin preservar padres.

#### [BSC-LT/ALIA-2606-SFT](https://huggingface.co/datasets/BSC-LT/ALIA-2606-SFT)

- **Uso:** mezcla SFT multilingüe de 714k conversaciones; puede aportar español, multi-turn, robustez y seguimiento exacto de instrucciones.
- **Licencia/procedencia:** CC-BY-4.0; BSC-LT declara mezcla humana y sintética en español, catalán, inglés, euskera, gallego y parte en portugués. La tarjeta indica uso en ALIA-40b-instruct-2606.
- **Formato/tamaño:** tarjeta Hub indica 100k–1M, un `train`, y metadatos de cinco lenguas; Viewer no estaba disponible en esta auditoría.
- **Regla:** seleccionar sólo filas con idioma español (y una proporción explícita de otras lenguas si se desea), conservar `source`/provenance y no usarlo como evaluación.

## 5. Holdouts y benchmarks: nunca entrenarlos

| Holdout | Qué mide | Tratamiento |
|---|---|---|
| `bengaliAI/BFCL` / Berkeley Function Calling Leaderboard | llamadas simples, paralelas, multi-turn y casos de no llamada; categorías con evaluación ejecutable | sólo evaluación. La tarjeta declara Apache-2.0 y 24 MB, pero advierte que no es compatible directamente con `load_dataset`; seguir su repositorio oficial. |
| `BSC-LT/IFEval_es` | 541 instrucciones verificables en español (formato, longitud, palabras clave) | sólo evaluación; CC-BY-4.0; la tarjeta dice que `test` no debe entrenar. |
| `open-r1/codeforces:test` | problemas recientes de programación con tests oficiales/generados | sólo evaluación de código; separar por `id` y aliases. |
| `SpreadsheetBench` verified-400 (referencia del adapter comunitario) | trayectorias de agentes de hojas de cálculo con herramienta real | sólo si se dispone de su licencia/runner; no inferir desempeño de Ornith desde el adapter. |
| contrato local Atlas | 20–50 tareas no vistas: no-call, llamada válida, JSON inválido, error de herramienta, reintento, parada y streaming | crear antes de entrenar, versionar hashes y mantener un subconjunto final congelado. |

El error más fácil es hacer un split aleatorio por turno. Para agentes, dividir por `conversation_id`, tarea, herramienta y dominio; de lo contrario el modelo ve la misma trayectoria o esquema en train y test.

## 6. Formato canónico JSONL para SFT

Preferir mensajes OpenAI-compatible y aplicar el chat template del checkpoint, no concatenar etiquetas manuales. Ejemplo mínimo (tres filas):

```jsonl
{"id":"es_001","messages":[{"role":"system","content":"Responde en español. Usa herramientas sólo cuando sean necesarias."},{"role":"user","content":"¿Qué archivos hay en /tmp?"},{"role":"assistant","tool_calls":[{"id":"call_001","type":"function","function":{"name":"list_dir","arguments":"{\"path\":\"/tmp\"}"}}]},{"role":"tool","tool_call_id":"call_001","content":"{\"entries\":[\"a.txt\"]}"},{"role":"assistant","content":"En /tmp hay un archivo: a.txt."}],"tools":[{"type":"function","function":{"name":"list_dir","description":"Lista un directorio","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}]}
{"id":"es_002","messages":[{"role":"user","content":"Resume este texto en dos frases: ..."},{"role":"assistant","content":"Primera frase. Segunda frase."}]}
{"id":"es_003","messages":[{"role":"user","content":"¿Puedes borrar todo?"},{"role":"assistant","content":"No llamo a una herramienta porque falta una ruta y una confirmación explícita."}]}
```

Validaciones obligatorias antes de tokenizar:

1. roles permitidos y alternancia; cada `tool_call_id` debe tener un `tool` posterior;
2. `arguments` debe ser JSON parseable y ajustarse al schema;
3. no incluir secretos, tokens, mensajes de usuario reales ni razonamiento privado;
4. verificar que `tools` y la plantilla de chat que se sirven sean idénticos a los del contrato;
5. enmascarar pérdida a tokens del asistente/tool-call (no optimizar sólo por una respuesta final copiada).

Para datos Alpaca, convertir `instruction/input/output` a `user/assistant` y conservar `id`/provenance. Para BFCL, conservar el runner oficial y no convertirlo silenciosamente a SFT.

## 7. Preparar un dataset sintético pequeño y auditable

Empieza con 30–100 conversaciones, no con cientos de miles. Diseña 10 familias de casos: no-call, llamada simple, argumentos opcionales, llamada paralela, dos turnos dependientes, resultado vacío, error transitorio/retry, error permanente, salida truncada y finalización. Genera variantes de nombres/valores sin poner credenciales reales. Cada fila debe tener `source="synthetic_atlas_v46"`, `generator_version`, `tool_schema_hash`, `expected_calls` y `split`.

Proporción inicial sugerida (hipótesis a medir, no garantía): 50% tool-call válido, 20% no-call, 15% recuperación/error, 10% multi-turn, 5% español técnico. Congela 20% como validación y 20–30 ejemplos finales como holdout escrito por una persona distinta al generador. Un modelo maestro puede proponer candidatos, pero un validador determinista debe rechazar JSON inválido y llamadas que no satisfagan el estado.

El script `datasets-examples/prepare_synthetic.py` sólo genera una muestra local de demostración y valida estructura; no llama a una API, no descarga nada y no debe tratarse como dataset de producción.

## 8. Receta PEFT/QLoRA: primero verificar targets reales

> **Actualización v4.7:** la [guía específica Qwen3.5 de Unsloth](https://unsloth.ai/docs/models/qwen3.5/fine-tune) desaconseja actualmente QLoRA de 4 bits para esta familia. La receta genérica anterior no está validada para Ornith. Empieza por [la guía revisada LoRA BF16](/laboratorio/entrenamiento/) y una prueba de un paso, no por un entrenamiento largo. El kit nuevo rechaza la ruta NF4 del trainer histórico. No se ejecutó entrenamiento GPU.

### 8.1 9B denso

PEFT documenta `target_modules="all-linear"` como opción genérica QLoRA, pero aquí no se usa como atajo automático: en un modelo multimodal puede incluir visión y en Qwen3.5 las capas son híbridas. El código oficial define `self_attn.q_proj/k_proj/v_proj/o_proj`, `mlp.gate_proj/up_proj/down_proj` y, para atención lineal, `linear_attn.in_proj_qkv/in_proj_z/in_proj_b/in_proj_a/out_proj`. No afirmar que todos existen en cada capa ni que todos sean seguros para un adapter sin enumerar `named_modules()` en la versión exacta de Transformers.

Secuencia recomendada:

1. cargar `AutoConfig` y confirmar `model_type`, `architectures` y versión de Transformers;
2. cargar el modelo en el entorno de entrenamiento y ejecutar `verify_targets.py`;
3. empezar con targets explícitos de módulos `nn.Linear` que sí aparezcan en el tronco textual, excluyendo cualquier nombre que contenga `visual`, `vision`, `merger`, `projector` o `router`; el ejemplo conserva **rutas completas**, no sólo sufijos como `q_proj`, porque un sufijo podría coincidir también en visión; no usar `all-linear` en la receta Atlas;
4. congelar visión al principio salvo que la tarea sea multimodal; si se entrena visión, crear un experimento separado y medir regresión textual;
5. estudiar primero LoRA BF16. La ruta genérica NF4 queda suspendida por la advertencia de compatibilidad; no es una alternativa automáticamente aprobada si BF16 no cabe. `datasets-examples/train_qlora.py` del kit v4.7 exige `--bf16` para entrenar y sigue sin validación GPU;
6. guardar `adapter_config.json`, lista de targets encontrados, versiones, seed, longitud, batch efectivo y `trainable_parameters`.

Punto de partida experimental (no garantía): `r=16–32`, `alpha=2r`, dropout 0.05, `bias="none"`, loss sólo en assistant/tool-call, longitud inicial hasta 256 tokens para el primer smoke test. Subir longitud únicamente tras comprobar calidad y memoria.

### 8.2 35B-A3B MoE

El `config.json` oficial confirma 256 expertos, top-8 y 40 capas. En el código Transformers Qwen3.5-MoE, los expertos no son `nn.Linear`: `mlp.experts.gate_up_proj` y `mlp.experts.down_proj` son `nn.Parameter` 3-D; el router es `mlp.gate.weight`; el experto compartido sí tiene `gate_proj/up_proj/down_proj` y `shared_expert_gate` es lineal. PEFT documenta que estos parámetros requieren `target_parameters`, no simplemente `target_modules`. Aunque `shared_expert_gate` sea lineal, queda fuera de la allowlist inicial del script; sólo se debe estudiar en un experimento explícito y separado.

Por eso no copiar la receta del 9B. Primera corrida segura: adaptar sólo `q_proj/v_proj/o_proj` de atención full y/o `linear_attn` lineales que el script confirme, dejando expertos y router congelados. Segunda corrida aislada: añadir los parámetros expertos sólo si la versión de PEFT y el modelo pasan un smoke test de forward/backward, con rank por experto explícito y presupuesto de parámetros. No entrenar el router en la primera prueba: puede cambiar el balance de expertos y no se puede atribuir una regresión.

El adapter community `ciocan/ornith-1.5-9b-spreadsheetbench-lora` demuestra una receta concreta para el 9B (`all-linear`, rank 32, alpha 64, dropout 0.05, BF16, 32k, 2 épocas, loss assistant-only, un H100), pero esa configuración se conserva como evidencia comunitaria, no como receta Atlas: no sabemos por esa tarjeta si su `all-linear` envolvió sólo texto o también módulos multimodales. No copiarla automáticamente al MoE 35B. Su propia evaluación reporta regresión frente a un harness fuerte; debe leerse como advertencia de que un adapter puede reducir bucles sin arreglar el contrato.

### Bibliotecas

- **PEFT:** adaptación y guardado de adapters; fuente primaria para `target_modules="all-linear"`, `target_parameters` MoE y quantization/LoftQ.
- **TRL:** `SFTTrainer`, integración PEFT y trainers de preferencia; usar el chat template y collator de pérdida assistant-only, validando firmas de la versión instalada.
- **Transformers + bitsandbytes:** carga QLoRA; confirmar que la clase `Qwen3_5*ForConditionalGeneration` y la versión exigida por el checkpoint están presentes.
- **Axolotl:** orquestación YAML SFT/LoRA/QLoRA. Sus guías sirven como plantilla, pero una guía de Qwen3.5 no es prueba de soporte para el checkpoint Ornith; comprobar el model type localmente.
- **Unsloth:** alternativa rápida de entrenamiento. Tratar compatibilidad con Ornith multimodal/híbrido/MoE como no verificada hasta un smoke test; no asumir que una receta Llama/Qwen densa se transfiera.
- **LLaMA-Factory:** opción adicional para datasets OpenAI/ShareGPT; el mismo principio: validar clase, template, targets y máscara de pérdida.

Ninguna de estas bibliotecas garantiza que un modelo entrenado conserve streaming, parser, MTP, visión, speculative decoding o serving vLLM/SGLang. La prueba de aceptación debe ejecutar la ruta real.

### Contrato de versiones del ejemplo

El `config.json` oficial de Ornith 1.5-9B declara `transformers_version=5.12.1`; esto es una pista de compatibilidad del checkpoint, no una orden de instalar esa versión a ciegas. El script comprueba en tiempo de ejecución las firmas y capacidades que necesita: clase `AutoModelForImageTextToText`, `LoraConfig.target_parameters` para expertos 3-D, `SFTConfig.assistant_only_loss` y `SFTTrainer.processing_class` (o el nombre legado `tokenizer`). Si una versión no expone alguno, termina con `FAIL-CLOSED` antes de entrenar. No se instaló ningún paquete ni se generó un lock de Python en esta auditoría; antes de una corrida se debe capturar `pip freeze` del entorno aislado junto con la revisión del checkpoint y anotar las fuentes primarias en `sources-datasets.json`.

El ejemplo `datasets-examples/test_train_qlora_cpu.py` valida en CPU la clasificación denso/MoE, los filtros de visión/router y el rechazo de JSONL inválido. No sustituye el forward/backward de una muestra en GPU; ese smoke sigue pendiente y no se deben prometer VRAM o compatibilidad por lectura de una receta.

## 9. Evaluación antes/después

Registrar una línea base congelada antes de tocar datos:

1. **Contrato:** 20–50 casos Atlas, temperatura 0, mismo template y parser; exactitud de no-call, schema, nombre, argumentos, `call_id`, número de turnos, recuperación y parada.
2. **Herramientas:** BFCL oficial para categorías comparables, con exact match/AST y ejecución; nunca reemplazar el runner por un `json.loads` casero sin decirlo.
3. **Español:** IFEval_es y un set humano pequeño de respuestas técnicas, midiendo instrucción, idioma, estructura y factualidad.
4. **Código:** Codeforces `test` o un conjunto propio de problemas no vistos; compilar/ejecutar con sandbox, timeout y tests ocultos.
5. **Regresión general:** 20 prompts de conversación y 20 prompts multimodales si se conserva visión.

Para cada corrida guardar pass rate, errores por categoría, longitud de salida, llamadas válidas/invalidas, latencia y memoria pico. Comparar base/adaptador/merged sólo con el mismo seed, prompt, max tokens y servidor. `train loss` menor no prueba que la herramienta funcione.

## 10. Distilación maestro→alumno

Separar dos escenarios:

- **35B-A3B maestro → 9B denso alumno:** útil si el objetivo es reducir coste de serving. Destilar salidas observables: respuesta final, decisión de llamar, nombre/argumentos canónicos, resultados de herramienta y recuperación. Para tareas de código, conservar tests y no destilar soluciones inválidas. No prometer que el 9B herede visión, contexto, MTP o razonamiento sólo por ver textos del maestro.
- **9B maestro → 35B-A3B alumno:** sólo tiene sentido para un comportamiento de contrato muy estrecho o una tarea específica; el alumno es mayor y el coste de entrenamiento puede no justificarse. Usar el mismo conjunto de tareas y un holdout independiente para confirmar que no se aprendió la idiosincrasia del 9B.

Como las arquitecturas son distintas, empezar con **response distillation/SFT**: maestro genera una trayectoria y el validador conserva únicamente mensajes visibles, tool calls y resultados. Tokeniza la salida del maestro con el tokenizer del alumno y entrena sobre esos IDs; no intentes copiar IDs ni logits del maestro. Añadir KL/logit distillation sólo si los dos tokenizers tienen vocabulario, merges, special tokens y mapeo de posiciones verificados byte a byte; si difieren, la receta correcta es distilación de respuesta/sequence-level, no KL ingenua. `MiniLLM` y su código son referencias primarias para distilación de modelos de lenguaje, no una receta Ornith ya validada.

Para agentes, el conjunto de distilación debe conservar casos negativos (no llamar) y errores; si sólo se conserva la trayectoria exitosa del maestro, el alumno puede llamar de más y atascarse. No publicar cadenas de pensamiento privadas del maestro; usar etiquetas observables (`tool_name`, `arguments`, `outcome`, `final_answer`) y un resumen corto de razón sólo si forma parte del contrato.

### Ejemplo practicable: teacher → dataset filtrado → QLoRA

El encabezado se conserva para no romper enlaces antiguos. La recomendación v4.7 es **SFT/LoRA BF16 experimental**; no ejecutar NF4 como receta validada.

`datasets-examples/distill_answers.py` implementa el primer tramo sin descargar pesos ni ejecutar herramientas. El JSONL de entrada contiene `id`, mensajes `system/user` y un `expected` literal escrito por el validador. Por defecto el script sólo valida localmente y no abre red:

```bash
python datasets-examples/distill_answers.py \
  --input datasets-examples/distill_fixture.jsonl \
  --base http://127.0.0.1:9000/v1 \
  --model TU_MAESTRO_VERIFICADO \
  --output /tmp/distill-validated.jsonl \
  --validate
```

La validación rechaza contenido distinto del literal o `finish_reason` diferente de `stop`. Para generar respuestas visibles desde un endpoint OpenAI-compatible propio hay que pedirlo explícitamente; la llave se lee únicamente de `ATLAS_TEACHER_KEY`, el límite es pequeño (`--max-samples≤8`, `--max-tokens≤512`) y el fichero de salida nuevo nunca se sobreescribe:

```bash
read -r -s -p 'Llave del endpoint maestro: ' ATLAS_TEACHER_KEY
export ATLAS_TEACHER_KEY
python datasets-examples/distill_answers.py \
  --input prompts-atlas.jsonl --base http://127.0.0.1:9000/v1 \
  --model TU_MAESTRO_VERIFICADO --output runs/teacher-pass.jsonl \
  --generate --max-samples 4 --max-tokens 256
```

El puerto 9000 es **un ejemplo**, no un maestro ya instalado. Consulta `/v1/models` y confirma el checkpoint detrás del alias; no atribuyas el 35B-A3B al vLLM 9B que observamos en 8122. Usa HTTPS para un maestro remoto o un túnel SSH a localhost. Nunca pongas claves en la URL; el helper rechaza credenciales/query en `--base`.

Sólo las respuestas visibles que pasan el checker se escriben como mensajes `assistant`; no se copia la respuesta HTTP cruda ni campos de razonamiento privado. Cada fila conserva hash de los mensajes de entrada, modelo/base del teacher, `finish_reason` y tokens reportados. Después se puede pasar ese JSONL a `datasets-examples/train_qlora.py --check`/`--train` junto con el checkpoint local del alumno. Esto es una receta de contrato estrecho, no evidencia de que la destilación mejore Codex/OpenCode; el holdout debe permanecer separado y la prueba GPU sigue pendiente.

Prueba offline:

```bash
python datasets-examples/test_distill_answers_cpu.py
```

## 11. Adaptadores LoRA comunitarios: encontrados y no confirmados

Resultados de una búsqueda acotada en Hub; «no confirmado» no significa «no existe».

- **Encontrado y base exacta 1.5-9B:** `ciocan/ornith-1.5-9b-spreadsheetbench-lora`. La tarjeta declara PEFT, base `ornith-ai/Ornith-1.5-9B`, 282 trayectorias de entrenamiento y 118 tareas held-out. Es un adapter real compatible por identidad de base, pero su objetivo SpreadsheetBench y su receta `all-linear` no son prueba de la receta Atlas.
- **Encontrados pero base 1.0, no reutilizar automáticamente:** `khudgins/Ornith-1.0-9B-ThinkingCap` y `khudgins/Ornith-1.0-35B-ThinkingCap`. La tarjeta describe adapters LoRA sobre Ornith 1.0; no son sustitutos de Ornith 1.5.
- **Arquitectura vecina, base no Ornith:** `manifesta/scientific-chart-qa-lora-qwen3.5-9b` declara base Qwen/Qwen3.5-9B. Puede servir para comparar un adapter Qwen3.5, pero no debe cargarse sobre Ornith sin prueba de arquitectura, tokenizer y base exacta.
- **35B-A3B 1.5:** en los resultados revisados no confirmé un repositorio que declare ser un adapter PEFT sobre `ornith-ai/Ornith-1.5-35B-A3B`; aparecieron cuantizaciones, merges y derivados. No se concluye que no exista: se requiere inspección de `adapter_config.json` y `base_model_name_or_path` de cada candidato antes de citarlo.

Un adapter sólo es reutilizable si `adapter_config.json` declara la misma base/revisión (o se demuestra equivalencia), targets que existen en el model tree y tokenizer/template compatible. El modelo descargable o una página «fine-tuned» no prueba que el repositorio contenga un adapter separado.

## 12. Memoria y coste: lo que sí y no se puede afirmar

No doy cifras garantizadas de VRAM. La memoria depende de pesos BF16/4-bit, optimizador, rank y targets, activaciones, longitud, gradiente, checkpointing, visión, número de expertos activos, fragmentación y versión de kernels. Un MoE con 3B activos por token no implica que sólo haya que cargar 3B de pesos: los 35B y sus estados pueden dominar memoria. Un contexto configurado de 262k no demuestra que una corrida de entrenamiento o tres secuencias de esa longitud sean viables.

Medir por experimento: memoria antes/después de carga, pico forward, pico backward/optimizer, tokens/s, batch efectivo, longitud y si hubo offload/OOM. Cambiar una variable cada vez: 9B/35B, BF16/QLoRA, rank, targets, longitud, batch, checkpointing.

## 13. Vídeos útiles encontrados

Los adjuntos sólo aportan el corpus de vídeos ya auditado y no un dataset. Como apoyo comunitario —no evidencia primaria de compatibilidad Ornith— la matriz r2/r3 contiene:

- [How to Fine-Tune LLMs for AI Agents: SFT and QLoRA Guide using Unsloth](https://www.youtube.com/watch?v=Jg0rT_fRvTg): procedimiento educativo; el propio registro dice que no prueba Ornith.
- [Steps By Step Tutorial To Fine Tune LLAMA 2 With Custom Dataset Using LoRA And QLoRA](https://www.youtube.com/watch?v=Vg3dS-NLUT4): conceptos reproducibles en Llama 2, no targets Ornith.
- [Mastering LLM Fine-Tuning with QLoRA](https://www.youtube.com/watch?v=QzsjHUhZZLE): contexto comunitario; no usar cifras como evidencia.
- [How they built Gorilla](https://www.youtube.com/watch?v=wOK1sX4QPBc): contratos de API/BFCL; apoyar afirmaciones con el [proyecto Gorilla/BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html).

## 14. Límites y siguientes pasos seguros

Pendiente antes de cualquier entrenamiento: fijar revisión de licencias y PII, construir el contrato Atlas y su holdout, instalar versiones en un entorno separado, ejecutar sólo `verify_targets.py` sobre los checkpoints ya disponibles, hacer forward/backward de una muestra minúscula y comparar contra la línea base. No se debe presentar ningún resultado de calidad, memoria, compatibilidad de Unsloth/Axolotl, ni mejora de Codex/OpenCode hasta ejercer la ruta completa.
