El fallo más común al integrar Llama API no es la capacidad del modelo, sino tres parámetros desalineados: Base URL, método de autenticación y nombre del modelo. Después de que Meta cerrara la vista previa pública de Llama API en julio de 2026, los puntos de acceso a Llama se reparten entre proveedores de nube, plataformas de inferencia, servicios autohospedados y gateways compatibles con OpenAI. La forma de las solicitudes es parecida, pero los detalles no coinciden del todo.

Este artículo recorre el orden "confirmar el acceso, armar la URL, encontrar el nombre del modelo, enviar la primera solicitud, tratar streaming y llamadas a herramientas, diagnosticar errores y migrar desde la interfaz antigua". Los ejemplos usan la interfaz compatible con OpenAI; la lista de modelos y los precios se rigen por precios de modelos.

Nota: Meta y Llama son marcas de Meta Platforms, Inc.; Groq, OpenRouter, AWS, Google Cloud y otros nombres son marcas de sus respectivos titulares. Este artículo es solo una explicación técnica y no implica afiliación, representación ni respaldo de las plataformas mencionadas.

1. Confirma tres cosas antes de integrar

Sea cual sea el proveedor, escribe tres cosas en la configuración:

  • Base URL: protocolo, dominio y prefijo de ruta; normalmente termina en /v1.
  • Autenticación: Bearer Token, firma IAM o cuenta de servicio; no se mezclan.
  • Nombre del modelo: el ID interno de la plataforma, no el nombre comercial de la página de marketing.

Añade dos confirmaciones no técnicas: por qué regiones y nodos pasan los datos, y el ciclo de vida de la versión del modelo. Lo primero afecta el cumplimiento; lo segundo, si tendrás que migrar dentro de seis meses.

2. Base URL: el SDK añade la ruta automáticamente

El base_url del SDK de OpenAI solo llega hasta el prefijo de versión; el SDK añade /chat/completions después. Por eso:

  • Correcto: https://api.groq.com/openai/v1
  • Incorrecto: https://api.groq.com/openai/v1/chat/completions (se duplica la ruta)
  • Incorrecto: https://api.groq.com/openai (falta /v1; la mayoría de las plataformas devuelve 404)

El prefijo varía: Groq usa /openai/v1, OpenRouter usa /api/v1 y un vLLM propio usa /v1 por defecto. Los endpoints de nube son más complejos; la dirección compatible con OpenAI de Vertex AI incluye proyecto, región y ruta de endpoint, así que no basta con copiar el dominio. Lo más seguro es copiar la Base URL completa del "ejemplo de solicitud" de la consola y validarla con una petición mínima.

3. Nombres de modelo: cada plataforma es distinta

El mismo modelo Llama puede escribirse de forma totalmente distinta:

Acceso Ejemplo de Base URL Ejemplo de modelo Nota
Groq https://api.groq.com/openai/v1 llama-3.3-70b-versatile Según la lista actual
OpenRouter https://openrouter.ai/api/v1 meta-llama/llama-3.3-70b-instruct Enrutamiento agregado; ojo con el prefijo
vLLM propio http://localhost:8000/v1 Lo define --served-model-name Sin ese flag, usa la ruta de los pesos
AWS Bedrock https://bedrock-runtime.us-east-1.amazonaws.com us.meta.llama4-scout-17b-instruct-v1:0 Usa Invoke/Converse, no es compatible con OpenAI
Gateway compatible https://ai.zhongshangqihang.com/v1 Según la lista de la consola Una Key para varios modelos

El nombre distingue mayúsculas, versión, cuantización y variante de razonamiento. Llama-3.3-70B-Instruct, llama-3.3-70b-versatile y meta-llama/llama-3.3-70b-instruct pueden no ser el mismo despliegue. No copies un ID de un blog y lo pongas en producción: confírmalo en la consola o con GET /models.

También mira el ciclo de vida. Google Cloud anunció que llama-3.3-70b-instruct-maas se retira el 21 de octubre de 2026; Llama 4 Scout de AWS está en fase Legacy y su fecha anunciada de fin de soporte es el 30 de marzo de 2027. Guarda los ID de modelo en configuración, no dispersos en el código de negocio, para no tener que buscar en todo el repositorio al migrar.

4. Primera llamada: primero curl

Prepara una clave de prueba y ponla en una variable de entorno para que no quede en el historial:

export LLAMA_API_KEY="tu_clave"

curl -s https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Explica en una frase qué es una interfaz compatible con OpenAI"}],
    "max_tokens": 128
  }'

En el JSON de respuesta revisa cuatro campos: si choices[0].message.content tiene contenido, si finish_reason es stop o length, si usage contabiliza tokens de entrada y salida, y si model coincide con lo solicitado. Si el model devuelto no es el que escribiste, puede haber enrutamiento o sustitución por alias, y eso afecta la factura y las evaluaciones.

5. SDK de Python: pon las diferencias en configuración

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLAMA_API_KEY"],
    base_url=os.environ["LLAMA_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["LLAMA_MODEL"],
    messages=[{"role": "user", "content": "Explica en una frase qué es una interfaz compatible con OpenAI"}],
    max_tokens=128,
    timeout=60,
)
print(resp.choices[0].message.content)

Tres hábitos de ingeniería evitan problemas después: fijar un timeout explícito; limitar los reintentos y reintentar solo errores reintentables; y poner base_url, model y max_tokens en configuración. No uses reintentos infinitos ni reintentes errores de parámetros como un 400.

También ojo con los nombres de parámetros. Algunas plataformas solo aceptan max_tokens; otras ya migraron a max_completion_tokens; otras limitan el rango de temperature, la cantidad de stop o los roles de mensaje. Guíate por la documentación del destino y no asumas que los parámetros de OpenAI se reenvían tal cual.

6. Streaming: procesa por bloques, no esperes el texto completo

Con stream=True, el servidor suele responder con Server-Sent Events: cada línea empieza con data: y termina con data: [DONE]. El cliente debe leer choices[0].delta.content bloque por bloque y manejar bloques vacíos, latidos y cortes de conexión. Tres problemas frecuentes:

  • Dar por hecho que delta.content siempre existe y fallar cuando llega None.
  • Un proxy o gateway que almacena la respuesta: el frontend cree que "no hay streaming" cuando en realidad todo llega de golpe.
  • El cliente se desconecta pero el servidor sigue generando, y se desperdicia cuota; define cancelación y timeout en la capa de negocio.

Si usas un gateway, confirma primero si reenvía SSE y si reescribe los eventos de error. La compatibilidad del streaming falla más que la de las llamadas normales; pruébala aparte antes de producción.

7. Llamadas a herramientas: confirma que la plataforma las soporta

El parámetro tools al estilo OpenAI no está completamente soportado por todos los proveedores de Llama. Antes de llamar, confirma tres cosas: que el modelo soporta llamadas a herramientas, que la plataforma reenvía tools y tool_choice, y que el finish_reason puede devolver tool_calls.

Los argumentos que devuelve el modelo suelen ser una cadena JSON, no un objeto. El backend debe analizarla y validarla contra el schema antes de ejecutar la función real; no pegues la salida del modelo directamente en SQL, shell ni interfaces internas. La ejecución debe tener timeout, idempotencia y límites de permisos, y el resultado fallido debe volver al modelo para que decida si reintenta o cambia parámetros. Las llamadas paralelas, el schema estricto y las herramientas en streaming son los puntos con más diferencias entre plataformas y hay que verificarlos uno por uno.

8. Errores comunes: primero el código de estado, luego el cuerpo

  • 401: clave ausente, con formato incorrecto, de otra plataforma o revocada.
  • 404: sobra o falta /v1 en la Base URL, o el nombre del modelo no existe.
  • 400: parámetro no soportado, por ejemplo mezclar max_tokens y max_completion_tokens o un rol de mensaje inválido.
  • 403: la clave es válida pero no tiene permiso sobre el modelo, proyecto o región.
  • 429: se alcanzó un límite de tasa o concurrencia. Lee Retry-After y usa retroceso exponencial con jitter; no reintentes a intervalos fijos.
  • 5xx: fallo o timeout del upstream. Reintenta solo solicitudes idempotentes y registra el ID de solicitud.
  • 200 con contenido vacío: puede ser finish_reason=length, filtrado de contenido o un error de parseo del streaming.

El orden recomendado es de afuera hacia adentro: primero curl para saltar el código de negocio, luego el SDK nativo y solo al final sospecha del prompt. Registra en los logs el ID de solicitud, el código de estado, el nombre del modelo y la Base URL; de lo contrario, los problemas entre plataformas son difíciles de reproducir.

9. Migrar desde la antigua Llama API: en orden

  1. Busca en código y configuración api.llama.com, /compat/v1 y nombres de modelo antiguos, y enumera todos los puntos de llamada.
  2. Crea una clave en la nueva plataforma, confirma Base URL y nombre de modelo, y valida una petición mínima con curl.
  3. Crea una tabla de mapeo de modelos con el nuevo ID, el límite de contexto, el límite de salida y si soporta streaming y herramientas.
  4. Sustituye Base URL y autenticación, conserva timeouts, reintentos y campos de log, y no cambies la lógica de negocio de paso.
  5. Prueba por separado streaming y llamadas a herramientas; son los dos puntos donde más aparece "funciona sin streaming y falla con streaming".
  6. Haz una evaluación con muestras reales y luego envía entre 5% y 10% del tráfico, observando tasa de error y latencia p95.
  7. Mantén la ruta antigua o un proveedor de respaldo y completa un simulacro de reversión antes del cambio total.

La migración no termina cuando "devuelve texto", sino cuando calidad, latencia, límites y factura son aceptables y, si hay un problema, puedes localizar la solicitud exacta.

Preguntas frecuentes

¿La Base URL de Llama API es fija?

No. El acceso anterior de Llama API de Meta ya cerró y la Base URL actual la determina la plataforma elegida. Groq, OpenRouter, un vLLM propio y los gateways compatibles usan prefijos distintos; hay que guiarse por el ejemplo de la consola.

¿Por qué el mismo modelo Llama tiene nombres diferentes en cada plataforma?

Las plataformas añaden su propio prefijo, versión, cuantización e identificador de despliegue. El nombre del modelo es un ID interno, no el nombre genérico de la familia. Al cambiar de plataforma, normalmente hay que cambiar también el nombre.

¿Se puede llamar a Llama directamente con el SDK de OpenAI?

Sí, siempre que la plataforma de destino ofrezca una interfaz /chat/completions compatible con OpenAI. Apunta base_url a la dirección de la plataforma, cambia api_key por la clave de esa plataforma y model por su ID; con eso tienes la llamada mínima. Las herramientas, el streaming y la estructura de errores todavía deben validarse uno por uno.

¿Hay que cambiar de SDK para el streaming?

La mayoría de los SDK de OpenAI soportan stream=True, así que no hace falta cambiar de SDK. Pero confirma que la plataforma devuelva SSE estándar, que el marcador final sea [DONE] y que el gateway no almacene la respuesta.

¿Qué reviso primero si falla una llamada a herramientas?

Primero confirma si el modelo y la plataforma declaran soporte de herramientas; luego revisa que el JSON Schema de tools sea válido y que la plataforma acepte tool_choice; por último, mira el finish_reason devuelto y si el JSON de argumentos se puede analizar. Reduce capas en ese orden y no empieces cambiando el prompt.

Siguientes pasos

Elige un acceso, valida con curl la Base URL y el nombre de modelo del ejemplo de la consola, y luego integra el SDK de Python; streaming y herramientas se aceptan por separado. Si necesitas un punto único, registros y cambio entre modelos, empieza por registrarte en ZSQH AI Gateway; la lista de modelos y la facturación se rigen por precios de modelos.

Lecturas relacionadas: