Governar o acesso a múltiplos modelos de IA

Coloque uma function de gateway na frente do AI Inference e de um provedor de terceiros para autenticar equipes, rotear, fazer fallback, usar cache e registrar.

Última atualização

Ver como Markdown Configurar agente

Uma equipe de plataforma apoia equipes de produto que chamam modelos de IA de vários provedores e do AI Inference. Cada equipe guarda as suas próprias chaves de provedor e o seu próprio código de fallback, então ninguém consegue rotear uma requisição para outro modelo quando um provedor falha, parar uma equipe que gasta além do seu orçamento ou dizer qual modelo respondeu a uma requisição. Esta página coloca um gateway criado com Functions na frente de todos os modelos. As aplicações chamam um único endpoint com uma chave de equipe, e o gateway autentica a equipe, escolhe um modelo por política, faz fallback para o próximo modelo quando uma chamada falha, armazena em cache as respostas que quem chama permite e registra cada chamada. O resultado é medido pelas requisições respondidas apesar de uma falha de provedor, pelo gasto por equipe dentro do orçamento, pela parcela de requisições respondidas a partir do cache e pela cobertura de auditoria das chamadas de modelo.

Este caso de uso não cobre a criação das aplicações ou dos agentes que chamam os modelos. Para isso, consulte Criar agentes de IA.

Pré-requisitos

  • Uma aplicação e um workload que servem o domínio do gateway, com o Application Accelerator ativado, que o behavior Run Function exige. Para criá-los, consulte Primeiros passos com Applications.
  • KV Store habilitado na conta. O produto está em Preview e não vem habilitado por padrão, então solicite acesso pelo Technical Support.
  • Um personal token, para a chamada ao KV Store. Para criar um, consulte Gerencie personal tokens.
  • A Azion CLI, instalada e autorizada, para armazenar as variáveis de ambiente.
  • Um provedor de terceiros cujo endpoint de chat aceite o formato de chat completions da OpenAI, com a URL dele, um nome de modelo e uma API key.
  • Um endpoint HTTPS da sua plataforma de analytics ou de logs que aceite requisições POST, para os logs de uso e de auditoria.
  • Os valores da sua própria configuração. Esta página usa ai-gateway para o namespace do KV Store, a function e o cache, general e long-context para os dois aliases de modelo que o gateway oferece, checkout-team para uma equipe e gateway.example.com para o domínio. Substitua cada valor pelo seu em todas as etapas.

Produtos necessários

O gateway precisa deO que significaProdutoDocumentado em
Um endpoint que guarda a lógica de roteamento, de fallback e de autenticaçãoUma function na aplicação do gateway, executada em todos os caminhos por uma regraFunctionsPrimeiros passos com Functions
Modelos hospedados na plataforma entre as rotasAzion.AI.run com um id de modelo do catálogo de modelos do AI InferenceAI InferenceChame um modelo no AI Inference a partir de uma function
Chaves das equipes, os modelos que cada equipe pode chamar e se uma equipe ainda está dentro do orçamentoUm registro por equipe, lido pela key a cada requisiçãoKV StoreKV Store API
Prompts repetidos respondidos sem chamada ao modelo, onde quem chama permiteRespostas armazenadas e encontradas com a Cache APICacheArmazene em cache a resposta de uma function com a Cache API
Um registro de uso e de auditoria de cada chamada de modeloUma linha de log por chamada, enviada da fonte de dados FunctionsData StreamEnvie logs para um endpoint HTTP
Uma requisição investigada depois do fatoAs linhas de log da function para essa requisiçãoReal-Time EventsFontes de dados do Real-Time Events
Uma regra que executa a functionO behavior Run Function, que exige o Application Accelerator na aplicaçãoApplication AcceleratorComo Functions funciona

Arquitetura de referência

Esta página constrói o Multi-model AI gateway: uma function na frente de todos os modelos, com a política, as chaves e o log em um único lugar.

