rukh · lab

// curso · 13 módulos · ≈ 163 h de trabajo

Dos fases, un artefacto.

Cada módulo cierra con algo que funciona y se mide con la misma tabla: legalidad, exactitud, puzles y Elo frente a Stockfish. Rukh empieza como un aprendiz que no sabe ni leer una jugada y, módulo a módulo, recorre las mismas etapas que cualquier modelo de lenguaje: datos, preentrenamiento, afinado, alineamiento y evaluación. La fase 1 está publicada entera; la fase 2, con los agentes, viene después.

// el recorrido · el recorrido

  1. M0 El tallerEntorno reproducible
  2. M1 Datos y tokensDatos y tokenización
  3. M2 El decoderPreentrenar un GPT
  4. M3 El encoderEmbeddings y clasificar
  5. M4 Fine-tuningSFT y LoRA
  6. M5 AlineamientoPreferencias: DPO, GRPO
  7. M6 Evaluar y publicarMedir y desplegar
  8. FASE 2 El entrenadorAgentes, RAG, MCP

¿Prefieres la foto completa antes de entrar al detalle? Cómo funciona un LLM cuenta el mismo camino de corrido, sin código y con animaciones, y enlaza a la lección donde haces cada paso.

Las dos cifras de cada módulo son dos relojes distintos. Trabajo es el tiempo contigo delante: leer, escribir el código y hacer los ejercicios. GPU y red es el reloj de pared sin ti: entrenamientos, descargas y partidas contra el motor en la máquina de referencia (RTX 5090). Casi todo ese segundo reloj se puede saltar descargando el artefacto ya hecho con rukh pull; cada lección de labs dice cuál.

01 / Fase 1// siete módulos · 65 lecciones · ≈ 133 h de trabajo + 41 h de GPU y red

