Boas práticas para produção

Este guia reúne boas práticas para ajudar você a passar do protótipo à produção. Tanto quem já tem experiência em engenharia de aprendizado de máquina quanto quem está começando a explorar a área encontrará orientações para usar a plataforma em produção, desde a proteção do acesso à nossa API até o projeto de uma arquitetura robusta que suporte grandes volumes de tráfego. Use essas orientações para planejar uma implantação tranquila e eficaz do seu aplicativo.

Para saber mais sobre as boas práticas para colocar um aplicativo em produção, assista à nossa palestra do Developer Day:

Configuração da organização

Depois de entrar na sua conta da OpenAI, você pode consultar o nome e o ID da organização nas configurações da organização. O nome identifica sua organização nas interfaces de usuário. O ID da organização é um identificador exclusivo que você pode usar nas requisições à API.

Quem faz parte de várias organizações pode enviar um cabeçalho para especificar qual organização usar em uma requisição à API. O uso dessas requisições conta para a cota da organização especificada. Se você não enviar o cabeçalho, a cobrança será feita à organização padrão. Você pode alterar sua organização padrão nas configurações de usuário.

Você pode convidar novos membros para a organização pela página da equipe. Os membros podem ser leitores ou proprietários.

Leitores:

• Podem fazer requisições à API.
• Podem consultar informações básicas da organização.
• Podem criar, atualizar e excluir recursos da organização, como assistentes, salvo indicação em contrário.

Proprietários:

• Têm todas as permissões dos leitores.
• Podem alterar as informações de cobrança.
• Podem gerenciar os membros da organização.

Gerenciamento de limites de cobrança

Depois que você informa os dados de cobrança, a OpenAI define um limite de uso aprovado para sua organização. Sua cota aumenta automaticamente à medida que o uso da plataforma cresce e você passa de uma faixa de uso para outra. Você pode consultar seu limite de uso atual na página de limites nas configurações da conta.

Configure alertas de gastos na página de limites para receber notificações quando o uso ultrapassar determinado valor em dólares. Para impor um teto mensal, defina um limite rígido de gastos. Quando os gastos monitorados atingem esse limite, o tráfego da API sujeito a ele é interrompido. Consulte o guia de limites de gastos antes de ativar um limite rígido em produção.

Chaves de API

A API da OpenAI usa chaves de API para autenticação. Acesse a página de chaves de API para obter a chave que você usará nas requisições.

Use uma conta de serviço do projeto como identidade do aplicativo para evitar depender da chave pessoal de um desenvolvedor. Consulte Chaves de API e contas de serviço para saber como escolher as credenciais e automatizar o gerenciamento de projetos e chaves.

Essa é uma maneira relativamente simples de controlar o acesso, mas é essencial proteger as chaves. Evite expor chaves de API no código ou em repositórios públicos. Armazene-as em um local seguro. Disponibilize as chaves para o aplicativo por meio de variáveis de ambiente ou de um serviço de gerenciamento de segredos. Assim, você não precisa inseri-las diretamente no código. Saiba mais em Boas práticas para proteger chaves de API.

Recomendamos enfaticamente definir uma data de expiração ao criar uma chave de API de projeto e estabelecer uma rotina de rotação de chaves. Antes que uma chave expire, crie outra para substituí-la, atualize seus aplicativos para usar a nova chave e revogue a antiga depois de verificar que a nova funciona.

Nas configurações da plataforma, os administradores podem impor um prazo máximo de validade para as chaves de API no nível da organização ou do projeto. As novas chaves devem expirar dentro do prazo configurado, o que impede que permaneçam válidas indefinidamente. O limite do projeto não pode exceder o da organização.

Na seção Governança de chaves de API das configurações da plataforma, os administradores de organizações e projetos podem restringir os tipos de chave de API que podem ser criados. Eles podem permitir apenas chaves de contas de serviço, permitir apenas chaves de projeto pertencentes a usuários ou desativar por completo a criação de chaves de API. As restrições da organização sempre têm precedência. As configurações do projeto podem acrescentar restrições, mas não podem flexibilizar as da organização. Esses controles se aplicam apenas à criação de chaves. As chaves de API existentes não são afetadas.

Depois de ativar o rastreamento, você pode monitorar o uso das chaves de API na página de uso. Para chaves geradas antes de 20 de dezembro de 2023, o rastreamento vem desativado por padrão. Você pode ativá-lo no painel de gerenciamento de chaves de API para acompanhar o uso a partir de então. Todas as chaves geradas após 20 de dezembro de 2023 já têm o rastreamento ativado. O painel exibe como Untracked qualquer uso anterior que não tenha sido rastreado.

Projetos de homologação

À medida que seu aplicativo cresce, pode ser útil criar projetos separados para os ambientes de homologação e produção. Você pode criar esses projetos no painel para isolar o desenvolvimento e os testes e evitar interrupções acidentais no aplicativo em produção. Você também pode restringir o acesso dos usuários ao projeto de produção e definir limites específicos de taxa e de gastos para cada projeto.

Como dimensionar a arquitetura da solução

Ao projetar um aplicativo ou serviço que use nossa API em produção, planeje como ampliar sua capacidade para atender à demanda de tráfego. Independentemente do provedor de serviços de nuvem escolhido, considere os seguintes aspectos:

• Escalabilidade horizontal: você pode ampliar o aplicativo horizontalmente para atender a requisições de várias origens. Isso pode envolver a implantação de servidores ou contêineres adicionais para distribuir a carga. Se escolher essa abordagem, certifique-se de que a arquitetura suporte vários nodes e tenha mecanismos para balancear a carga entre eles.
• Escalabilidade vertical: outra opção é ampliar o aplicativo verticalmente, aumentando os recursos disponíveis em um único node. Nesse caso, você aumenta a capacidade do servidor para lidar com a carga adicional. Se escolher essa abordagem, certifique-se de que o aplicativo consiga aproveitar os recursos extras.
• Uso de cache: armazenar os dados acessados com frequência permite reduzir o tempo de resposta sem precisar fazer chamadas repetidas à nossa API. Projete o aplicativo para usar dados em cache sempre que possível e invalidar o cache quando novas informações forem adicionadas. Por exemplo, você pode armazenar dados em um banco de dados, em um sistema de arquivos ou em um cache na memória, conforme as necessidades do aplicativo.
• Balanceamento de carga: considere técnicas de balanceamento de carga para distribuir as requisições de maneira uniforme entre os servidores disponíveis. Você pode, por exemplo, colocar um balanceador de carga na frente dos servidores ou usar DNS round-robin. Distribuir a carga ajuda a melhorar o desempenho e a reduzir gargalos.

Compactação do corpo das requisições

Para reduzir o volume de dados enviados, compacte o corpo JSON da requisição com zstd ao chamar POST /v1/responses. Defina Content-Encoding: zstd e mantenha Content-Type: application/json.

1234567zstd -3 -c request.json > request.json.zst

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: zstd" \
  --data-binary @request.json.zst

A API descompacta o corpo antes de processar a requisição. A compactação reduz o número de bytes enviados pela rede. O uso de tokens e os limites de contexto do modelo permanecem os mesmos.

O corpo da requisição deve ter no máximo 128 MiB, tanto compactado quanto descompactado. Além disso, o tamanho do corpo descompactado não pode exceder 100 vezes o tamanho do corpo compactado. Para requisições que excedem esses limites, a API retorna HTTP 413. A API retorna HTTP 400 se os dados zstd forem inválidos ou incompletos. Os demais limites de requisição continuam em vigor.

Compactação de mensagens WebSocket

O modo WebSocket da API Responses oferece suporte a permessage-deflate em wss://api.openai.com/v1/responses. Essa extensão do WebSocket usa DEFLATE para reduzir o tamanho das mensagens. Antes de se conectar, ative a extensão nas configurações de compactação do seu cliente WebSocket.

Gerenciamento de limites de taxa

Ao usar nossa API, é importante entender os limites de taxa e levá-los em conta no planejamento.

Redução da latência

Latência é o tempo entre o envio de uma requisição e o retorno da resposta após o processamento. Nesta seção, veremos alguns fatores que influenciam a latência dos nossos modelos de geração de texto e como reduzi-la.

A latência de uma requisição de geração de texto depende principalmente de dois fatores: o modelo e o número de tokens gerados. O ciclo de vida de uma requisição de geração de texto é o seguinte:

Em geral, a etapa de geração de tokens responde pela maior parte da latência.

Na prática: os tokens do prompt acrescentam pouca latência às chamadas de geração de texto. Gerar os tokens da resposta leva muito mais tempo, pois o modelo gera um token por vez. Quanto mais longa a resposta, maior a latência acumulada, já que cada token precisa ser gerado.

Fatores que afetam a latência e como reduzir seu impacto

Agora que vimos os conceitos básicos de latência, vamos examinar os fatores que podem afetá-la, em ordem aproximada do maior para o menor impacto.

Modelo

Nossa API oferece modelos com diferentes níveis de complexidade e capacidade de lidar com tarefas variadas. Os modelos mais capazes, como o gpt-6-astra, podem gerar respostas mais complexas e diversas, mas também levam mais tempo para processar sua consulta. Modelos como o gpt-5.6-terra e o gpt-5.6-luna podem gerar respostas mais rapidamente e a um custo menor. Já o gpt-6-astra é uma escolha padrão mais indicada quando você precisa de mais capacidade para lidar com tarefas complexas. Escolha o modelo que melhor atenda ao seu caso de uso, considerando o equilíbrio entre velocidade, custo e qualidade.

Número de tokens da resposta

Solicitar respostas com muitos tokens pode aumentar a latência:

• Reduza o limite de tokens: entre requisições que geram quantidades semelhantes de tokens, as que têm um valor menor para o parâmetro max_tokens apresentam menor latência.
• Inclua sequências de parada: para evitar a geração de tokens desnecessários, adicione uma sequência de parada. Por exemplo, você pode usar esse recurso para gerar uma lista com um número específico de itens. Ao usar 11. como sequência de parada, você pode gerar uma lista de apenas 10 itens, pois a geração termina ao chegar a 11.. Leia nosso artigo de ajuda sobre sequências de parada para saber como fazer isso.
• Gere menos respostas: reduza os valores de n e best_of quando possível. O parâmetro n indica quantas respostas gerar para cada prompt, e best_of permite selecionar o resultado com a maior probabilidade logarítmica por token.

Se n e best_of forem iguais a 1 (o valor padrão), o número de tokens gerados não ultrapassará max_tokens.

Se n (o número de respostas retornadas) ou best_of (o número de respostas geradas para seleção) tiver valor > 1, cada requisição produzirá várias saídas. Nesse caso, você pode estimar o número de tokens gerados como [ max_tokens * max (n, best_of) ].

Streaming

Ao definir stream: true em uma requisição, você faz com que o modelo comece a retornar os tokens assim que ficam disponíveis, sem esperar pela geração de toda a sequência. O tempo para receber todos os tokens permanece o mesmo, mas o aplicativo recebe o primeiro token mais cedo. Isso é útil quando você quer mostrar o progresso ao usuário ou interromper a geração. Vale a pena experimentar o streaming para ver se ele melhora a experiência do usuário.

Processamento em lote

Dependendo do caso de uso, o processamento em lote pode ajudar. Se você envia várias requisições ao mesmo endpoint, pode agrupar os prompts para enviá-los em uma única requisição. Isso reduz o número de requisições necessárias. O parâmetro de prompt aceita até 20 prompts distintos. Recomendamos testar essa abordagem para verificar se ela ajuda no seu caso. Em algumas situações, o número de tokens gerados pode aumentar, o que torna a resposta mais lenta.

Gestão de custos

Para monitorar os custos, você pode definir um limite de notificação na sua conta para receber um alerta por e-mail quando o uso ultrapassar determinado valor. Use o painel de acompanhamento de uso para monitorar o consumo de tokens no ciclo de cobrança atual e nos anteriores.

Geração de texto

Um dos desafios de levar um protótipo para produção é prever no orçamento o custo de manter o aplicativo em operação. A OpenAI oferece um modelo de cobrança por uso, com preços por 1.000 tokens (cerca de 750 palavras). Para estimar os custos, você precisa projetar o consumo de tokens. Considere o volume de tráfego, a frequência com que os usuários vão interagir com o aplicativo e a quantidade de dados a processar.

Para identificar oportunidades de economia, considere como o custo depende do número de tokens e do preço por token. A partir dessa relação, você pode reduzir os custos de duas maneiras. A primeira é diminuir o custo por token usando modelos menores para algumas tarefas. A segunda é reduzir a quantidade de tokens necessários. Para isso, você pode usar prompts mais curtos, fazer o ajuste fino dos modelos ou armazenar em cache consultas frequentes dos usuários para evitar processá-las repetidamente.

Experimente nossa ferramenta interativa de tokenização para estimar custos. Tanto a API quanto o Playground incluem a contagem de tokens na resposta. Depois que seu aplicativo estiver funcionando com nosso modelo mais capaz, verifique se outros modelos conseguem produzir os mesmos resultados com menor latência e custo. Saiba mais no nosso artigo de ajuda sobre o uso de tokens.

Estratégia de MLOps

Ao levar seu protótipo para produção, considere desenvolver uma estratégia de MLOps. MLOps (operações de aprendizado de máquina) é a prática de gerenciar todo o ciclo de vida dos modelos de aprendizado de máquina, inclusive daqueles cujo ajuste fino você faz com nossa API. Ao elaborar sua estratégia de MLOps, considere os seguintes aspectos:

• Gestão de dados e modelos: gerencie os dados usados no treinamento ou no ajuste fino do modelo e acompanhe as versões e alterações.
• Monitoramento do modelo: acompanhe o desempenho do modelo ao longo do tempo para detectar possíveis problemas ou quedas de desempenho.
• Retreinamento do modelo: mantenha o modelo atualizado conforme os dados ou os requisitos mudam. Repita o treinamento ou o ajuste fino conforme necessário.
• Implantação do modelo: automatize a implantação do modelo e dos artefatos associados no ambiente de produção.

Considerar esses aspectos do aplicativo ajuda a manter o modelo relevante e com bom desempenho ao longo do tempo.

Segurança e conformidade

Ao levar seu protótipo para produção, você precisará identificar e atender aos requisitos de segurança e conformidade aplicáveis ao seu aplicativo. Isso envolve examinar os dados com os quais você trabalha, entender como nossa API os processa e determinar quais normas você deve seguir. Nossa documentação mais completa e atualizada está disponível nas práticas de segurança e no portal de confiança e conformidade. Consulte também nossa política de privacidade e nossos Termos de Uso.

Considere, entre outros aspectos, o armazenamento, a transmissão e a retenção dos dados. Também pode ser necessário adotar medidas de proteção da privacidade dos dados, como criptografia ou anonimização, quando possível. Além disso, siga boas práticas de programação segura, como a sanitização dos dados de entrada e o tratamento adequado de erros.

Boas práticas para o uso seguro

Ao criar seu aplicativo com nossa API, considere nossas boas práticas para o uso seguro para que o aplicativo seja seguro e bem-sucedido. Essas recomendações destacam a importância de testar o produto em profundidade, antecipar e tratar possíveis problemas e reduzir as oportunidades de uso indevido.

Considerações de negócio

Ao levar projetos de IA do protótipo à produção, considere como criar um ótimo produto com IA e como esse produto se relaciona com a atividade principal da sua empresa. Ainda não temos todas as respostas, mas um bom ponto de partida é a palestra do Developer Day em que exploramos essas questões com alguns dos nossos clientes: