Las 10 trampas que te vas a encontrar el primer mes montando IA local
De todos los errores que hemos documentado, estos son los que casi todo el mundo pisa al empezar con vLLM, llama.cpp o SGLang. Síntoma, causa y la comprobación de treinta segundos que te ahorra la tarde.
Llevamos muchas trampas documentadas. Algunas son muy de nuestro montaje. Pero hay diez que vemos repetirse en cualquiera que empieza a servir modelos en su propia máquina. Aquí van, ordenadas por lo pronto que te las vas a encontrar.
1. Copiar el --gpu-memory-utilization de otra máquina
En una máquina con memoria unificada, la «memoria de la GPU» es la del sistema. Copiamos un
0.90 de una receta ajena: eran ~109 GiB de 121,6 para vLLM y casi nada para el sistema
operativo. Apagado con el botón (P-069).
Comprobación: calcula cuánto deja libre para el sistema antes de arrancar, no después.
2. Fiarte de lo que dice la configuración en vez de lo que está corriendo
Nuestra documentación dijo durante 18 horas que el speculative decoding estaba apagado. Estaba encendido, y atribuimos a otra cosa una mejora del 79 % (P-001). Peor: el propio endpoint de estado decía «none» aunque el drafter funcionaba (P-002).
Comprobación: docker inspect <contenedor> --format '{{json .Config.Cmd}}' y el log de
arranque. La máquina manda sobre cualquier documento.
3. Medir la primera petición después de arrancar
La primera petición tras un arranque paga compilaciones, cachés frías y asignaciones. La misma medida repetida minutos después fue un 25 % más rápida (P-019).
Comprobación: siempre una o dos peticiones de calentamiento que no cuentan.
4. Medir TTFT mirando solo content
Los modelos que razonan envían el pensamiento en otro campo (reasoning_content, o reasoning
a secas según el runtime). Un medidor que solo mira content cuenta cero tokens durante
todo el razonamiento y te da un TTFT absurdo (P-016).
Comprobación: cuenta los tokens que reporta el servidor (stream_options.include_usage), no
fragmentos del stream. Con decodificación especulativa, un fragmento trae varios tokens
(EXP-0058).
5. Que la caché te regale la medida
Si tus prompts de prueba comparten el principio, la caché de prefijo se ahorra el trabajo y el prefill parece milagroso. Nos pasó con prompts generados con la misma semilla: el corto era el prefijo exacto del largo (P-094).
Comprobación: mira cached_tokens en la respuesta. Tiene que ser 0 en una medida en frío.
6. Descargar el modelo sin la plantilla de chat
Los repositorios modernos de Hugging Face guardan la plantilla en chat_template.jinja, aparte.
Un script de descarga con una lista de extensiones «exhaustiva» que no incluye *.jinja deja el
modelo sin plantilla (P-015). Arranca, responde… y responde mal.
Comprobación: ls del directorio del modelo. Si hay chat_template.jinja en el repo, tiene
que estar en tu disco.
7. Pensar que el cliente usa el contexto que sirve el servidor
Subimos el contexto de un modelo a 262K. El cliente seguía compactando la conversación a 65K,
porque tenía ese número escrito a mano en su configuración (P-022). Lo mismo
con max_tokens: manda el cliente.
Comprobación: mira qué contexto y qué salida máxima declara cada cliente, no solo el servidor.
8. «No tiene memoria y se queda parado»: casi nunca es el contexto
Síntomas: «se pierde», «se queda parado», «cosas simples le cuestan». Todo apunta al contexto y
en nuestro caso no lo era (P-023): el pico de uso real fue de 12.553 tokens
de 262.144 disponibles, un 4,8 %. Lo que sí había en cada mensaje fallido era un error de
herramientas (Expected 'function.name' to be a string) que el cliente no enseñaba.
Comprobación: antes de tocar el contexto, mira cuántos tokens usa de verdad cada turno y qué error devuelve cada mensaje fallido. Es gratis y suele dar la respuesta.
9. Un corte de luz deja los contenedores sin DNS… y vLLM no falla: se cuelga
Si un contenedor se crea durante el arranque del sistema, antes de que el resolvedor del host
esté listo, Docker le copia un resolv.conf que apunta a 127.0.0.53… que dentro del
contenedor no es nadie. Toda consulta DNS falla. Y vLLM, que consulta Hugging Face aunque tengas
los pesos en disco, no da error: reintenta para siempre (P-031).
Comprobación: docker exec <contenedor> cat /etc/resolv.conf. Si ves 127.0.0.53, recrea
el contenedor (docker compose up -d --force-recreate): el fichero se fija al crearlo, así que
reiniciarlo no lo arregla.
10. Medir con una petición cuando el uso real son varios agentes
Todas nuestras cifras del primer mes eran de un solo flujo. El uso real eran varios agentes a la vez, y ahí lo que manda es el agregado (P-084). Un modelo que gana con una petición puede perder con ocho.
Comprobación: mide siempre ×1 y ×4 u ×8, con los tokens del servidor sobre el reloj de pared.
La regla que las resume todas
Nueve de estas diez trampas tienen la misma forma: un indicador dice una cosa y la realidad es otra. La configuración, el endpoint de estado, el cliente, la primera medida, la caché. La defensa también es siempre la misma: una prueba de extremo a extremo —una petición real que devuelve una respuesta real— antes de creerte cualquier número.
Tienes más en Trampas, con buscador. Y de vez en cuando contamos una en X.