Boas práticas

Uma chamada de modelo é um código que pertence a você invocando um modelo que você não opera. Seu código escolhe qual modelo responde, o que chega até ele e o que o chamador recebe no fim. O modelo lê a requisição exatamente como ela chega, então as decisões que moldam uma resposta são tomadas antes da chamada.

No AI Inference, o código que faz a chamada é uma função, e a chamada é Azion.AI.run. Cada prática abaixo é uma das decisões que essa chamada deixa para você. Os valores em si pertencem a outras páginas. Os campos da requisição estão em Invocação de modelos, e as condições que Azion aplica a um modelo estão em Limites do AI Inference. O caminho que uma requisição percorre está em Como AI Inference funciona.

As seções seguem a ordem em que as decisões surgem: a autenticação que o endpoint não carrega, o id do modelo e as capacidades que um modelo declara. As duas últimas tratam da entrada que a função envia e da resposta que ela lê.

A autenticação que o endpoint não carrega

Uma aplicação implantada a partir do AI Inference Starter Kit responde em um Workload Domain, na forma xxxxxxxxxx.map.azionedge.net, e serve nele um endpoint compatível com OpenAI. A autenticação nesse endpoint é inteiramente sua. Azion não emite nenhuma credencial para uma chamada de modelo nem exige uma. Uma requisição que alcança o domínio alcança a função, a menos que o seu próprio código a interrompa.

A consequência é o que uma aplicação implantada faz quando nada é acrescentado a ela. Ela responde a toda requisição que alcança o domínio, e cada requisição que o endpoint serve executa um modelo. Uma chamada de modelo consome Compute Time, a duração da execução ativa multiplicada pela memória alocada. Um endpoint aberto é, portanto, consumo que qualquer pessoa pode iniciar. Para a métrica e o valor cobrado, consulte Preços.

A verificação pertence à função, antes da chamada de modelo. A função recebe a requisição e a pré-processa, então ela é o lugar em que uma requisição pode ser rejeitada sem que um modelo seja executado. Associar um domínio personalizado no lugar do Workload Domain muda onde a aplicação responde, não o que ela verifica.

Ids de modelo, copiados em vez de derivados

Um modelo é endereçado pelo seu id e por nada mais. O id é o primeiro argumento de Azion.AI.run e o campo model do corpo de uma requisição HTTP, e nenhuma URL base ou host o acompanha.

Os ids não compartilham uma forma única. Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 é o caminho do repositório do modelo, sem alteração. casperhansen-mistral-small-24b-instruct-2501-awq é o mesmo caminho com a barra substituída por um hífen. qwen-qwen25-vl-3b-instruct-awq está em minúsculas e também perdeu o ponto da versão. gpt-oss-20b descartou a organização por completo.

Nenhuma regra transforma o nome de um modelo no seu id. Um id montado a partir do nome está certo para alguns modelos do catálogo e errado para outros. O erro é uma string, e é por isso que ele parece correto. Copie o id da própria página do modelo em Modelos de AI, onde cada página declara o id que alcança aquele modelo.

As capacidades que um modelo declara para si

O que um modelo aceita é uma propriedade daquele modelo, e não do AI Inference. Cada página em Modelos de AI declara o seu próprio comprimento de contexto, os tipos de entrada que aceita e se suporta chamada de ferramentas. O catálogo não é uniforme em nenhum dos três. Os comprimentos de contexto vão de 8k tokens a 131k tokens. Alguns modelos aceitam apenas texto, e outros aceitam texto e imagens. A chamada de ferramentas é declarada como suportada em algumas páginas e não suportada em outras.

Uma requisição que não corresponde é uma requisição que o modelo não consegue servir. Uma imagem enviada a um modelo que aceita apenas texto é uma delas. Um prompt mais longo que o contexto que o modelo aceita é outra. As duas são decididas no seu código antes da chamada, que é onde elas podem ser verificadas.

Onde a página de um modelo não declara nada para uma capacidade, nada sobre aquela capacidade está declarado. Leia um campo em branco como desconhecido, e não como um sim ou um não, e confirme antes que um código dependa dele.

A entrada decidida antes da chamada

Tudo o que um modelo lê foi montado pela sua função, na mesma execução que faz a chamada. O pré-processamento fica de um lado de Azion.AI.run e a formatação da resposta do outro, e os dois são código que você escreveu.

A chamada é aguardada, então o tempo que o modelo passa gerando é tempo que a função passa esperando. O tamanho do que você envia faz parte disso. Um prompt que carrega um documento inteiro onde uma seção bastaria é lido por completo, dentro de uma execução medida enquanto ela acontece.

Restringir a entrada é feito antes da chamada, em vez de corrigido depois dela. A resposta declara o que a requisição consumiu: usage.prompt_tokens carrega os tokens lidos da requisição, e usage.total_tokens carrega a requisição e a resposta juntas. Esses dois campos são a forma de medir uma mudança em um prompt. Para os campos da resposta, consulte Invocação de modelos.

Optional chaining na resposta do modelo

Ler o texto que um modelo de chat gerou significa percorrer quatro níveis dentro de um objeto: choices, a sua primeira entrada, o message dessa entrada e o content dele. As funções de exemplo que Azion publica os percorrem como modelResponse?.choices?.[0]?.message?.content, com optional chaining em cada nível.

A resposta não é idêntica para todo modelo e toda chamada. Ela carrega campos que apenas alguns modelos retornam, como o conteúdo de raciocínio e as probabilidades logarítmicas. Ler os níveis com optional chaining é o que impede que um nível ausente encerre a leitura.

A diferença está em onde uma falha cai. Com optional chaining, a função recebe undefined e decide o que o chamador obtém; sem ele, a própria leitura falha dentro da função. Uma das funções de exemplo que Azion publica encadeia ?.trim() na mesma leitura, de modo que o valor é normalizado onde é obtido.