AI Engineering Academy · Lección

El endpoint de Chat Completions

Comprenderá el array de mensajes con roles de system, user y assistant, creará su primer prompt e interpretará el objeto de respuesta que devuelve la API.

Lección 2 de 413 pasos

El endpoint de Chat Completions es una lección gratuita de AI Engineering Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Engineering Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Engineering Academy incluye 4 lecciones en total.

La arquitectura del array de mensajes

El endpoint Chat Completions funciona con un array de mensajes: una lista de turnos, cada uno con un rol (system, user o assistant). El modelo no tiene estado, por lo que debe enviar el historial cada vez.

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': 'You are a concise Python tutor.'},
        {'role': 'user', 'content': 'What is a list comprehension?'}
    ]
)

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

El rol system: definición del comportamiento

El mensaje system es su herramienta de mayor impacto. Define la personalidad, las reglas y el formato del modelo antes de que el usuario escriba una sola palabra. Dedique tiempo a esta parte: determina todo lo demás. Consulte el código.

system_prompt = '''You are a customer support agent for TechShop.
You help customers with: order tracking, returns, and product questions.
You do NOT discuss pricing changes or competitor products.
Always respond in 2-3 sentences maximum.
If you cannot help, say: 'Let me connect you with a human agent.'
'''

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': system_prompt},
        {'role': 'user', 'content': 'Where is my order #12345?'}
    ]
)

Gestión de conversaciones con varios turnos

Para mantener una conversación, debe añadir cada turno al array de mensajes y volver a enviarlo completo. Así parece que el modelo recuerda: usted le proporciona todo el historial.

history = [
    {'role': 'system', 'content': 'You are a helpful assistant.'}
]

def chat(user_message):
    history.append({'role': 'user', 'content': user_message})
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=history
    )
    assistant_reply = response.choices[0].message.content
    history.append({'role': 'assistant', 'content': assistant_reply})
    return assistant_reply

print(chat('My name is Alice.'))
print(chat('What is my name?'))  # model remembers 'Alice'

Anatomía de la respuesta de la API

La respuesta es un objeto, no solo texto. choices contiene la respuesta, finish_reason indica por qué se detuvo y usage cuenta los tokens, que determinan el coste. Registre estos datos en producción.

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Say hello in one word.'}]
)

# Accessing response fields
print('Content:', response.choices[0].message.content)
print('Finish reason:', response.choices[0].finish_reason)  # 'stop'
print('Model:', response.model)  # exact version like gpt-4o-mini-2024-07-18
print('Prompt tokens:', response.usage.prompt_tokens)
print('Completion tokens:', response.usage.completion_tokens)
print('Total tokens:', response.usage.total_tokens)

Comprensión de finish_reason

finish_reason indica por qué se detuvo la generación. 'stop' significa que terminó; 'length' significa que alcanzó max_tokens y la respuesta quedó cortada a mitad. Compruébelo siempre: la truncación es un error silencioso.

def safe_completion(messages, max_tokens=500):
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=messages,
        max_tokens=max_tokens
    )
    choice = response.choices[0]
    
    if choice.finish_reason == 'length':
        print(f'WARNING: Response was truncated at {max_tokens} tokens!')
    elif choice.finish_reason == 'content_filter':
        print('WARNING: Response blocked by content filter!')
        return None
    
    return choice.message.content

Selección del modelo adecuado

Elija el modelo adecuado para cada tarea. gpt-4o es la opción más potente para razonamientos difíciles; gpt-4o-mini es mucho más barato y resuelve bien la mayoría de las tareas. Haga pruebas de rendimiento antes de dar por hecho que un modelo más grande es mejor.

# Model comparison guidance
models = {
    'gpt-4o': {
        'use_for': 'Complex reasoning, code generation, nuanced analysis',
        'input_cost_per_1M': 2.50,  # USD
        'output_cost_per_1M': 10.00
    },
    'gpt-4o-mini': {
        'use_for': 'Classification, extraction, summarization, Q&A',
        'input_cost_per_1M': 0.15,
        'output_cost_per_1M': 0.60
    }
}
# gpt-4o is ~17x more expensive on input tokens

Tipos de contenido en los mensajes

El contenido de un mensaje puede ser algo más que texto. En modelos de visión como gpt-4o, puede enviar una lista que combine texto e imágenes, lo que permite hacer preguntas sobre gráficos o capturas de pantalla.

# Sending an image to a vision-capable model
response = client.chat.completions.create(
    model='gpt-4o',
    messages=[
        {
            'role': 'user',
            'content': [
                {
                    'type': 'text',
                    'text': 'What is in this image? Describe in one sentence.'
                },
                {
                    'type': 'image_url',
                    'image_url': {'url': 'https://example.com/photo.jpg'}
                }
            ]
        }
    ]
)

