// glosario · 171 términos
Las palabras, con el proyecto delante.
Cada término se define con lo que hace en Rukh, no en abstracto. Las lecciones enlazan aquí desde el texto subrayado.
- acumulación de gradiente
- En Rukh, partir el lote que no cabe en la GPU en varias pasadas que sí caben, acumulando sus gradientes antes de un solo paso del optimizador.
grad_accum: 4conbatch_size: 64son 256 secuencias efectivas; la pérdida de cada micro-lote se divide porgrad_accumpara que los gradientes sumados equivalgan a una media y el tamaño del paso no dependa de cuántos micro-lotes se acumulen. - AdamW
- Optimizador Adam con el decaimiento de pesos desacoplado del gradiente: mantiene medias móviles del gradiente (β₁) y de su cuadrado (β₂) para dar a cada parámetro su propio paso, y resta aparte una fracción del peso. En Rukh: β = 0,9/0,95, weight decay 0,1 aplicado solo a las matrices.
- Adaptador
- El fichero que sale de entrenar con LoRA: solo las matrices
AyB, sin los pesos base. En Rukh son 1 578 824 bytes (0,34 % del modelo) y por sí solos no hacen nada, porque son una corrección a unos pesos concretos. Se publican en su propio repositorio, con la card diciendo sobre qué base se montan, y en la demo viajan como entradas del grafo ONNX para que cambiar de estilo cueste 1,6 MB en vez de otro modelo entero. - adjudicación
- Decidir el resultado de una partida que se cortó sin terminar en el tablero —en Rukh, porque el modelo se quedó sin contexto— juzgando la posición final con una búsqueda corta del motor o, si no hay motor, con el recuento de material. Anotarla como tablas no sería neutral: regalaría medio punto al bando que iba perdiendo, y ese sesgo apunta siempre para el mismo lado.
- Agente
- Programa en el que un modelo de lenguaje decide qué herramienta llamar (motor, modelo, libro, buscador), observa el resultado y vuelve a decidir, en bucle, hasta cumplir una tarea. El entrenador de la fase 2 es un agente construido con LangGraph y trazado con LangSmith.
- aislamiento de origen cruzado
- Estado que el navegador concede a una página que envía
Cross-Origin-Opener-Policy: same-originyCross-Origin-Embedder-Policy: require-corp, y que es el requisito para usarSharedArrayBuffery, con él, WASM multihilo. La demo de Rukh lo declara en nginx aunque después use un solo hilo: tenerlo puesto significa que el día que el respaldo de WASM sea el camino principal no hay que cambiar el despliegue. - Alineamiento
- Cambiar lo que un modelo prefiere, no lo que sabe. El preentrenamiento y el afinado ajustan la probabilidad de la siguiente jugada para parecerse a un corpus; el alineamiento la ajusta para parecerse a un criterio: cuál de dos jugadas es mejor (DPO), o cuánto vale una jugada según una función (GRPO). La diferencia práctica es de dónde sale la señal: de imitar a alguien, o de una comparación que nadie jugó nunca.
- Alucinación
- Respuesta que suena segura y es falsa: una cita que no existe, un dato inventado. Sale de la tarea misma del modelo, que genera la continuación más verosímil y no la verdadera, y que no trae de serie una forma de decir «no lo sé». Se reduce dándole las fuentes (RAG), pidiéndole que cite, alineándolo para que reconozca la duda y comprobando lo que dice; no desaparece.
- Aprendizaje en contexto
- Lo que hace un modelo cuando aprende una tarea de los ejemplos que lleva el propio prompt, sin que cambie ni uno de sus pesos: le enseñas tres traducciones y traduce la cuarta. Dura lo que dura la conversación. En Rukh la versión mínima son los tokens de Elo: el nivel se pide escribiéndolo delante, no reentrenando.
- Atención
- Operación que mezcla las posiciones de una secuencia: cada posición emite una consulta (Q), cada una ofrece una clave (K) y un valor (V); el producto escalar entre consulta y claves, escalado por 1/√d y pasado por softmax, da los pesos con los que se promedian los valores. Es la única parte del Transformer donde las posiciones se hablan entre sí.
- Baseline
- El rival tonto contra el que se mide un modelo, para saber si su número significa algo. En M3 es una heurística de material (peón 1, caballo y alfil 3, torre 5, dama 9) más movilidad, que llama error a toda jugada que pierda un punto neto. Se mide sobre las mismas filas y con la misma definición de acierto que el encoder: un margen medido sobre dos conjuntos distintos no es un margen.
- Baseline de un grupo
- El número contra el que se compara una recompensa para saber si fue buena o mala. Sin baseline, «0,8» no significa nada. PPO entrena una red de valor para estimarla; GRPO usa la media del propio grupo, que no cuesta nada y no hay que entrenar. El precio es que si el grupo no tiene dispersión, el baseline se come toda la señal.
- Baseline público
- Un modelo que entrenó otra persona, medido con exactamente el mismo harness que los propios: los mismos peldaños, la misma máscara de legalidad, el mismo día. Sin eso, la comparación es entre dos instrumentos y no entre dos modelos. En la tabla de Rukh son el Qwen3 afinado (M4) y el nanoGPT de ajedrez de Karvonen; se juegan aquí, no se copian de su paper.
- bfloat16
- Formato de coma flotante de 16 bits con los mismos 8 bits de exponente que fp32 y solo 7 de mantisa: pierde precisión pero conserva el rango, así que un gradiente pequeño no se va a cero. Por eso entrena sin escalado de pérdida, al contrario que fp16, cuyo exponente de 5 bits desborda por abajo.
- Bootstrap
- Remuestrear los datos con reemplazo muchas veces y recalcular el estadístico en cada remuestreo para ver cuánto se mueve. El intervalo del Elo de Rukh sale así: 500 remuestreos de las 160 partidas (
bootstrap: 500en la suite), un ajuste por remuestreo, y los percentiles 2,5 y 97,5. Cubre el ruido del muestreo de partidas y nada más: no cubre que el rival cambie entre ejecuciones ni que los peldaños estén mal colocados. - BPE (byte-pair encoding)
- Tokenizador aprendido de los datos: parte de los caracteres, fusiona una y otra vez el par de tokens adyacentes más frecuente y guarda cada fusión en orden hasta llegar al tamaño de vocabulario pedido (4 096 en Rukh). Sobre texto UCI redescubre primero las casillas, luego las jugadas y al final trozos de apertura. Nada queda fuera de vocabulario: lo raro se parte en trozos más cortos.
- Bradley-Terry
- El modelo que convierte preferencias en puntuaciones: la probabilidad de que
agane abesσ(r(a) − r(b)). Su consecuencia más útil y la más fácil de olvidar es que solo ve diferencias: sumar una constante a todas las puntuaciones no cambia nada, así que la escala de un reward model no significa nada por sí sola y compararla entre dos entrenamientos no tiene sentido. - Broadcasting
- La regla por la que PyTorch y NumPy operan tensores de formas distintas sin copiarlos: se alinean las dimensiones por la derecha y las de tamaño 1 se estiran.
(2, 3) + (3,)suma el vector a cada fila;mask[:, None, None, :]convierte la máscara de relleno(B, T)en(B, 1, 1, T)para aplicarla a las puntuaciones de atención(B, H, T, T). Si dos dimensiones no son iguales ni 1, la operación falla. - Cabeza (head)
- La capa final que traduce la representación en la salida de una tarea concreta; en inglés, head. El encoder de M3 lleva tres sobre el mismo tronco —valor, resultado y error garrafal— y cada una es una sola capa lineal, a propósito: si una lineal acierta, la información ya estaba en la representación. No confundir con la cabeza de atención, que es otra cosa.
- Cabeza de atención
- Una atención completa calculada en un subespacio de la representación.
rukh-smallparte sus 512 dimensiones en 8 cabezas de 64: cada una aprende su propio criterio de parecido y sus propios pesos, y sus salidas se concatenan y se vuelven a proyectar. Mismo coste que una cabeza de 512, ocho patrones distintos por capa. - Calibración
- Un modelo está calibrado cuando sus probabilidades significan lo que dicen: de todas las veces que dice 0,3, acierta más o menos tres de cada diez, como un meteorólogo fiable. En M3 el detector de errores no lo está —sus probabilidades viven entre 0,002 y 0,310—, y por eso el umbral de fábrica de 0,5 no marca ninguna jugada. Aun calibrado, con una clase del 3,7 % el mejor umbral para F1 estaría muy por debajo de 0,5.
- Capa (layer)
- Cada uno de los bloques que se apilan para formar la red; en inglés, layer. Un bloque del decoder de Rukh es atención más MLP con sus dos normalizaciones, y
smallapila doce de 512 dimensiones y ocho cabezas. También se llama capa a una transformación suelta, como la lineal final que convierte el vector de la última posición en logits. - CC0
- Dedicación al dominio público de Creative Commons: el autor renuncia a todos los derechos. Lichess publica sus partidas, puzles y evaluaciones bajo CC0, así que se pueden recortar, redistribuir y usar para entrenar sin pedir permiso (se cita por cortesía).
- Centipeón (cp)
- Unidad de la evaluación de un motor: 100 centipeones equivalen a un peón de ventaja. Es la etiqueta que Rukh cruzó en M1 desde las evaluaciones de Lichess y la que el encoder aprende a predecir, acotada con
tanh(cp/400)para que un mate valga ±1 en vez de diez mil y no domine la pérdida. Un error se define como perder ≥ 100 cp respecto a la mejor línea de la posición anterior. - Checkpoint
- Fotografía de un entrenamiento guardada en disco: pesos, estado del optimizador, paso alcanzado, configuración y procedencia (hash del vocabulario, del manifiesto de datos y SHA de git). Sirve para reanudar, para evaluar y para publicar; en Rukh se escribe uno cada 1 000 pasos más el mejor por pérdida de validación.
- clave de caché
- En Rukh, el hash de los ajustes que cambian lo que significa un elemento guardado de una evaluación. Es la promesa de que dos ejecuciones con la misma clave midieron lo mismo: si la clave incluye un campo que no cambia el elemento, invalida trabajo ya pagado; si le falta uno que sí lo cambia, devuelve como nuevo un resultado viejo. M6 la partió en dos familias, partidas y puzles, para que subir el número de partidas no tirara los puzles.
- Colección
- Una página del Hub que lista repositorios en un orden. La de Rukh se monta desde el catálogo de
rukh pullconrukh publish collection, así que lo que se puede descargar, lo que se puede leer y lo que está en la tabla son la misma lista. Es idempotente: ejecutarla dos veces no cambia nada. - Conexión residual
- Suma de la entrada de una subcapa a su salida (
x + f(x)). La derivada de esa suma es la identidad más la def, así que el gradiente llega íntegro a las capas de abajo aunquefaporte poco; el flujo de vectores que atraviesa el modelo de principio a fin se llama por eso corriente residual. - Correlación (Pearson y Spearman)
- Un número entre −1 y 1 que dice si dos cantidades suben juntas: 1, a la par; 0, sin relación; −1, una baja cuando la otra sube. Hay dos maneras de medir si un número predicho acompaña al real. Pearson mide si los valores se alinean en una recta y le importa la escala; Spearman es Pearson sobre los rangos, así que solo mide si el orden coincide: el podio frente a los cronos. Se publican las dos porque discrepan exactamente cuando el modelo tiene bien el orden y mal la escala, que es lo que le hace un
tanhacotado a una puntuación en centipeones. Las dos se calculan contratanh(cp/400), la escala con la que se entrena la cabeza, nunca contra elcpen bruto.GOAL.mdpide ≥ 0,80 leído sobre Spearman; el checkpoint publicado en M3 se queda en 0,520 (Pearson 0,648) y la pérdida con término de orden sube a 0,6665: criterio no cumplido. - Criterio de aceptación
- El listón que un hito se fija por escrito y antes de medir nada: una frase con un número y una comparación, del tipo «legalidad ≥ 99 % por argmax» o «Elo por condición monótono, con intervalos». Escribirlo antes es lo que impide la trampa más común al evaluar un modelo, que es mirar el resultado y decidir después qué contaba como éxito. En Rukh cada módulo cierra diciendo cuáles de sus criterios cumple y cuáles no; los que no se cumplen se publican igual, con la medida de por qué.
- Cuantización
- Guardar y calcular los pesos con menos bits de los que se entrenaron: fp16 (la mitad de tamaño, sin pérdida apreciable) o int8 dinámico (una cuarta parte, con algo de error). En Rukh se cuantizan solo las matrices (
MatMulyGemm) y cada fichero pasa una prueba de paridad contra PyTorch antes de subirse. A 4 bits, la receta de QLoRA en M4, cada peso es uno de 16 niveles: NF4 los coloca donde se amontonan los pesos de una red entrenada (una campana centrada en cero, con un cero exacto), cada bloque de 64 pesos guarda su escala, y esas escalas se cuantizan a su vez a 8 bits (doble cuantización). Para multiplicar, cada bloque se descuantiza al vuelo a bf16: ahorra memoria, no cálculo, y solo sirve para una base congelada; el adaptador que se entrena encima sigue en bf16. - Cuantización dinámica
- Guardar los pesos como enteros de 8 bits con una escala por tensor y cuantizar las activaciones en cada inferencia, sin calibración previa. Es lo que hace
onnxruntimepara int8. El error de redondeo se concentra donde los logits de las dos mejores jugadas están cerca, que es donde la decisión es difícil; por eso la paridad cae más de lo que el tamaño del error sugiere. - Dataloader
- En PyTorch, el objeto que toma un Dataset (que sabe cuántos ejemplos hay y cuál es el ejemplo i), los baraja con una semilla, los agrupa en lotes y los prepara en paralelo con varios workers mientras la GPU calcula el lote anterior. El de Rukh sirve ventanas (x, y) de 200 tokens alineadas a <bos>.
- Decoder
- Arquitectura Transformer con atención causal: cada posición solo mira hacia atrás, así que sirve para generar de izquierda a derecha. GPT es un decoder;
MoveDecoder, el modelo de Rukh, también. - Desbalanceo de clases
- Que una clase sea mucho más frecuente que la otra. En detección de errores solo una fracción pequeña de las jugadas pierde 100 cp, así que la exactitud es inútil como métrica (decir siempre «no» ya la deja altísima) y hay que mirar precisión, exhaustividad y F1 sobre la clase rara. También cambia el entrenamiento: la pérdida promedia sobre las filas etiquetadas y la clase mayoritaria manda si no se compensa.
- Descenso de gradiente
- La manera de entrenar una red: calcular hacia dónde crece la pérdida respecto a cada peso (el gradiente, que se obtiene por retropropagación) y mover todos los pesos un pasito en sentido contrario. Repetido millones de veces sobre lotes distintos, la pérdida baja. AdamW es la variante que usa Rukh.
- DPO
- Direct Preference Optimization: entrena la política directamente sobre los pares, sin reward model y sin bucle de refuerzo. La referencia es implícita —una copia congelada de los pesos de partida— y
βmide cuánto se le deja alejarse de ella. Con una jugada por respuesta, la pérdida se reduce a comparar dos log-probabilidades en una sola posición. - DuckDB
- Base de datos analítica embebida que ejecuta SQL sobre ficheros parquet locales o remotos (
hf://). Es la herramienta con la querukh data fetchaplica los filtros del recorte antes de materializar nada en disco. - Ejecución de control
- Volver a medir lo mismo sobre el sujeto sin el tratamiento, para saber cuánto del efecto ya estaba ahí. Es el grupo placebo de un ensayo clínico aplicado a un modelo: en M4, el mismo barrido por cabecera de Elo sobre
medium-v4, que por debajo de 1800 no tiene cabecera ninguna. Recorrió 161 de los 219 puntos del eje con tokens que nunca habían recibido un gradiente, lo que convirtió «el condicionamiento da fuerza» en «un prefijo desconocido le estorba, y estorbarle cuesta unos ciento sesenta puntos». Cuesta una hora de máquina y es la diferencia entre un titular y una medición. - Ejecución en seco (dry run)
- Recorrer entero el camino de un comando sin el efecto que la hace irreversible —sin red, sin subir nada, sin escribir—; en inglés, dry run, y en Rukh el flag
--dry-run. Vale la pena porque ejercita justo lo que suele romperse (qué se iba a subir, con qué nombre y a qué repositorio) sin publicar nada, y los tests lo usan para probar publicadores sin tocar el Hub. - Elo
- Escala de fuerza de juego: una diferencia de 200 puntos implica que el mejor gana unas tres de cada cuatro veces. Lichess usa Glicko-2, compatible en la práctica. Rukh estima el Elo de cada modelo jugando contra Stockfish limitado y publica el intervalo de confianza.
- Elo estimado
- Fuerza del modelo obtenida ajustando la fórmula logística del Elo a los resultados de partidas contra Stockfish limitado a varios niveles. No es un Elo de la FIDE ni de Lichess: es el número que mejor explica esos resultados, y solo significa algo acompañado de su intervalo de confianza y de la lista de rivales.
- Embedding
- Tabla que asigna un vector aprendido a cada id del vocabulario, y por extensión ese vector. En
rukh-smallla tabla es de 2 030 × 512: cada jugada UCI entra en el modelo como un punto en un espacio de 512 dimensiones, aprendido a la vez que el resto de la red. - Encoder
- Transformer con atención bidireccional: cada posición ve toda la secuencia. No genera; representa. En Rukh el encoder lee una partida entera y produce un vector por posición del que salen el valor y la detección de errores.
- Enfrentamiento directo
- Medir una diferencia haciendo que los dos modelos jueguen entre sí, en vez de medir dos Elo absolutos contra una escalera y restarlos. Sale unas cuatro veces más barato en partidas y se ahorra el ruido del tercero: en un enfrentamiento los dos juegan la misma partida. Es el instrumento con el que M5 mide, y el que separó del cero un +40 Elo que la escalera dejaba solapado.
- Entropía cruzada
- La pérdida con la que se entrena todo modelo de lenguaje: menos el logaritmo de la probabilidad que el modelo le dio al token que venía de verdad, promediado sobre las posiciones. Si le dio 0,70, paga 0,35; si le dio 0,035, paga 3,35. En PyTorch es
F.cross_entropy(logits, objetivo), que hace el softmax por dentro, y en Rukh llevaignore_index=0para que el relleno<pad>no cuente. Un modelo que reparte por igual entre las 2 030 jugadas paga ln 2030 ≈ 7,6: es el punto de partida de toda curva de pérdida del decoder. - Entropía de aperturas
- Cuánto varía el modelo sus primeras jugadas, en bits. Se juega contra sí mismo N veces y se mide la entropía de Shannon de las líneas distintas: 0 es siempre la misma partida, log2(N) es una diferente cada vez. Depende del muestreo —a temperatura casi cero cualquier decoder saca 0— así que siempre se publica con la temperatura a la que se leyó, junto a la entropía de la primera jugada, que no depende del muestreo en absoluto.
- Época (epoch)
- Una pasada completa por el conjunto de entrenamiento; en inglés, epoch. Sirve para contar cuántas veces se le ha enseñado el mismo dato. Con corpus grandes Rukh no llega ni a una —el afinado por maestros son 194,6 M de tokens sobre el pack de élite, 0,16 de una época, así que cada muestra que ve es nueva—, y en ese régimen la unidad útil es el paso, no la época.
- Error típico
- Cuánto se movería una media si se repitiera la medida: la desviación de una sola observación dividida por la raíz del número de observaciones. Una moneda tiene una desviación de 0,5 por tirada, así que la proporción de caras en 100 tiradas tiene un error típico de 0,05 y un intervalo del 95 % de ±0,098 (1,96 errores típicos). En Rukh es lo que convierte «ganó el 60 % de 20 partidas» en un número con su margen, y la razón de que la precisión mejore con la raíz del tamaño: cuatro veces más partidas, la mitad de error.
- Estimador k3
- La forma de calcular la penalización KL con las jugadas que la política ya sorteó, sin recorrer todo el vocabulario:
exp(d) − d − 1cond = log π_ref − log πde cada jugada sorteada, promediado. Vale cero cuando la política y la referencia dan la misma probabilidad a la jugada y es positivo en cualquier otro caso, así que funciona como castigo. La restada secas sale negativa la mitad de las veces y le pagaría al modelo por alejarse. GRPO en Rukh lo usa conbeta_kl: 0.02. - Exhaustividad
- De todo lo que había que marcar, qué fracción marcó el detector:
VP/(VP+FN). Responde a «¿cuántos errores se me escapan?». Se mueve en contra de la precisión: bajar el umbral captura más errores reales y también más falsas alarmas, y elegir el punto de esa curva es una decisión de producto, no de entrenamiento. En Rukh el umbral por defecto es 0,5 y está enconfigs/eval/encoder.yaml. - F1
- Media armónica de precisión y exhaustividad:
2·P·R/(P+R). Se usa cuando una clase es rara y la exactitud engaña: en M3 los errores son el 3,7 % de las filas, así que un detector que dijera siempre «no es error» acertaría el 96,3 % de las veces y tendría F1 cero. La armónica castiga el desequilibrio: la pata mala manda, y con precisión 1,0 y exhaustividad 0,01 da 0,02, no 0,5. Depende del punto de operación: la cabeza publicada da 0,0000 en el umbral de fábrica de 0,5 y 0,180 en el umbral elegido en la mitadtune(0,0663) y medido en la mitadscore. El listón deGOAL.mdpara M3 es superar en cinco puntos de F1 a la heurística de material; medido, +9,2. - FEN
- Cadena de texto que describe una posición completa: piezas por fila, turno, derechos de enroque, casilla al paso y contadores de jugadas. Es la clave con la que se cruzan las posiciones de las partidas con las evaluaciones públicas de Stockfish.
- Fichero de bloqueo
- Fichero generado (
uv.lockaquí) con la versión exacta y el hash de cada paquete que el entorno instala, incluidas las dependencias indirectas. Se versiona en git: es la diferencia entre «instala pydantic 2.x» y «instala exactamente lo que había el día que se midió esto». En Rukh, un test (test_lock_guard.py) lo lee para comprobar que los dos extras de torch siguen bloqueando la misma versión. - Fine-tuning
- Seguir entrenando un modelo ya entrenado sobre datos más específicos o con un objetivo distinto. Puede tocar todos los pesos (completo) o solo unos pocos (parcial, LoRA). En Rukh, el decoder base se afina con partidas de maestros y con tokens de Elo objetivo.
- Fuga de datos
- Cualquier camino por el que información del conjunto de validación llega al de entrenamiento. No falla: los números mejoran, y se descubre cuando el modelo sale al mundo. En Rukh se evita partiendo por mes (enero entrena; de febrero, desde M2 parte 4, validan las primeras 100 000 partidas y el resto del mes entrena), por PuzzleId con semilla en los puzles, entrenando el BPE solo con datos de enero y, en M3, repartiendo la tabla de posiciones por
game_idcon un CRC-32 de la semilla y el id, nunca por posición: dos posiciones consecutivas de la misma partida se diferencian en una jugada. El umbral del detector se elige además en una mitadtuney se mide en otrascore, partidas también por partida. - Fusión de BPE (merge)
- Cada una de las uniones de un par de tokens que el BPE aprende, guardada en el orden en que la aprendió; en inglés, merge, que es como se llama en el fichero
merges.txty en la variablemergesdel lab. Tokenizar es aplicarlas en ese mismo orden: aplicar una tardía antes que una temprana da otra segmentación y peor. En Rukh son 4 069 para un vocabulario de 4 096. - Gradiente
- Las derivadas de la pérdida respecto a cada peso: para cada uno, cuánto y en qué sentido cambiaría la pérdida si se moviera un poquito. Apunta hacia donde la pérdida crece, así que el descenso de gradiente mueve los pesos en sentido contrario. PyTorch lo calcula con
loss.backward()y lo deja en el.gradde cada parámetro; se acumula entre llamadas, y por eso cada paso de Rukh empieza conoptimizer.zero_grad(). - Gradiente de política
- La regla con la que el aprendizaje por refuerzo sube lo que salió bien: la pérdida es
−ventaja · log π(acción), y su gradiente sube la probabilidad de la acción elegida si la ventaja es positiva y la baja si es negativa, quitándosela a las demás (o dándosela) en proporción a lo que tenían. En M5, con cuatro jugadas y ventaja 1,5, un paso lleva la elegida de 0,21 a 0,40. Es el núcleo de REINFORCE, PPO y GRPO. - GRPO
- Group Relative Policy Optimization: la política propone un grupo de respuestas a la misma entrada, una función las puntúa, y cada una se empuja arriba o abajo según cómo le fue frente a la media de su propio grupo. El grupo es el baseline, así que no hace falta una red de valor. Su consecuencia menos obvia: un grupo cuyas respuestas puntúan igual no aporta gradiente ninguno.
- Grupo plano
- Un grupo de GRPO cuyas candidatas puntúan todas igual. El baseline cae encima de todas, las ventajas son cero y el paso no aporta gradiente, con el motor ya pagado. En Rukh son el 38 % de los grupos a temperatura 1,0. Subir la temperatura los reduce —26 % a 1,3, 19 % a 1,6— pero cuesta más análisis de motor por grupo, y medido sale a la par: unos 0,18 grupos útiles por análisis en las tres.
- hash de pesos
- SHA-256 de los tensores de un modelo —nombre, tipo, forma y bytes, en orden de nombre—, en vez del hash del fichero que los contiene. Es la identidad que comparten dos ficheros con el mismo modelo escritos de forma distinta: el
best.ptdel entrenamiento lleva el estado del optimizador y la copia que sube al Hub no. En Rukh (D-135) es lo que permite publicar una card sobre un fichero descargado y seguir rechazando unos pesos distintos. - Instruction tuning
- Afinado supervisado (SFT) sobre pares instrucción → respuesta, para que un LLM obedezca lo que se le pide en la propia entrada en vez de limitarse a continuar texto. Rukh no lo hace tal cual: sus dos tokens de cabecera
<wXXXX> <bXXXX>son condicionamiento con tokens de control, el pariente más pequeño de un prompt de sistema. Comparten la lección práctica: una instrucción solo funciona si el entrenamiento vio ejemplos de ella, y los tramos por debajo de 1800 no los vio hasta M4. - Intervalo de confianza
- Rango dentro del que cabría la medida si se repitiera; Rukh publica el del 95 % por bootstrap (500 remuestreos) junto a cada Elo. Dos estimaciones solo se pueden declarar distintas si sus intervalos no se solapan: que los puntos estén ordenados («monótono») es barato y sale por azar; que los intervalos se separen es lo que sobrevive al ruido. Cuando se solapan, la aritmética
n > 3,84 / (Δp)²dice si faltan partidas o si no hay diferencia, y el suelo de reproducibilidad de la escalera pone un límite que más partidas no bajan: M4 lo estimó en unos ±40 Elo de una sigma con dos tiradas, y M6 lo revisó con cuatro (con la máquina parada, el reloj repite al nivel del ruido de muestreo, D-137). - KV cache
- Memoria de las claves (K) y valores (V) de atención de los tokens ya procesados. Al generar token a token, el modelo solo calcula K y V del token nuevo y reutiliza los guardados, en vez de recalcular toda la secuencia en cada paso. Cambia memoria por tiempo: es lo que hace rápidos a los chats y lo que llena la GPU con contextos largos.
- Licencia de pesos
- Con qué permiso se pueden usar los pesos publicados, que no es el de los datos ni el del código. Los de Rukh salen con Apache 2.0 porque las partidas y los puzles de Lichess son CC0; un modelo entrenado sobre datos con restricciones hereda las restricciones, y la card es donde se dice.
- Límite por nodos
- Darle al motor un presupuesto de nodos de búsqueda por jugada en vez de un tiempo. Con tiempo, lo que Stockfish explora en 0,1 s depende de lo que esté haciendo la máquina (D-068: la carga de CPU vale unos +13 Elo). Con nodos la búsqueda es determinista, pero el rival no:
UCI_LimitStrengthaleatoriza a propósito con los dos límites. M6 lo midió con el mismo modelo y la misma semilla: 17 Elo entre dos tiradas por nodos y 0 entre dos por tiempo con la máquina parada, así que el rival se quedó por reloj (D-137) yelo_nodesqueda en la suite para máquinas compartidas y para el lab en que el propio jugador carga la CPU. - Log-probabilidad
- El logaritmo de la probabilidad que el modelo da a un token,
log π(jugada | posición). Se trabaja con logaritmos porque las probabilidades de una secuencia se multiplican y se vuelven diminutas, mientras que sus logaritmos se suman; siempre es ≤ 0, y 0 es certeza.log_softmaxla calcula a partir de los logits sin pasar por probabilidades que redondearían a cero. DPO compara las de la política con las de la referencia; GRPO las multiplica por la ventaja. - Log-verosimilitud
- Cuánto se creen unos parámetros lo que ya pasó: el logaritmo de la probabilidad que el modelo le daba a cada resultado observado, sumado sobre todos ellos. Siempre es negativa, y cuanto más cerca de cero, mejor explica los datos. En el Elo de Rukh es
Σ s · log P + (1 − s) · log(1 − P)sobre las partidas, y el Elo publicado es el que la hace máxima; entrenar el decoder es lo mismo con otro signo, porque la entropía cruzada es la log-verosimilitud media cambiada de signo. - Logits
- Puntuación bruta que el modelo asigna a cada token del vocabulario antes de convertirla en probabilidades (con softmax). En Rukh hay un logit por jugada UCI posible; la demo pone a menos infinito los de las jugadas ilegales antes de muestrear, y la temperatura y el top-k actúan sobre ellos.
- LoRA
- Low-Rank Adaptation: en vez de modificar una matriz de pesos W, se aprende una corrección B·A de rango r (A de r × d, B de d × r, con B inicializada a cero para que el modelo adaptado sea el base en el paso 0) y se suma a W escalada por alpha/r. Entrena pocos parámetros —en
medium, 393 216 con r = 8 sobre consulta y valor, el 0,34 %—, se guarda como un adaptador de 1,6 MB y se puede cambiar en caliente. QLoRA hace lo mismo sobre un modelo base cuantizado a 4 bits. - Lote (batch)
- Las muestras que el modelo ve de una vez antes de un paso del optimizador; en inglés, batch, que es como se llama en el código (
batch_size). La GPU quiere tensores rectangulares, así que un lote es una matriz de forma fija: en Rukh, 64 secuencias de 200 tokens. Cuanto más grande, menos ruido tiene el gradiente y más memoria cuesta; cuando no cabe, la acumulación de gradiente simula uno mayor sumando varios lotes pequeños antes del paso. - Manifiesto de datos
- Fichero JSON que acompaña a cada recorte con los filtros exactos, los meses, los conteos y el hash de cada fichero. Sin manifiesto no hay reproducibilidad: es lo que permite decir qué datos vio un modelo.
- Marco de pila (stack frame)
- El espacio donde viven los argumentos y las variables locales de una llamada mientras esa llamada está en curso; en inglés, stack frame. Desaparece cuando la función vuelve, y por eso guardar algo ahí a propósito —en vez de en un campo del objeto— es una forma de decir «esto no sobrevive a la llamada».
- Máscara
- Tensor de ceros y unos que dice qué posiciones cuentan y cuáles no. En el curso hay tres con el mismo nombre: la causal (M2) impide mirar hacia delante; la de padding marca el relleno (aquí resuelta con ignore_index); la de legalidad (demo) pone a cero las jugadas ilegales antes de muestrear.
- Máscara causal
- Restricción que impide a cada posición mirar hacia delante: antes del softmax, los pesos de las claves futuras se ponen a menos infinito. Sin ella el modelo vería la jugada que tiene que predecir y la pérdida bajaría sin que aprendiese nada. En Rukh la aplica
F.scaled_dot_product_attention(..., is_causal=True). Es lo que hace «causal» a un modelo: en M3 el encoder es el mismo bloque concausal=False, y cada posición ve la secuencia entera. - Memmap
- Fichero mapeado a memoria: np.load(..., mmap_mode="r") no lee el array, sino que lo mapea en el espacio de direcciones y el sistema operativo trae las páginas cuando se tocan. Un GB de tokens uint16 arranca al instante y varios workers comparten las mismas páginas físicas sin copiar nada.
- Mezcla de expertos (MoE)
- Variante del transformer en la que la red feed-forward de cada bloque se parte en muchos "expertos" y un pequeño enrutador elige, para cada token, solo unos pocos. El modelo tiene muchísimos parámetros pero cada token usa una fracción, así que sabe más sin costar proporcionalmente más por token. Rukh no la usa.
- MLflow
- Registro de experimentos: cada entrenamiento guarda su configuración, sus métricas por paso y sus artefactos en una base SQLite local (
rukh mlflow uila abre en el navegador). Las model cards del curso se generan desde ahí para que ningún número se escriba a mano. - MLM (masked language modeling)
- Objetivo de preentrenamiento de BERT: se esconde una parte de los tokens y el modelo, que ve la secuencia por los dos lados, tiene que reconstruirlos. En Rukh se llama masked move modeling porque el token es una jugada: se tapa el 15 % de las jugadas de la partida y de esas el 80 % se sustituye por
<mask>, el 10 % por otra jugada al azar y el 10 % se deja tal cual. Los tokens de control (<bos>, Elo, resultado,<eos>) nunca se tapan: son la condición, no la señal. - Model card
- El README de un repositorio del Hub, y la afirmación pública de qué se publicó y qué se midió. Las de Rukh se generan desde
run.jsonyresults.json, no se escriben a mano, y llevan el SHA del fichero y el de los pesos, el muestreo y la suite de cada número, la fecha, lo que no se midió y la licencia.rukh publish cardslas regenera todas desde la tabla y sube solo el README. - Modelo de lenguaje
- Red neuronal entrenada para predecir el siguiente token dada la secuencia anterior. Aplicado a partidas de ajedrez, predice la siguiente jugada dadas las jugadas previas; de esa única tarea emergen las reglas y el juego.
- Modelo de razonamiento
- Modelo entrenado para escribir un borrador de pasos intermedios (cadena de pensamiento) antes de la respuesta final, normalmente con aprendizaje por refuerzo sobre recompensas verificables: se premia la respuesta correcta y el modelo descubre que pensar por escrito ayuda. Gasta más tokens en inferencia a cambio de acertar más en problemas con solución comprobable.
- Modelo multimodal
- Modelo que lee (o escribe) algo más que texto: imágenes, audio, vídeo. La imagen se corta en parches y el audio en tramos cortos; cada trozo se convierte en un vector, igual que un token de texto, y el mismo transformer los lee todos en una sola secuencia. Rukh no lo es: su único «idioma» son las jugadas.
- Muestreo
- Elegir el siguiente token sorteándolo según las probabilidades del modelo, en vez de coger siempre el más probable (argmax). Una jugada con probabilidad 0,6 sale seis de cada diez veces. En la demo de Rukh se muestrea solo entre las jugadas legales; la temperatura y el top-k deciden cuánto se aleja el sorteo de la favorita.
- multi-PV
- Modo de análisis en el que un motor devuelve varias líneas candidatas para la misma posición, ordenadas de mejor a peor, en vez de solo la mejor. Las evaluaciones publicadas por Lichess son multi-PV, y en Rukh eso da dos cosas gratis: el valor de la posición (la mejor línea) y los pares de preferencia de M5 (la mejor contra una suficientemente peor).
- No transitividad
- Que A gane a B y B gane a C no obliga a que A gane a C. Pasa cuando el resultado depende del emparejamiento y no solo de una fuerza única por jugador, y en M5 se midió: las tres aristas entre la base y los dos DPO —1 600 partidas la de DPO off-policy contra la base, 800 las otras dos, siempre con las dos direcciones agrupadas— dejan un residuo de 45 Elo con un error típico de 18, o sea 2,6 σ. La consecuencia práctica: si te importa cuál de dos modelos gana, enfréntalos; no restes lo que cada uno hizo contra un tercero.
- Norma de Frobenius
- El tamaño de una matriz en un solo número: la raíz cuadrada de la suma de los cuadrados de todos sus elementos, como la longitud de un vector que tuviera todos sus números en fila. Sirve para decir cuánto pesa una matriz al lado de otra. En M4,
‖ΔW‖ / ‖W‖compara la corrección de un adaptador con la matriz que corrige: sobre la consulta del primer bloque demedium, la delora-e4es el 4,41 %, y aun así cambia del todo la primera jugada. - Olvido catastrófico
- Cuando afinar un modelo con datos nuevos le hace perder lo que sabía. No avisa: la pérdida sobre los datos nuevos baja mientras la capacidad vieja se deshace. La defensa no es una técnica sino una medición: se afina con tasa baja, pocos pasos, y se vuelve a medir contra el listón anterior. En M4 el listón es el Elo del modelo base; si el afinado por Elo lo hundiera, el eje habría salido caro.
- On-policy / off-policy
- De dónde salen las respuestas que se comparan. Off-policy: de otro sitio —en Rukh, de las evaluaciones de Lichess—, y dicen qué jugada es mejor tanto si el modelo iba a considerarla como si no. On-policy: del propio modelo, muestreando varias jugadas en la posición y puntuándolas. La distinción importa porque un modelo solo pierde partidas con las jugadas que juega.
- ONNX
- Formato abierto para describir el grafo de una red y sus pesos, independiente del framework que la entrenó. Es lo que permite entrenar en PyTorch y ejecutar en el navegador con
onnxruntime-web, sin Python ni backend. - Oráculo
- Lo que decide si una salida del modelo estuvo bien. En ajedrez es Stockfish: para cualquier jugada dice si es legal y cómo de buena, en milisegundos y gratis. Casi ningún dominio tiene uno así, y la primera pregunta de cualquier proyecto de IA es cuál es su oráculo, cuánto cuesta preguntarle y cuánto se parece su juicio al que de verdad importa.
- Padding
- Relleno con el token <pad> (id 0) para que todas las secuencias de un lote tengan la misma longitud, porque la GPU quiere tensores rectangulares. La pérdida lo ignora con ignore_index. En Rukh casi no hay padding: las partidas se empaquetan en flujo y solo la última ventana se rellena.
- Par de preferencia
- Dos respuestas a la misma entrada, una marcada como mejor (
chosen) y otra como peor (rejected). En Rukh son dos jugadas legales en la misma posición, con la diferencia en centipeones que el motor les puso. Un par no dice cuánto vale una jugada: dice cuál de las dos gana, y eso basta para Bradley-Terry. - Paridad
- En cuántas posiciones la jugada elegida por un modelo exportado coincide con la del modelo original. Mide si la exportación está bien hecha, no si el modelo exportado juega igual de bien: un 95,40 % (int8 de
small, M2) es un modelo que juega otra cosa una vez de cada veinte, y su Elo hay que medirlo jugando. - Parquet
- Formato de fichero columnar y comprimido. Lichess publica sus partidas así en Hugging Face, y DuckDB puede filtrarlas en remoto leyendo solo las columnas y los bloques necesarios (predicate pushdown), lo que hace posible recortar 73 GB a unos pocos sin descargarlo todo.
- Peaje del alineamiento
- Lo que se pierde al ganar. En M5, alinear con DPO dobló la tasa de propuestas ilegales del modelo: 1,3-1,5 % en la base, 2,4-2,6 % con pares propios, 2,9-3,8 % con pares de fuera, y
nll_weightno lo evitó. No rompe las partidas —la jugada ilegal se rescata con un sorteo enmascarado— pero es distribución que se ha ido a otro sitio. La regla: mide el coste en la misma ejecución en la que mides el beneficio. - peft
- La librería de Hugging Face que implementa los métodos de afinado con pocos parámetros —LoRA entre ellos— sobre cualquier
PreTrainedModel. En Rukh no se usa para entrenar los adaptadores propios, que están escritos a mano ensrc/rukh/models/lora.py: se usa como implementación de referencia. La misma configuración sobre los mismos pesos base, con la mismaAcopiada de un lado a otro, tiene que optimizar el mismo número paso a paso; entests/unit/test_hf_wrapper.pysale idéntica hasta el último bit durante seis pasos. Sí es la que entrena el QLoRA de Qwen3, donde el objetivo es recorrer el camino del ecosistema. - Penalización KL
- La divergencia KL mide cuánto se aleja una distribución de otra:
Σ p · log(p/q), cero si son iguales y mayor cuanto más difieren (no es simétrica, así que no es una distancia en sentido estricto). La penalización KL es el término que ata la política a la copia congelada de donde salió; sin él, una recompensa verificable es una invitación a dejar de jugar al ajedrez y ponerse a cultivar el número. Rukh usa el estimador k3,exp(d) − d − 1cond = log π_ref − log π, que es no negativo por construcción: la diferencia de log-probabilidades a secas es negativa la mitad de las veces y pagaría al modelo precisamente por alejarse. - Pérdida (loss)
- El número que el entrenamiento minimiza: cuánto se equivoca el modelo sobre un lote; en inglés, loss. En el decoder es la entropía cruzada entre los logits y el token que venía de verdad, y las posiciones de relleno no cuentan (
ignore_index). No se lee sola: una pérdida de 2,1 no significa nada sin saber sobre qué vocabulario se calculó, y por eso el curso la convierte en perplejidad para compararla. - Perplejidad
- Exponencial de la entropía cruzada media. Se lee como "entre cuántas opciones equiprobables duda el modelo": perplejidad 20 sobre un vocabulario de 2 030 jugadas significa que acierta como si estuviera eligiendo al azar entre veinte. Baja cuando baja la pérdida; es la misma cifra en otra escala.
- PGN
- Formato de fichero de partidas: cabeceras entre corchetes (
[White "..."],[Result "1-0"]) y las jugadas en SAN, con comentarios opcionales como%clko%eval. La demo exporta PGN; los volcados de Lichess lo usan como origen. - Plantilla de chat
- Formato fijo con tokens especiales que marca quién habla en una conversación (sistema, usuario, asistente) y que el modelo aprende en el afinado. Para el modelo, un chat es una sola secuencia plana de tokens: la plantilla es la misma idea que los tokens de control de Elo de Rukh.
- Ply (media jugada)
- Una jugada de un solo bando.
1. e4 e5son dos plies y una jugada completa. Los filtros del recorte y las longitudes de secuencia del modelo se cuentan en plies porque es lo que ve el modelo: un token por ply. - Política (policy)
- El modelo visto como quien decide: dada una posición, la distribución de jugadas que propone; en inglés, policy. Es el nombre que el aprendizaje por refuerzo le da a lo que en el resto del curso es «el modelo», y aparece en M5 porque DPO y GRPO la entrenan contra una referencia congelada de la que
βmide cuánto se le deja alejarse. - Pooling
- Reducir los T vectores que devuelve un encoder a uno solo que represente la secuencia entera. Rukh implementa los dos clásicos:
clstoma el vector de la primera posición (<bos>en la entrada de jugadas,<cls>en la de casillas) ymeanpromedia solo los tokens reales, nunca el relleno. Ese único vector es lo que leen las tres cabezas de M3 y lo que se guarda como embedding de posición. - Potencia estadística
- Qué diferencia es capaz de detectar un experimento del tamaño que tiene. Para una tasa de puntos medida en
npartidas, dos intervalos del 95 % dejan de tocarse cuando la diferencia supera1,96 (se₁ + se₂), es decir, hacen falta unas3,84 / (Δp)²partidas por condición. Sirve en los dos sentidos: antes, para saber si merece la pena medir; después, para distinguir «faltan partidas» de «no hay diferencia». Un resultado negativo sin este número no es un resultado. - PPO
- Proximal Policy Optimization: el algoritmo de refuerzo con el que se alineaban los modelos de lenguaje antes de DPO y de GRPO. Necesita dos entrenamientos —un reward model y una red de valor que estima cuánto vale cada estado— y por eso Rukh no lo usa: DPO se salta la red de valor con una referencia implícita, y GRPO la sustituye por la media del propio grupo de candidatas. Aparece en M5 como el punto de comparación que explica qué se ahorra cada uno de los dos caminos que sí se implementan.
- Pre-norm
- Orden de un bloque Transformer en el que la normalización va antes de la subcapa y su salida se suma a la entrada:
x = x + attn(ln1(x)). Deja un camino sin obstáculos entre la pérdida y las primeras capas, y es lo que permite apilar doce bloques y entrenarlos sin trucos. La variante contraria (post-norm) es la del artículo original y necesita mucho más cuidado. - Precisión
- De todo lo que el detector marcó, qué fracción era de verdad:
VP/(VP+FP). Responde a «¿me puedo fiar cuando avisa?». Es la mitad de F1 que le importa a la demo: una barra que grita «error» en jugadas correctas se apaga a los cinco minutos. No confundir con exactitud, que cuenta también los aciertos sobre la clase mayoritaria. - Precisión media
- Área bajo la curva de precisión-exhaustividad: resume todos los puntos de operación posibles en un número que no depende de ninguno. Su referencia no es 0,5 sino la tasa base, que es lo que saca un orden aleatorio (0,037 en M3); el encoder publicado saca 0,112, el triple. Es más pesimista que el ROC AUC con una clase rara porque solo mira si los positivos están arriba —la primera página del buscador—, y cuando las dos discrepan es la que más se parece a lo que ve el usuario.
- Predicate pushdown
- Empujar el filtro hasta el almacén de datos para que solo viaje lo que pasa el filtro, en vez de traerlo todo y descartar en local. Es lo que permite que
rukh data fetchsaque un recorte de dos meses de Lichess (73 GB por mes en parquet) descargando solo los pocos GB de partidas que cumplen los filtros. - Preentrenamiento
- Primera y más cara fase de un modelo de lenguaje: aprender a predecir el siguiente token (o el token tapado, en un encoder) sobre una montaña de texto sin etiquetar. Deja un modelo que conoce el idioma, o el ajedrez, pero que todavía no sigue instrucciones. En Rukh es el entrenamiento del decoder en M2 y el masked move modeling de M3.
- PreTrainedModel
- La clase base de
transformersque define el contrato que habla todo el ecosistema de Hugging Face:from_pretrained,save_pretrained, unaPretrainedConfigserializable y unforwardque devuelve un objeto conlogitsyloss. Rukh no la hereda en su decoder: escribe una envoltura de cien líneas (src/rukh/models/hf.py) que contiene unMoveDecoder, así que hay una sola definición del paso hacia delante en el repositorio y el test de que las dos dan los mismos logits comprueba que el envoltorio es fiel. Lo que eso compra es concreto:peft,trly el Hub funcionan sobre el decoder sin reimplementar ninguno. - Probe lineal
- Congelar un modelo y entrenar encima solo una capa lineal para una tarea nueva. Si la capa lineal acierta, la información ya estaba en la representación y el preentrenamiento la puso ahí; si no acierta, no se puede concluir que no esté, solo que no está de forma linealmente legible. En Rukh es el modo
probederukh train heads, y un test comprueba que los pesos del encoder salen idénticos bit a bit. - Prompt de sistema
- Instrucciones que quien despliega un chat pone al principio de cada conversación, antes de lo que escribe el usuario («eres un asistente de…», «responde en español»). Para el modelo son tokens como cualquier otros, marcados con el rol de sistema en la plantilla de chat; el afinado le enseña a darles prioridad.
- Proxy
- Un número que se mueve en la misma dirección que lo que importa, casi siempre, hasta que deja de hacerlo. La pérdida de validación es el proxy de la fuerza; el top-1 lo es de la calidad. Rukh tiene dos contraejemplos medidos: el mismo checkpoint con dos muestreos se lleva unos 180 Elo con la misma pérdida (1359 con muestreo casi determinista frente a 1181 con la temperatura 0,6 de la demo, D-047), y GRPO subió la recompensa que optimizaba mientras colapsaba la política (M5). La regla: mide la métrica de dominio, y usa el proxy para decidir cuándo medirla.
- Punto de operación
- El umbral a partir del cual una probabilidad se convierte en una decisión («p ≥ 0,0663 es error»). Precisión, exhaustividad y F1 dependen de él; ROC AUC y precisión media no. Es un hiperparámetro legítimo, pero solo hay una forma honesta de elegirlo: en filas que no son las que se puntúan. En Rukh las filas etiquetadas del conjunto held-out se parten en dos por
game_id, la mitadtuneelige el umbral que maximiza F1 y la mitadscorees la que se publica. Cada checkpoint tiene el suyo (0,0663 ellast-nde jugadas, 0,04459 el de casillas), y el 0,5 de fábrica deconfigs/eval/encoder.yamlse publica al lado, nunca como titular. - QLoRA
- LoRA sobre un modelo base cuantizado a 4 bits: los pesos congelados ocupan una cuarta parte y los adaptadores siguen entrenándose en 16 bits, así que cabe en la GPU un modelo que en fp16 no cabría. El ahorro se nota cuando el peso está en las capas lineales; a 0,6 B parámetros, con una tabla de embeddings que es el 26 % del modelo y no se cuantiza, el ahorro medido fueron 341 MB de pesos (29 %) y 7 MB del pico de memoria (0,4 %). El nombre promete más de lo que da a esa escala, y decirlo forma parte de usarlo bien.
- RAG
- Retrieval-Augmented Generation: antes de generar, se recuperan fragmentos relevantes (posiciones parecidas, párrafos de un libro) por similitud de embeddings y se le dan al modelo como contexto. Permite citar fuentes y actualizar conocimiento sin reentrenar.
- Rango (de una matriz)
- Cuántas direcciones independientes describe una matriz. Una de 768×768 puede tener hasta 768; el producto B·A de LoRA con r=8 tiene como mucho 8, y ahí está todo: es lo que lo abarata (12 288 números en vez de 589 824) y también lo que lo limita, porque cualquier corrección que el adaptador quiera aprender tiene que caber en esas ocho direcciones.
- Recompensa (reward)
- El número que dice si una salida fue buena; en inglés, reward. Puede estimarlo un modelo entrenado con preferencias —el reward model de M5— o calcularlo un programa que se puede auditar y que no se entrena, como la recompensa verificable que consulta a Stockfish. Lo que el entrenamiento optimiza es la recompensa, no lo que querías: si la regla se puede rodear, el modelo la rodea.
- Recompensa verificable
- Una recompensa que calcula un programa y se puede comprobar, en vez de estimarla un modelo entrenado con opiniones. El ajedrez es uno de los pocos sitios donde se puede escribir entera: una jugada es legal o no, un mate es un mate, y el motor pone un número a la posición. Lo que gana es que no puede equivocarse como se equivoca un modelo aprendido; lo que no gana es inmunidad al reward hacking, porque sigue siendo un diseño humano.
- recorte de gradiente
- Reescalar el vector de gradientes cuando su norma global supera un umbral (1,0 en Rukh), antes de cada paso del optimizador. Es un seguro contra un lote patológico: sin él, una secuencia rara puede mover los pesos lo suficiente para tirar horas de entrenamiento. El
grad_normregistrado en MLflow pegado al umbral paso tras paso significa que la tasa de aprendizaje es alta. - Referencia (modelo de referencia)
- Una copia congelada de los pesos de partida: ni se entrena ni se publica, y está en modo evaluación para que el dropout no le meta ruido. DPO y GRPO miden contra ella cuánto se ha movido la política: DPO compara las log-probabilidades de las dos jugadas del par con las que les daba la referencia, y GRPO le pone una penalización KL. Es el checkpoint del que parte cada entrenamiento: en los modelos publicados de M5,
medium-v4tal como salió de M2. - Registro de decisiones
- El cuaderno del proyecto:
docs/decisiones-de-ejecucion.md, en el reporukh. Cada entrada lleva un identificador (D-070,D-107,D-126) y dice tres cosas: qué se decidió, por qué, y qué cuesta si está mal. Las lecciones citan esos identificadores cuando un número del curso depende de una decisión discutible o de un error que hubo que corregir, para que puedas ir a la fuente y no fiarte solo del relato. - Regresión logística
- Ajustar una curva en forma de S que convierte una diferencia en una probabilidad —en el Elo,
1 / (1 + 10^((rival − modelo)/400))— eligiendo el parámetro que hace más probables los resultados observados. El Elo de Rukh es una regresión logística con un único parámetro, el propio Elo, resuelta por Newton en dos o tres pasos; Bradley-Terry, en M5, es la misma curva conσy puntuaciones aprendidas. - Retropropagación
- El cálculo que dice a cada peso hacia dónde moverse. Tras medir el error a la salida, se recorre la red una vez hacia atrás multiplicando, eslabón a eslabón, cuánto influyó cada pieza en la siguiente (la regla de la cadena); cada peso recibe así su parte de la culpa y su signo. Cuesta del orden de una pasada hacia delante más, y es lo que hace posible entrenar millones de pesos a la vez; en Rukh lo hace PyTorch con
loss.backward(). - Reward hacking
- Que el modelo maximice el número en vez de hacer la tarea. En Rukh se midió sin entrenar nada: seis recompensas, cinco de ellas rotas a propósito, sobre el mismo grupo de candidatas. Las seis coronan la misma jugada —el daño no está en la cima— y las rotas se ven en la forma del grupo: una sola candidata catastrófica se lleva el 46 % de la ventaja, y el valor de una recompensa sin tope se mueve 47 veces su intervalo legal al cambiar la profundidad del motor.
- Reward model
- Una red que lee una respuesta y devuelve un número, entrenada con pares de preferencia para que le dé más al preferido. Es lo que hace falta para PPO y lo que DPO no necesita. En Rukh lee la posición resultante con el encoder de casillas y acierta en torno al 75 % de los pares no vistos; falla justo en la banda de mate, que es donde una recompensa verificable acierta siempre.
- RLHF
- Reinforcement learning from human feedback: la receta que convierte un LLM base en un asistente. Se recogen preferencias (de dos respuestas, cuál es mejor), se entrena con ellas un reward model y se optimiza la política contra él sin dejar que se aleje demasiado del modelo de partida. En Rukh el «humano» es Stockfish, y M5 recorre la receta clásica y sus dos atajos, DPO y GRPO.
- ROC AUC
- Probabilidad de que, cogidos al azar un positivo y un negativo, el modelo puntúe más alto al positivo: 0,5 es una moneda y 1 es orden perfecto. No depende de ningún umbral, así que ningún punto de operación puede halagarla ni hundirla; en M3 el mismo modelo con F1 0,0000 en el umbral de 0,5 tiene 0,740 de ROC AUC. Con una clase muy rara se deja impresionar por lo bien que se ordenan los negativos entre sí, por lo que se publica junto a la precisión media, que solo mira si los positivos suben. En Rukh está escrita a mano sobre rangos en
src/rukh/eval/. - RoPE
- Codificación de posición rotatoria (rotary position embedding): en vez de sumar un vector de posición, rota por pares las dimensiones de las consultas y las claves con un ángulo proporcional a la posición. El producto escalar entre dos posiciones depende entonces solo de su distancia, y no hace falta una tabla de posiciones. En Rukh es la alternativa a las posiciones aprendidas (
pos: rope). - safetensors
- Formato de serialización de tensores que el Hub de Hugging Face espera y previsualiza, y que no ejecuta código al leerse. Guarda tensores y no alias, así que un modelo con tied embeddings —donde
lm_head.weightytokens.weightson un tensor con dos nombres— tiene que publicar el nombre atado fuera del fichero y volver a atarlo al cargar. - SAN
- Notación algebraica estándar, la de los libros:
Nf3,O-O,exd5+. Es compacta para humanos pero ambigua sin el tablero (hay que saber qué caballo puede ir a f3). Lichess publica las partidas en SAN; Rukh las convierte a UCI conpython-chess. - Secuencia
- La lista ordenada de ids que el modelo recibe como entrada. En Rukh, una partida codificada: <bos>, los dos tramos de Elo, las jugadas, el resultado y <eos>. Su longitud depende de la tokenización: unos 80 tokens por partida en UCI, cuatro o cinco veces más por carácter.
- semi join
- Cruce que devuelve las filas de la tabla izquierda que tienen alguna coincidencia en la derecha, sin traer ninguna columna de la derecha y sin duplicar filas. En Rukh es lo que permite cruzar nuestras posiciones con los 42 GB de evaluaciones de Lichess leyendo solo la columna de la clave: DuckDB descarta los bloques sin coincidencias y descarga unos cientos de megas en vez del fichero entero.
- Semilla (seed)
- El número que fija el azar de una ejecución —inicialización, barajado, dropout, muestreo—; en inglés, seed. Sin ella dos entrenamientos idénticos dan números distintos y no se sabe si una diferencia es el cambio o la tirada. En Rukh el barajado usa
seed + epoch, para que dos épocas no sirvan el mismo orden, y fijarla es lo que convierte «el modelo mejoró» en una afirmación comprobable. - SFT (supervised fine-tuning)
- Seguir entrenando un modelo ya preentrenado con el mismo objetivo —predecir el siguiente token— pero sobre un corpus elegido. No cambia la pérdida ni la arquitectura: cambia de qué distribución salen los ejemplos, y eso es todo lo que hace falta para mover el comportamiento. En Rukh son los dos afinados del hito:
medium-masterssobre partidas de élite ymedium-elosobre un corpus plano en Elo. - Shard
- Uno de los ficheros en los que se parte un dataset grande. Un mes de
Lichess/standard-chess-gamesson 72 parquet de un gigabyte, y de cómo se leen depende que la descarga funcione: leerlos en remoto son miles de peticiones de rango contra un mismo anfitrión, que contestaHTTP 429a mitad de camino (medido: 0,02 MB/s después de cincuenta minutos, con cero bytes escritos). Bajar cada shard entero, filtrarlo en local y borrarlo va a 14,8 MB/s, deja un pico de disco de un fichero y permite reanudar por el shard en el que se paró. - Sobreoptimización
- Lo que pasa cuando se optimiza un sustituto de lo que se quiere más allá del punto en que se parecen: la recompensa medida sigue subiendo mientras la calidad real se estanca o baja. Es la ley de Goodhart aplicada al entrenamiento. En M5, la recompensa de GRPO sube también cuando la política colapsa hacia unas pocas jugadas; se detecta midiendo con un instrumento distinto del que se optimiza (la arena) y se frena con la KL.
- Softmax
- Función que convierte una lista de puntuaciones (logits) en probabilidades que suman 1: exponencia cada número y divide por la suma. Agranda las diferencias, así que el favorito se lleva más de lo que su ventaja bruta sugiere. Aparece dos veces en cada paso: dentro de la atención y al final, para elegir el siguiente token.
- Sondeo de compilación (compile probe)
- Una pasada de mentira que se hace a propósito antes de entrenar para que
torch.compilecompile ahí, y falle ahí si va a fallar; en inglés, probe. Paga por adelantado el minuto de compilación y convierte un error de forma dinámica en un error del primer segundo en vez de uno de la media hora. No es el probe lineal de M3, que es otra cosa con el mismo nombre en inglés. - Stockfish
- Motor de ajedrez libre (GPL-3) y el más fuerte disponible. En Rukh no juega por el modelo: es el juez. Con
UCI_LimitStrengthyUCI_Elo(1320-3190) se convierte en un rival calibrado para estimar Elo, y a poca profundidad da recompensas baratas para el alineamiento. - Suelo de reproducibilidad
- Cuánto se mueve una medición cuando no se cambia nada: el límite por debajo del cual dos números del mismo instrumento no se pueden distinguir. En la escalera de Rukh son unos 40 puntos de Elo de una sigma —±80 al 95 %—, medidos midiendo
medium-eloa<w1800>dos veces con la misma semilla y obteniendo 1498 y 1558. La semilla fija el muestreo del modelo y no el del rival, que juega por tiempo y conUCI_LimitStrength, así que «las mismas 160 partidas» no son las mismas partidas. Cualquier diferencia entre modelos más pequeña que eso no es una diferencia entre modelos, y no hay número de partidas que lo arregle. - Tabla única
- La tabla de resultados que mide todas las etapas de Rukh con las mismas columnas: tasa de jugadas legales sin máscara, top-1 y top-3 por tramo de Elo, puzles resueltos por dificultad y Elo estimado contra Stockfish con su intervalo de confianza. Se fija en M0 y cada modelo, del primer decoder de M2 al de M6, añade una fila; como las columnas no cambian, dos filas cualesquiera se pueden comparar.
- Tasa base
- Frecuencia de la clase positiva en los datos: en M3, los errores son el 3,7 % de las filas etiquetadas. Es el número que hay que preguntar antes de leer cualquier exactitud, porque un detector que siempre dice «no» acierta uno menos la tasa base (96,3 %) sin saber nada de ajedrez, y es la referencia de la precisión media: un orden aleatorio saca exactamente la tasa base (0,037), no 0,5.
- Tasa de legalidad
- Porcentaje de jugadas propuestas por el modelo que son legales cuando no se le enmascaran las ilegales. Es la primera métrica de la tabla única: mide si el modelo ha aprendido las reglas solo viendo partidas. En la demo, la legalidad la decide chess.js; el modelo solo propone.
- Temperatura
- Divisor que se aplica a los logits antes del softmax. Por debajo de 1 concentra la probabilidad en las jugadas que el modelo prefiere (con temperatura 0 es directamente el argmax) y por encima de 1 la reparte. En Rukh el valor por defecto es 0,6: juego variado pero no temerario.
- Tensor
- El array de PyTorch: números de un único tipo (
dtype) en una rejilla rectangular con forma (shape), en CPU o en GPU, que además recuerda cómo se calculó para poder derivar. En Rukh un lote de tokens es un tensorint64de forma(64, 200)y los logits del decoder, uno de coma flotante de forma(64, 200, 2030). Es unndarrayde NumPy con GPU y autograd. - Tied embeddings
- Reutilizar la misma matriz para leer tokens (embedding de entrada) y para escribirlos (capa de salida sobre el vocabulario). En
rukh-smallahorra 1 039 360 parámetros y fuerza a que la representación con la que se lee una jugada sea la misma con la que se apuesta por ella. - tipado pato
- Aceptar un objeto por los métodos que tiene y no por la clase de la que hereda: «si grazna como un pato…». En Rukh es lo que permite que un grafo ONNX de 68 líneas (
OnnxDecoder) juegue en la escalera de Stockfish por el mismo camino que un checkpoint, implementando solo las tres cosas que el muestreador mira:next_logits,parametersycfg.block. - Token
- Unidad mínima que el modelo lee y escribe. En Rukh, por defecto, un token es una jugada completa en notación UCI (
e2e4); en otras tokenizaciones puede ser un carácter o un trozo de texto aprendido por BPE. El modelo nunca ve letras ni tableros: ve identificadores enteros de tokens. - Top-1
- Exactitud de siguiente jugada en su forma estricta: porcentaje de posiciones de partidas no vistas en las que la jugada más probable del modelo es exactamente la que jugó el humano. Es la segunda métrica de la tabla única y se publica global y por tramo de Elo. No mide fuerza de juego, sino parecido con el humano: un modelo con top-1 perfecto contra partidas de 1200 jugaría como un 1200, errores incluidos. El techo tampoco es el 100 %, porque el mismo humano en la misma posición no siempre juega lo mismo. M2 midió 51,1 % con
small. - Top-3
- La versión laxa de la misma medida: porcentaje de posiciones en las que la jugada humana está entre las tres más probables del modelo. Se publica junto al top-1 porque este solo engaña: cuando hay tres jugadas razonables, repartir la probabilidad entre ellas es lo correcto, no un fallo. Top-1 mediocre con top-3 alto dice que el modelo entiende la posición aunque no adivine qué humano concreto está a los mandos; los dos bajos dicen que no ha aprendido nada. M2 midió 79,4 % con
small. - Top-k
- Truncamiento del muestreo: solo se conservan los k tokens de mayor probabilidad y el resto pasa a probabilidad cero antes de sortear. Con k = 20 el modelo nunca juega una ocurrencia de la cola de la distribución, que es de donde salen casi todas las jugadas absurdas.
- Top-p (nucleus)
- Filtro de muestreo que se queda con el grupo más pequeño de tokens cuya probabilidad acumulada llega a p (por ejemplo 0,9) y descarta el resto. A diferencia de top-k, el número de candidatos se adapta: pocos cuando el modelo está seguro, muchos cuando duda. El curso usa top-k; top-p es el habitual en los chats.
- torch.compile
- Función de PyTorch que traduce el modelo a código de GPU especializado para las formas de los tensores que ve, y lo acelera sin cambiar lo que calcula. La especialización es su precio: un tensor con otra forma dispara una recompilación de segundos. Por eso el dataloader de M1 usa
drop_last=True, para que el último lote de cada época no llegue más corto; en M2 el entrenamiento lo activa y, si el sistema no puede compilar, sigue sin él. - Transformer
- Arquitectura de red en la que casi todos los LLM de hoy se basan: una pila de bloques iguales, cada uno con una capa de atención (las posiciones se miran entre sí) y una red feed-forward (cada posición se procesa por separado), unidas por conexiones residuales y normalización. El decoder de M2 y el encoder de M3 son dos transformers que solo se diferencian en la máscara de atención.
- Tubería (pipe)
- El canal por el que dos procesos se pasan datos; en inglés, pipe. Todo lo que cruza se serializa con
pickle, así que el coste no es el cálculo sino la copia: en M1, el objeto del dataset viaja entero una vez por worker, y con 18,9 millones de partidas son 145 MB que cortan la tubería antes del primer paso con unUnpicklingErrorque no menciona los datos por ningún lado. - UCI
- Dos cosas con el mismo nombre. La notación UCI escribe una jugada como casilla de origen, casilla de destino y promoción opcional (
e7e8q): no depende del contexto, por eso es la tokenización por defecto. El protocolo UCI es la forma en que hablamos con Stockfish desdepython-chess. - uv
- Gestor de paquetes y entornos de Python (de Astral) que en este proyecto fija el intérprete (
.python-version), resuelve las dependencias, escribe el fichero de bloqueouv.locky ejecuta todo conuv run. Sustituye a pip, venv y pip-tools a la vez, y es lo que hace que el entorno sea reproducible entre máquinas. - Valores singulares
- Las longitudes de las direcciones por las que una matriz puede empujar, que salen de su descomposición en valores singulares (SVD). Cuántos son distintos de cero es el rango de la matriz, y eso convierte la afirmación central de LoRA en una línea de álgebra comprobable: la corrección
(alpha/r)·B·Ade un adaptador de rango 8 tiene exactamente ocho valores singulares distintos de cero, y el noveno es cero de verdad (2,8·10⁻⁷ frente a 0,18 del octavo) y no «pequeño». Sobre la matriz de consulta del primer bloque demedium, que tiene 768 y ninguno nulo, la corrección pesa el 4,41 % en norma de Frobenius. - Ventaja (advantage)
- Cuánto mejor fue una respuesta que el baseline con el que se la compara; en inglés, advantage. Es lo que multiplica al gradiente —
ventaja · log π(jugada | prompt)—, así que una ventaja positiva empuja esa jugada arriba y una negativa la empuja abajo. En GRPO sale del propio grupo: si las ocho candidatas puntúan igual, todas las ventajas son cero y el paso no aporta gradiente con el motor ya pagado. - Ventana de contexto
- Número máximo de tokens que el modelo puede ver a la vez; en Rukh, 200 (el bloque del dataloader). Lo que no cabe se trunca. Como la atención cuesta el cuadrado de la longitud, una ventana cuatro veces mayor es dieciséis veces más cara, y por eso importa que el 99,8 % de las partidas del recorte quepan en 200 tokens UCI (medido sobre 20 000 partidas de enero; por carácter solo cabe el 7,77 %).
- Vocabulario
- La lista de todos los tokens que el modelo conoce, cada uno con un id entero fijo. En Rukh el vocabulario UCI tiene 2 030 entradas: 8 tokens especiales, 54 tramos de Elo y las 1 968 jugadas posibles, enumeradas sin mirar datos. Su tamaño fija el de la capa de embeddings y el de la capa de salida.
- Warmup
- Arranque en el que la tasa de aprendizaje sube linealmente desde cero durante los primeros pasos (1 000 en
small) antes de empezar a decaer. Evita que Adam dé pasos enormes mientras sus medias móviles todavía se estiman con un puñado de gradientes —en el paso 1, con uno solo—, que es cuando un modelo recién inicializado se rompe: no con unNaN, sino cayendo en predecir siempre las jugadas más frecuentes del corpus. - WASM
- WebAssembly: formato binario que el navegador ejecuta a velocidad cercana a la nativa. En Rukh es el respaldo de WebGPU y corre el grafo int8 (unos 43 MB frente a los 79 del fp16), que es lo que hace que la demo cargue en un móvil; el runtime se sirve desde el propio origen, nunca desde un CDN.
- web worker
- Hilo aparte del navegador, sin acceso al DOM, que se comunica con la página por mensajes. En la demo de Rukh el worker es el dueño de la sesión de ONNX Runtime: el hilo principal nunca toca el runtime, así que descargar 40 MB de modelo y ejecutar una inferencia no bloquean el tablero.
- WebGPU
- API del navegador que da acceso a la GPU para cómputo general, y el camino rápido de la demo de Rukh:
onnxruntime-webejecuta con ella el grafo fp16. Cuando no hay adaptador —o cuando crear la sesión sobre él falla— la demo cae a WASM y publica el motivo debajo de la insignia del backend. - β (beta)
- Cuánto se le deja alejarse a la política de su referencia congelada: la dureza de la correa. En DPO multiplica la diferencia de log-probabilidades dentro de la sigmoide y en Rukh vale 0,1; en GRPO el mismo papel lo juega el peso de la penalización KL,
beta_kl: 0.02. Pequeña, la correa es floja y la política persigue la señal hasta olvidarse de jugar; grande, casi no se mueve.