Limites de taxa e gastos com o Terraform

Use este guia para gerenciar um limite de taxa existente em um projeto e criar um alerta de gastos mensais. Os limites de taxa restringem o uso dos modelos pelo projeto em determinado período. Os alertas de gastos notificam sua equipe quando os gastos mensais atingem um valor definido, mas não interrompem as solicitações à API nem impõem um teto de gastos.

Ao concluir o fluxo de trabalho principal, você terá uma configuração reutilizável que:

• Consulta os registros de limites de taxa disponíveis para um projeto existente.
• Gerencia os limites de solicitações e de tokens de um modelo.
• Envia um alerta por e-mail quando os gastos mensais do projeto atingem o valor definido.

Antes de começar

Conclua a configuração do provedor do Terraform e exporte uma chave da API de administração na variável de ambiente OPENAI_ADMIN_KEY. Você também precisa dos seguintes itens:

• O ID de um projeto existente.
• Pelo menos um endereço de e-mail para receber os alertas de gastos.

Use um projeto de teste para avaliar o fluxo de trabalho. Na próxima seção, você vai identificar o registro de limite de taxa de um modelo de texto. A OpenAI cria os registros de limites de taxa disponíveis para o projeto. O Terraform atualiza esses registros, sem criar novos.

Consultar os limites de taxa do projeto

Consulte os registros de limites de taxa disponíveis para o projeto:

1234567data "openai_project_rate_limits" "current" {
  project_id = "proj_123"
}

output "project_rate_limits" {
  value = data.openai_project_rate_limits.current.rate_limits
}

A fonte de dados faz uma solicitação somente leitura:

• project_id seleciona o projeto a consultar.
• rate_limits contém um objeto para cada limite de taxa disponível por modelo, com os campos id e model e os valores dos limites aplicáveis.
• A saída exibe os registros após a execução de terraform plan ou terraform apply.

Use o registro cujo campo model corresponde ao modelo que você quer controlar. Copie o id desse registro. O próximo recurso usa esse valor como rate_limit_id. Informe o ID explicitamente para evitar que uma alteração no provedor ou na API leve à seleção de outro registro.

Gerenciar um limite de taxa existente

Configure os limites de solicitações e de tokens no registro selecionado para o modelo de texto:

123456resource "openai_project_rate_limit" "application" {
  project_id                = "proj_123"
  rate_limit_id             = "rl-gpt-3.5-turbo"
  max_requests_per_1_minute = 500
  max_tokens_per_1_minute   = 200000
}

Cada argumento tem uma função específica:

• project_id identifica o projeto cujo limite de taxa será alterado.
• rate_limit_id identifica um registro existente de limite de taxa de um modelo. Esse valor é diferente do ID do modelo.
• max_requests_per_1_minute limita o número de solicitações que o projeto pode enviar ao modelo por minuto.
• max_tokens_per_1_minute limita o número de tokens que o projeto pode processar com o modelo por minuto.

Defina apenas os campos aplicáveis ao registro selecionado. Outros tipos de registro podem disponibilizar limites para imagens por minuto, megabytes de áudio por minuto, solicitações por dia ou tokens de entrada do Batch por dia. O valor configurado não pode exceder o limite disponível para a organização e o projeto.

Embora o primeiro plano do Terraform indique que esse recurso será adicionado, o provedor atualiza o registro de limite de taxa existente e depois o armazena no estado do Terraform. Quando você altera um limite configurado, o provedor envia outra atualização.

Configurar um alerta de gastos do projeto

Crie um alerta de gastos mensais para o projeto:

123456789resource "openai_project_spend_alert" "monthly" {
  project_id                          = "proj_123"
  threshold_amount                    = 20000
  currency                            = "USD"
  interval                            = "month"
  notification_channel_type           = "email"
  notification_channel_recipients     = ["platform-alerts@example.com"]
  notification_channel_subject_prefix = "OpenAI project spend"
}

A configuração do alerta define a condição de gastos que aciona a notificação e o canal de envio:

• project_id restringe o alerta aos gastos de um único projeto.
• threshold_amount define, em centavos, o valor de gastos mensais que aciona o alerta. 20000 equivale a US$ 200.
• currency deve ser USD.
• interval deve ser month.
• notification_channel_type deve ser email.
• notification_channel_recipients deve conter pelo menos um destinatário.
• notification_channel_subject_prefix é um texto opcional acrescentado ao início do assunto dos e-mails de alerta.

O Terraform cria o alerta e armazena o alert_id gerado. Quando você altera o valor que aciona o alerta ou os campos de notificação, o Terraform atualiza o alerta. Remover o recurso exclui o alerta remoto.

