Referência de Headers

O Floopy utiliza headers HTTP personalizados para controlar o comportamento do gateway por requisição. Envie esses headers junto com os headers padrão Authorization e Content-Type ao chamar o gateway.

Headers de Requisição

Headers de Cache

Controlam como o gateway faz cache de requisições e respostas.

Headers de Prompt

Referenciam prompts gerenciados da biblioteca de prompts do Floopy.

Campo do Body: inputs

Ao usar um prompt gerenciado com floopy-prompt-id, você pode enviar um objeto inputs no body JSON da requisição para preencher as variáveis do template. O gateway substitui os placeholders {{key}} no template do prompt pelos valores correspondentes de inputs.

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "placeholder"}],
  "inputs": {
    "language": "English",
    "topic": "quantum computing"
  }
}

Ordem de resolução: valores de inputs têm prioridade, depois os valores padrão do template na configuração do prompt, e por último o placeholder é mantido como está. O campo inputs é removido antes que a requisição chegue ao provedor LLM.

Consulte o guia de Gerenciamento de Prompts para exemplos completos.

Headers de Segurança

Ativam o firewall LLM para verificar prompts contra ataques de injeção e conteúdo inseguro.

Headers de Tratamento de Tokens (Em Breve)

Controlam como o gateway lida com requisições que excedem a janela de contexto do modelo. Esta funcionalidade está planejada e ainda não está disponível.

As três estratégias planejadas são:

• truncate — Remove mensagens do início da conversa para caber no limite de tokens do modelo. A mensagem de sistema e as mensagens mais recentes são preservadas.
• middle-out — Mantém a primeira e a última mensagem da conversa e remove as mensagens do meio. Útil quando tanto o contexto inicial quanto a mensagem mais recente do usuário são importantes.
• fallback — Troca para um modelo com uma janela de contexto maior em vez de modificar as mensagens. O gateway seleciona um modelo apropriado do mesmo provedor.

Headers de Roteamento

Sobrescrevem o comportamento de roteamento padrão para uma única requisição.

Headers de Rate Limit

Sobrescrevem a política de rate limit padrão para uma única requisição.

O formato da política é <limit>;w=<window>;u=<unit>;s=<segment>:

• limit — O número máximo de unidades permitidas dentro da janela.
• w (window) — Janela de tempo em segundos. A janela mínima é de 60 segundos.
• u (unit) — A unidade a ser contada: request (número de requisições) ou cents (custo em centavos).
• s (segment) — Como segmentar o limite: global (compartilhado entre todos os usuários), user (por usuário final via floopy-user-id) ou custom (por chave personalizada).

Exemplo: 100;w=60;u=request;s=global significa 100 requisições por 60 segundos, aplicado globalmente.

Escopo de Projeto

Segmenta requisições por projeto para rastreamento de custos e analytics por projeto.

Veja o guia de Projetos para a cadeia de fallback completa e modelo de ambientes.

Headers de Sessão e Propriedades

Anexam metadados de sessão e propriedades customizadas às requisições para rastreamento e analytics.

Propriedades customizadas aparecem no dashboard de observabilidade e podem ser usadas para filtrar e agrupar requisições.

Headers de Resposta

O gateway adiciona esses headers a cada resposta. Eles fornecem metadados sobre como a requisição foi processada.