Saltar al contenido
AI•5 min de lectura

Tool calls rotos en vLLM, el parser genérico hf y el dolor #1 de la comunidad

Tu agente llama una función, el modelo responde con el JSON del tool call, y tu servidor lo parsea mal. El agente reintenta, el usuario espera, y el thread de soporte se llena de logs. Ese escenario fue el tema más discutido de la comunidad de inferencia en octubre. El post de Ubicloud sobre arreglar la precisión de tool calls en vLLM lideró las discusiones del mes. - Fuente Fixing Tool-Call Accuracy in vLLM

La buena noticia es que la v0.32 de vLLM trajo el cambio estructural que este problema necesitaba, y esta guía cubre por qué se rompen los tool calls, qué cambió y cómo debuggear los que sigan rotos.

Por qué se rompen los tool calls

El modelo no emite JSON limpio de tool calls. Emite texto con un formato de conversación específico, y ese formato varía por familia de modelos. Llama usa un dialecto, Qwen otro, Mistral el suyo. El trabajo del tool call parser es traducir ese texto al schema de OpenAI que tu cliente espera.

El problema histórico de vLLM era la matriz de parsers. Un parser por familia de modelo, seleccionado a mano con --tool-call-parser, y el default que era incorrecto para tu modelo si no leías la documentación. El resultado conocido, tool calls que funcionan en desarrollo con un modelo y se rompen en producción con otro, o que se rompen después de actualizar el modelo a una versión nueva que cambió su template.

La raíz del problema no está en vLLM sino en el checkpoint. La mayoría de los modelos ya traen su formato de respuesta declarado en el tokenizer config o en un response_template. Pedirle al operador que sepa ese formato y elija el parser correcto duplicaba información y garantizaba desalineación. - Fuente PR #58604

Lo que cambió en la v0.32

El parser genérico hf lee el formato directamente del checkpoint. El mismo tratamiento para tool calls y para reasoning, con --tool-call-parser hf y --reasoning-parser hf.

vllm serve $MODEL \
  --tool-call-parser hf \
  --reasoning-parser hf

Con eso desaparece la adivinanza por modelo. El parser confía en lo que el entrenador del modelo declaró, y los modelos nuevos funcionan sin esperar el release del parser específico. Para los modelos con formatos que el template no cubre, los parsers dedicados siguen disponibles, ahora como excepción y no como regla.

La misma versión trajo /v1/systemone, un endpoint de decisiones estructuradas sobre un estado, y la v0.33 agregó /v1/decisions activado por default en modelos soportados, que extiende la idea a clasificación y scoring nativos. Si tu agente decidía entre opciones con un prompt artesanal y parsing de texto, hoy hay un endpoint para eso. - Fuente v0.32.0 release, v0.33.0 release

El debugging que sigue siendo necesario

El parser genérico resuelve la selección, no la calidad. Estos son los cuatro puntos de falla que sigo viendo, en orden de frecuencia.

El template del checkpoint está mal o es ambiguo. Pasa con fine-tunes de comunidad. Verifica el response_template real del tokenizer, y si está mal, corregirlo en tu repo del modelo, no parchearlo con un parser distinto.

El modelo alucina el formato bajo presión. Con outputs largos o structure forzada, algunos modelos mezclan el formato de tool call con texto plano. La guía oficial de structured outputs de vLLM cubre forzar el schema desde el sampler con guided decoding, que elimina la clase entera de errores de formato al costo de algo de throughput. - Fuente vLLM structured outputs

Tu cliente espera un dialecto distinto. El parser produce el formato OpenAI. Si tu agente habla el dialecto Anthropic de tool use, la traducción intermedia es tu bug, no del motor. Los proveedores lo resuelven con endpoints nativos, vLLM expone Messages API además del OpenAI-compatible.

La versión del modelo cambió su template. El pin de versiones que aplico a vLLM aplica al modelo. Un update del checkpoint puede cambiar el response_template y tu parser configurado quedó viejo. El smoke test de canario de mi guía de migración existe para atrapar exactamente esto. - Fuente vLLM v0.33.0

Cómo medir la precisión de tus tool calls

Lo que no se mide no se arregla. El harness mínimo que uso por modelo y por versión de vLLM.

# tool-call-smoke.py — 20 casos, 3 familias de tools
import json, requests

CASES = [
    ("busca vuelos CDMX a LIM el 12 de diciembre", {"tool": "search_flights", "args": {"from": "CDMX", "to": "LIM", "date": "2026-12-12"}}),
    ("cancela la orden 8842", {"tool": "cancel_order", "args": {"order_id": "8842"}}),
    # ... tu propio set con los tools reales de tu agente
]

def check(resp_json, expected):
    calls = resp_json["choices"][0]["message"].get("tool_calls") or []
    if not calls:
        return False
    c = calls[0]["function"]
    return c["name"] == expected["tool"] and json.loads(c["arguments"]) == expected["args"]

passed = 0
for prompt, expected in CASES:
    r = requests.post(f"{BASE}/v1/chat/completions", json={
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
        "tools": TOOLS,
    }).json()
    passed += check(r, expected)

print(f"{passed}/{len(CASES)} tool calls correctos")

Veinte casos cubren el 80% de las regresiones que he visto. Corre el harness en cada cambio de versión de vLLM, de modelo y de parser, y guarda los resultados junto al pin de versiones. Cuando el número baje, el diff del template del modelo te dice por qué.

Tips finales

  1. Pasa al parser hf en cuanto actualices a v0.32+. Elimina la configuración por modelo y alinea el motor con lo que el checkpoint declara.
  2. Guarda los templates de tus checkpoints en tu repo. Un diff de response_template explica la mayoría de las regresiones misteriosas de tool calls.
  3. Guided decoding para schemas críticos. Si un tool call malformado dispara un pago o un borrado, forzar el schema vale el throughput perdido.
  4. Corre el harness de 20 casos en cada canario. Los tres puntos donde el tool calling se rompe son versiones, templates y clientes. Los tres aparecen en un canario de 30 requests.
  5. Reporta los parsers que falten. El equipo de vLLM prioriza con señales de uso, y el parser correcto a veces solo falta para tu familia de modelo. - Fuente vLLM GitHub

Los tool calls rotos dejaron de ser un misterio del modelo y se convirtieron en un problema de pipeline verificable. Eso es una mejora real.

¿Cuántos de tus bugs de agente terminaban siendo un parser mal elegido? Cuéntame en los comentarios.


> Más posts