Pular para o conteúdo

Veja cada execução, ouça cada leitor, versione cada prompt.

O gateway pelo qual as suas requisições já passam as registra como execuções com o custo estimado do provedor, recebe scores e feedback de usuários finais sobre elas e preenche os prompts gerenciados antes das próprias verificações. Uma só integração, nas suas próprias contas de provedor.

As contas do INFRO são self-service. O catálogo, a documentação e o contrato da API são públicos, o gateway está implantado, e tudo o que vai além da v1 está marcado para depois. Planos e teste

Execuções

Um turno de agente, uma resposta com recuperação ou um pipeline de documentos são várias chamadas de modelo. Envie um id de trace com cada uma delas e o INFRO as lista como uma só execução, com quanto a execução custou no seu provedor, e a pergunta passa a ser qual execução e qual etapa.

  • Uma linha por execução

    Requisições que compartilham um id de trace e um fluxo de trabalho são uma execução: suas requisições, erros, duração, modelos, custo estimado do provedor, scores e versões de prompt.

  • Encontre a execução que importa

    Filtre por fluxo de trabalho, modelo, usuário final ou erros, e ordene por custo ou duração em uma janela de até 31 dias.

  • Depois, cada etapa

    Abra uma execução no console, ou chame o endpoint de trace, para ver as requisições dela em ordem com o custo de cada etapa.

Um header em cada chamada.

Uma requisição sem id de trace não pertence a nenhuma execução. As execuções são agrupadas por fluxo de trabalho e id de trace juntos, porque os ids de trace são seus e dois fluxos de trabalho podem reutilizar o mesmo.

Uma execução cobre as chamadas de modelo que passaram pelo INFRO, e diz isso em cada resposta. O contrato completo está em Execuções.

# Send the same trace id on every call of one run
curl https://api.infro.io/v1/chat/completions \
  -H "Authorization: Bearer $INFRO_API_KEY" \
  -H "X-INFRO-Trace-Id: run_42" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-5", "metadata": {"workflow": "support-answer"},
       "messages": [{"role": "user", "content": "Where is my order?"}]}'

# Then list the costliest failing runs of that workflow
curl "https://api.infro.io/v1/runs?workflow=support-answer&sort=costliest&has_errors=true" \
  -H "Authorization: Bearer $INFRO_API_KEY"

Scores e feedback

Os scores do seu código, dos monitores de avaliação, da sua equipe e das pessoas que leem suas respostas chegam à mesma requisição, execução e versão de prompt. Scores não são requisições ao gateway e não contam na cota de requisições do seu plano.

  • Feedback de quem lê a resposta

    Cada resposta bem-sucedida traz um token assinado. A página que mostra a resposta o envia com um polegar para cima ou para baixo, sem chave de API no navegador.

  • Scores do seu código

    Um número, um sim ou não, ou um rótulo, em uma requisição ou em uma execução inteira, com um comentário opcional.

  • Dos monitores de avaliação e da sua equipe

    Os monitores de avaliação pontuam uma parte das respostas servidas, e os membros pontuam uma requisição pelo console. Cada score fica na requisição, na sua execução e na sua versão de prompt.

O token é a única autoridade.

O endpoint de feedback não precisa de chave de API e aceita qualquer origem. Um token identifica uma requisição, pode avaliar essa requisição e nada mais, e expira após sete dias.

Como repassar o token pelo seu próprio servidor, limites e retenção estão em Scores e feedback.

// The answer's response carried X-INFRO-Feedback-Token.
const feedbackToken = res.headers.get("X-INFRO-Feedback-Token");

// When the person clicks thumbs up: no API key in the browser.
await fetch("https://api.infro.io/v1/feedback", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: feedbackToken, value: true }),
});

Gerenciamento de prompts

Mantenha prompts como versões numeradas com rótulos e indique um em uma chat completion. A versão passa pela mesma lista de permissões, pelos mesmos guardrails e pelo mesmo orçamento que toda requisição, porque o gateway a preenche antes deles, e a versão fica registrada na requisição.

  • Versões que nunca mudam

    Uma versão contém mensagens com variáveis e pode trazer um modelo e configurações padrão. Uma alteração é uma nova versão.

  • Preenchido antes das verificações

    O gateway preenche a versão antes do roteamento, das listas de permissões de modelos, dos guardrails e da verificação de gastos, então cada um lê as mensagens finais.

  • O rótulo production é movido por uma pessoa

    Rótulos como staging são movidos pelo código. O rótulo protegido production é movido por um proprietário ou administrador no console, e cada movimentação fica no log de auditoria.

  • O registro de cada versão

    Requisições, taxa de erro, latência p50 e p95, custo estimado do provedor por requisição, score médio e proporção de feedback, na janela que você escolher.

  • Reverta movendo o rótulo

    Aponte production para a versão anterior. As requisições passam a usá-la em até cinco segundos, sem deploy.

  • Um campo ou um header

    Indique o prompt no corpo da requisição com suas variáveis, ou em um header para um cliente que não consegue adicionar um campo.

Indique o prompt; o gateway faz o resto.

A resposta diz qual versão respondeu. Os prompts são resolvidos em chat completions e nas requisições de Messages e Responses de agentes de código. Um prompt que a sua aplicação busca e envia diretamente a um provedor não é verificado pelo gateway, e a resposta diz isso.

Rótulos, variáveis, rótulos protegidos e a API de gerenciamento estão em Gerenciamento de prompts.

curl https://api.infro.io/v1/chat/completions \
  -H "Authorization: Bearer $INFRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5",
    "prompt": {
      "id": "support-reply",
      "label": "production",
      "variables": { "customer_name": "Ada" }
    },
    "messages": [{ "role": "user", "content": "Where is my order?" }]
  }'

Avaliadores

Escreva uma rubrica, escolha qualquer modelo de chat que você tenha conectado, e o INFRO o usa para julgar respostas pelo gateway: uma amostra do tráfego real, ou requisições anteriores sob demanda. Cada veredicto chega como um score na requisição que julgou.

  • Sua rubrica, qualquer modelo de chat

    Uma rubrica com a pergunta, a resposta e, nos experimentos, a saída esperada. O juiz devolve um número, um resultado de aprovado ou reprovado, ou uma das suas categorias.

  • Em tempo real, dentro de um limite mensal

    Julgue uma parcela das respostas servidas, filtradas por projeto, modelo, versão de prompt ou fluxo de trabalho. O julgamento sobre o tráfego real fica pausado naquele mês quando o limite de gastos do avaliador é atingido.

  • Ou requisições anteriores, sob demanda

    Julgue até 1,000 requisições registradas em segundo plano, com o número de requisições e o custo estimado do provedor primeiro e um teto de gastos no qual o processo para.

Uma chamada do juiz é uma requisição como qualquer outra.

Roda na sua conta de provedor e é cobrado de você por esse provedor. Uma chamada do juiz sobre o tráfego real roda como a chave que fez a requisição julgada, então o acesso a modelos, os guardrails e os orçamentos dessa chave se aplicam, e ela começa depois que a resposta é enviada, sem nunca a deixar mais lenta nem alterá-la. Toda chamada do juiz conta na cota de requisições do seu plano.

Placeholders, tipos de saída e falhas estão em Avaliadores.

# Judge 5% of one model's answers, at most $25 a month
curl -X POST "https://api.infro.io/manage/v1/evaluators" \
  -H "Authorization: Bearer $INFRO_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "helpfulness",
    "model": "openai/gpt-5.4",
    "rubric": "Does the answer address what was asked, accurately and completely?\n\nQuestion: {{input}}\n\nAnswer: {{output}}",
    "output": {"type": "numeric"},
    "sampling": {"rate": 0.05, "models": ["anthropic/claude-sonnet-5"]},
    "monthly_spend_limit": 25
  }'

Datasets e experimentos

Monte um dataset a partir das requisições que você já registrou, reexecute-o pelo gateway em modelos, versões de prompt e configurações, e compare quanto cada um pontuou e custou, com uma estimativa prévia e um teto.

  • A partir do seu tráfego com um clique

    Adicione uma requisição registrada, ou todas as requisições que os filtros atuais mostram (até 1,000), com a resposta como saída esperada, se quiser.

  • Ou enviados

    JSONL ou CSV de até 5 MB, ou itens enviados pelo código. Um problema indica a linha ou o registro.

  • Mantido até você excluí-lo

    Itens que você escolheu manter, não vinculados à retenção do seu log de requisições, e excluídos junto com o dataset, o projeto dele ou a sua organização.

  • Até seis variantes

    Um modelo ou rota, uma versão de prompt e configurações por variante. Cada resposta é julgada por até cinco avaliadores e comparada por scores, taxa de erros, latência e custo estimado por item.

  • Primeiro a estimativa, depois um teto

    O número de requisições, o custo estimado do provedor e a parcela da sua cota de requisições antes de qualquer coisa rodar. É obrigatório um teto de gastos de pelo menos o valor da estimativa, e a execução para nele.

  • Pelas mesmas verificações

    Cada chamada é uma requisição ao gateway nos seus próprios provedores: acesso a modelos, guardrails, ambiente e limites de gastos se aplicam.

Nada roda até você definir o teto.

Um modelo sem tarifa conhecida aparece como sem preço e o experimento não pode começar, porque o gasto dele não poderia ser mantido dentro do teto. Os veredictos dos juízes de um experimento ficam com o experimento, então um teste nunca altera um score de produção.

Variantes, motivos de parada e a comparação estão em Experimentos; a criação e o envio de itens, em Datasets.

# Estimate first: nothing runs with dry_run
curl -X POST "https://api.infro.io/manage/v1/experiments" \
  -H "Authorization: Bearer $INFRO_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "support-golden",
    "variants": [
      {"label": "current", "model": "anthropic/claude-sonnet-5", "prompt": {"slug": "support-reply", "version": 3}},
      {"label": "candidate", "model": "anthropic/claude-sonnet-5", "prompt": {"slug": "support-reply", "version": 4}},
      {"label": "cheaper", "model": "openai/gpt-5.4-mini", "prompt": {"slug": "support-reply", "version": 4}}
    ],
    "evaluators": ["helpfulness"],
    "dry_run": true
  }'

Regras de reversão

Uma regra observa um rótulo de um prompt. Quando a versão para a qual ele aponta pontua abaixo do seu limite, a regra volta o rótulo para a versão anterior, ou apenas alerta: a mesma mudança auditada que uma pessoa faz no console.

  • Três sinais

    A média de um score, a taxa de aprovação de um score de aprovado ou reprovado, ou a proporção de votos negativos dos seus usuários finais, verificada a cada cinco minutos na sua janela quando há respostas pontuadas suficientes.

  • Reversão, ou apenas um alerta

    A regra volta o rótulo para a versão anterior ou para a que você indicar, ou apenas alerta. Em qualquer caso, fica no log de auditoria e é enviado aos seus canais de alerta.

  • Rótulos protegidos, autorizados por uma pessoa

    Uma regra que move um rótulo protegido é salva por um proprietário ou administrador no console. Um token de gerenciamento nunca grava uma.

Cada regra se lê como uma frase.

Uma regra dispara uma vez por versão e depois fica em silêncio até alguém mover o rótulo de novo. Se uma pessoa mover o rótulo enquanto a verificação roda, a pessoa prevalece. As regras leem scores, que não contam na sua cota de requisições, e não chamam nenhum modelo.

Métricas, janelas, rótulos protegidos e a API de gerenciamento estão em Regras de reversão de prompts.

# Roll staging back when users dislike a version
curl https://api.infro.io/manage/v1/prompts/support-reply/rules \
  -H "Authorization: Bearer $INFRO_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "staging",
    "metric": "thumbs_down_share_above",
    "threshold": 0.3,
    "min_samples": 100,
    "window_minutes": 60,
    "action": "rollback",
    "target_version": "previous"
  }'

Ao lado das suas ferramentas

Seu próprio coletor

Cada requisição também pode ser enviada como um span OpenTelemetry para um coletor que você escolher, a partir do caminho da requisição, com o endpoint e os headers definidos no console. Execuções e scores ficam no INFRO; seus traces ficam onde a sua equipe já os lê.

Exportação OpenTelemetry

Também usa o Langfuse?

Eles funcionam juntos. O Langfuse é uma plataforma open source de observabilidade e avaliação, com filas de anotação para revisão humana e experimentos que rodam o seu próprio código, com recuperação e ferramentas incluídas, o que o INFRO não tem. O INFRO fica no caminho da requisição: roteia, faz failover e recusa gasto antes de o seu provedor ser chamado, e seus juízes e experimentos rodam nesse mesmo caminho. Uma receita testada para enviar os spans do INFRO ao Langfuse ainda não foi publicada.

Comparação entre o INFRO e o Langfuse

Perguntas frequentes

O INFRO pode gerenciar prompts?

Sim, em todos os planos. Salve um prompt como versões numeradas com rótulos como production e staging, e indique-o em uma chat completion com um campo prompt ou o header X-INFRO-Prompt. O gateway preenche a versão antes do roteamento, das listas de permissões de modelos, dos guardrails e da verificação de gastos, então cada verificação lê as mensagens finais, e a versão fica registrada na requisição. Uma versão nunca muda; reverter é mover o rótulo para uma versão anterior, que as requisições passam a usar em até cinco segundos e sem deploy. O rótulo protegido production é movido por um proprietário ou administrador no console.

