English Arabic 简体中文 繁體中文 Français Deutsch 日本語 한국어 Português Русский Español

OpenAI Python SDK: Instalación, configuración e integración práctica

Por / / LLM, API / 7 minutos de lectura
OpenAI Python SDK: Instalación, configuración e integración práctica
Tabla de contenido
  1. Instalar el paquete Python de OpenAI
  2. La clase OpenAI Client
  3. Completaciones de Chat: Solicitud Básica
  4. Respuestas en Streaming
  5. Llamadas a Funciones
  6. Uso Asíncrono con AsyncOpenAI
  7. SDK de JavaScript de OpenAI
  8. Integración de Azure OpenAI con Python
  9. Cambiar a la API Compatible con OpenAI de Novita AI
  10. Modelos de Código Abierto a través de Novita AI
  11. Preguntas Frecuentes
  12. Artículos Recomendados

El SDK de OpenAI para Python (openai en PyPI) es el cliente oficial de Python para la API de OpenAI. Maneja la autenticación, el formateo de solicitudes, el análisis de respuestas, el streaming y los reintentos, para que no tengas que implementarlos tú mismo. Esta guía cubre la instalación, la clase principal OpenAI, las completaciones de chat, el streaming, las llamadas a funciones, el uso asíncrono, el SDK equivalente de JavaScript, la integración con Azure OpenAI y cómo apuntar el mismo SDK al endpoint compatible con OpenAI de Novita AI para usar modelos de pesos abiertos sin reescribir tu código.

Instalar el paquete Python de OpenAI

Se requiere Python 3.8 o superior:

pip install openai

Para desarrollo, agrégalo a tu requirements.txt o pyproject.toml:

pip install openai>=1.0.0

La versión 1.x (publicada a finales de 2023) cambió significativamente la interfaz con respecto a la API 0.x. Si estás migrando código antiguo, ten en cuenta que openai.ChatCompletion.create() ya no existe; usa client.chat.completions.create() en su lugar.

Configura tu clave de API como variable de entorno. No la incluyas en el código fuente:

export OPENAI_API_KEY="sk-..."

La clase OpenAI Client

La clase OpenAI es el punto de entrada principal. Por defecto, lee la clave de API de la variable de entorno OPENAI_API_KEY, o puedes pasarla explícitamente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

El cliente gestiona el pool de conexiones, los reintentos y los tiempos de espera. Debes crear una instancia y reutilizarla en toda tu aplicación, no instanciarla por cada solicitud.

Opciones configurables al inicializar:

Parámetro Valor predeterminado Descripción
api_key Variable de entorno OPENAI_API_KEY Credencial de autenticación
base_url https://api.openai.com/v1 Anulación para proxy o API compatible
timeout 600s Tiempo de espera por solicitud
max_retries 2 Reintentos automáticos en errores de límite de tasa
http_client None Cliente httpx personalizado para configuración de proxy o certificados

Completaciones de Chat: Solicitud Básica

