// glosario · 60 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.
- 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.
- 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.
- 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í.
- 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.
- 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.
- Cabeza de atención
- Una atención completa calculada en un subespacio de la representación. `rukh-small` parte 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.
- 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.
- 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 de `f`, así que el gradiente llega íntegro a las capas de abajo aunque `f` aporte poco; el flujo de vectores que atraviesa el modelo de principio a fin se llama por eso corriente residual.
- Correlación (Pearson y Spearman)
- Dos maneras de medir si un número predicho acompaña al real. Pearson mide si los valores se alinean en una recta; Spearman es Pearson sobre los rangos, así que solo mide si el orden coincide. 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 `tanh` acotado a una puntuación en centipeones. `GOAL.md` pide ≥ 0,8 entre el valor del encoder y el `cp` de Stockfish.
- 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 (`MatMul` y `Gemm`) y cada fichero pasa una prueba de paridad contra PyTorch antes de subirse.
- 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.
- DuckDB
- Base de datos analítica embebida que ejecuta SQL sobre ficheros parquet locales o remotos (`hf://`). Es la herramienta con la que `rukh data fetch` aplica los filtros del recorte antes de materializar nada en disco.
- 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-small` la 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.
- 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á en `configs/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 Rukh, un detector que dijera «no es error» siempre acertaría el 90 % de las veces y tendría F1 cero. La media armónica castiga el desequilibrio, así que solo sube si las dos suben. El listón de `GOAL.md` para M3 es superar en cinco puntos de F1 a la heurística de material.
- 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.
- 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, febrero valida), por PuzzleId con semilla en los puzles, y entrenando el BPE solo con datos de enero.
- Línea base
- 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.
- 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 un producto de dos matrices pequeñas A·B de rango r y se suma a W. Entrena pocos parámetros, se guarda como un adaptador de unos MB y se puede cambiar en caliente. QLoRA hace lo mismo sobre un modelo base cuantizado a 4 bits.
- 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.
- 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)`.
- 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.
- 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 ui` la 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.
- 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.
- 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.
- 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.
- 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.
- 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 `%clk` o `%eval`. La demo exporta PGN; los volcados de Lichess lo usan como origen.
- Ply (media jugada)
- Una jugada de un solo bando. `1. e4 e5` son 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.
- Pooling
- Reducir los T vectores que devuelve un encoder a uno solo que represente la secuencia entera. Rukh implementa los dos clásicos: `cls` toma el vector de la primera posición (`<bos>` en la entrada de jugadas, `<cls>` en la de casillas) y `mean` promedia 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.
- 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.
- 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 `probe` de `rukh train heads`, y un test comprueba que los pesos del encoder salen idénticos bit a bit.
- 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.
- RLVR
- Aprendizaje por refuerzo con recompensas verificables: la recompensa la calcula un programa (aquí, un motor de ajedrez) y no una persona ni un modelo entrenado con opiniones. GRPO es el algoritmo con el que Rukh lo aplica; DPO es la alternativa sin bucle de refuerzo.
- 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`).
- 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 con `python-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.
- 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_LimitStrength` y `UCI_Elo` (1320-3190) se convierte en un rival calibrado para estimar Elo, y a poca profundidad da recompensas baratas para el alineamiento.
- 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.
- Tied embeddings
- Reutilizar la misma matriz para leer tokens (embedding de entrada) y para escribirlos (capa de salida sobre el vocabulario). En `rukh-small` ahorra 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.
- 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-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.
- 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 desde `python-chess`.
- 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 95 % de las partidas quepan en 200 tokens UCI.
- 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 cuatro gradientes, que es cuando un modelo recién inicializado se rompe.