APIs de LLM para Desenvolvedores: Introdução às Chat Completions

Você tem uma ótima ideia para um recurso com IA, mas quando começa a ler a documentação da API, se depara com uma parede de jargões: tokens, temperature, streaming, system prompts. Parece que você precisa de um segundo diploma só para enviar uma mensagem. A boa notícia é que o conceito central é simples: você envia uma lista de mensagens, e o modelo devolve uma resposta. Todo o resto é ajuste fino. Este artigo mostra os passos práticos para integrar uma API de chat completion de LLM ao seu aplicativo, com código que você pode adaptar hoje mesmo.

O que é uma API de Chat Completion?

No seu cerne, uma API de chat completion recebe um histórico de conversa como entrada e retorna a próxima mensagem da conversa. O histórico é um array de objetos de mensagem, cada um com um role e um content. Os roles geralmente são system, user e assistant. A mensagem de sistema define o comportamento do assistente, a mensagem do usuário é o que a pessoa digitou, e a mensagem do assistente é o que o modelo respondeu anteriormente. Ao enviar todo o histórico, você dá ao modelo o contexto para gerar uma resposta coerente.

A maioria dos provedores (OpenAI, Anthropic, Google e alternativas de código aberto) segue um padrão semelhante, embora o endpoint e o payload exatos possam variar. Depois de entender um, você consegue se adaptar aos outros rapidamente.

Passo a Passo: Sua Primeira Chamada de API

Vamos percorrer um exemplo mínimo usando Python e o SDK da OpenAI. Você pode instalá-lo com pip install openai. Defina sua chave de API como variável de ambiente para mantê-la fora do seu código.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain what an API is in one sentence."}
    ]
)

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

É isso. O objeto de resposta contém uma lista de choices; normalmente você pega a primeira. O conteúdo da mensagem é a resposta do modelo. Você também pode acessar estatísticas de uso para acompanhar o consumo de tokens.

Parâmetros-Chave que Você Deve Ajustar

Além das mensagens, alguns parâmetros controlam a saída do modelo:

• model: Qual modelo usar. Modelos menores são mais baratos e rápidos; modelos maiores são mais capazes.
• temperature: Controla a aleatoriedade. 0 é determinístico, 1 é criativo. Para tarefas factuais, use um valor baixo; para brainstorming, use um mais alto.
• max_tokens: Limita o comprimento da resposta. Defina isso para evitar respostas inesperadamente longas (e caras).
• top_p: Uma alternativa à temperature para controlar a diversidade. Normalmente você ajusta um ou outro, não ambos.
• stream: Quando true, a API envia respostas parciais conforme são geradas, melhorando a latência percebida.

Respostas em Streaming para Melhor UX

Esperar por uma resposta completa pode parecer lento, especialmente para respostas longas. O streaming permite exibir o texto conforme ele chega. Veja como lidar com um stream em Python:

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Cada chunk contém um delta com um pedaço da resposta. Você acumula esses pedaços para construir a mensagem completa. Em um aplicativo web, você pode encaminhar esses chunks para o navegador usando Server-Sent Events (SSE) ou WebSockets.

Tratamento de Erros e Limites de Taxa

APIs falham. Redes oscilam. Limites de taxa são atingidos. Sua integração deve lidar com isso de forma elegante. Erros comuns incluem:

• 401 Unauthorized: Chave de API inválida. Verifique sua variável de ambiente.
• 429 Too Many Requests: Você atingiu um limite de taxa. Implemente backoff exponencial e tente novamente.
• 500 Internal Server Error: Problema do lado do provedor. Tente novamente com um atraso.

Sempre envolva chamadas de API em blocos try/except e registre falhas. Para produção, considere usar uma biblioteca como tenacity para retentativas.

Gerenciando Custos e Tokens

Tokens são a moeda das APIs de LLM. Tanto tokens de entrada quanto de saída contam na sua fatura. Para manter os custos previsíveis:

• Use modelos menores para tarefas simples.
• Reduza o histórico da conversa para as últimas mensagens quando o contexto completo não for necessário.
• Defina max_tokens para limitar o comprimento da saída.
• Faça cache de respostas frequentes se o seu caso de uso permitir.

Monitore o uso pelo painel do provedor ou registrando as contagens de tokens de cada resposta.

Considerações de Segurança e Privacidade

Ao enviar dados de usuários para uma API de LLM, você está confiando esses dados a um terceiro. Revise as políticas de retenção de dados do provedor. Evite enviar informações sensíveis como senhas ou identificadores pessoais. Se for necessário, considere modelos auto-hospedados ou provedores com fortes garantias de privacidade. Além disso, nunca exponha sua chave de API em código do lado do cliente; sempre faça proxy das requisições pelo seu backend.

FAQ

Qual é a diferença entre um chat completion e um completion comum?

Chat completions são projetados para interfaces conversacionais. Eles aceitam uma lista de mensagens com roles, permitindo que o modelo mantenha o contexto. Completions comuns recebem uma única string de prompt e são menos adequados para diálogos com múltiplos turnos.

Como escolho o modelo certo?

Comece com um modelo menor e mais barato para prototipagem. Se precisar de melhor raciocínio ou contexto mais longo, migre para um modelo maior. Teste ambos na sua tarefa específica para encontrar o melhor equilíbrio entre custo e desempenho.

Posso usar vários provedores de LLM em um único app?

Sim. Muitos desenvolvedores abstraem as chamadas de API por trás de uma interface e alternam provedores com base em custo, latência ou recursos. Bibliotecas como LiteLLM ou LangChain podem ajudar a unificar diferentes APIs.

Próximos Passos

Agora que você consegue fazer uma chamada básica, experimente system prompts para direcionar o comportamento do modelo. Tente streaming para melhorar a experiência do usuário. E sempre fique de olho no uso de tokens. Conforme você constrói, pode precisar formatar respostas JSON do modelo para processamento posterior. Para isso, um formatador JSON pode ajudar você a validar e formatar a saída rapidamente.