SDKs de OpenAI y otros

El SDK de Python de OpenAI es el patrón de referencia para completaciones de chat, embeddings y llamadas a herramientas. LiteLLM y bibliotecas similares abstraen múltiples proveedores cuando necesitas flexibilidad de proveedor.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

from openai import OpenAI
 
client = OpenAI()  # lee OPENAI_API_KEY
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hola"}],
)
print(response.choices[0].message.content)

Cuándo usar esto:

• Para construir sobre modelos GPT-4o, GPT-4o-mini o de embeddings.
• Para migrar del SDK de OpenAI v0 (openai.ChatCompletion) a v1.
• Para abstraer entre OpenAI, Anthropic y modelos locales con LiteLLM.
• Para llamar a la API de Respuestas o a los puntos finales de lotes para ahorrar costos.

Ejemplo de trabajo

"""openai_sdks.py - chat, embeddings, herramientas y fallback de LiteLLM."""
from __future__ import annotations
 
import json
import os
from openai import OpenAI, AsyncOpenAI
 
client = OpenAI()
 
# Completación de chat
chat = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Eres un asistente útil."},
        {"role": "user", "content": "¿Qué es FastAPI?"},
    ],
    temperature=0.2,
)
print(chat.choices[0].message.content)
 
# Embeddings
emb = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Tuberías de datos en Python", "Conceptos básicos de aprendizaje automático"],
)
print("dimensión del embedding:", len(emb.data[0].embedding))
 
# Llamada a función
tools = [{
    "type": "function",
    "function": {
        "name": "search_docs",
        "description": "Busca documentación interna",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]
tool_resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Busca documentación sobre validadores de pydantic"}],
    tools=tools,
)
msg = tool_resp.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    print(f"herramienta: {call.function.name}({call.function.arguments})")
 
# Multi-proveedor LiteLLM
try:
    import litellm
    response = litellm.completion(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hola"}],
    )
    print("litellm:", response.choices[0].message.content[:50])
except ImportError:
    print("litellm no instalado - omitiendo")

Lo que esto demuestra:

• Patrón de cliente del SDK de OpenAI v1 para chat y embeddings.
• Llamadas a herramientas/funciones con parámetros de esquema JSON.
• Vectores de embeddings para tuberías de búsqueda semántica.
• LiteLLM como un envoltorio multi-proveedor "plug-and-play".

Inmersión Profunda

Cómo funciona

• Instancia de cliente contiene la clave API, la URL base y la configuración HTTP.
• Completaciones de chat envían mensajes; el modelo devuelve una opción de completación.
• Embeddings mapean texto a vectores densos para búsqueda de similitud.
• Llamadas a herramientas permiten al modelo solicitar la ejecución de funciones con argumentos analizados.
• AsyncOpenAI replica la API síncrona para servidores web asíncronos.

Comparación de Proveedores

Notas de Python

# URL base personalizada (Azure OpenAI, proxy local)
client = OpenAI(base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"])
 
# Uso asíncrono en FastAPI
async def ask(question: str) -> str:
    client = AsyncOpenAI()
    resp = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content or ""

Errores Comunes

• Uso de la API v0 obsoleta - openai.ChatCompletion.create ha sido eliminada. Solución: migrar al cliente OpenAI().
• Claves API codificadas - las claves en el código fuente se confirman en git. Solución: variables de entorno y gestores de secretos.
• No manejar tool_calls - el modelo solicita una función pero el código la ignora. Solución: comprobar message.tool_calls y usar un bucle.
• Ignorar límites de tasa - errores 429 bajo carga. Solución: retroceso exponencial; respetar las cabeceras retry-after.
• Dimensiones incorrectas del modelo de embedding - mezclar modelos rompe la búsqueda vectorial. Solución: fijar un modelo de embedding por índice.
• Asumir contenido no nulo - las negativas o las llamadas a herramientas dejan content como None. Solución: comprobar antes de usar .content.

Alternativas

Preguntas Frecuentes

# v0 (obsoleto)
# openai.ChatCompletion.create(model="gpt-3.5-turbo", messages=[...])
# v1
client = OpenAI()
client.chat.completions.create(model="gpt-4o-mini", messages=[...])

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
)

models = client.models.list()
for m in models.data:
    print(m.id)

client = OpenAI(timeout=30.0, max_retries=3)

Relacionado

• SDK de Anthropic Claude - Patrones específicos de Claude
• Embeddings y Similitud - modelos de embedding
• Salida Estructurada - modo JSON
• Modelos Locales y de Código Abierto - Ollama y vLLM
• Uso de Herramientas y Llamadas a Funciones - bucles de herramientas

Versiones de Stack: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.