Limites de taxa e gastos com Terraform

Use este guia para gerenciar um limite de taxa existente de um projeto e criar um alerta de gastos mensais. Os limites de taxa restringem o uso de modelos por um projeto ao longo do tempo. Os alertas de gastos notificam sua equipe quando o uso mensal atinge um limiar, 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:

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

Antes de começar

Conclua a configuração do provedor Terraform e exporte uma chave da API de administração como OPENAI_ADMIN_KEY. Você também precisa de:

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

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

Consulte os limites de taxa do projeto

Leia os registros de limites de taxa disponíveis para um 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 ser inspecionado.
• rate_limits contém um objeto para cada limite de taxa de modelo disponível, incluindo seus 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 corresponda ao modelo que você quer controlar. Copie seu id; o próximo recurso usa esse valor como rate_limit_id. Mantenha o ID como uma entrada explícita para evitar que uma alteração no provedor ou na API selecione outro registro.

Gerencie um limite de taxa existente

Gerencie os limites de solicitações e tokens do registro selecionado de 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 modelo. Não é um ID de modelo.
• max_requests_per_1_minute limita o número de solicitações que o projeto pode enviar para esse modelo a cada minuto.
• max_tokens_per_1_minute limita o número de tokens que o projeto pode processar para esse modelo a cada minuto.

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

Embora o primeiro plano do Terraform mostre esse recurso como uma adição, o provedor atualiza o registro de limite de taxa existente e depois o armazena no estado do Terraform. Alterar um limite configurado envia outra atualização.

Configure um alerta de gastos do projeto

Crie um alerta de gastos mensais do 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 definição do alerta combina a condição de gastos e o canal de notificação:

• project_id restringe o alerta aos gastos de um projeto.
• threshold_amount é o limiar mensal em centavos. 20000 representa USD 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 adicionado ao assunto dos e-mails de alerta.

O Terraform cria o alerta e armazena o alert_id gerado. Alterar o limiar ou os campos de notificação atualiza o alerta. Remover o recurso exclui o alerta remoto.

Os alertas de gastos são notificações, não limites rígidos. Defina uma resposta a incidentes ou uma ação administrativa para cada limiar e use os limites de taxa para restringir o volume de solicitações de forma independente.

Configure um alerta de gastos da organização

Use um alerta da organização quando o limiar precisar abranger os 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 as mesmas unidades de limiar, intervalo, moeda e campos de notificação de um alerta de projeto. Ele não recebe um project_id, pois mede os gastos de toda a organização. O exemplo envia um e-mail após os gastos mensais da organização atingirem USD 1.000.

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

Execute o exemplo completo

Os exemplos específicos 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 dos limites de taxa do projeto, um limite de taxa gerenciado e 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 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, um limiar em centavos e os destinatários do alerta:

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 tokens que não excedam os limites atualmente disponíveis para o projeto. A saída available_rate_limits no plano mostra os registros e valores atuais para comparação.

Inicialize o Terraform e depois revise e aplique um plano salvo:

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

O primeiro plano deve conter dois recursos a serem adicionados. O Terraform descreve o recurso de limite de taxa como uma adição ao estado, mas sua aplicação atualiza o registro de limite de taxa existente na OpenAI. A outra adição cria o alerta de gastos do projeto. Após a aplicação, terraform output exibe 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 mais alterações. Se o resultado mostrar divergências, verifique se outro administrador ou alguma automação alterou o limite de taxa ou o alerta de gastos antes de aplicar outra atualização.