Las completaciones de chat son el caso de uso más común. La lista messages sigue el mismo formato que la API: una lista de diccionarios con role/content que representan la conversación:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Eres un asistente de codificación útil."},
        {"role": "user", "content": "¿Cuál es la diferencia entre una lista y una tupla en Python?"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

La respuesta es un objeto ChatCompletion. Campos clave:

  • response.choices[0].message.content — la respuesta de texto
  • response.usage.prompt_tokens — tokens consumidos por la entrada
  • response.usage.completion_tokens — tokens consumidos por la salida
  • response.model — la versión del modelo que sirvió la solicitud

Para uso en producción, pasa max_tokens para evitar costos de generación descontrolados y temperature=0 o valores bajos cuando necesites salidas deterministas.

Respuestas en Streaming

Para interfaces interactivas donde los usuarios ven los tokens a medida que llegan, usa stream=True:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Explica los generadores de Python en lenguaje sencillo."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Usar el administrador de contexto (sentencia with) asegura que la conexión se cierre correctamente después de la iteración. El atributo .text_stream produce cadenas de texto simples; .stream produce objetos de evento sin procesar si necesitas metadatos como estadísticas de uso por fragmento.

Si necesitas streaming sin un administrador de contexto:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Enumera 5 buenas prácticas de Python."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Llamadas a Funciones

Las llamadas a funciones permiten que el modelo decida cuándo llamar a una función y devuelva un objeto JSON con argumentos. Tu aplicación ejecuta la función y luego envía el resultado de vuelta para que el modelo lo incorpore en su respuesta:

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Devuelve el clima actual de una ciudad.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nombre de la ciudad, ej. 'Ciudad de México'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "¿Cómo está el clima en Tokio?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    # Ejecuta aquí tu función real
    result = {"city": args["city"], "temperature": "18°C", "condition": "nublado"}

    messages.append(choice.message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

El modelo devuelve finish_reason="tool_calls" cuando quiere invocar una función. Tú ejecutas la función, agregas el resultado a la lista de mensajes y haces una segunda solicitud. Este bucle de dos pasos es el patrón estándar.

Uso Asíncrono con AsyncOpenAI

Para FastAPI, servicios basados en asyncio, o cualquier código que se beneficie de E/S no bloqueante, usa AsyncOpenAI:

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def get_response(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256,
    )
    return response.choices[0].message.content

async def main():
    result = await get_response("¿Qué es asyncio en Python?")
    print(result)

asyncio.run(main())

AsyncOpenAI es un equivalente asíncrono directo; todos los métodos se pueden esperar. Esto es preferible a usar asyncio.to_thread para envolver el cliente síncrono.

SDK de JavaScript de OpenAI

El SDK de JavaScript de OpenAI (openai en npm) refleja de cerca la interfaz de Python. Instálalo:

npm install openai

Completación de chat básica en Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "Eres un asistente útil." },
    { role: "user", content: "Explica promesas vs async/await en JavaScript." },
  ],
  max_tokens: 512,
});

console.log(response.choices[0].message.content);

Streaming en JavaScript:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Resume la API fetch en 3 oraciones." }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(text);
}

El SDK de JavaScript soporta Node.js 18+, Deno y entornos de navegador (aunque exponer tu clave de API en el navegador no es seguro; usa un proxy del lado del servidor). La opción base_url para apuntar a APIs compatibles funciona exactamente como en Python.

Integración de Azure OpenAI con Python

Si estás usando el servicio Azure OpenAI en lugar de la API directa de OpenAI, usa el cliente AzureOpenAI del mismo paquete:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

response = client.chat.completions.create(
    model="gpt-4o",  # El nombre de tu implementación en Azure
    messages=[
        {"role": "user", "content": "¿Cómo uso Azure OpenAI con Python?"},
    ],
)

print(response.choices[0].message.content)

Variables de entorno requeridas para Azure:

  • AZURE_OPENAI_API_KEY: La clave de API de tu recurso Azure
  • AZURE_OPENAI_ENDPOINT: La URL de tu endpoint, ej. https://tu-recurso.openai.azure.com/

El parámetro model en Azure OpenAI se refiere al nombre de tu implementación, no al nombre del modelo subyacente. Configura api_version para que coincida con la versión de la API de Azure que usa tu implementación (consulta la documentación de Azure OpenAI para las versiones compatibles actuales).

Para autenticación a través de Microsoft Entra ID (anteriormente Azure AD) en lugar de una clave de API:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

Cambiar a la API Compatible con OpenAI de Novita AI

Novita AI expone un endpoint compatible con OpenAI en https://api.novita.ai/openai. Puedes usar el mismo SDK de Python o JavaScript de openai, cambiando solo base_url y api_key. No se requieren otros cambios de código:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Eres un asistente de codificación útil."},
        {"role": "user", "content": "Explica cómo afecta el GIL de Python al multithreading."},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)
)

Obtén una clave de API de Novita AI en [novita.ai/settings/key-management](https://novita.ai/settings/key-management). La misma clave funciona en todas las APIs de Novita AI, incluido el endpoint compatible con OpenAI.

JavaScript con Novita AI:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVITA_API_KEY,
  baseURL: "https://api.novita.ai/openai",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-coder-30b-a3b-instruct",
  messages: [{ role: "user", content: "Escribe una chuleta de anotaciones de tipo en Python." }],
  max_tokens: 600,
});

console.log(response.choices[0].message.content);

Todo lo demás — streaming, llamadas a funciones, uso asíncrono, response_format, temperature, max_tokens — funciona de manera idéntica. El endpoint de Novita AI sigue la especificación de la API de Chat Completions de OpenAI.

Modelos de Código Abierto a través de Novita AI

Cambiar base_url te da acceso a un catálogo de modelos de pesos abiertos que ahora son competitivos con los modelos fronterizos de código cerrado en tareas específicas. Para flujos de trabajo de codificación, llamadas a funciones y razonamiento de contexto largo, la brecha práctica se ha reducido sustancialmente.

Modelos disponibles a través del endpoint compatible con OpenAI de Novita AI que vale la pena evaluar:

DeepSeek V4 Pro (deepseek/deepseek-v4-pro): Un modelo MoE grande (licencia cercana a MIT) que se ubica cerca de la cima de SWE-Bench y los benchmarks de llamadas a funciones. Fuerte para agentes de codificación, revisión de código y tareas de uso de herramientas de múltiples pasos donde de otro modo recurrirías a GPT-4o o Claude Opus.

Qwen3 Coder 30B A3B Instruct (qwen/qwen3-coder-30b-a3b-instruct): Un modelo MoE disperso de 30B de la familia Qwen Coder, optimizado para generación de código, triaje de errores y revisión de pull requests. A $0.07 por 1M de tokens de entrada y $0.27 por 1M de tokens de salida en Novita AI, es sustancialmente más barato que la mayoría de las APIs cerradas para asistencia de codificación rutinaria.

Qwen3 235B A22B Instruct (qwen/qwen3-235b-a22b-instruct-2507): Un modelo MoE grande (Apache 2.0) con sólido rendimiento en razonamiento y codificación multilingüe. Bueno para tareas donde actualmente usas GPT-4o para respuestas creativas o complejas pero deseas reducir el costo por token a gran escala.

El formato del ID del modelo en Novita AI es provider/model-name. Lo pasas directamente al parámetro model en el SDK.

Un patrón de enrutamiento sencillo para equipos que quieran mezclar modelos abiertos y cerrados:

def get_client(use_novita: bool = False) -> OpenAI:
    if use_novita:
        return OpenAI(
            api_key=os.environ["NOVITA_API_KEY"],
            base_url="https://api.novita.ai/openai",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Usa pesos abiertos para tareas de codificación sensibles al costo y de alto volumen
coding_client = get_client(use_novita=True)

# Usa OpenAI para tareas donde el modelo cerrado es realmente mejor
openai_client = get_client(use_novita=False)

Esto te permite hacer pruebas A/B de la calidad de salida, comparar el rendimiento por tarea y cambiar el volumen a modelos más baratos sin tocar la lógica de las solicitudes.

Preguntas Frecuentes

¿Cuál es el nombre del paquete Python de OpenAI?

El nombre del paquete en PyPI es openai. Instálalo con pip install openai.

¿Cómo se llama la clase cliente de OpenAI en Python?

La clase principal es OpenAI para uso síncrono y AsyncOpenAI para uso asíncrono. Ambas están en el módulo openai: from openai import OpenAI, AsyncOpenAI.

¿El SDK de OpenAI para Python soporta streaming?

Sí. Usa client.chat.completions.stream() como administrador de contexto, o pasa stream=True a client.chat.completions.create() e itera sobre los fragmentos.

¿Cuál es el nombre del paquete del SDK de JavaScript de OpenAI?

El paquete npm es openai. Instálalo con npm install openai. Las firmas de clase y métodos son casi idénticas al SDK de Python.

¿Cómo uso Azure OpenAI con Python?

Usa la clase AzureOpenAI del paquete openai. Pasa azure_endpoint, api_key y api_version. El parámetro model se refiere al nombre de tu implementación de Azure, no al modelo subyacente.

¿Puedo usar el SDK de OpenAI para Python con otros proveedores?

Sí. Cualquier proveedor que implemente el formato de API de Chat Completions de OpenAI se puede usar configurando base_url en el cliente. El endpoint de Novita AI en https://api.novita.ai/openai es un ejemplo; todo el conjunto de características del SDK — streaming, llamadas a funciones, asíncrono — funciona sin cambios.

¿Cómo mantengo segura mi clave de API de OpenAI?

Guarda la clave en una variable de entorno (OPENAI_API_KEY) y léela con os.environ["OPENAI_API_KEY"]. Nunca la pongas en el código fuente, repositorios públicos, registros de compilación o JavaScript del lado del cliente.

Artículos Recomendados

Publicaciones relacionadas