Integração com OpenAI
Regras
- Use o pacote oficial
openai — new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
- Streaming para chat:
stream: true com iterador assíncrono — nunca bloqueie até a conclusão completa para respostas voltadas ao usuário
- Chamada de funções: defina funções com JSON Schema, lide com
tool_calls na resposta e retorne resultados como mensagens de ferramenta
- Saídas estruturadas: use
response_format: { type: "json_schema", json_schema: {...} } ou Zod com AI SDK
- Gerenciamento de tokens: estime tokens antes de enviar (aproximadamente 4 caracteres por token), corte o contexto para permanecer dentro dos limites
- Seleção de modelo:
gpt-4o para raciocínio complexo, gpt-4o-mini para tarefas simples — torne-o configurável
- Prompt do sistema como primeira mensagem — defina tom, restrições e formato de saída
- Temperatura: 0 para saídas determinísticas (extração de dados), 0,7-1,0 para tarefas criativas
- Limitação de taxa: respeite os cabeçalhos
x-ratelimit-*, implemente backoff exponencial em erros 429
Padrões
const stream = await openai.chat.completions.create({
model: "gpt-4o",
messages,
stream: true,
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || "";
process.stdout.write(content);
}
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages,
tools: [{ type: "function", function: { name: "get_weather", parameters: schema } }],
});
Evite
- Codificar chaves de API — sempre use variáveis de ambiente
- Ignorar limites de tokens — conte tokens e corte mensagens proativamente
- Usar
gpt-4o para tarefas triviais — use gpt-4o-mini para economizar custos
- Faltar com tratamento de erros nas chamadas de API — lide com erros 429, 500 e timeout de forma elegante