Leia o diagrama a partir da function. Cada chamada de modelo passa por ela, então ela é o único lugar em que uma equipe é identificada, um modelo é escolhido e uma chamada é registrada. As setas para os modelos são ordenadas: a política indica uma primeira rota e as rotas depois dela, e a function passa para a próxima apenas quando uma chamada falha. As setas para o KV Store e a Cache API são leituras que vêm antes de qualquer chamada de modelo, então uma equipe recusada ou uma resposta armazenada não custa nenhuma chamada de modelo.

Fluxo de dados

  1. Uma aplicação de equipe envia uma requisição compatível com a OpenAI para /v1/chat/completions, com a sua chave de equipe como bearer token e um alias de modelo em model, em vez de um id de modelo.
  2. O gateway calcula o hash da chave e lê o registro da equipe no KV Store. Uma chave desconhecida responde 401, uma equipe acima do orçamento responde 429, e um alias que a equipe não pode chamar responde 403.
  3. Quando quem chama permite cache, o gateway procura a requisição no cache e retorna uma resposta armazenada quando há correspondência.
  4. Caso contrário, o gateway chama as rotas do alias em ordem: primeiro um modelo do AI Inference, depois o provedor de terceiros quando a primeira chamada falha.
  5. O gateway grava uma linha de log com a equipe, o alias, o modelo que respondeu, se houve fallback, o resultado do cache e os tokens usados. O Data Stream a envia para a sua plataforma de analytics, e o Real-Time Events guarda as linhas de cada requisição para investigação.
  6. O gateway retorna a resposta do modelo e a armazena no cache quando quem chama permitiu.

Componentes

  • Functions: executa a autenticação, o roteamento e o fallback. A política é código na function ai-gateway, então uma mudança em uma rota chega a todas as equipes de uma vez, e nenhuma equipe guarda uma chave de provedor ou uma lógica de fallback própria.
  • AI Inference: executa os modelos hospedados na plataforma, chamados com Azion.AI.run e um id de modelo. Uma chamada a ele fica dentro da Azion e não precisa de chave de provedor.
  • provedores de LLM de terceiros: as integrações que executam modelos externos. A function os chama com chaves que lê de variáveis de ambiente, então a latência e as falhas deles entram apenas nas rotas que os indicam.
  • Cache: guarda respostas a prompts repetidos, pela Cache API da function. Uma resposta armazenada é retornada sem chamada de modelo, apenas para requisições cujo chamador permite.
  • KV Store: guarda as chaves, as cotas e os orçamentos: um registro por equipe no namespace ai-gateway, com a key formada por um hash da chave da equipe, com os modelos que a equipe pode chamar e se ela está dentro do orçamento. A function o lê a cada requisição.
  • Data Stream: envia as linhas de log de uso e de auditoria que a function grava, da fonte de dados Functions, para a sua plataforma de analytics, onde o gasto por equipe é somado.
  • Real-Time Events: guarda as linhas de log da function agrupadas por requisição, para investigar uma chamada depois do fato.
  • aplicação: o Platform Resource que é o endpoint do gateway. Uma regra executa a function nos caminhos dela, então todas as aplicações apontam para um único domínio.

Configure a function de gateway

O gateway é uma única function. Cada decisão que ele aplica está no código, então uma mudança de política é uma mudança de código que todas as equipes recebem de uma vez.

  • As equipes enviam um alias, não um id de modelo. general roteia para Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 no AI Inference, e long-context para gpt-oss-20b, cuja janela de contexto de 131k tokens é a mais longa entre os modelos que o AI Inference executa. Os dois fazem fallback para o provedor. Um alias permite que a equipe de plataforma mude o modelo por trás dele sem mudança no código de nenhuma equipe. O gateway chama uma rota do AI Inference como Chame um modelo no AI Inference a partir de uma function descreve, com estes valores: o id de modelo da rota e o body da requisição da equipe com stream definido como false.
  • A chave é armazenada como hash. A key do registro é team: seguida do SHA-256 da chave da equipe, então o KV Store nunca guarda uma chave utilizável. SHA-256 é um dos digests que crypto.subtle.digest suporta.
  • Uma chamada que falha passa para a próxima rota. Uma chamada que lança uma exceção, não retorna choices, responde com um status de erro ou passa de 30 segundos conta como falha. Trinta segundos limitam o tempo que uma equipe espera em uma rota antes que a próxima seja executada, dentro do limite de 5 minutos de tempo de execução de uma function.
  • O cache é decisão de quem chama. O gateway armazena em cache apenas requisições que trazem x-gateway-cache: allow, porque só a equipe sabe se uma resposta pode valer para todo prompt idêntico. O gateway armazena em cache como Armazene em cache a resposta de uma function com a Cache API descreve, com o cache ai-gateway, a key https://ai-gateway.cache/<sha-256 of the alias and the request body> e max-age=3600, uma hora.
  • Cada chamada grava uma linha de log. A linha é o registro de uso e de auditoria: o gasto de uma equipe é a soma dos seus total_tokens, e a linha indica o modelo que respondeu.
  • O alias fallback-test comprova o fallback. A primeira rota dele indica um id de modelo que não existe, então toda chamada a ele faz fallback. Remova-o depois de Verifique a configuração.

Para armazenar os valores que a function lê, execute estes comandos com a Azion CLI. Uma key que contém key ou secret é armazenada como secret por padrão:

Shell
01azion create variables --key "PROVIDER_URL" --value "<provider-chat-completions-url>" --secret false
02azion create variables --key "PROVIDER_MODEL" --value "<provider-model-name>" --secret false
03azion create variables --key "PROVIDER_API_KEY" --value "<provider-api-key>"
04azion create variables --key "ADMIN_SECRET" --value "<admin-secret>"

Crie uma function chamada ai-gateway com este código. A chamada ao provedor envia a chave como Authorization: Bearer; mude esse header para o que o seu provedor exige:

JavaScript
01const ROUTES = {
02 "general": [
03 { kind: "azion", model: "Qwen/Qwen3-30B-A3B-Instruct-2507-FP8" },
04 { kind: "provider" }
05 ],
06 "long-context": [
07 { kind: "azion", model: "gpt-oss-20b" },
08 { kind: "provider" }
09 ],
10 "fallback-test": [
11 { kind: "azion", model: "no-such-model" },
12 { kind: "provider" }
13 ]
14};
15const PROVIDER_TIMEOUT_MS = 30000;
16const CACHE_SECONDS = 3600;
17
18async function sha256(text) {
19 const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
20 return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
21}
22
23async function callRoute(route, body) {
24 if (route.kind === "azion") {
25 const response = await Azion.AI.run(route.model, body);
26 if (!response?.choices?.length) throw new Error("no choices in the response");
27 return response;
28 }
29 const controller = new AbortController();
30 const timer = setTimeout(() => controller.abort(), PROVIDER_TIMEOUT_MS);
31 try {
32 const response = await fetch(Azion.env.get("PROVIDER_URL"), {
33 method: "POST",
34 headers: {
35 "Authorization": `Bearer ${Azion.env.get("PROVIDER_API_KEY")}`,
36 "Content-Type": "application/json"
37 },
38 body: JSON.stringify({ ...body, model: Azion.env.get("PROVIDER_MODEL") }),
39 signal: controller.signal
40 });
41 if (!response.ok) throw new Error(`provider answered ${response.status}`);
42 return await response.json();
43 } finally {
44 clearTimeout(timer);
45 }
46}
47
48async function putTeam(request, kv) {
49 if (request.method !== "PUT") {
50 return new Response("Method not allowed", { status: 405 });
51 }
52 if (request.headers.get("Authorization") !== `Bearer ${Azion.env.get("ADMIN_SECRET")}`) {
53 return new Response("Unauthorized", { status: 401 });
54 }
55 const { key, team, models, status } = await request.json();
56 if (!key || !team || !Array.isArray(models) || !["active", "blocked"].includes(status)) {
57 return Response.json({ error: "key, team, models, and status are required" }, { status: 400 });
58 }
59 await kv.put(`team:${await sha256(key)}`, { team, models, status });
60 return Response.json({ team, models, status });
61}
62
63export default {
64 async fetch(request, env, ctx) {
65 const url = new URL(request.url);
66 const kv = await Azion.KV.open("ai-gateway");
67 if (url.pathname === "/admin/teams") {
68 return putTeam(request, kv);
69 }
70 if (request.method !== "POST" || url.pathname !== "/v1/chat/completions") {
71 return new Response("Not found", { status: 404 });
72 }
73
74 const started = Date.now();
75 const auth = request.headers.get("Authorization") ?? "";
76 const teamKey = auth.startsWith("Bearer ") ? auth.slice(7) : "";
77 const team = teamKey ? await kv.get(`team:${await sha256(teamKey)}`, "json") : null;
78 if (!team) {
79 return Response.json({ error: "unknown team key" }, { status: 401 });
80 }
81 if (team.status !== "active") {
82 return Response.json({ error: "team budget reached" }, { status: 429 });
83 }
84
85 const { model: alias, ...body } = await request.json();
86 if (!ROUTES[alias] || !team.models.includes(alias)) {
87 return Response.json({ error: `model ${alias} is not allowed for ${team.team}` }, { status: 403 });
88 }
89 body.stream = false;
90
91 const cacheAllowed = request.headers.get("x-gateway-cache") === "allow";
92 const cache = await caches.open("ai-gateway");
93 const cacheKey = `https://ai-gateway.cache/${await sha256(JSON.stringify({ alias, body }))}`;
94 if (cacheAllowed) {
95 const hit = await cache.match(cacheKey);
96 if (hit) {
97 console.log(JSON.stringify({ event: "model_call", team: team.team, alias, route: null, ok: true, fallback: false, cache: "hit", total_tokens: 0, ms: Date.now() - started }));
98 return new Response(await hit.text(), {
99 headers: { "Content-Type": "application/json", "x-gateway-cache": "hit" }
100 });
101 }
102 }
103
104 let result = null;
105 let answered = null;
106 let attempts = 0;
107 for (const route of ROUTES[alias]) {
108 attempts++;
109 try {
110 result = await callRoute(route, body);
111 answered = route.model ?? "provider";
112 break;
113 } catch (error) {
114 console.log(JSON.stringify({ event: "route_failed", team: team.team, alias, route: route.model ?? "provider", error: String(error?.message ?? error) }));
115 }
116 }
117
118 console.log(JSON.stringify({
119 event: "model_call", team: team.team, alias, route: answered, ok: result !== null,
120 fallback: attempts > 1, cache: cacheAllowed ? "miss" : "off",
121 total_tokens: result?.usage?.total_tokens ?? 0, ms: Date.now() - started
122 }));
123 if (!result) {
124 return Response.json({ error: `every route of ${alias} failed` }, { status: 502 });
125 }
126
127 const text = JSON.stringify(result);
128 if (cacheAllowed) {
129 await cache.put(cacheKey, new Response(text, {
130 headers: { "Content-Type": "application/json", "cache-control": `max-age=${CACHE_SECONDS}` }
131 }));
132 }
133 return new Response(text, {
134 headers: { "Content-Type": "application/json", "x-gateway-route": answered }
135 });
136 },
137};

Execute a function com estes valores, seguindo Primeiros passos com Functions:

  • Instância da function: ai-gateway, sem Args.
  • Regra: uma regra de Request Phase chamada gateway - all paths, com o critério ${uri} starts with / e o behavior Run Function selecionando a instância ai-gateway.

O gateway responde em /v1/chat/completions e /admin/teams, e todos os outros caminhos respondem 404. A Cache API não é definida no azion dev, então teste a function depois do deploy.

Configure os registros das equipes

Um registro de equipe é um objeto JSON sob team:<sha256 of the team key> no namespace ai-gateway: o nome da equipe, os aliases que ela pode chamar e o seu status. O gateway lê o registro a cada requisição e admite uma requisição apenas enquanto status for active.

A aplicação do orçamento lê esse status em vez de contar cada chamada. O KV Store aceita uma gravação por segundo na mesma key e não oferece incremento atômico, então um contador gravado a cada requisição perderia atualizações sob tráfego concorrente. Em vez disso, o gasto é calculado na sua plataforma de analytics a partir dos total_tokens das linhas de log de cada equipe. Quando uma equipe chega ao seu orçamento, um operador define o status dela como blocked, e o gateway passa a responder 429 a essa equipe.

Para criar o namespace, envie o nome dele à API do KV Store:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/kv/namespaces \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"name": "ai-gateway"}'

A API responde 201 com o namespace. Um namespace não pode ser renomeado nem excluído, então confira o nome antes de enviá-lo:

JSON
01{
02 "name": "ai-gateway",
03 "created_at": "2026-01-01T12:00:00.000000",
04 "last_modified": "2026-01-01T12:00:00.000000"
05}

As keys são gravadas a partir de uma function, e não pela API, então o caminho /admin/teams do gateway grava cada registro. Para adicionar uma equipe que pode chamar general e fallback-test, gere uma chave de equipe aleatória e envie-a com o segredo de administração:

Shell
01curl -X PUT https://gateway.example.com/admin/teams \
02 -H 'Authorization: Bearer <admin-secret>' \
03 -H 'Content-Type: application/json' \
04 -d '{"key":"<checkout-team-key>","team":"checkout-team","models":["general","fallback-test"],"status":"active"}'

O gateway responde com o registro que armazenou, sem a chave:

{"team":"checkout-team","models":["general","fallback-test"],"status":"active"}

Entregue a chave da equipe à equipe uma única vez, porque o gateway guarda apenas o hash dela. Para bloquear a equipe, envie a mesma requisição com "status":"blocked", e com "status":"active" para admiti-la de novo.

Configure o stream de uso e de auditoria

Cada linha model_call é um registro de uso e de auditoria, e o Data Stream entrega as linhas da fonte de dados Functions para a sua plataforma de analytics, onde o gasto e os fallbacks são somados por equipe.

Crie o stream como Envie logs para um endpoint HTTP mostra, com estes valores:

  • Data Source: Functions. Na API, functions_console.
  • Template: Functions Event Collector, cuja variável $log_message carrega cada linha que a function grava.
  • Opção: Filter Workloads, com o workload do gateway como o único workload escolhido. Um filtro impede que este stream desative os outros streams da conta, o que salvar um stream ativo com amostragem faz.
  • Connector: Standard HTTP/HTTPS POST, com a URL da sua plataforma de analytics e o header que ela exige para aceitar a requisição.

O stream fica ativo de um a dois minutos depois de salvo. A sua plataforma de analytics passa a receber uma linha model_call por requisição e uma linha route_failed por rota que falhou.

Verifique a configuração

Cada verificação envia uma requisição de chat com a chave de equipe da etapa dos registros das equipes.

  • Uma equipe alcança um modelo por um alias. Envie uma requisição para general:

    Shell
    01curl -s -i -X POST https://gateway.example.com/v1/chat/completions \
    02 -H 'Authorization: Bearer <checkout-team-key>' \
    03 -H 'Content-Type: application/json' \
    04 -d '{"model":"general","max_tokens":200,"messages":[{"role":"user","content":"Name three European capitals."}]}'

    A resposta traz x-gateway-route: Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 e um objeto chat.completion cujo texto gerado fica em choices[0].message.content.

  • Uma rota que falha faz fallback. Envie a mesma requisição com "model":"fallback-test". A resposta traz x-gateway-route: provider, e as linhas de log dessa requisição guardam uma linha route_failed para no-such-model e depois uma linha model_call com "fallback":true.

  • Um prompt repetido que quem chama permite é respondido a partir do cache. Envie a requisição para general duas vezes com o header x-gateway-cache: allow. A segunda resposta traz x-gateway-cache: hit.

  • O gateway recusa o que a política recusa. Uma requisição sem o header Authorization responde 401. Uma requisição para long-context, que checkout-team não pode chamar, responde 403. Depois que você define o status da equipe como blocked, qualquer requisição com a chave dela responde 429.

  • Cada chamada é registrada. A sua plataforma de analytics recebe uma linha model_call para cada requisição acima, com "team":"checkout-team". Para ler as linhas de uma requisição, abra a fonte de dados Functions Console no Real-Time Events, onde a variável ID agrupa as linhas de uma única requisição.

Remova o alias fallback-test de ROUTES e do registro da equipe depois que a verificação de fallback passar. Uma regra nova leva alguns minutos para se propagar.

Medindo resultados

MétricaOnde lerComo é quando funciona
Requisições respondidas apesar de uma falha de provedorAs linhas model_call com "ok":true e "fallback":true, na sua plataforma de analyticsCada falha de rota em uma linha route_failed é seguida de um model_call bem-sucedido para a mesma requisição, a menos que todas as rotas tenham falhado
Gasto por equipe dentro do orçamentoA soma de total_tokens por team no período do orçamento, na sua plataforma de analyticsA soma de cada equipe fica abaixo do seu orçamento, e uma equipe que chega a ele tem status definido como blocked
Parcela de requisições respondidas a partir do cacheAs linhas model_call com "cache":"hit" sobre as linhas com "cache":"hit" ou "cache":"miss"Sobe para equipes que permitem cache em prompts que se repetem
Cobertura de auditoria das chamadas de modeloA contagem de linhas model_call contra as invocações do gateway na aba Functions do Real-Time Metrics, descontadas as chamadas a /admin/teams e as requisições recusadasAs duas contagens coincidem, então cada chamada de modelo tem um registro

Boas práticas

  • Dê a cada equipe a sua própria chave e faça a rotação dela substituindo o registro. A key do registro é o hash da chave da equipe, então uma nova chave é um novo registro. Defina o registro antigo como blocked assim que a equipe trocar, porque uma key do KV Store não pode ser listada e um registro esquecido continua legível.
  • Mantenha a chave do provedor em uma variável de ambiente. A function lê PROVIDER_API_KEY com Azion.env.get(), então a chave nunca aparece no código, e as equipes nunca a guardam. Uma variável alterada só chega à function depois de um novo deploy.
  • Deixe as equipes optarem pelo cache por requisição. Uma resposta em cache é retornada para todo prompt idêntico, qualquer que seja a equipe que o envia. Armazenar em cache um prompt cuja resposta precisa mudar, como um que pergunta sobre o estado atual de uma conta, retorna uma resposta desatualizada por uma hora.
  • Considere as leituras do KV Store na taxa de requisições do gateway. Cada requisição lê um registro de equipe, e o KV Store inclui 100.000 keys lidas por dia antes que uma cobrança se aplique. Para as quantidades incluídas e a tarifa acima delas, consulte Limites do KV Store.

Guias deste caso de uso

Armazene em cache a resposta de uma function com a Cache APIArmazena e encontra as respostas que quem chama permite que o gateway armazene em cache.Chame um modelo no AI Inference a partir de uma functionChama a primeira rota de um alias, um modelo no AI Inference, com Azion.AI.run.