Skip to content

English · Español

Lab 03 — Lectura anotada del block_manager.py de vLLM

Objetivo: leer el asignador real de KV cache de paged attention en el upstream de vLLM y producir un comentario anotado con tus propias palabras.

Tiempo estimado: 4–6 horas (mayormente lectura + redacción de notas; sin codificar).

Prerrequisito: theory 03 leída; sabes describir paged attention sin notas.

Lo que produces

docs/phase-27-modern-attention/notes/vllm-block-manager-annotated.md que contenga:

  • El texto completo de vllm/core/block_manager.py (o el subconjunto relevante) parafraseado — no pegues el archivo literal (licencia; además, parafrasear es el trabajo).
  • Comentario sección a sección con tus propias palabras.
  • Cinco respuestas a las preguntas de abajo.

experiments/27-paged-attn-reading/manifest.json registrando: la versión de vLLM que leíste, el SHA del commit, la fecha.

Un README.md corto en el directorio del experimento apuntando a las notas.

Procedimiento

Paso 1 — encontrar el archivo

  • Clona vLLM en un commit específico (registra el SHA). No leas main; fija a una release.
  • Localiza vllm/core/block_manager.py y vllm/block.py.

Paso 2 — leer por estructura (1 hora)

  • Identifica las clases principales. Típicamente: BlockTable, BlockAllocator, BlockManager.
  • Para cada clase: ¿qué estado mantiene? ¿Cuál es la API pública (métodos llamados desde fuera)?
  • Dibuja un diagrama de secuencia (mermaid basado en texto en tu archivo de notas) mostrando el ciclo de vida de una request desde add_request a free_request.

Paso 3 — leer por semántica (2–3 horas)

Para cada método público, anota:

  • Qué hace en una frase.
  • Qué invariantes preserva (p. ej., "la page table nunca apunta a una página liberada").
  • Qué podría salir mal y cómo el código lo maneja.

Paso 4 — responder las cinco preguntas

En tu archivo de notas, con citas a números de línea / funciones específicas:

  1. Algoritmo de asignación de páginas. ¿Es basado en free-list, en bitmap, u otra cosa? ¿Por qué la estructura elegida es apropiada para el patrón de acceso?
  2. Política de desalojo. Cuando se agotan las páginas, ¿qué secuencias se desalojan? ¿LRU? ¿Basado en prioridad? ¿Qué le ocurre a una secuencia cuya página se desaloja en medio de la generación?
  3. Disparador del copy-on-write. ¿Cuándo ocurre? ¿Cuál es el mecanismo real — copia la página de forma eager o lazy?
  4. Representación de la page table. ¿Lista por secuencia de IDs de bloques físicos? ¿Una estructura más astuta? ¿Cómo se mantiene baja la latencia de búsqueda?
  5. Interfaz con el kernel de atención. ¿Cómo accede el kernel GPU realmente a K/V dada la page table? (No hace falta meterte en el kernel CUDA — sólo el handoff del lado Python.)

Paso 5 — conectar de vuelta con theory 03

En un párrafo de cierre:

  • Confirma o corrige cada afirmación de theory 03 contra el código real.
  • Anota un detalle en la implementación que theory 03 no mencionó (siempre hay alguno).

Condiciones de parada

  • El archivo anotado tiene ≥ 1500 palabras de tu prosa (no código pegado).
  • Las cinco preguntas tienen respuestas con citas a número de línea.
  • El párrafo de conexión identifica al menos una simplificación de theory 03.

Restricciones

  • No copies-pegues código de vLLM literal. Parafrasea: reescribe la lógica con tus palabras. Snippets de código ≤ 5 líneas valen para ilustrar.
  • Cita el SHA del commit que leíste. La API de vLLM evoluciona; los lectores futuros necesitan saber qué versión mirabas.
  • No hace falta ejecutar vLLM. Es un lab de lectura + escritura. (Si tienes tiempo y GPU en cloud, ejecutar vLLM con un debugger para pasar por add_request es un excelente ejercicio opcional.)

Errores típicos

  • Leer sin tomar notas. Todo se difuminará. Toma notas según avanzas, no al final.
  • Saltarte las partes que son "sólo ingeniería". Suelen ser donde vive la astucia. (Indirección de la page table, alineamiento, lógica de swap-out de páginas KV → memoria CPU bajo presión — todo no trivial.)
  • Confundir paged attention (el kernel) con paged attention (el asignador). Este lab es el segundo. El kernel está en vllm/attention/ops/paged_attn.py; lo mencionamos pero no lo leemos línea a línea.

Cuándo consultar solutions/

La "solución" aquí es solutions/03-paged-attn-reading-ref.md (apertura de fase) — la propia lectura anotada de Claude sobre el mismo archivo en el mismo commit. Compara estructura y comprueba si se te escapó algo importante. No la consultes antes de escribir la tuya; el valor de este lab es el acto de leer.

Siguiente lab: lab/04-mqa-gqa.md.