BroadRouter
Comenzar

Tool calling con modelos abiertos: esquemas, paralelismo, reintentos

Por el equipo de BroadNet Inference · 4 min de lectura · Publicado · Actualizado

Los modelos abiertos en APIs compatibles con OpenAI usan el mismo formato tools y tool_calls que OpenAI. Mantenga los esquemas pequeños y planos, analice los argumentos como cadenas JSON, valídelos antes de ejecutar nada y devuelva los errores al modelo como resultados de herramienta para que reintente. Limite los pasos. En BroadNet, GLM 5.3 y Qwen3.8 27B listan soporte de herramientas.

El tool calling (llamada a herramientas) es lo que convierte un modelo en un agente. Con modelos abiertos en una API compatible con OpenAI, el formato de la petición es el mismo que usaría con OpenAI. Lo que cambia es la frecuencia con que algo sale mal y lo que hace el servidor para evitarlo. Este artículo cubre el formato, cómo escribir esquemas que los modelos abiertos manejen bien, las llamadas en paralelo, los cinco fallos que realmente verá y un bucle de Python que los resiste.

¿Cómo funciona el tool calling en una API compatible con OpenAI?

  1. Usted envía messages más una lista tools. Cada herramienta tiene un nombre, una descripción y un JSON Schema para sus argumentos.
  2. El modelo responde con finish_reason: "tool_calls" y una lista tool_calls. Cada entrada tiene un id, un nombre de función y arguments como una cadena JSON.
  3. Su código ejecuta cada llamada y añade un mensaje role: "tool" por llamada, con el tool_call_id correspondiente.
  4. Vuelve a llamar a la API. El modelo responde o pide más herramientas.

El modelo nunca ejecuta nada. Su código decide qué se ejecuta.

¿Cómo escribir los esquemas de las herramientas?

Los modelos abiertos siguen con más fiabilidad los esquemas sencillos. Estas reglas salen de la guía de OpenAI y de lo que suele romperse:

  • Nombre las herramientas por la acción, como read_file o search_code, y diga en la descripción cuándo usar cada una.
  • Mantenga la lista corta. La guía de OpenAI presenta menos de 20 funciones al inicio de un turno como una sugerencia flexible. Además, cada esquema se envía en cada llamada; vea el presupuesto de tokens del agente.
  • Prefiera argumentos planos. Cadenas, números, booleanos y enums. Evite el anidamiento profundo y los objetos de forma libre.
  • Use enums para opciones fijas, de modo que el modelo no pueda inventarse un valor. El generador de JSON Schema convierte un objeto de argumentos de ejemplo en un esquema plano que puede pegar en parameters.
  • Marque los campos obligatorios. El modo estricto de OpenAI exige additionalProperties: false y todos los campos en required, con null como tipo para los opcionales. Que un proveedor aplique strict o no varía, así que valide igualmente.

¿Y las llamadas a herramientas en paralelo?

Un modelo puede devolver varias entradas en tool_calls en un mismo turno, por ejemplo tres lecturas de archivo. Ejecute las llamadas independientes de forma concurrente y devuelva un resultado por cada tool_call_id, en cualquier orden. Si sus herramientas tienen efectos secundarios que dependen unos de otros, ponga parallel_tool_calls: false; la guía de OpenAI indica que eso limita al modelo a cero o una llamada por turno. Compruebe que su proveedor lo respeta.

¿Por qué fallan las llamadas a herramientas?

Fallo Lo que ve Solución
Argumentos mal formados json.loads lanza una excepción Devuelva el error de análisis como resultado de herramienta; reintente
No coincide con el esquema Falta un campo, tipo erróneo, enum inventado Valide; devuelva el error de validación
Herramienta desconocida Un nombre que nunca definió Devuelva “unknown tool, available: …”
No llama cuando debería Responde con texto tool_choice: "required" o una función con nombre
Llamada cortada finish_reason: "length" Suba max_tokens; el razonamiento lo comparte

Los dos primeros son esperables, no raros. La documentación de tool calling de vLLM dice que en modo auto, salvo que una herramienta fije strict: true (o el servidor imponga un mínimo de rigor) y el parser del modelo admita restricciones, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (Traducción: «vLLM extrae las llamadas a herramientas del texto en bruto, así que los argumentos pueden estar a veces mal formados o incumplir el esquema de parámetros de la función»). Una función con nombre usa el backend de salidas estructuradas de vLLM. Su proveedor puede servir los modelos de otra manera, así que considere obligatoria la validación.

La última fila sorprende a quien usa modelos de razonamiento. GLM 5.3 y Qwen3.8 27B piensan antes de responder, y el pensamiento cuenta dentro de max_tokens. Por qué las respuestas llegan vacías o cortadas explica cuánto margen dejar.

Un bucle de herramientas que valida y reintenta

import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")

Aquí importan tres decisiones de diseño:

  1. Los errores vuelven al modelo como resultados de herramienta. El modelo ve qué estaba mal y suele corregirlo en el turno siguiente. Lanzar una excepción desperdicia esa oportunidad.
  2. El bucle está acotado. max_steps detiene a un modelo que sigue llamando herramientas sin avanzar.
  3. Los reintentos de transporte van aparte. max_retries en el cliente gestiona los 429 y 5xx. Los argumentos incorrectos se gestionan en el bucle. No mezcle ambas cosas; vea errores y reintentos.

En herramientas con efectos secundarios, como enviar un correo, añada una clave de idempotencia para que un paso reintentado no actúe dos veces. Agentes de larga duración trata este tema.

¿Qué modelos de BroadNet admiten tool calling?

Modelo Herramientas listadas Contexto Notas
GLM 5.3 Sí 1,048,576 También salida estructurada
Qwen3.8 27B Sí 262,144 También entrada de imágenes
DeepSeek V4.1 Flash No listadas 1,048,576 Entrada de imágenes; pruebe las herramientas antes de depender de ellas
Gemma 4 VL 26B No listadas 32,768 No apto para bucles de herramientas

Para elegir entre los dos modelos con herramientas, vea GLM 5.3 frente a Qwen3.8 27B. Cuando la respuesta final debe ajustarse a una forma pero no hace falta ejecutar ninguna función, la salida estructurada es más sencilla que una herramienta.

Dónde encaja BroadNet Inference

BroadNet Inference sirve GLM 5.3 y Qwen3.8 27B con tool calling listado, mediante el formato estándar de chat completions, así que el bucle anterior funciona sin cambios con el SDK de OpenAI para Python. Los precios por token están en la página de precios. No aloja herramientas del lado del servidor, como búsqueda web o ejecución de código, y su documentación no lista tool calling para DeepSeek V4.1 Flash, el modelo de los planes ilimitados. Para un agente con uso intensivo de herramientas, use GLM 5.3 o Qwen3.8 27B por token. Si de todos modos quiere el plan fijo, compruebe con una hora del plan Meteoro (Meteor) por $1 que DeepSeek V4.1 Flash llama a sus herramientas de forma fiable antes de comprar un mes.

Preguntas frecuentes

¿Los modelos abiertos admiten function calling?

Muchos sí, pero el soporte depende del modelo y de cómo lo sirve el proveedor. En BroadNet Inference, la documentación lista tool calling para GLM 5.3 y Qwen3.8 27B. No lo lista para DeepSeek V4.1 Flash ni para Gemma 4 VL 26B.

¿Por qué los argumentos de mis llamadas a herramientas son JSON inválido?

Salvo que el servidor restrinja la decodificación, los argumentos se generan como texto y se analizan después. La documentación de vLLM indica que los argumentos extraídos del texto en bruto pueden estar mal formados de vez en cuando. Capture el error de análisis y devuélvalo como resultado de herramienta para que el modelo se corrija.

¿Cómo desactivo las llamadas a herramientas en paralelo?

En el formato de OpenAI, ponga parallel_tool_calls en false. Eso limita al modelo a cero o una llamada por turno. Compruebe que su proveedor respeta el campo.

¿Por qué el modelo responde con texto en lugar de llamar a una herramienta?

Con tool_choice en auto, decide el modelo. Ponga tool_choice en required, o en una función concreta, cuando la llamada sea obligatoria. Compruebe también que la descripción de la herramienta indica cuándo usarla.

¿Por qué se corta mi llamada a herramienta?

Los modelos de razonamiento cuentan el pensamiento dentro de max_tokens. Un límite pequeño puede terminar la respuesta a mitad de los argumentos. Revise finish_reason y suba max_tokens.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity