# Invocação de modelos Você invoca um modelo com duas coisas: o id do modelo e um corpo de requisição compatível com OpenAI. [AI Inference](/pt-br/documentacao/plataforma/ai-inference/) aceita essa requisição por duas interfaces, e as duas alcançam os mesmos modelos. Você chama o binding `Azion.AI.run` dentro de uma [função](/pt-br/documentacao/plataforma/functions/), ou envia uma requisição POST para o endpoint HTTP compatível com OpenAI servido pela aplicação que você implanta. Os campos da requisição são os mesmos nas duas interfaces. ## O binding Azion.AI.run `Azion.AI.run` é o binding de runtime que uma função chama para invocar um modelo. Ele recebe o id do modelo e o corpo da requisição que esta página descreve, e a chamada é assíncrona. O binding pertence ao runtime, e não ao AI Inference, então os parâmetros, a chamada e o valor de retorno dele estão documentados com os outros bindings do runtime, em [AI Inference API](/pt-br/documentacao/devtools/runtime/api-reference/ai/). ## O endpoint HTTP O endpoint HTTP aceita uma requisição POST para `/v1/chat/completions` com um corpo JSON. Azion não hospeda esse endpoint. O host é a aplicação que você implanta, que responde em um domínio na forma `xxxxxxxxxx.map.azionedge.net`, ou em um domínio personalizado associado a ela. Uma aplicação implantada a partir do [AI Inference Starter Kit](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/frameworks/ai-inference-starter-kit/) serve o endpoint nesse domínio. Uma requisição a um modelo de chat por HTTP: ```bash curl -X POST https:///v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen3-30B-A3B-Instruct-2507-FP8", "max_tokens": 500, "messages": [ { "role": "user", "content": "Name three European capitals." } ] }' ``` Azion não emite nenhuma credencial para uma chamada de modelo, e o endpoint não carrega autenticação da Azion. A autenticação é o que você adiciona à sua própria aplicação. Quando sua aplicação exige um header, inclua-o na requisição, por exemplo `-H "Authorization: Bearer [TOKEN VALUE]"`. --- ## Campos da requisição Estes campos formam o corpo de uma requisição a um modelo de chat, seja pelo binding, seja por HTTP. Por HTTP, o corpo também carrega um campo `model` com o id do modelo. Pelo binding, o primeiro parâmetro carrega o id e o corpo não o repete. Cada modelo de chat indica a [OpenAI Chat API](https://developers.openai.com/api/reference/overview) como o endpoint com o qual é compatível, então um campo se comporta como esse schema descreve; os tipos, os padrões e os limites abaixo são os que AI Inference declara. Um traço na coluna Padrão significa que o schema não define padrão para o campo. | Campo | Tipo | Obrigatório | Padrão | Descrição | | ------------------- | ------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | array | Sim | — | A conversa enviada ao modelo. Cada entrada é um objeto de mensagem de system, user ou assistant. | | `temperature` | number | Não | — | Temperatura de amostragem. Mínimo `0`, máximo `2`. | | `top_p` | number | Não | `1` | Valor de amostragem top-p. Mínimo `0`, máximo `1`. | | `n` | integer | Não | `1` | Número de respostas a gerar. Mínimo `1`. | | `stream` | boolean | Não | `false` | Envia a resposta em stream em vez de retorná-la inteira. Aceita `true` ou `false`. | | `max_tokens` | integer | Não | — | Número máximo de tokens que o modelo gera. Mínimo `1`. | | `presence_penalty` | number | Não | `0` | Penalidade de presença aplicada à saída. Mínimo `-2`, máximo `2`. | | `frequency_penalty` | number | Não | `0` | Penalidade de frequência aplicada à saída. Mínimo `-2`, máximo `2`. | | `tools` | array | Não | — | As definições de ferramentas que o modelo pode chamar, em um modelo que declara Tool calling entre suas capacidades. As páginas dos modelos que a suportam mostram o formato. | O context length, o tool calling e os tipos de entrada que um modelo aceita são valores por modelo, e não fazem parte deste schema. Para o modelo que você chama, consulte [Modelos de AI](/pt-br/documentacao/plataforma/ai-inference/modelos/). ## Objetos de mensagem Cada entrada do array `messages` é um objeto de mensagem, e o campo `role` indica qual dos três objetos ela é. Cada objeto exige `role` e `content`. O campo `role` é um enum com um único valor, então o objeto e o role são a mesma escolha. O campo `content` recebe texto como string ou, em um modelo que aceita imagens, um array de partes de conteúdo. | Role | Objeto do schema | Campos obrigatórios | | ----------- | ------------------ | ------------------- | | `system` | `SystemMessage` | `role`, `content` | | `user` | `UserMessage` | `role`, `content` | | `assistant` | `AssistantMessage` | `role`, `content` | Um array `messages` que carrega um turno anterior: ```json { "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Name three European capitals." }, { "role": "assistant", "content": "Amsterdam, Athens, and Lisbon." }, { "role": "user", "content": "Which of them is furthest south?" } ] } ``` Um modelo que aceita imagens recebe `content` como um array de partes de conteúdo em vez de uma string. Cada parte indica o seu `type` e carrega o campo que esse tipo usa. As páginas dos modelos que aceitam imagens mostram esse formato; um modelo somente de texto recebe a string. | Parte de conteúdo | Tipo | Carrega | | ----------------- | ------ | ------------------------------------------------- | | `type` | string | Qual é o tipo desta parte: `text` ou `image_url`. | | `text` | string | O texto da parte, quando `type` é `text`. | | `image_url` | object | A imagem da parte, quando `type` é `image_url`. | | `image_url.url` | string | A URL de onde o modelo lê a imagem. | Um array `content` que carrega texto e uma imagem: ```json { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ``` Para saber se um modelo aceita imagens, consulte os tipos de entrada na página dele em [Modelos de AI](/pt-br/documentacao/plataforma/ai-inference/modelos/). --- ## Requisições de embedding Um modelo de embedding recebe um corpo de requisição que o schema de chat não define. `input` carrega o texto a converter em embedding e é o único campo obrigatório. Os outros dois definem o vetor retornado, e cada um aceita um conjunto fixo de valores; um valor fora do conjunto não faz parte do schema. | Campo | Tipo | Obrigatório | Descrição | | ----------------- | --------------- | ----------- | ------------------------------------------------------------------------------------------ | | `input` | string ou array | Sim | O texto a converter em embedding. Um array contém strings, integers ou arrays de integers. | | `encoding_format` | string | Não | A codificação do embedding na resposta: `float` ou `base64`. | | `dimensions` | integer | Não | O tamanho do vetor que o modelo retorna: `256`, `512`, `1024`, `2048` ou `4096`. | Para armazenar os vetores que um modelo de embedding retorna e consultá-los, consulte [Vector Search](/pt-br/documentacao/plataforma/sql-database/vector-search/). ## Requisições de reranking Uma requisição de reranking não carrega um array `messages`. Em vez disso, ela carrega um de dois pares de entrada, e cada par contém um valor único e uma coleção a ser pontuada contra esse valor. Uma requisição usa um par ou o outro, e o schema indica `query` e `documents` como o par obrigatório. | Campo | Tipo | Carrega | | -------------------- | ---------------- | ---------------------------------------------------------------- | | `query` | string | A consulta contra a qual os documentos são classificados. | | `documents` | array de strings | Os documentos a classificar por relevância em relação a `query`. | | `text_1` | string | O primeiro texto que o modelo processa. | | `text_2` | array de strings | Os textos que o modelo pontua em relação a `text_1`. | | `top_n` | integer | Declarado pelo schema, que não indica padrão nem limites. | | `max_tokens_per_doc` | integer | Declarado pelo schema, que não indica padrão nem limites. | --- ## Campos da resposta Um modelo retorna um objeto, qualquer que seja a interface que carregou a requisição. O formato depende do que o modelo faz, e os três abaixo cobrem todos os modelos do catálogo. As páginas dos modelos mostram um payload completo para os modelos que têm um. Um modelo de chat retorna um objeto `chat.completion`: | Campo | Tipo | Carrega | | ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | | `id` | string | O identificador desta completion. | | `object` | string | `chat.completion`. | | `created` | integer | Quando a completion foi criada. | | `model` | string | O id do modelo que respondeu. | | `choices` | array | As respostas geradas, uma entrada por resposta solicitada em `n`. | | `choices[].index` | integer | A posição da entrada em `choices`. | | `choices[].message` | object | A mensagem gerada. | | `choices[].message.role` | string | `assistant`. | | `choices[].message.content` | string | O texto gerado. É daqui que uma resposta de chat é lida. | | `choices[].message.reasoning_content` | string | O raciocínio que o modelo retornou, quando ele retorna algum. | | `choices[].message.tool_calls` | array | As ferramentas que o modelo escolheu chamar, em um modelo que declara Tool calling entre suas capacidades. | | `choices[].finish_reason` | string | Por que a geração parou, como `stop` ou `tool_calls`. | | `choices[].stop_reason` | string | A condição de parada que encerrou a geração. | | `choices[].logprobs` | object | As log probabilities, quando o modelo as retorna. | | `usage` | object | Os tokens que a requisição e a resposta consumiram. | | `usage.prompt_tokens` | integer | Os tokens lidos da requisição. | | `usage.completion_tokens` | integer | Os tokens gerados na resposta. | | `usage.total_tokens` | integer | Os dois somados. | | `usage.prompt_tokens_details` | object | O detalhamento dos tokens do prompt. | | `prompt_logprobs` | object | As log probabilities do prompt, quando o modelo as retorna. | Um modelo de embedding retorna um objeto `list` cujo array `data` contém um embedding por entrada: | Campo | Tipo | Carrega | | ------------------ | ---------------- | ------------------------------------------------ | | `id` | string | O identificador desta resposta. | | `object` | string | `list`. | | `created` | integer | Quando a resposta foi criada. | | `model` | string | O id do modelo que respondeu. | | `data` | array | Os embeddings, um por entrada. | | `data[].index` | integer | A posição da entrada em `data`. | | `data[].object` | string | `embedding`. | | `data[].embedding` | array de números | O vetor, do tamanho selecionado em `dimensions`. | | `usage` | object | Os tokens que a requisição consumiu. | Um modelo de reranking retorna os resultados classificados: | Campo | Tipo | Carrega | | --------------------------- | ------- | ----------------------------------------------------------- | | `id` | string | O identificador desta resposta. | | `model` | string | O id do modelo que respondeu. | | `results` | array | As entradas classificadas, da maior pontuação para a menor. | | `results[].index` | integer | A posição que a entrada ocupava na coleção de entrada. | | `results[].document` | object | A entrada que foi classificada. | | `results[].document.text` | string | O texto dessa entrada. | | `results[].relevance_score` | number | O quanto o modelo julgou a entrada relevante. | | `usage.total_tokens` | integer | Os tokens que a requisição consumiu. | --- ## Recursos relacionados - [AI Inference API](/pt-br/documentacao/devtools/runtime/api-reference/ai.md): O binding que uma função chama, com os parâmetros e o valor de retorno dele. - [Como AI Inference funciona](/pt-br/documentacao/plataforma/ai-inference/como-funciona.md): O que executa um modelo e de onde a requisição desta página é servida. - [Primeiros passos com AI Inference](/pt-br/documentacao/plataforma/ai-inference/primeiros-passos.md): Implante uma aplicação e envie uma primeira requisição a um modelo. - [Modelos de AI](/pt-br/documentacao/plataforma/ai-inference/modelos.md): O id a passar e as capacidades que cada modelo declara para si. - [Limites do AI Inference](/pt-br/documentacao/plataforma/ai-inference/limites.md): As condições em que Azion encerra ou desprovisiona um modelo. - [Functions](/pt-br/documentacao/plataforma/functions.md): O runtime que contém o binding e os limites que restringem uma chamada. - [Preços](/pt-br/documentacao/fundamentos/precos.md#ai-inference): Como o consumo de AI Inference é medido e cobrado.