Ir al contenido principal
Español— Elegir un idioma
Menú

AsyncOpenAI con httpx.Timeout

Lección 2 de 12 Actualizado el 30 de julio de 2026 Avanzado
En esta página
  1. La alternativa del SDK de OpenAI
  2. Configurar AsyncOpenAI para xAI
  3. Entender httpx.Timeout
  4. Enviar solicitudes
  5. Gestión de errores con httpx
  6. Cuándo elegir AsyncOpenAI frente al SDK de xAI
  7. Puntos clave

La alternativa del SDK de OpenAI

El SDK nativo de xAI no es tu única opción para trabajar de forma asíncrona con la API de Grok. El SDK de OpenAI, ampliamente adoptado en el ecosistema de Python, funciona con la API de xAI gracias a la compatibilidad de formatos. Este enfoque te permite reutilizar código existente de OpenAI y aprovechar el ecosistema de herramientas circundante.

Configurar AsyncOpenAI para xAI

La inicialización requiere tres parámetros: tu clave de API, la URL base de xAI y un tiempo de espera ajustado para los modelos de razonamiento:

from openai import AsyncOpenAI
import httpx

client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0)
)

El detalle clave aquí es httpx.Timeout(3600.0). El SDK de OpenAI utiliza httpx como su cliente HTTP subyacente y el tiempo de espera predeterminado es de 10 minutos. Para los modelos de razonamiento de Grok, debes aumentar este valor a 3600 segundos (una hora) para evitar desconexiones prematuras.

Entender httpx.Timeout

La clase httpx.Timeout acepta varios parámetros que controlan diferentes fases de la conexión:

# Tiempo de espera uniforme: 3600 s para todo
timeout = httpx.Timeout(3600.0)

# Tiempo de espera granular
timeout = httpx.Timeout(
    connect=10.0,    # tiempo de espera de conexión inicial
    read=3600.0,     # tiempo de espera de lectura de respuesta
    write=30.0,      # tiempo de espera de envío de solicitud
    pool=10.0        # tiempo de espera para una conexión libre
)

En producción, puedes ajustar finamente estos valores. La conexión inicial debe fallar rápidamente si el servidor es inalcanzable (10 segundos son suficientes), mientras que el tiempo de espera de lectura debe ser lo bastante paciente para aguardar el razonamiento del modelo.

Enviar solicitudes

La sintaxis sigue el formato estándar del SDK de OpenAI, utilizando await:

import asyncio

async def query_grok(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = asyncio.run(query_grok("What are the advantages of Rust over C++?"))

Verás la misma estructura que en la API de OpenAI: un array messages con roles y contenido. La respuesta sigue el mismo esquema y es accesible mediante response.choices[0].message.content.

Gestión de errores con httpx

El SDK de OpenAI con httpx proporciona excepciones específicas que debes capturar:

from openai import APITimeoutError, APIConnectionError, RateLimitError

async def safe_query(prompt: str) -> str | None:
    try:
        response = await client.chat.completions.create(
            model="grok-4.20-0309-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Se ha superado el tiempo de espera: la solicitud ha tardado demasiado")
        return None
    except RateLimitError:
        print("Se ha alcanzado el límite de tasa: reduce la frecuencia de las solicitudes")
        return None
    except APIConnectionError:
        print("No se puede conectar con el servidor de xAI")
        return None

Las tres excepciones más comunes son APITimeoutError (el modelo no respondió dentro del tiempo asignado), RateLimitError (has superado los límites de RPM/TPM) y APIConnectionError (problema de red).

Cuándo elegir AsyncOpenAI frente al SDK de xAI

El SDK de OpenAI es preferible si ya dispones de una base de código de OpenAI, utilizas herramientas de terceros compatibles con OpenAI (LangChain, LiteLLM) o deseas cambiar de proveedor sin modificar tu código. No obstante, el SDK nativo de xAI ofrece un acceso más directo a funciones específicas de Grok, como las herramientas integradas.

Puntos clave

  • AsyncOpenAI funciona con la API de xAI mediante base_url="https://api.x.ai/v1"
  • httpx.Timeout(3600.0) es necesario para los modelos de razonamiento
  • El formato de solicitud y respuesta es idéntico al de la API estándar de OpenAI
  • Las excepciones APITimeoutError, RateLimitError y APIConnectionError cubren los principales casos de error
  • Esta opción es ideal para reutilizar código existente o integrar herramientas de terceros compatibles con OpenAI