Os alertas de gastos apenas enviam notificações, sem impor um teto de gastos. Defina uma resposta a incidentes ou uma ação administrativa para cada valor de alerta e use os limites de taxa para controlar o volume de solicitações de forma independente.

Configurar um alerta de gastos da organização

Use um alerta da organização quando o valor que aciona a notificação se aplicar aos gastos de toda a organização:

1234567resource "openai_organization_spend_alert" "monthly" {
  threshold_amount                = 100000
  currency                        = "USD"
  interval                        = "month"
  notification_channel_type       = "email"
  notification_channel_recipients = ["platform-alerts@example.com"]
}

Esse recurso usa a mesma unidade para o valor de alerta, o mesmo intervalo, a mesma moeda e os mesmos campos de notificação que um alerta de projeto. Como contabiliza os gastos de toda a organização, ele não aceita o argumento project_id. Neste exemplo, o alerta envia um e-mail quando os gastos mensais da organização atingem US$ 1.000.

Você pode gerenciar os alertas do projeto e da organização em conjunto. Use valores de alerta e destinatários distintos quando equipes diferentes forem responsáveis pela resposta em cada escopo.

Executar o exemplo completo

Os exemplos anteriores usam valores concretos para explicar cada recurso. A configuração completa substitui os valores específicos do ambiente por variáveis e reúne a consulta aos limites de taxa do projeto, o gerenciamento de um desses limites e a criação de um alerta de gastos do projeto.

Salve a configuração a seguir como main.tf:

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = ">= 1.0.0"
    }
  }
}

provider "openai" {}

variable "project_id" {
  type = string
}

variable "rate_limit_id" {
  type        = string
  description = "Existing rate-limit record for the text model to manage."
}

variable "max_requests_per_minute" {
  type = number
}

variable "max_tokens_per_minute" {
  type = number
}

variable "project_spend_threshold_cents" {
  type        = number
  description = "Monthly project spend threshold in cents."

  validation {
    condition     = var.project_spend_threshold_cents > 0
    error_message = "The project spend threshold must be greater than zero."
  }
}

variable "alert_recipients" {
  type = list(string)

  validation {
    condition     = length(var.alert_recipients) > 0
    error_message = "Provide at least one spend-alert recipient."
  }
}

data "openai_project_rate_limits" "current" {
  project_id = var.project_id
}

resource "openai_project_rate_limit" "application" {
  project_id                = var.project_id
  rate_limit_id             = var.rate_limit_id
  max_requests_per_1_minute = var.max_requests_per_minute
  max_tokens_per_1_minute   = var.max_tokens_per_minute
}

resource "openai_project_spend_alert" "monthly" {
  project_id                          = var.project_id
  threshold_amount                    = var.project_spend_threshold_cents
  currency                            = "USD"
  interval                            = "month"
  notification_channel_type           = "email"
  notification_channel_recipients     = var.alert_recipients
  notification_channel_subject_prefix = "OpenAI project spend"
}

output "available_rate_limits" {
  value = data.openai_project_rate_limits.current.rate_limits
}

output "managed_rate_limit_model" {
  value = openai_project_rate_limit.application.model
}

output "project_spend_alert_id" {
  value = openai_project_spend_alert.monthly.alert_id
}

Crie o arquivo terraform.tfvars com o ID de um projeto existente, o ID do registro de limite de taxa que você identificou para um modelo de texto, os limites aprovados, o valor de alerta em centavos e os destinatários da notificação:

12345678project_id    = "proj_123"
rate_limit_id = "rl-gpt-3.5-turbo"

max_requests_per_minute = 500
max_tokens_per_minute   = 200000

project_spend_threshold_cents = 20000
alert_recipients               = ["platform-alerts@example.com"]

Escolha valores de solicitações e de tokens que não excedam os limites disponíveis no momento para o projeto. A saída available_rate_limits do plano mostra os registros e valores atuais para comparação.

Inicialize o Terraform e, em seguida, revise e aplique o plano salvo:

123456terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

O primeiro plano deve indicar a adição de dois recursos. O Terraform indica que o recurso de limite de taxa será adicionado ao estado, mas, ao aplicar o plano, ele atualiza o registro de limite de taxa existente na OpenAI. A outra adição cria o alerta de gastos do projeto. Depois que o plano for aplicado, terraform output exibirá os limites de taxa disponíveis, o modelo associado ao registro gerenciado e o ID do alerta.

Execute terraform plan novamente para confirmar que a configuração não gera outras alterações. Se o plano indicar divergências, verifique se outro administrador ou alguma automação alterou o limite de taxa ou o alerta de gastos antes de aplicar uma nova atualização.