El parámetro n: varias finalizaciones

El parámetro n devuelve varias finalizaciones para un mismo prompt. Es útil para elegir la mejor o para evaluar la confianza: si todas las n respuestas coinciden, el modelo parece seguro; si difieren, proceda con cautela.

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Name the capital of Germany.'}],
    n=3,  # generate 3 independent completions
    temperature=0.5
)

for i, choice in enumerate(response.choices):
    print(f'Completion {i+1}: {choice.message.content}')

# Check if all completions agree (confidence signal)
answers = [c.message.content.strip() for c in response.choices]
print('All agree:', len(set(answers)) == 1)

Gestión de la respuesta como cadena

Para obtener la respuesta como texto, la ruta es siempre response.choices[0].message.content. Envuélvala en una función auxiliar y controle el valor None, que aparece en las llamadas a herramientas o cuando intervienen filtros.

def get_completion(prompt, system='You are a helpful assistant.', model='gpt-4o-mini'):
    '''Simple helper that returns the response text as a string.'''
    response = client.chat.completions.create(
        model=model,
        messages=[
            {'role': 'system', 'content': system},
            {'role': 'user', 'content': prompt}
        ]
    )
    content = response.choices[0].message.content
    if content is None:
        raise ValueError(f'No content in response. Finish reason: {response.choices[0].finish_reason}')
    return content

result = get_completion('Explain recursion in one sentence.')
print(result)

Inspección de la solicitud y la respuesta sin procesar

¿Está depurando respuestas extrañas? Inspeccione la solicitud y la respuesta sin procesar. Al establecer OPENAI_LOG=debug, se muestra el cuerpo completo en el terminal: es la forma más rápida de ver qué se está transmitiendo.

import json
import httpx

# Enable debug logging (shows full request/response)
import os
os.environ['OPENAI_LOG'] = 'debug'

# Or use a custom logging client:
class LoggingClient(httpx.Client):
    def send(self, request, *args, **kwargs):
        print('REQUEST:', request.method, request.url)
        print('BODY:', json.loads(request.content))
        response = super().send(request, *args, **kwargs)
        print('STATUS:', response.status_code)
        return response

Construcción de un bucle de chat mínimo

Ahora puede construir un bucle de chat mínimo: mantenga una lista de mensajes, añada cada turno, envíela completa y repita. Este patrón sencillo sustenta todas las aplicaciones de chat de la API. El código lo muestra.

import openai

client = openai.OpenAI()

SYSTEM_PROMPT = 'You are a helpful assistant. Be concise.'

def simple_chat_loop():
    messages = [{'role': 'system', 'content': SYSTEM_PROMPT}]
    print('Chat started. Type "quit" to exit.')

    while True:
        user_input = input('You: ').strip()
        if user_input.lower() == 'quit':
            break
        if not user_input:
            continue

        messages.append({'role': 'user', 'content': user_input})

        response = client.chat.completions.create(
            model='gpt-4o-mini',
            messages=messages,
            max_tokens=500
        )

        assistant_reply = response.choices[0].message.content
        messages.append({'role': 'assistant', 'content': assistant_reply})
        print(f'Assistant: {assistant_reply}\n')

print('Example chat loop defined. Run simple_chat_loop() to start.')

Comprobación rápida

Compruebe su comprensión de los conceptos de Ingeniería de IA de esta lección.

Resumen de la lección

Ha aprendido los fundamentos del chat: el array de mensajes controla la conversación y la respuesta contiene content, finish_reason y el recuento de tokens. A continuación: los parámetros.

Gratis para empezar

Aprende Python con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos
30
Lecciones
120

Preguntas frecuentes

¿La lección «El endpoint de Chat Completions» es gratis?

Sí — el texto completo de «El endpoint de Chat Completions» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Engineering Academy, actualiza a CoddyKit PRO. El curso de AI Engineering Academy incluye 4 lecciones en total.

¿Qué aprenderé en «El endpoint de Chat Completions»?

Comprenderá el array de mensajes con roles de system, user y assistant, creará su primer prompt e interpretará el objeto de respuesta que devuelve la API. Practicas AI Engineering Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Engineering Academy?

No se requiere experiencia previa. AI Engineering Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «El endpoint de Chat Completions»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Engineering Academy?

Sí. Cada lección de AI Engineering Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Configuración del entorno de Python
  2. El endpoint de Chat Completions
  3. Control del comportamiento del modelo con parámetros
  4. Gestión de errores y límites de velocidad
← Volver a AI Engineering Academy