Pipelines de IA

Os pipelines do AI Gateway são as etapas de processamento que a AIVAX aplica antes e durante a inferência. Eles podem adicionar contexto, reescrever consultas, expor ferramentas, moderar entradas, roteir modelos, truncar conversas e chamar workers externos.

A maioria dos pipelines é configurada nos parâmetros do gateway. Opções ao nível da requisição podem sobrescrever alguns parâmetros de inferência em chamadas diretas chat/completions.

RAG #

RAG vincula collections a um AI Gateway. O gateway controla:

• Coleções incluídas na recuperação.
• Número máximo de documentos recuperados.
• Pontuação mínima.
• Nome do reranker.
• Se referências de fragmentos são incluídas.
• Estratégia de consulta.

Quando um gateway possui coleções de conhecimento e a última mensagem do usuário contém texto, a AIVAX pode recuperar documentos correspondentes antes da chamada ao modelo. Para estratégias de injeção, o contexto recuperado é inserido no início da última mensagem do usuário. Se uma coleção vinculada tem seu próprio texto de contexto, esse contexto de coleção é adicionado às instruções do sistema.

Estratégias de consulta:

• Plain: Usa a última mensagem do usuário como consulta de busca.
• Concatenate: Junta o número configurado mais recente de mensagens do usuário linha a linha e busca com o texto combinado.
• UserRewrite: Reescreve mensagens recentes do usuário em uma ou mais consultas de busca usando um modelo resolvedor.
• FullRewrite: Reescreve mensagens recentes do usuário e do assistente em uma ou mais consultas de busca usando um modelo resolvedor.
• QueryFunction: Adiciona uma função de consulta ao modelo. O modelo decide quando buscar nas coleções vinculadas, e os resultados da busca são retornados como respostas de ferramenta. O modelo pode restringir uma busca com um document filter opcional.

Estratégias de reescrita adicionam custo de modelo resolvedor (veja Pricing) e latência. Elas são úteis quando usuários fazem perguntas de acompanhamento, como “e sobre este caso?”, pois o resolvedor pode transformar a conversa recente em uma consulta de busca mais clara.

Definir muitos resultados de RAG aumenta o uso de tokens de entrada e pode elevar o custo final da inferência (veja Pricing). Comece com um número pequeno de resultados e aumente apenas quando o modelo não tiver evidência suficiente.

Instruções #

Configurações de instrução moldam o prompt exposto ao provedor:

• Instruções do sistema: adicionadas ao conjunto de instruções do sistema.
• Fontes remotas de instruções do sistema: obtidas de URLs configuradas e adicionadas ao conjunto de instruções do sistema.
• Modelo de prompt do usuário: substitui {prompt} pelo texto de cada mensagem do usuário antes de enviá‑la ao modelo.
• Pré‑preenchimento do assistente: adiciona conteúdo inicial do assistente antes da geração quando o modelo oferece pré‑preenchimento.

Fontes remotas de instrução são obtidas como texto, dentro de um limite de tamanho de resposta (veja Request and payload limits). Sua duração de cache é configurável; o padrão é 600 segundos.

Alguns modelos não suportam pré‑preenchimento do assistente, temperatura, sequências de parada ou esforço de raciocínio. A validação integrada de modelo rejeita configurações incompatíveis do gateway quando essas limitações são conhecidas.

Habilidades #

Habilidades são pacotes de instruções sob demanda disponíveis para o modelo. Quando um gateway habilita habilidades, a AIVAX carrega as habilidades da conta configuradas no gateway e pode expor funções internas relacionadas a habilidades.

Leia mais sobre skills.

Pré‑processamento multimodal #

O pré‑processamento multimodal converte conteúdo de mídia selecionado em texto antes da chamada principal ao modelo. Cada tipo de conteúdo (imagens, áudio, vídeo e arquivos) usa seu próprio mecanismo: um modelo multimodal menor (InferenceLow) ou maior (InferenceHigh), OCR para imagens e arquivos, ou reconhecimento de fala para áudio. Consulte Multimodal pre-processing para os mecanismos aceitos.

A configuração do gateway multimodalResolverParameters substitui as flags obsoletas enabledMultimodalFeatures. Gateways que ainda usam as flags continuam funcionando com os mecanismos equivalentes até que multimodalResolverParameters seja definido.

Use pré‑processamento quando o modelo principal for texto‑primeiro ou quando quiser que a AIVAX normalize a mídia em contexto textual. Para modelos multimodais diretos, envie a mídia original sem pré‑processamento para que o modelo possa inspecioná‑la diretamente.

Os resultados são armazenados em cache por conteúdo e mecanismo para reutilização.

Parametrização #

O pipeline de parametrização configura opções de requisição ao modelo, como:

• temperature
• top_p
• presence_penalty
• frequency_penalty
• stop
• max_completion_tokens
• reasoning_effort
• verbosity
• seed

Valores ao nível da requisição podem sobrescrever valores do gateway quando o endpoint suporta o parâmetro. Alguns modelos integrados rejeitam parâmetros específicos, e provedores BYOK podem ter suas próprias restrições.

Truncamento de contexto #

O pipeline de truncamento de contexto usa uma contagem aproximada de tokens. Quando ContextMaximumSize está definido e a conversa ultrapassa o limite, o gateway segue ContextOverflowAction:

• Throw: Retorna um erro em vez de chamar o modelo.
• Truncate: Remove mensagens não‑sistêmicas mais antigas até que a conversa caiba.

O truncamento preserva mensagens do sistema e mantém pelo menos uma mensagem do usuário quando possível. Se a mensagem do usuário restante ainda ultrapassar o limite, a requisição falha com um erro de tamanho de mensagem.

Em planos mais baixos, o contexto de entrada efetivo pode ser limitado mesmo quando um contexto maior está configurado; veja Plans and limits.

Truncamento de mensagens de ferramenta #

ToolContextCount controla quantas mensagens de resposta de ferramenta recentes mantêm seu conteúdo original. Quando definido como um valor maior que zero, mensagens de ferramenta mais antigas permanecem na conversa, mas seu conteúdo é substituído por:

[tool response truncated - call this tool again]

Isso pode reduzir o uso de contexto em longas conversas agenteicas. Também pode prejudicar cadeias onde um resultado antigo de ferramenta continua importante, portanto use apenas quando o modelo puder chamar a ferramenta novamente com segurança. Reescrever mensagens antigas de ferramenta também altera o prefixo da requisição, o que pode reduzir a taxa de acerto do cache de prompt; para verificar isso no seu uso, veja why a prompt cache hit rate is low.

Ferramentas do lado do servidor #

Ferramentas do lado do servidor são funções internas executadas pela AIVAX durante a inferência. Elas podem provir de:

• Ferramentas internas.
• Funções de protocolo.
• Fontes remotas de funções de protocolo.
• Fontes MCP.
• QueryFunction RAG.
• Habilidades.
• Ambiente bash opcional.

Eventos de ferramenta do lado do servidor podem ser transmitidos aos clientes como atualizações servertool.

Ferramentas internas #

Ferramentas internas podem ser configuradas em um gateway ou fornecidas por requisição com builtin_tools. Flags de ferramentas internas disponíveis incluem:

• DateTime — data e hora atuais via get_date_time; configure dateTimeTimeZone nas opções de ferramenta interna (padrão: America/Los_Angeles, Horário do Pacífico).

• WebSearch

• AdvancedWebUsage (desativado; retorna uma resposta indisponível. Veja Changelogs.)

• OpenUrl

• Code

• Request

• Calendar

• Remember

• GenerateWebPage

• GenerateDocument

• XPostsSearch

• ImageGeneration

Consulte Built-in tools.

MCP e funções de protocolo #

Ferramentas listadas por uma fonte MCP tornam‑se disponíveis ao modelo com seus esquemas declarados. Resultados de ferramentas MCP podem incluir texto, imagens e áudio; resultados de mídia são anexados à conversa como mensagens adicionais quando suportado.

Funções de protocolo expõem callbacks HTTP ou URLs de callback da AIVAX como ferramentas chamáveis pelo modelo. Fontes remotas de funções de protocolo são obtidas e armazenadas em cache antes que suas ferramentas fiquem disponíveis ao modelo.

Veja Protocol functions e MCP.

Interpretador de funções #

Um manipulador de ferramenta pode adicionar comportamento de chamada de ferramenta para modelos que não produzem chamadas nativas de forma confiável. Valores suportados são:

• native ou null: Usa chamada nativa de ferramenta do modelo.
• react.v1.selfcall: Usa o manipulador de auto‑chamada estilo ReAct.

Se um nome de manipulador não for reconhecido, a configuração do gateway falha no momento da inferência.

Moderação #

