Conceitos de Gateway de IA

Um Gateway de IA armazena uma configuração de inferência reutilizável. Passe o ID ou slug do gateway no campo model da solicitação, e a AIVAX aplica suas configurações de modelo, instruções, coleções RAG, ferramentas, habilidades, workers, moderação e controles de contexto antes de chamar o modelo.

Use um gateway quando o mesmo comportamento precisar ser reutilizado por vários clientes ou alterado sem a necessidade de reimplantar o aplicativo que faz a chamada. Use uma chamada de inferência direta quando o aplicativo controlar o modelo, o prompt, as ferramentas e o contexto de cada solicitação.

Trate a configuração do gateway como sensível: GET /api/v1/ai-gateways/<id> retorna os parâmetros completos para a conta proprietária, incluindo apiKey em texto puro quando o gateway usa uma chave de provedor externa.

Fronteira de responsabilidade #

Um gateway separa dois papéis:

• O aplicativo cliente envia mensagens e, com uma chave privada, substituições opcionais de solicitação.
• O administrador do gateway controla a política operacional: qual modelo é executado, o que ele recebe como instrução, o que ele pode ler, quais ferramentas ele pode chamar e quais limites se aplicam.

Essa fronteira permite alterar um modelo, um prompt ou uma lista de ferramentas em um único local, enquanto todos os clientes continuam chamando o mesmo identificador. Cada recurso abaixo é opcional. Comece com um modelo e instruções do sistema, e adicione outros recursos apenas quando o caso de uso exigir: cada ferramenta, habilidade ou coleção adiciona tokens de entrada, custo e mais um caminho pelo qual o modelo pode escolher incorretamente.

As seções abaixo descrevem o que cada recurso faz e quando usá-lo. O documento Pipeline de processamento detalha o comportamento específico de cada etapa.

Modelo e provedor #

O modelo do gateway é either um modelo integrado da AIVAX ou um modelo servido pela sua própria chave de provedor (BYOK).

• Modelos integrados usam baseAddress: "@integrated" e um nome de modelo como @openai/gpt-5-mini. A AIVAX seleciona o provedor, fatura a conta e aplica o roteamento de provedores.
• Modelos BYOK usam o endereço base de um endpoint de provedor compatível com OpenAI, sua apiKey de provedor e o nome do modelo do provedor. A AIVAX ainda executa o pipeline do gateway, mas o provedor fatura você diretamente e o roteamento de provedores não se aplica. Solicitações BYOK usam o limite de taxa BYOK do plano; consulte Planos e limites.

Use um modelo integrado, a menos que você precise de um modelo, contrato ou região que apenas sua conta de provedor ofereça. Consulte Modelos e nomes de gateway para saber como o modelo é identificado.

Roteamento de modelos #

O roteamento de modelos seleciona um modelo diferente para cada solicitação. O roteador de complexidade classifica a última solicitação do usuário como baixa, média ou alta complexidade e executa o modelo configurado para esse nível, com um esforço de raciocínio opcional por nível. A resposta inclui o cabeçalho X-Model-Routed-Complexity quando um nível foi selecionado.

Use-o quando a maioria das solicitações for simples, mas algumas precisarem de um modelo mais forte, para que você não pague o preço do modelo mais forte em todas as solicitações. Não o use quando todas as respostas devem vir do mesmo modelo para consistência ou conformidade.

O roteamento de modelos difere do roteamento de provedores, que mantém o modelo e escolhe qual provedor o atende.

Instruções #

As configurações de instrução moldam o prompt recebido pelo modelo:

Escreva instruções sobre comportamento, não sobre configurações que o gateway já controla, como limites de truncamento ou a lista de ferramentas. Consulte Instruções para o limite de tamanho da fonte remota e as regras de falha.

Parâmetros do modelo #

O gateway pode definir valores padrão para temperature, top_p, presence_penalty, frequency_penalty, stop, max_completion_tokens, reasoning_effort e verbosity. seed é aceito apenas por solicitação. Solicitações enviadas com uma chave privada podem substituir a maioria desses valores; consulte Substituir valores do gateway.

Defina parâmetros no gateway quando o comportamento deve ser igual para todos os clientes, por exemplo, uma temperatura baixa para um assistente de extração. Alguns modelos integrados rejeitam parâmetros como temperatura, sequências de parada ou esforço de raciocínio; a AIVAX rejeita a configuração do gateway quando a limitação é conhecida.

Janela de contexto e truncamento #

contextMaximumSize limita o número aproximado de tokens de entrada enviados ao modelo, e contextOverflowAction decide o que acontece quando uma conversa excede esse limite:

• Throw retorna um erro em vez de chamar o modelo. Este é o padrão.
• Truncate remove as mensagens mais antigas que não são do sistema até que a conversa caiba, e então continua.
• TruncateHard truncar como Truncate, mas falha na solicitação se o prompt ainda não couber.

Use o truncamento para chats de longa duração nos quais as rodadas anteriores perdem relevância, como conversas de suporte. Mantenha Throw quando cada mensagem for importante, como em uma revisão de documentos, para que o aplicativo decida o que remover. No plano Free, o contexto de entrada é limitado independentemente desta configuração; consulte Limites. Consulte Truncamento de contexto para saber como as mensagens são removidas e quando a verificação é executada.

Truncamento de mensagens de ferramentas #

toolContextCount mantém apenas os resultados de ferramentas mais recentes intactos. Mensagens de ferramentas mais antigas permanecem na conversa, mas seu conteúdo é substituído por uma nota curta solicitando ao modelo que chame a ferramenta novamente.

Use-o em conversas agênticas longas cujas ferramentas retornam payloads grandes que são relevantes apenas uma vez, como resultados de pesquisa. Evite-o quando um resultado de ferramenta inicial permanecer importante posteriormente. Reescrever mensagens antigas também altera o prefixo do prompt, o que pode reduzir o cache de prompts.

Flags #

Flags alteram como a AIVAX prepara a solicitação do provedor para modelos com comportamento específico. Configure-as em Flags e switches de normalização no editor de gateways ou em parameters.flags.

Flags compensam limitações de modelos. Deixe-os não definidos, a menos que você observe o problema que uma flag resolve.

Pré-processamento multimodal #

O pré-processamento multimodal converte imagens, áudio, vídeo e arquivos em texto antes que o modelo principal seja executado. Cada tipo de mídia usa seu próprio mecanismo: um modelo multimodal menor ou maior, OCR ou fala-para-texto.

Use-o quando o modelo principal for apenas texto, ou quando um modelo mais barato puder descrever a mídia uma vez e um modelo de texto mais forte puder raciocinar sobre a descrição. Não o use quando o modelo principal precisar ver a mídia original, como ao comparar detalhes visuais. Consulte Pré-processamento multimodal para os mecanismos e sua cobrança.

Conhecimento (RAG) #

Um gateway pode vincular coleções para que o modelo responda com base em seus documentos. O gateway controla o limite de resultados, pontuação mínima, reranker, comportamento de referência e estratégia de consulta. Escolha a estratégia pelo tipo de conversa:

• Plain pesquisa com a última mensagem do usuário. Use-o para perguntas isoladas.
• Concatenate junta mensagens recentes do usuário. Use-o quando os usuários dividem uma pergunta em várias mensagens.
• UserRewrite e FullRewrite reescrevem mensagens recentes em consultas de pesquisa com um modelo resolvedor. Use-os quando perguntas de acompanhamento dependem de rodadas anteriores, ao custo de uma inferência extra.
• QueryFunction fornece ao modelo uma ferramenta de pesquisa para que ele decida quando pesquisar. Use-o quando muitas mensagens não precisarem de recuperação. Requer um modelo com chamada de ferramentas.

Consulte RAG para o comportamento completo.

Ferramentas #

Ferramentas permitem que o modelo aja e leia dados em tempo real. Um gateway pode expor vários tipos:

Ferramentas integradas, ferramentas MCP, funções de protocolo e o shell são ferramentas do lado do servidor: a AIVAX as executa durante a solicitação e retorna apenas a resposta final. Habilite apenas ferramentas com um papel claro e dê a elas nomes específicos e esquemas restritivos.

Habilidades #

Habilidades são pacotes de instruções que o modelo carrega sob demanda. Use-as para procedimentos especializados que apenas algumas solicitações precisam, para que seu texto não ocupe as instruções do sistema de cada solicitação.

Manipulador de ferramentas #

O manipulador de ferramentas, ou interpretador de funções, está obsoleto. Ele adiciona chamada de ferramentas para modelos que não produzem chamadas de ferramentas nativas confiáveis: native ou nenhum valor usa a chamada de ferramentas nativa do modelo; react.v1.selfcall usa um manipulador estilo ReAct.

Não o use em novos gateways; escolha um modelo com chamada de ferramentas nativa. Consulte Interpretador de funções (obsoleto).

Explicações de ferramentas #

toolInvocationExplanations solicita ao modelo que explique cada chamada de ferramenta do lado do servidor com um motivo curto e objetivo, que a AIVAX retorna junto com o evento da ferramenta. Use-o quando o cliente mostrar a atividade da ferramenta aos usuários finais. Consulte Explicações de ferramentas.

Moderação #

A moderação de entrada avalia a conversa textual antes que o modelo principal seja executado e faz o modelo recusar solicitações que alcancem a sensibilidade configurada em uma categoria. Use-a para políticas amplas de segurança em assistentes voltados para o usuário. Ela não modera a saída ou a mídia, e não é um mecanismo de autorização. Consulte Moderação.

Workers #

Workers chamam seu endpoint durante eventos do gateway, para que seu código possa bloquear uma mensagem, reescrever o contexto, adicionar ferramentas ou substituir um resultado de ferramenta. Use-os quando uma decisão depender de dados que apenas seu sistema possui, como o estado da conta do usuário. O worker executa no caminho crítico, portanto, mantenha-o rápido e determinístico.

Fuso horário #

timeZone define o fuso horário IANA que o modelo usa para ler e escrever datas. Aplica-se a get_date_time, ferramentas de agendamento e ao shell, e o padrão é America/Sao_Paulo. Defina-o para o fuso horário dos seus usuários; uma solicitação pode substituí-lo com time_zone.

Preços #

Um gateway não tem taxa separada. As solicitações são cobradas pelo modelo e pelos recursos que o gateway usa: tokens de inferência, reescrita ou inferências de pré-processamento, moderação, ferramentas e RAG. Consulte Preços de inferência.