AI Engineering Academy · Aula

O endpoint de conclusões de conversa

Entenda a matriz de mensagens com as funções de sistema, usuário e assistente, crie seu primeiro prompt e interprete o objeto de resposta retornado pela API.

Aula 2 de 413 etapas

O endpoint de conclusões de conversa é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.

A arquitetura da matriz de mensagens

O endpoint de conclusões de chat funciona com uma matriz de mensagens: uma lista de turnos, cada um com uma função (sistema, usuário ou assistente). O modelo não mantém estado, portanto você envia o histórico todas as vezes.

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)

A função do sistema: definindo o comportamento

A mensagem do sistema é sua ferramenta mais poderosa. Ela define a personalidade, as regras e o formato do modelo antes que o usuário digite uma palavra. Dedique tempo a isso — essa mensagem molda tudo. Veja o 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?'}
    ]
)

Gerenciando conversas com vários turnos

Para manter uma conversa em andamento, você usa append para adicionar cada turno à matriz de mensagens e reenvia tudo. É assim que o modelo parece se lembrar: você fornece a ele o histórico completo.

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'

Anatomia da resposta da API

A resposta é um objeto, não apenas texto. choices contém a resposta, o motivo de finalização informa por que ela parou e o uso contabiliza os tokens — que determinam seu custo. Registre esses dados em produção.

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)

Entendendo o motivo de finalização

motivo de finalização informa por que a geração parou. 'stop' significa que terminou; 'length' significa que atingiu max_tokens e foi interrompida no meio da resposta. Sempre verifique isso — o truncamento é um erro 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

Selecionando o modelo certo

Escolha o modelo certo para a tarefa. gpt-4o é o mais potente para raciocínios complexos; gpt-4o-mini é muito mais barato e lida bem com a maioria das tarefas. Faça uma avaliação comparativa antes de presumir que o maior sempre é melhor.

# 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 conteúdo nas mensagens

O conteúdo de uma mensagem pode ser mais do que texto. Para modelos de visão, como o gpt-4o, você envia uma lista que combina texto e imagens — assim, pode fazer perguntas sobre gráficos ou capturas de tela.

# 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'}
                }
            ]
        }
    ]
)

O parâmetro n: várias conclusões

O parâmetro n retorna várias conclusões para um único prompt. Isso é útil para escolher a melhor ou avaliar a confiança: se todas as n respostas concordarem, o modelo está seguro; se divergirem, tenha 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)

Tratando a resposta como uma string

Para obter a resposta como texto, o caminho é sempre response.choices[0].message.content. Coloque-o em uma função auxiliar — e trate o caso de None, que ocorre em chamadas de ferramentas ou por causa de 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)

Inspecionando a requisição e a resposta brutas

Está depurando respostas estranhas? Inspecione a requisição e a resposta brutas. Definir OPENAI_LOG=debug imprime o corpo completo no seu terminal — a maneira mais rápida de ver o que está sendo transmitido.

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

Criando um ciclo de chat mínimo

Agora você pode criar um ciclo de chat mínimo: mantenha uma lista de mensagens, use append para adicionar cada turno, envie tudo e repita. Esse padrão simples dá suporte a todos os aplicativos de chat da API. O código mostra como fazer isso.

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.')

Verificação rápida

Teste sua compreensão dos conceitos de Engenharia de IA desta lição.

Recapitulação da lição

Você aprendeu o núcleo do chat: a matriz de mensagens controla a conversa, e a resposta contém o conteúdo, o motivo de finalização e a contagem de tokens. A seguir: parâmetros.

Grátis para começar

Aprenda Python com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos
30
Aulas
120

Perguntas Frequentes

A aula “O endpoint de conclusões de conversa” é grátis?

Sim — o texto completo de “O endpoint de conclusões de conversa” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.

O que vou aprender em “O endpoint de conclusões de conversa”?

Entenda a matriz de mensagens com as funções de sistema, usuário e assistente, crie seu primeiro prompt e interprete o objeto de resposta retornado pela API. Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Engineering Academy?

Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “O endpoint de conclusões de conversa”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Engineering Academy?

Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Configurando seu ambiente Python
  2. O endpoint de conclusões de conversa
  3. Controlando o comportamento do modelo com parâmetros
  4. Tratamento de erros e limites de taxa
← Voltar para AI Engineering Academy