Un modelo de lenguaje de ajedrez desde cero

  1. M09,5 h + 2 h de GPU0/5

    Taller: repo, entorno, datos y tablero

    Los tres repos, uv con CUDA, el recorte de datos de Lichess con su manifiesto, Stockfish verificado, MLflow local y un tablero que solo acepta jugadas legales. M0 no tiene labs: cada lección se comprueba con sus cajas «Ejecútalo».

    • El repositorio rukh escrito desde un directorio vacío: los veintitrés ficheros de código, configuración y tests del tag p0, todos en el curso y explicados. Lo único que siempre se trae con un comando es el .gitattributes; los ficheros plegados que no quieras teclear, también, y cada lección dice con qué comando.
    • Un entorno reproducible: uv sync --extra cu128 y rukh info lo demuestran.
    • Stockfish verificado por UCI y MLflow registrando cada ejecución con su SHA de git.
    • Dos meses de Lichess descargados con filtros documentados y manifiesto.
    • Un tablero en la web que solo acepta jugadas legales, todavía sin modelo.
    1. 00Qué vas a construir, y cómo se estudia45 min
    2. 01El repositorio: del directorio vacío a la CLI `rukh`125 min
    3. 02El juez y el cuaderno: Stockfish y MLflow150 min + 5 de GPU
    4. 03Los datos: seis mil millones de partidas y un recorte justificado120 min + 100 de GPU
    5. 04El tablero: la legalidad la decide el navegador120 min
  2. M117,5 h + 3 h de GPU0/10

    Del PGN al tensor: datos y tokenización

    El pipeline de datos entero y la primera decisión de modelado: de PGN a UCI, posiciones cruzadas con Stockfish, puzles, pares de preferencia, y tres tokenizaciones de la misma partida comparadas con datos y no con opiniones.

    • El pipeline `rukh data` escrito paso a paso: cada módulo de `data/` y `tokenize/`, en el curso y explicado.
    • Seis datasets listos para Hugging Face, con su card generada desde el manifiesto, publicados en tu propia cuenta o ensayados con `--dry-run` (los de referencia están en `chorcat/`).
    • Un dataloader que sirve las tres tokenizaciones (UCI, SAN por carácter, BPE) en ventanas alineadas al principio de cada partida, con el padding fuera de la pérdida.
    • Tokens por partida y cobertura de vocabulario, medidos y comparados.
    • El tokenizador UCI en Python y en TypeScript, con una fixture de paridad.
    1. 01Del PGN al tensor: qué es un token50 min
    2. 02De PGN a UCI: reproducir seis millones de partidas130 min
    3. 03El pipeline: un YAML, nueve pasos, siete subcomandos130 min
    4. 04Posiciones y evaluaciones: el join que no descarga 42 GB115 min
    5. 05Puzles y pares de preferencia: dos conjuntos que ya estaban hechos90 min
    6. 06Los tres vocabularios120 min
    7. 07Empaquetar y servir lotes130 min
    8. 08Publicar el dataset105 min
    9. 09El tokenizador en el navegador105 min
    10. 10Los labs del pipeline60 min + 175 de GPU
  3. M228 h + 8 h de GPU0/12

    El decoder: un GPT que juega

    Embeddings, atención con máscara causal, bloques pre-norm y la receta de entrenamiento, escritos a mano y entrenados en la RTX 5090. Termina con el modelo exportado a ONNX y jugable en la web.

    • El decoder, la receta, el muestreo, la suite de evaluación y la exportación, escritos línea a línea en el curso; los tests largos que no se recorren se traen de `p2` con un comando.
    • tiny y small entrenados desde cero, y medium-v4 con el código y las configuraciones de la etiqueta p3-elo-1200; small supera el 99 % de jugadas legales sin máscara.
    • Un Elo estimado con intervalo contra una escalera de Stockfish, y la historia de cómo se corrigió la escalera.
    • Juegas contra el modelo en la demo (WebGPU o WASM), y ves su atención y su entrenamiento en la lección.
    1. 00PyTorch mínimo: tensores, módulos y un bucle que aprende70 min
    2. 01El decoder: escribirlo a mano40 min
    3. 02El decoder a mano: config, bloques y el modelo100 min
    4. 03La receta de entrenamiento190 min + 45 de GPU
    5. 04Muestrear jugadas175 min
    6. 05Legalidad, exactitud y puzles200 min
    7. 06El Elo y la suite290 min + 40 de GPU
    8. 07Exportar a ONNX165 min + 20 de GPU
    9. 08Jugar en el navegador165 min
    10. 09Publicar el modelo130 min
    11. 10Los labs del decoder125 min + 10 de GPU
    12. 11Más datos, no más red: de small a medium-v435 min + 368 de GPU
  4. M324 h + 2,5 h de GPU0/11

    El encoder: entender la posición

    Un encoder bidireccional preentrenado con masked move modeling y afinado con cabezas de valor y de detección de errores, y la lección de por qué una exactitud del 96,8 % sobre una clase del 3,7 % no significa nada.

    • La barra de evaluación y la alerta de error en la demo, con su contrato de carga; y, explicadas, las dos causas que tuvieron apagada la alerta: el umbral de fábrica de 0,5, que una cabeza sin calibrar no alcanza, y una barra que le daba casillas al encoder publicado, que espera jugadas. La demo publicada ya lee del fichero el esquema y el umbral afinado (9,6 %), y le da la partida.
    • El detector de errores supera a la heurística de material en 9 puntos de F1; la correlación con Stockfish se queda en 0,52 al cerrar el hito (0,67 con la pérdida de ordenación y el encoder grande, que llegan en `p4`) y se explica por qué.
    • Medido: afinar solo los dos últimos bloques gana al modelo entero en el error del valor, y el 25 % de las etiquetas compra lo mismo que el 100 %.
    1. 01El encoder: la línea que lo cambia todo50 min
    2. 02Las capas compartidas: un bloque, dos modelos65 min
    3. 03El encoder a mano: el mismo bloque con `causal=False`80 min
    4. 04Cabezas y casillas: tres preguntas y una segunda entrada100 min
    5. 05Masked move modeling: el preentrenamiento y la receta compartida195 min + 16 de GPU
    6. 06Entrenar las cabezas: etiquetas, congelación y la curva195 min + 25 de GPU
    7. 07Evaluar el encoder: qué se mide y qué sale150 min + 5 de GPU
    8. 08El encoder: medir sin engañarse165 min
    9. 09Exportar el encoder: dos salidas, tres precisiones y una model card210 min + 5 de GPU
    10. 10La barra de evaluación: el segundo worker y la alerta que nombra la jugada135 min
    11. 11El encoder: los labs95 min + 90 de GPU
  5. M421,5 h + 14,5 h de GPU0/10

    Fine-tuning e instrucción

    Qué cambia un afinado y qué no: SFT con partidas de maestros, condicionamiento por Elo, LoRA escrita a mano y comprobada contra peft, adaptadores intercambiables en caliente y QLoRA de Qwen3 sobre PGN.

    • LoRA escrito a mano, el eje de Elo con sus tokens de control, los adaptadores de estilo y el QLoRA de Qwen3: las piezas que enseñan cada decisión, en el curso; lo que no se recorre se trae de p4 con un comando.
    • Un adaptador de 1,6 MB (el 0,34 % del modelo) sube 1. e4 del 60 % al 99,85 % sin coste medible, y se cambia en caliente en la demo.
    • Los tokens de Elo por debajo de 1800 funcionan: la entropía de la primera jugada es monótona en las seis condiciones.
    • Ningún afinado mueve el Elo de forma demostrable, y las tres herramientas que lo establecen: partidas necesarias, ejecución de control y suelo de reproducibilidad.
    1. 01Fine-tuning: qué es y cuántas maneras hay35 min
    2. 02Los tokens de Elo y el corpus que faltaba150 min + 35 de GPU
    3. 03LoRA escrita a mano120 min + 15 de GPU
    4. 04Estilo y texto PGN: los dos cortes del corpus130 min + 20 de GPU
    5. 05QLoRA con `transformers`: el decoder entra en el ecosistema235 min + 75 de GPU
    6. 06Adaptadores y publicación: 1,6 MB que llegan al navegador210 min + 20 de GPU
    7. 07Diversidad y barridos: dos veredictos en vez de uno165 min + 180 de GPU
    8. 08El selector en la demo: seis condiciones y 1,6 MB110 min
    9. 09Lo que salió: cinco mediciones y cuatro criterios40 min
    10. 10Los labs del afinado100 min + 530 de GPU
  6. M516,5 h + 6 h de GPU0/9

    Alineamiento con recompensas verificables

    El modelo deja de imitar y empieza a preferir: reward model con Bradley-Terry, DPO con pares de fuera y de dentro de política, GRPO contra una recompensa que un motor verifica, y una galería de reward hacking medida.

    • Un instrumento que mide diferencias en vez de restar dos absolutos: unas 4 veces más barato en partidas, con su control.
    • Los tres métodos baten a su base con el intervalo separado del cero: DPO +65 y +57, GRPO +44 Elo.
    • GRPO mejora las jugadas y, si se le deja, colapsa la política: la recompensa se maximiza dejando de ser diverso.
    1. 01Alineamiento: el instrumento y la teoría justa50 min
    2. 02El reward model: una cabeza escalar sobre el encoder de M3155 min + 5 de GPU
    3. 03DPO: la referencia implícita, y de dónde salen las dos jugadas130 min + 40 de GPU
    4. 04GRPO y la recompensa que un motor verifica215 min + 90 de GPU
    5. 05La arena: dos modelos jugando entre sí115 min + 10 de GPU
    6. 06Publicar lo alineado: un reward model no es una política90 min + 5 de GPU
    7. 07Los modelos alineados en la demo40 min
    8. 08Alineamiento: cómo se mide y lo que salió40 min
    9. 09Alineamiento: los labs150 min + 210 de GPU
  7. M616 h + 5 h de GPU0/9

    Evaluar, exportar, publicar

    Ningún modelo nuevo: la tabla única de todas las etapas medida el mismo día con un comando, el suelo del instrumento medido antes de fiarse de él, dos baselines públicos, lo que cuesta el int8, las cards y la demo con arena y puzles.

    • La tabla entera, trece filas de decoder medidas el mismo día (once con rukh eval nightly, dos a mano), con dos baselines: el nanoGPT de Karvonen y el Qwen3 general afinado en M4.
    • El suelo del instrumento medido cuatro veces (1538/1538 por reloj, 1541/1524 por nodos) y la decisión que dejó.
    • Veintiuna model cards regeneradas desde la tabla, la colección del Hub, y la demo con arena y puzles en vivo.
    1. 01Evaluar: la teoría justa40 min
    2. 02La escalera calibrada: el rival por nodos y la identidad de unos pesos95 min
    3. 03El baseline público: el nanoGPT de Karvonen en nuestra escalera150 min
    4. 04La tabla cada noche: doce etapas, un comando, una fecha110 min
    5. 05El Hub y las cards: el catálogo, la vuelta y la afirmación pública180 min
    6. 06int8 y el jugador ONNX: un grafo exportado en la escalera85 min
    7. 07La demo final: arena, puzles y tu propio modelo desde el disco130 min
    8. 08Evaluar: lo que salió45 min
    9. 09Evaluar: los labs de cierre110 min + 310 de GPU
