Python OpenAI

openai es una potente biblioteca de Python para interactuar con una serie de modelos y servicios de OpenAI.

openai encapsula todas las llamadas a la API RESTful, lo que permite a los desarrolladores integrar fácilmente potentes capacidades de IA en sus aplicaciones Python, como procesamiento de lenguaje natural, generación de imágenes y reconocimiento de voz, entre otras.

Funciones principales:

• Generación de texto: usa modelos como GPT-4 o GPT-5 para generar artículos, código, resúmenes, diálogos, etc.
• Generación de imágenes: crea imágenes a partir de descripciones de texto mediante el modelo DALL-E.
• Embeddings: convierte texto en representaciones vectoriales, comúnmente utilizado en tareas como búsqueda semántica, clasificación de texto y agrupamiento.
• Conversión de voz a texto: transcribe archivos de audio a texto usando el modelo Whisper.
• Ajuste fino (Fine-tuning): entrena un modelo más específico proporcionando tu propio conjunto de datos.
• API de Asistentes (Assistants): crea aplicaciones complejas que pueden comprender el contexto, invocar herramientas y realizar interacciones a largo plazo.

Dirección de código abierto de openai:https://github.com/openai/openai-python

¿Cómo usar?

Requisitos del entorno:

• Versión de Python: 3.9 o superior.
• Bibliotecas dependientes: httpx (predeterminado), aiohttp (opcional), websockets (necesario para Realtime API).

Primero, necesitas instalar la biblioteca openai con pip:

pip install openai

o 

pip3 install openai

Luego necesitas ir al sitio web oficial de OpenAIhttps://platform.openai.com/ registrar una cuenta y generar una API Key en la página de claves de API.

Ver la versión instalada:

import openai
print(openai.__version__)  # 输出当前 SDK 版本

Descripción de parámetros:

Modelos de terceros

En China, actualmente acceder a OpenAI es un poco complicado; muchos proveedores nacionales también son compatibles con OpenAI, como DeepSeek, Qwen y GLM.

DeepSeek

DeepSeek API es totalmente compatible con el formato de API de OpenAI; solo necesita modificar una pequeña configuración para usar directamente el SDK de OpenAI o herramientas compatibles para acceder a DeepSeek API.

Forma de uso

A continuación, usamos el SDK de OpenAI para acceder al modelo Tongyi Qianwen en el servicio Bailian.

Ejemplo de llamada no streaming

Al ejecutar el código se puede obtener el siguiente resultado:

Soy Tongyi Qianwen, un modelo de lenguaje a gran escala desarrollado de forma independiente por el Laboratorio Tongyi, perteneciente al grupo Alibaba. Puedo ayudarte a responder preguntas y crear textos, como escribir historias, redactar documentos oficiales, escribir correos electrónicos, guiones, realizar razonamiento lógico, programar, etc. También puedo expresar opiniones y jugar juegos. Si tienes alguna pregunta o necesitas ayuda, ¡no dudes en decírmelo!

Ejemplo de llamada streaming

Al ejecutar el código se puede obtener el siguiente resultado:

Soy Tongyi Qianwen, un modelo de lenguaje a gran escala desarrollado de forma independiente por el Laboratorio Tongyi, perteneciente al grupo Alibaba. Puedo ayudarte a responder preguntas y crear textos, como escribir historias, redactar documentos oficiales, escribir correos electrónicos, guiones, realizar razonamiento lógico, programar, etc. También puedo expresar opiniones y jugar juegos. Si tienes alguna pregunta o necesitas ayuda, ¡no dudes en decírmelo!

Funciones especiales

Función de visión (Vision)

Admite entrada de imágenes (URL o codificación Base64) para lograr interacción multimodal.

Entrada de URL de imagen:

Entrada de imagen codificada en Base64:

Uso asíncrono (Async usage)

Reemplace OpenAI por AsyncOpenAI y llame a la API con await:

Ejemplo asíncrono básico:

Optimización para escenarios asíncronos (backend aiohttp), instale la versión extendida:

pip install openai[aiohttp]

Optimización del backend aiohttp:

Respuestas en streaming (Streaming responses)

Obtenga respuestas en tiempo real basadas en Server Side Events (SSE), con interfaz consistente para síncrono/asíncrono.

Ejemplo de streaming síncrono:

Ejemplo de streaming asíncrono:

API en tiempo real (Realtime API)

Diálogo multimodal de baja latencia (texto/audio), implementado sobre WebSocket, depende de la biblioteca websockets.

Ejemplo básico de texto:

Manejo de errores de la API en tiempo real:

Manual de referencia

El contenido de la siguiente tabla es:

• Inicialización del núcleo: para uso síncronoOpenAI, para uso asíncronoAsyncOpenAI, para AzureAzureOpenAI, se recomienda configurar la API Key mediante variables de entorno.
• Generación de texto: para la nueva versión se prefiere usarresponses.create(), para escenarios clásicos usarchat.completions.create(), para salida en streaming se debe configurarstream=True。
• Capacidades avanzadas: soporta multimodal (entrada de imágenes), API en tiempo real, carga de archivos/ajuste fino, el manejo de errores requiere capturarAPIErrorsubclases, el tiempo de espera/reintentos se pueden configurar de forma flexible.

Instalación e importación

Instalar el SDK oficial:

pip install --upgrade openai

Importar las clases principales:

from openai import OpenAI, AsyncOpenAI, AzureOpenAI