A moderação é um filtro de entrada que roda antes do modelo principal. Quando ao menos uma categoria de moderação está habilitada, a AIVAX envia a conversa textual disponível para um modelo de proteção. O modelo de proteção avalia a última solicitação do usuário no contexto estabelecido pela conversa e retorna uma pontuação de 0 a 10 para cada categoria.

Entendendo os níveis de sensibilidade #

O valor configurado no gateway é um nível de sensibilidade, não a pontuação do modelo de proteção. Um nível mais alto diminui a pontuação necessária para bloquear a entrada.

Para categorias habilitadas, o corte de bloqueio é 11 - nível de sensibilidade. Uma pontuação de 0 nunca bloqueia. Configure cada categoria de forma independente; a requisição é bloqueada quando qualquer categoria habilitada atinge seu corte.

Adicionar regras específicas do gateway #

Regras de moderação adicionais permitem que um administrador de gateway descreva políticas que não são totalmente expressas pelas descrições das categorias internas. O modelo de proteção lê essas regras junto com a política interna e as usa para calibrar as cinco pontuações.

Exemplo:

Allow users to describe accidents and injuries when asking for insurance coverage or assistance.
Treat requests for instructions to cause an accident or harm someone as dangerous content.

Regras adicionais orientam a classificação; elas não criam uma pontuação separada nem bloqueiam uma entrada diretamente. Pelo menos uma categoria deve ter nível de sensibilidade acima de 0 para que a moderação seja executada. No exemplo acima, habilite Conteúdo perigoso para que a pontuação do modelo de proteção possa gerar uma decisão de bloqueio.

Escreva regras como declarações curtas de política com casos explicitamente permitidos e proibidos. Não inclua segredos, credenciais ou dados operacionais privados, pois as regras são armazenadas na configuração do gateway e enviadas ao modelo de proteção durante a moderação.

O fragmento de gateway a seguir habilita diferentes níveis de sensibilidade e fornece orientações específicas ao domínio para o modelo de proteção. Os valores são apenas um exemplo, não uma baseline recomendada para produção:

{
  "moderationParameters": {
    "violenceThreshold": 4,
    "sexualExplicitThreshold": 4,
    "politicalThreshold": 2,
    "dangerousContentThreshold": 6,
    "jailbreakThreshold": 7,
    "additionalRules": "Allow descriptions of accidents and injuries for insurance support. Treat instructions to cause accidents or harm someone as dangerous content."
  }
}

O que acontece quando uma entrada é bloqueada #

Quando qualquer categoria habilitada atinge seu corte:

1. A AIVAX marca as mensagens originais da conversa como indisponíveis para a requisição principal de inferência.
2. A AIVAX as substitui por uma instrução identificando as categorias que causaram o bloqueio.
3. O modelo principal gera uma recusa em vez de responder à solicitação original.

A recusa é gerada pelo modelo; a moderação não devolve um corpo de resposta fixo. Se todos os modelos de moderação falharem em produzir um resultado válido, a requisição não é rejeitada. O modelo principal recebe então instruções estritas derivadas das categorias configuradas, níveis de sensibilidade e regras adicionais, e aplica a política por conta própria. Se sua aplicação deve falhar de forma fechada quando a moderação estiver indisponível, imponha isso na sua aplicação ou em um worker.

Contexto e limitações atuais #

O modelo de proteção recebe o histórico completo da conversa, não apenas a última mensagem. Papéis de mensagem e texto são preservados como dados de conversa serializados não confiáveis para reduzir a chance de que instruções dentro da conversa sobrescrevam a política de proteção. Se a conversa exceder a janela de contexto da proteção, o contexto mais antigo pode ser truncado.

A moderação atualmente se aplica apenas ao texto de entrada:

• Saída gerada não é moderada.
• Imagens, áudio, vídeo e conteúdo de arquivos não são analisados. O modelo de proteção recebe apenas um marcador indicando que mídia estava presente.
• Autorização de ferramenta ou worker ainda requer política ao nível da aplicação; a moderação não é um mecanismo de autorização.
• A moderação adiciona uma inferência de proteção antes da inferência principal, o que acrescenta latência e uso de moderação cobrável.

Use a moderação para políticas de segurança amplas. Use workers quando a decisão depender de identidade externa, estado de conta ou política de negócio específica.

Para um guia de decisão sobre prompts de sistema, etapa de moderação separada e autorização, veja LLM input moderation: system prompt or separate moderation step?.

Workers #

Configure eventos de worker e detalhes de endpoint nos parâmetros do gateway; implemente o comportamento do evento no seu endpoint externo. Veja AI Workers.