Controle de solicitações e gastos do AI Gateway

Introdução

Uma aplicação de IA precisa de dois tipos diferentes de proteção contra tráfego. Um limite de taxa conta as solicitações em uma janela de tempo e interrompe um pico repentino antes que ele alcance o modelo. Um limite de gastos acompanha o custo estimado do modelo durante uma janela mais longa e protege um orçamento. Um controla com que frequência os clientes podem enviar trabalho; o outro controla quanto esse trabalho pode custar.

Você criará um AI Gateway autenticado e descartável. Ele permitirá apenas duas solicitações em uma janela deslizante curta, para que três solicitações pequenas demonstrem uma resposta 429 Too Many Requests sem gerar tráfego desnecessário para o modelo. Depois que a janela for liberada, você comprovará que a inferência normal voltou a funcionar. Você também adicionará uma regra de gastos diários de cinco dólares com escopo para o Workers AI e para o modelo selecionado. Em vez de gastar dinheiro para esgotar o limite, você lerá a regra armazenada.

Se você entrou diretamente neste curso, primeiro conclua Conectar o LabEx à sua conta da Cloudflare. Esse laboratório apresenta o terminal do LabEx, a autorização de dispositivo do Wrangler e o ID da conta. Conclua também Rotear a inferência por um gateway antes deste laboratório, pois ele reutiliza os limites separados de gateway e autorização upstream.

O laboratório usa o modelo hospedado pela Cloudflare @cf/meta/llama-3.3-70b-instruct-fp8-fast com o faturamento Standard do Workers AI. Workers Paid, Unified Billing e credenciais de provedores externos não são necessários. Apenas três solicitações pequenas devem chegar ao modelo. Pare, em vez de tentar novamente repetidamente, se a alocação diária compartilhada do Workers AI não estiver disponível.

A configuração instala o Node.js 22.22.0 e o Wrangler 4.132.0 local do projeto em /home/labex/project/ai-gateway-limits. Ela prepara verificações independentes somente de leitura, mas não autoriza o Wrangler, não cria um gateway, não cria um token nem envia tráfego ao modelo. O LabEx destrói a VM após o laboratório; ainda assim, você excluirá o gateway e o token na nuvem, porque destruir uma VM não remove recursos remotos.

Autorize a VM e dê nome ao experimento

Nesta etapa, você conectará a VM recém-criada à sua conta de aprendizagem e registrará nomes exclusivos para os recursos que pertencem a você.

Cada laboratório do LabEx começa em uma VM nova. Autorizar esta VM permite que o Wrangler chame o Workers AI na sua conta de aprendizagem; isso ainda não cria um gateway.

Entre no projeto preparado, confirme a CLI fixada e inicie a autorização do dispositivo:

cd /home/labex/project/ai-gateway-limits
npx wrangler --version
npx wrangler login --device --browser=false --scopes account:read user:read ai:write

Abra o link exibido, informe o código e autorize a conta de aprendizagem pretendida. Em seguida, consulte os dados estruturados de identidade:

npx wrangler whoami --json

Espere ver o Wrangler 4.132.0 e loggedIn: true. Substitua YOUR_ACCOUNT_ID pelo ID real de 32 caracteres exibido para a conta pretendida:

GATEWAY_ID="labex-c09-g04-$(openssl rand -hex 6)"
TOKEN_NAME="$GATEWAY_ID-token"
cat > .labex/state.json <<JSON
{
  "accountId": "YOUR_ACCOUNT_ID",
  "gatewayId": "$GATEWAY_ID",
  "tokenName": "$TOKEN_NAME"
}
JSON
cat .labex/state.json

Esses identificadores não são segredos. Salvá-los faz com que todas as consultas e ações de limpeza posteriores tenham como alvo apenas os recursos descartáveis deste laboratório.

Crie um gateway com um limite curto de solicitações

Nesta etapa, você configurará um contador de solicitações em todo o gateway que poderá demonstrar a proteção contra picos com segurança.

Um limite de taxa de solicitações é um contador dentro de uma janela de tempo. Este laboratório usa uma janela deslizante: a qualquer momento, o AI Gateway consulta os 20 segundos anteriores. Depois de duas solicitações nesse intervalo, outra solicitação será rejeitada com HTTP 429 antes de chegar ao Workers AI.

Abra o Cloudflare Dashboard e escolha AI → AI Gateway → Create a custom gateway. Use o gatewayId salvo. Mantenha Collect Logs e Authenticated Gateway ativados. Ative Rate Limit Requests, escolha Change e defina:

limite: 2 solicitações;
intervalo: 20 segundos;
técnica: sliding.

Mantenha o cache e as novas tentativas desativados. Mantenha o faturamento do Workers AI em Standard e crie o gateway. Criar primeiro a política de solicitações fornece um recurso estável antes de você adicionar a política de custos separada.

Adicione um limite de gastos com escopo e leia-o novamente

Nesta etapa, você adicionará um orçamento de custos ao mesmo gateway e limitará exatamente quais solicitações pertencem a ele.

Um limite de gastos é um orçamento, não um contador de solicitações. O AI Gateway estima o custo de cada solicitação concluída com base no preço e no uso do modelo e depois o adiciona às regras correspondentes. Essa estimativa é eventualmente consistente, portanto o tráfego simultâneo pode exceder brevemente um orçamento. A limitação de taxa continua sendo útil mesmo quando existe uma regra de gastos.

Abra a guia Settings do novo gateway. Ative Spend Limits, escolha Add rule e configure uma regra:

limite de custo: $5;
janela: 1 day;
técnica: Sliding;
filtro de provedor: workers-ai;
filtro de modelo: meta/llama-3.3-70b-instruct-fp8-fast.

Salve a regra e revise os dois controles. O campo do modelo usa o formato author/model porque o provedor já foi selecionado separadamente; a URL de inferência posterior ainda usará o nome completo do Workers AI, começando com @cf/.

As configurações do gateway mostram um limite deslizante de duas solicitações e uma regra de limite de gastos ativada

Os filtros de provedor e modelo tornam esta uma regra específica, em vez de um orçamento compartilhado para tráfego não relacionado do gateway. Cinco dólares é um valor deliberadamente alto para este pequeno exercício: você verificará a política sem tentar esgotá-la.

Abra My Profile → API Tokens, escolha Create Token → Create Custom Token e use o tokenName salvo. Adicione duas permissões de conta, AI Gateway — Edit e AI Gateway — Run, e inclua somente a conta de aprendizagem pretendida. Edit permite que o laboratório leia e exclua posteriormente o gateway exato; Run autentica o tráfego de inferência. O Wrangler fornece a credencial upstream separada do Workers AI.

Depois de revisar o resumo, crie o token. A Cloudflare o exibirá uma vez dentro de um comando de verificação. Copie somente o valor do token depois de Bearer, não o comando curl ao redor, e armazene-o usando entrada oculta:

bash -c '
while :; do
  read -ersp "Paste the AI Gateway token: " GATEWAY_TOKEN
  printf "\n"
  [ -n "$GATEWAY_TOKEN" ] && break
  printf "Token cannot be empty; paste it again.\n" >&2
done
umask 077
printf "%s" "$GATEWAY_TOKEN" > .labex/gateway-token
unset GATEWAY_TOKEN
chmod 600 .labex/gateway-token
'

Leia novamente os campos importantes que não são secretos por meio da API de gerenciamento:

ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID" \
  > .labex/gateway.json
unset GATEWAY_TOKEN
node - <<'NODE'
const b=require('./.labex/gateway.json'), g=b.result||{}, spend=g.spend_limits||{};
console.log(JSON.stringify({
  success:b.success,
  id:g.id,
  rate:{limit:g.rate_limiting_limit,interval:g.rate_limiting_interval,technique:g.rate_limiting_technique},
  spend_limits:{enabled:spend.enabled,rules:spend.rules}
},null,2));
NODE

Espere ver uma regra de taxa deslizante de duas solicitações em 20 segundos e uma regra de custo diário de cinco dólares ativada, com os filtros de provedor e modelo. Essa leitura comprova a configuração; ela não afirma que o orçamento foi consumido.

Observe a rejeição de solicitações com três chamadas

Nesta etapa, você usará três solicitações pequenas para observar a política de contagem de solicitações sem criar um pico grande de tráfego.

Agora você enviará três solicitações pequenas em sequência. As duas primeiras serão permitidas. A terceira deverá receber 429 e nunca chegar ao modelo. Isso é mais seguro e barato do que gerar um grande pico de tráfego.

Salve privadamente o token de curta duração do Wrangler desta VM para autorizar o Workers AI upstream:

umask 077
npx wrangler auth token --json \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s).token))' \
  > .labex/upstream-token
chmod 600 .labex/upstream-token

Envie as três chamadas. Cada uma inclui metadados sintéticos para que as solicitações sejam fáceis de identificar nos logs; a própria regra de gastos corresponde a elas por meio dos filtros de provedor e modelo do Workers AI:

ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
MODEL='@cf/meta/llama-3.3-70b-instruct-fp8-fast'
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
for NUMBER in 1 2 3; do
  METADATA=$(printf '{"lab":"g04-limits","request":"burst-%s","synthetic":true}' "$NUMBER")
  STATUS=$(curl --http1.1 -sS \
    -o ".labex/burst-$NUMBER-response.json" -w '%{http_code}' \
    -H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
    -H "Authorization: Bearer $UPSTREAM_TOKEN" \
    -H "cf-aig-metadata: $METADATA" \
    -H 'Content-Type: application/json' \
    --data "{\"prompt\":\"Reply with the number $NUMBER.\",\"max_tokens\":4}" \
    "https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
  printf '%s\n' "$STATUS" | tee ".labex/burst-$NUMBER-status.txt"
done
unset GATEWAY_TOKEN UPSTREAM_TOKEN METADATA

Espere:

200
200
429

O 429 é um resultado de proteção bem-sucedido. Isso significa que a solicitação foi interrompida no gateway, portanto não consumiu outra inferência do modelo nem avançou o contador de gastos.

Aguarde a recuperação da janela deslizante

Nesta etapa, você aguardará a limpeza da janela curta e comprovará que o gateway permite novamente a inferência normal.

Um limite de taxa deve proteger contra picos sem desativar permanentemente a aplicação. Aguarde um pouco mais do que a janela de 20 segundos e envie outra solicitação pequena:

sleep 22
ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
MODEL='@cf/meta/llama-3.3-70b-instruct-fp8-fast'
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
STATUS=$(curl --http1.1 -sS \
  -o .labex/recovery-response.json -w '%{http_code}' \
  -H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
  -H "Authorization: Bearer $UPSTREAM_TOKEN" \
  -H 'cf-aig-metadata: {"lab":"g04-limits","request":"recovery","synthetic":true}' \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"Reply only with recovered.","max_tokens":4}' \
  "https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset GATEWAY_TOKEN UPSTREAM_TOKEN
printf '%s\n' "$STATUS" | tee .labex/recovery-status.txt
node -e 'const b=require("./.labex/recovery-response.json"); console.log(b.result?.response ?? b.result)'

Espere HTTP 200 e uma resposta curta gerada. A recuperação comprova que o 429 veio da janela de tempo configurada, e não de credenciais inválidas ou de um modelo com problema.

Relacione a política às evidências do Dashboard

Nesta etapa, você relacionará os resultados da API e do HTTP aos controles e logs visíveis no Dashboard.

Volte para AI → AI Gateway, selecione o gateway salvo e abra Settings. Confirme que o limite de taxa ainda mostra duas solicitações, 20 segundos e aplicação deslizante. Em Spend Limits, inspecione a única regra e verifique o custo de cinco dólares, a janela deslizante de um dia e os filtros de provedor e modelo.

O gateway selecionado exibe os controles de taxa e de gastos com escopo salvos

Em seguida, abra Logs. As duas solicitações iniciais bem-sucedidas e a solicitação recuperada deverão aparecer após a propagação normal dos logs. A terceira solicitação rejeitada pode ser representada de outra forma porque foi interrompida antes da inferência no provedor; o status HTTP salvo é a evidência autoritativa do limite de taxa.

Os logs do gateway mostram apenas as pequenas chamadas permitidas ao Workers AI durante o teste do limite de taxa

Observe o que não é necessário: você não precisa gastar cinco dólares, reduzir a regra para um valor perigosamente pequeno nem repetir chamadas até que uma rejeição por custo apareça. A leitura da API de gerenciamento comprova o escopo da política de gastos, enquanto o experimento com três chamadas comprova separadamente a aplicação do limite de solicitações.

Exclua o gateway descartável

Nesta etapa, você removerá somente o gateway nomeado no inventário do laboratório e comprovará sua ausência enquanto a autorização continua disponível.

Exclua o gateway enquanto o token de gerenciamento ainda puder comprovar que o recurso exato foi removido:

ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS -X DELETE \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID" \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const b=JSON.parse(s);if(!b.success)process.exit(1);console.log("gateway deletion accepted")})'
unset GATEWAY_TOKEN

GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways" \
  > .labex/gateways-after-delete.json
unset GATEWAY_TOKEN
node -e 'const b=require("./.labex/gateways-after-delete.json"),id=process.argv[1],found=(b.result||[]).some(g=>g.id===id);console.log("gateway absent:",!found);if(found)process.exit(1)' "$GATEWAY_ID"

Espere gateway absent: true. Um inventário autenticado diferencia uma exclusão real de uma falha de rede ou de uma página à qual você não consegue mais acessar.

Revogue o token e saia

Nesta etapa, você revogará o token restante do Dashboard, apagará as duas cópias na VM e desconectará o Wrangler.

No Cloudflare Dashboard, abra My Profile → API Tokens. Encontre o tokenName salvo exato, abra Actions, escolha Delete, revise a confirmação e exclua somente esse token. Agora é seguro revogá-lo porque a exclusão do gateway já foi comprovada.

Apague as duas cópias temporárias do token e desconecte o Wrangler:

shred -u .labex/gateway-token .labex/upstream-token
npx wrangler logout
npx wrangler whoami --json || true
test ! -e .labex/gateway-token -a ! -e .labex/upstream-token \
  && echo "local token files removed"

Espere loggedIn: false e local token files removed. A sessão do Dashboard é separada e continuará conectada. O LabEx destrói esta VM temporária quando o laboratório termina, em vez de preservá-la.

Resumo

Você aplicou dois controles complementares do AI Gateway. Uma janela deslizante de duas solicitações rejeitou a terceira solicitação de baixo volume com HTTP 429 e depois permitiu automaticamente o tráfego quando a janela foi liberada. Uma regra de gastos diários separada, de cinco dólares, foi limitada ao Workers AI e a um modelo, e sua configuração armazenada foi verificada sem desperdiçar uso do modelo.

O próximo laboratório usa outro controle de confiabilidade do gateway: um fallback limitado. Você encaminhará uma falha controlada do modelo principal para um segundo modelo compatível, enquanto uma solicitação saudável ao modelo principal será concluída na primeira etapa.

Controle de solicitações e limites de gastos