Como coletar feedback dos usuários sobre respostas de IA?

Cada resposta bem-sucedida a uma chave do gateway traz um header X-INFRO-Feedback-Token: um token assinado pelo INFRO que identifica uma requisição e vale por sete dias. Entregue-o à página que mostra a resposta e, quando a pessoa clicar em polegar para cima ou para baixo, envie-o para POST /v1/feedback. Esse endpoint não precisa de chave de API, então a sua chave nunca chega ao navegador, e o token pode avaliar a própria requisição e nada mais. O feedback aparece na requisição, na sua execução e na versão de prompt que respondeu, e os scores não contam na sua cota de requisições.

O INFRO consegue avaliar a qualidade das respostas de IA?

Sim, com avaliadores, em todos os planos. Um avaliador é uma rubrica que um modelo de chat que você escolhe aplica às respostas, em uma das suas próprias conexões de provedor pelo gateway. Ele julga uma amostra do tráfego real, sujeita a um limite de gastos mensal que você define, ou até 1,000 requisições registradas sob demanda, com uma estimativa prévia e um teto de gastos. Cada veredicto é um score na requisição que julgou, ao lado dos seus próprios scores e do feedback dos seus usuários finais. O julgamento começa depois que a resposta é enviada, então nunca a deixa mais lenta nem a altera. Cada chamada do juiz é uma requisição no seu provedor, cobrada de você por esse provedor e contada na cota de requisições do seu plano.

O que é uma execução no INFRO?

As requisições de um fluxo de trabalho que levaram o mesmo id de trace: um turno de agente, uma resposta com recuperação ou um pipeline de documentos. Envie o id de trace no header X-INFRO-Trace-Id ou em metadata.trace_id, e o fluxo de trabalho em metadata, e GET /v1/runs e o console listam uma linha por execução com suas requisições, erros, duração, modelos, custo estimado do provedor, scores e versões de prompt. Uma execução cobre as chamadas de modelo que passaram pelo INFRO; o seu banco de dados vetorial, a recuperação e a sua própria computação não estão nos números dela.

Minha aplicação pode buscar um prompt e chamar o provedor por conta própria?

Sim: GET /v1/prompts devolve as mensagens e as configurações de uma versão com qualquer chave do gateway que possa usar o prompt. Um prompt usado assim não tem controles aplicados, porque o INFRO nunca vê a chamada: nenhum guardrail, lista de permissões ou limite de gastos se aplica e nenhuma requisição registra a versão, e a resposta diz isso. Indicar o prompt em uma chat completion pelo INFRO é o que aplica as verificações.

Como testo uma mudança de prompt ou de modelo antes de publicá-la?

Execute um experimento. Monte um dataset com um clique a partir de requisições registradas, ou envie um como JSONL ou CSV, e depois reexecute-o pelo gateway em até seis variantes: um modelo ou rota, uma versão de prompt e configurações. Seus avaliadores julgam cada resposta. A estimativa vem primeiro: o número de requisições e o custo estimado do provedor por variante. Para começar, você define um teto de gastos de pelo menos essa estimativa, e a execução para se o gasto dela chegar a ele. A comparação mostra scores, taxa de erro, latência p50 e p95 e custo estimado por item de cada variante, e Promover, no console, move um rótulo de prompt para a versão que uma variante executou.

Um prompt pode se reverter sozinho quando a qualidade cai?

Sim, com uma regra de reversão em um rótulo como production. A cada cinco minutos, a regra lê os scores das respostas servidas pela versão para a qual esse rótulo aponta, em uma janela que você escolhe: a média de um score, a taxa de aprovação de um score de aprovado ou reprovado, ou a proporção de votos negativos dos seus usuários finais. Quando o número cruza o seu limite com pelo menos o número mínimo de respostas pontuadas, a regra volta o rótulo para a versão anterior, ou apenas alerta. Cada mudança fica no log de auditoria e é enviada aos seus canais de alerta. Uma regra que move um rótulo protegido é salva por um proprietário ou administrador no console.

Todas as outras perguntas sobre o INFRO estão nas perguntas frequentes.

Começar

Qualidade e controle em um só registro.

A requisição que foi roteada, precificada e verificada é a requisição que recebeu o score, em todos os planos.