Integrar la API de GLM cuesta menos de lo que muchos imaginan: ofrece una interfaz compatible con OpenAI, así que un SDK de OpenAI existente suele necesitar solo tres cambios: la clave de API, la base URL y el nombre del modelo. La dificultad real no está en «si se puede llamar», sino en si el nombre del modelo es válido, cómo se procesa el streaming, qué formato devuelve el tool calling y qué parámetros no conviene copiar tal cual al migrar desde OpenAI.
Este artículo recorre la cadena completa con una petición mínima y luego amplía con streaming, tool calling, diagnóstico de errores y una lista de migración. Todos los ejemplos se pueden ejecutar directamente después de reemplazar la clave.
Nota: Zhipu, GLM y BigModel son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica afiliación, representación ni patrocinio de Zhipu. La base URL, los nombres de modelo, la longitud de contexto y los criterios de facturación pueden cambiar; guíate por la documentación oficial de la plataforma abierta de Zhipu y por la página de precios de modelos del sitio.
1. Preparativos antes de integrar
Antes de empezar, confirma tres elementos:
- Una clave de API utilizable, cuyo tipo coincida con la interfaz que vas a llamar.
- La base URL correcta: la conexión directa oficial y la dirección del gateway no se pueden mezclar.
- Un nombre de modelo que realmente esté disponible hoy; no copies ejemplos de artículos antiguos.
Si se trata de un proyecto nuevo, conviene validar primero la autenticación y la red con curl, y después integrar el SDK. Así, si algo falla, es más fácil determinar si el problema está en la clave, en la dirección o en el código.
2. Cómo completar la base URL
La base URL de la interfaz oficial compatible con OpenAI de Zhipu suele escribirse así:
https://open.bigmodel.cn/api/paas/v4
La dirección compatible con OpenAI de ZSQH AI Gateway es:
https://ai.zhongshangqihang.com/v1
Ambas se combinan con la ruta /chat/completions de OpenAI. No repitas el segmento de versión ni /chat/completions dentro del código, y no mezcles variantes con o sin barra final.
| Vía de integración | Ejemplo de base URL | Caso de uso | Consideraciones |
|---|---|---|---|
| Oficial de Zhipu | https://open.bigmodel.cn/api/paas/v4 |
Solo GLM y acceso a las funciones más recientes | Requiere cuenta oficial y saldo |
| Gateway ZSQH | https://ai.zhongshangqihang.com/v1 |
Entrada única para varios modelos y facturación unificada | Requiere crear una clave en el gateway |
3. Cómo elegir el nombre del modelo
La familia GLM se divide en categorías como texto, visión, voz y embeddings. Dentro de los modelos de texto hay distintos niveles: algunos priorizan la conversación general y los agentes, otros la baja latencia y la alta concurrencia, y otros admiten contextos más largos. Tomando como ejemplo la serie GLM-5 que figura actualmente en la documentación oficial, los nombres habituales incluyen glm-5.3, glm-5.3-flash, glm-5.2 y similares, pero los modelos se actualizan con frecuencia: los nombres realmente disponibles deben confirmarse en la consola y en la página de precios de modelos.
Al elegir, no mires solo «el más potente». Para tareas como preguntas de atención al cliente o clasificación por lotes, un nivel de baja latencia suele ser más rentable; para análisis de documentos largos o agentes complejos, conviene subir de nivel. Define el nombre del modelo como un elemento de configuración en lugar de fijarlo en el código, y los cambios posteriores serán mucho más sencillos.
Si la tarea implica comprender imágenes, elige un modelo con entrada visual; si implica búsqueda vectorial, usa la serie de embeddings. Las rutas y los parámetros de los modelos de texto, visión y vectores no son idénticos, así que no fuerces el mismo cuerpo de petición para todos. Antes de salir a producción, evalúa los modelos candidatos con el mismo conjunto de pruebas, compara precisión, latencia y consumo, y después decide el principal y el de respaldo.
4. Primera llamada con curl
Prepara primero las variables de entorno, para que la clave no quede en el historial de comandos:
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "Eres un asistente técnico conciso."},
{"role": "user", "content": "Explica en tres frases qué es un gateway de API."}
],
"temperature": 0.6
}'
Si la respuesta es normal, revisa tres campos: choices[0].message.content es la respuesta, usage es el consumo de esta llamada y finish_reason indica el motivo de finalización. Si recibes 401, revisa primero la clave y la cabecera; si recibes 1211, revisa primero el nombre del modelo.
5. Llamadas con el SDK de Python y streaming
El SDK de OpenAI requiere la versión 1.0 o superior. Al apuntar la base URL a GLM, la forma de llamar es prácticamente idéntica a la de OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Escribe una presentación de producto de menos de cien palabras."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Con el streaming hay que tener en cuenta que el primer chunk puede contener solo información de rol y un content vacío; no supongas que todos los chunks traen texto. Al activar el modo de razonamiento, el contenido de razonamiento puede aparecer en el campo reasoning_content, mientras que la respuesta final sigue en content; procesa ambos por separado para no mostrar el razonamiento interno al usuario final.
6. Tool calling y diferencias de parámetros
El tool calling sigue el formato tools y tool_choice de OpenAI. Cuando el modelo devuelve message.tool_calls, hay que analizar el function.arguments de cada llamada como JSON, ejecutar la función local y devolver el resultado como un mensaje con rol tool. En producción conviene validar los parámetros y controlar los tiempos de espera; no confíes ciegamente en los argumentos generados por el modelo.
Al migrar desde OpenAI hay varias diferencias que conviene revisar: el rango de temperature suele estar entre 0 y 1, y pasar 0 puede no tener efecto; el valor predeterminado ronda 0.6; algunas funciones nuevas requieren parámetros a través de extra_body. Los detalles concretos se rigen por la documentación oficial de compatibilidad con OpenAI.
En escenarios de streaming también hay que gestionar la desconexión del cliente. Cuando el usuario cierra la página, el servidor debería cancelar cuanto antes la petición ascendente para no seguir generando y facturando; si el negocio necesita la generación completa, traslada la tarea a una cola en segundo plano en lugar de depender de la conexión del frontend.
7. Correspondencia de errores frecuentes
| Síntoma | Causa posible | Cómo proceder |
|---|---|---|
| 401 / 1000 | Clave incorrecta o tipo incompatible | Verifica el tipo de clave y la cabecera |
| 1211 | El modelo no existe o no está habilitado | Consulta los modelos disponibles en la consola |
| 1261 | La entrada supera el límite de contexto | Comprime el prompt o divide en fragmentos |
| 1302 / 1305 | Límite de velocidad de la cuenta o plataforma ocupada | Reduce la concurrencia y reintenta con retroceso |
| 1113 | Cuenta sin saldo | Recarga y vuelve a intentar |
| Tiempo de conexión agotado | DNS, proxy o ruta de red | Usa primero curl para aislar la capa de red |
Los reintentos solo son útiles para 429, 5xx y tiempos de espera de red. Errores como 401, 1211 o 1261 no mejoran al reintentar; solo consumen tiempo y cuota.
8. Lista de comprobación para migrar desde OpenAI
- Haz una copia de seguridad de los prompts, los parámetros de modelo y el conjunto de evaluación actuales.
- Crea una clave exclusiva para GLM; no reutilices claves de otros proveedores.
- Convierte la base URL y el nombre del modelo en elementos de configuración.
- Compara calidad de salida, latencia y consumo con el mismo lote de muestras.
- Revisa la compatibilidad del análisis de streaming, el tool calling y la salida JSON.
- Ajusta reintentos, tiempos de espera y concurrencia, y observa durante una semana antes de migrar todo el tráfico.
9. Preguntas frecuentes (FAQ)
1. ¿La API de GLM es totalmente compatible con OpenAI?
La mayoría de las interfaces de uso común son compatibles, pero persisten diferencias en rangos de parámetros, campos de razonamiento y algunas capacidades avanzadas. Conviene verificar punto por punto con la documentación oficial de compatibilidad y no dar por hecho que todos los parámetros se comportan igual.
2. ¿Hay que añadir una barra al final de la base URL?
En la documentación oficial aparecen tanto formas con barra como sin barra, y el SDK suele gestionarlo automáticamente. Lo importante es no duplicar la ruta: elige una forma y mantenla uniforme en todo el proyecto.
3. ¿El streaming permite obtener el razonamiento?
Algunos modelos devuelven reasoning_content en modo de razonamiento. Mostrarlo o no depende del diseño del producto; en aplicaciones orientadas al usuario final suele mostrarse solo la respuesta definitiva.
4. ¿El tool calling usa el mismo formato que OpenAI?
La definición de herramientas y la estructura de retorno siguen básicamente el formato de OpenAI, pero los detalles de los parámetros pueden variar según el modelo. Antes de salir a producción, haz una ronda de pruebas de regresión con herramientas reales.
5. ¿Los nombres de modelo son iguales en el acceso oficial y en el gateway?
En la mayoría de los casos se usa el mismo conjunto de nombres, pero que el gateway tenga habilitado un modelo o admita un parámetro concreto debe confirmarse en la consola del gateway y en la página de precios de modelos.
