Roteie chamadas de modelo por uma function de gateway

Você roteia as chamadas de modelo de várias equipes por uma function: ela lê o registro de cada equipe no KV Store, chama as rotas de um alias de modelo em ordem, primeiro um modelo no AI Inference e um provedor de terceiros quando ele falha, armazena em cache as respostas que quem chama permite e grava uma linha de log por chamada. Para chamar um único modelo a partir de uma function antes, consulte Chame um modelo no AI Inference a partir de uma function.

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.

A Cache API não é definida no azion dev, então teste a function depois do deploy.

Os exemplos usam 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-os pelos seus valores.

Crie o namespace

A function abre o namespace ai-gateway a cada requisição, então o namespace precisa existir antes que a function seja executada.

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}

A conta guarda o namespace ai-gateway, vazio.

O caso de uso Governar o acesso a múltiplos modelos de IA usa os valores deste exemplo.

Armazene os valores que a function lê

A chave do provedor e o segredo de administração ficam fora do código, como variáveis de ambiente.

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>"

A conta guarda as quatro variáveis que a function de gateway lê com Azion.env.get().

O caso de uso Governar o acesso a múltiplos modelos de IA usa os valores deste exemplo.

Crie a function de gateway

A function responde em /v1/chat/completions para as equipes e em /admin/teams para o operador, e todos os outros caminhos respondem 404. O alias fallback-test indica um id de modelo que não existe, então toda chamada a ele faz fallback para o provedor.

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;

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}

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}

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}

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 }

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 }

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;

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) {

        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};

Para criar a function e a sua instância, siga Primeiros passos com Functions com o nome ai-gateway e dê à instância o nome ai-gateway, sem Args.

A aplicação tem uma instância ai-gateway que autentica uma equipe, roteia a requisição dela por alias e registra a chamada.

O caso de uso Governar o acesso a múltiplos modelos de IA usa os valores deste exemplo.

Execute a function em todos os caminhos

Crie uma regra de Request Phase como mostra Adicione a regra que executa a função, com o nome gateway - all paths, 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. Uma regra nova leva alguns minutos para se propagar.

Adicione um registro de equipe

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.

O namespace ai-gateway guarda o registro de checkout-team sob o hash da chave dela.

O caso de uso Governar o acesso a múltiplos modelos de IA usa os valores deste exemplo.

Confirme que o gateway roteia, faz fallback e recusa

Cada verificação envia uma requisição de chat com a chave de equipe de Adicione um registro de equipe.

Para enviar 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.

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.

Envie a requisição para general duas vezes com o header x-gateway-cache: allow. A segunda resposta traz x-gateway-cache: hit.

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.

O gateway roteia a requisição de cada equipe por alias, faz fallback quando uma rota falha e recusa o que o registro da equipe não permite. Remova o alias fallback-test de ROUTES e do registro da equipe depois que a verificação de fallback passar.

Estas verificações confirmam o caso de uso Governar o acesso a múltiplos modelos de IA.

Próximos passos

Armazene em cache a resposta de uma function com a Cache APIMonte uma chave de cache para uma requisição e exclua uma entrada depois de uma escrita.Governar o acesso a múltiplos modelos de IAO design a que este gateway serve: os aliases, o timeout de fallback, o cache e o modelo de orçamento, com o motivo de cada um.