Creación del cliente

Crear el cliente estándar de OpenAI:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY")

Crear el cliente mediante variables de entorno:

import os
from openai import OpenAI

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

Configurar el tiempo de espera de las solicitudes y el número de reintentos:

client = OpenAI(
    timeout=30,
    max_retries=2
)

Generación de texto (Responses API)

La solicitud más básica de generación de texto:

response = client.responses.create(
    model="gpt-5.2",
    input="用一句话解释什么是 Python"
)

print(response.output_text)

Restringir el comportamiento del modelo mediante instrucciones:

response = client.responses.create(
    model="gpt-5.2",
    instructions="你是一个严谨的 Python 教程作者",
    input="解释什么是列表推导式"
)

print(response.output_text)

Conversaciones de varios turnos

Construir diálogos contextuales usando el array input:

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {"role": "user", "content": "Python 是什么？"},
        {"role": "assistant", "content": "Python 是一门高级编程语言。"},
        {"role": "user", "content": "它适合做什么？"}
    ]
)

print(response.output_text)

Salida estructurada (JSON Schema)

Solicitar al modelo que devuelva datos JSON que cumplan con el Schema:

response = client.responses.create(
    model="gpt-5.2",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "tech_summary",
            "schema": {
                "type": "object",
                "properties": {
                    "title": {"type": "string"},
                    "summary": {"type": "string"}
                },
                "required": ["title", "summary"]
            }
        }
    },
    input="介绍 asyncio"
)

print(response.output_parsed)

Llamada a herramientas (Function Calling)

Definir herramientas y permitir que el modelo decida automáticamente si invocarlas:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取城市天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.responses.create(
    model="gpt-5.2",
    tools=tools,
    input="北京今天天气怎么样？"
)

print(response.output)

Salida en streaming (Streaming)

Salida en streaming síncrona:

with client.responses.stream(
    model="gpt-5.2",
    input="写一段 Python 示例代码"
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="")

Salida en streaming asíncrona:

stream = await client.responses.create(
    model="gpt-5.2",
    input="解释什么是生成式 AI",
    stream=True
)

async for event in stream:
    print(event)

Llamada asíncrona (AsyncOpenAI)

Usar el cliente asíncrono en asyncio:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    response = await client.responses.create(
        model="gpt-5.2",
        input="解释什么是事件循环"
    )
    print(response.output_text)

asyncio.run(main())

API en tiempo real (Realtime)

Usar WebSocket para conversaciones en tiempo real de baja latencia:

async with client.realtime.connect(model="gpt-realtime") as conn:
    await conn.session.update(
        session={"type": "realtime", "output_modalities": ["text"]}
    )

    await conn.conversation.item.create(
        item={
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "你好"}]
        }
    )

    async for event in conn:
        print(event)

Generación de imágenes

Generar imágenes a partir de texto:

image = client.images.generate(
    model="gpt-image-1",
    prompt="一只在写代码的猫",
    size="1024x1024"
)

print(image.data[0].url)

Generación de embeddings (Embeddings)

Generar incrustaciones vectoriales de texto:

embedding = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello world"
)

print(embedding.data[0].embedding)

Conversión de audio a texto (Speech to Text)

Convertir archivos de audio en texto:

audio_file = open("speech.mp3", "rb")

transcript = client.audio.transcriptions.create(
    model="whisper-1",
    file=audio_file
)

print(transcript.text)

Texto a voz (Text to Speech)

Convertir texto en archivos de voz:

speech = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input="你好，欢迎使用 OpenAI"
)

with open("output.mp3", "wb") as f:
    f.write(speech)

Gestión de archivos (Files API)

Subir archivos:

from pathlib import Path

client.files.create(
    file=Path("data.jsonl"),
    purpose="fine-tune"
)

Listar archivos:

files = client.files.list()
for f in files:
    print(f.id, f.filename)

Eliminar archivos:

client.files.delete(file_id="file-xxx")

Ajuste fino de modelos (Fine-tuning Jobs)

Crear una tarea de ajuste fino:

job = client.fine_tuning.jobs.create(
    training_file="file-xxx",
    model="gpt-3.5-turbo"
)

print(job.id, job.status)

Verificación de Webhook

Verificar y analizar solicitudes Webhook:

event = client.webhooks.unwrap(request_body, request_headers)

Solo verificar la firma:

client.webhooks.verify_signature(request_body, request_headers)

Manejo de errores

Capturar las excepciones lanzadas por el SDK:

import openai

try:
    client.responses.create(
        model="gpt-5.2",
        input="test"
    )
except openai.RateLimitError as e:
    print("触发速率限制：", e)
except openai.APIConnectionError as e:
    print("连接失败：", e)

Obtener el Request ID de las solicitudes fallidas:

try:
    client.responses.create(model="gpt-5.2", input="test")
except openai.APIStatusError as exc:
    print(exc.request_id)

Compatibilidad con Azure OpenAI

Inicializar el cliente de Azure OpenAI:

from openai import AzureOpenAI

client = AzureOpenAI(
    api_version="2023-07-01-preview",
    azure_endpoint="https://xxx.openai.azure.com"
)

Versiones y registros

Ver la versión del SDK:

import openai
print(openai.__version__)

Activar los registros de depuración del SDK:

export OPENAI_LOG=debug

Más referencias de API:https://github.com/openai/openai-python/blob/main/api.md