02 / Fase 2// seis módulos · cuatro semanas · ≈ 30 h estimadas

IA agéntica: el entrenador

  1. A16 hprevisto

    Embeddings y RAG: posiciones y libros

    Embeddings de posiciones con el encoder propio, un índice vectorial de millones de posiciones y RAG sobre libros de ajedrez de dominio público, evaluado con RAGAS.

    • "En posiciones parecidas, los maestros jugaron…" con recuperación por embedding.
    • Comentarios con citas literales de Capablanca y Lasker, con métricas RAGAS documentadas.
    • dataset · Índice de posiciones

    Lecciones en cuanto se cierre el hito.

  2. A27 hprevisto

    Agente con herramientas (LangGraph)

    Un agente entrenador que analiza una partida llamando al motor, al modelo, al libro de aperturas y al buscador, con trazas completas en LangSmith.

    • El agente comenta una partida completa decidiendo qué herramienta usar en cada jugada.
    • Cada ejecución deja una traza inspeccionable en LangSmith.

    Lecciones en cuanto se cierre el hito.

  3. A34 hprevisto

    Evaluación y observabilidad

    Suite de evaluación del entrenador con preguntas doradas, jueces automáticos y regresión por commit en LangSmith.

    • Suite de evaluación en LangSmith en verde.
    • Cada commit del agente se compara con el anterior sobre el mismo conjunto dorado.
    • report · Suite de evaluación

    Lecciones en cuanto se cierre el hito.

  4. A45 hprevisto

    Multiagente

    Tres roles que cooperan y se corrigen: jugador, entrenador y redactor del informe, orquestados como un grafo.

    • Jugador, entrenador y redactor producen un informe de partida coherente entre los tres.
    • report · Informe de partida

    Lecciones en cuanto se cierre el hito.

  5. A53 hprevisto

    MCP

    Las herramientas de ajedrez (motor, modelo, libro, índice) expuestas como un servidor MCP que cualquier cliente puede usar.

    • Servidor MCP con las herramientas de ajedrez, usable desde un cliente externo.

    Lecciones en cuanto se cierre el hito.

  6. A65 hprevisto

    Capstone

    El entrenador: backend opcional, comentarios en vivo mientras juegas y un informe final de la partida, publicado como cierre del curso.

    • Web del entrenador: juegas, te comenta en vivo y recibes un informe al final.
    • Post de cierre con la historia completa del proyecto.

    Lecciones en cuanto se cierre el hito.