Blog

Como Testar Aplicações LLM: Guia Completo do Promptfoo (2026)

Ashley Innocent

Ashley Innocent

19 março 2026

Como Testar Aplicações LLM: Guia Completo do Promptfoo (2026)

Em Resumo

Promptfoo é um framework de avaliação e "red-teaming" de LLMs de código aberto que ajuda desenvolvedores a testar aplicações de IA de forma sistemática. Ele suporta mais de 90 provedores de modelos, oferece mais de 67 plugins de ataque de segurança e roda 100% localmente para privacidade. Com 1.6 milhão de downloads no npm e uso em produção em empresas que atendem mais de 10 milhões de usuários, tornou-se o padrão para testes de LLMs. Comece com npm install -g promptfoo e promptfoo init --example getting-started.

Introdução

Você passou semanas construindo seu chatbot de suporte ao cliente alimentado por IA. Ele respondia às perguntas perfeitamente durante o desenvolvimento. Então, os usuários começaram a encontrar maneiras de fazê-lo vazar dados sensíveis, ignorar as barreiras de segurança e dar respostas inconsistentes.

Este cenário se repete todos os dias. As equipes lançam aplicações de LLM baseadas em intuição e testes manuais, apenas para descobrir vulnerabilidades e problemas de qualidade em produção. O custo de corrigir esses problemas após o lançamento é 100 vezes maior do que detectá-los durante o desenvolvimento.

Promptfoo resolve isso trazendo testes sistemáticos e automatizados para aplicações de LLM. Ele permite que você avalie prompts em múltiplos modelos, execute avaliações de "red-team" de segurança e detecte regressões antes que elas cheguem aos usuários.

Eu analisei a base de código do promptfoo (versão 0.121.2) e testei suas principais funcionalidades para trazer a você este guia completo. Você aprenderá como configurar avaliações, executar verificações de segurança, integrar com CI/CD e evitar armadilhas comuns.

Ao final, você terá um conjunto de testes funcional para sua aplicação de LLM e saberá como lançar com confiança.

💡
Se você trabalha com testes de API ou precisa validar o comportamento da API junto com seus testes de LLM, o Apidog oferece uma plataforma unificada para design, teste e documentação de API. Você pode usar ambas as ferramentas juntas: promptfoo para avaliação de LLM e Apidog para validação da camada de API.
botão

O Que É Promptfoo e Por Que Você Precisa Dele

Promptfoo é uma ferramenta de linha de comando e uma biblioteca Node.js para avaliar e realizar "red-teaming" em aplicações de LLM. Pense nele como um framework de testes construído especificamente para as peculiaridades do desenvolvimento de IA.

Ferramentas de teste tradicionais falham com LLMs porque as saídas não são determinísticas. Você não pode afirmar correspondências exatas de string quando o mesmo prompt produz respostas diferentes a cada vez. Promptfoo resolve isso com:

A ferramenta roda localmente em sua máquina. Seus prompts e dados de teste nunca saem do seu ambiente, a menos que você opte por recursos de nuvem. Este design focado na privacidade o torna adequado para testes com dados sensíveis.

O Problema Que o Promptfoo Resolve

A maioria das equipes testa aplicações de LLM manualmente. Eles enviam alguns prompts, leem as saídas e decidem se as coisas parecem boas. Essa abordagem tem três falhas fatais:

  1. Sem detecção de regressão - Você não consegue saber se uma atualização de modelo quebrou a funcionalidade existente
  2. Lacunas de cobertura - Testes manuais perdem casos de borda e entradas adversárias
  3. Sem métricas - Você não consegue acompanhar melhorias ou comparar modelos objetivamente

Promptfoo substitui isso por avaliações automatizadas que rodam a cada mudança. Você define os casos de teste uma vez e os executa contra qualquer modelo. Os resultados incluem taxas de aprovação/falha, comparações de custo e métricas de latência.

Quem Usa o Promptfoo

O projeto tem 1.6 milhão de downloads no npm e alimenta aplicações de LLM que atendem mais de 10 milhões de usuários finais. Empresas o utilizam para:

Em março de 2026, Promptfoo se juntou à OpenAI. O projeto permanece de código aberto e licenciado sob MIT, com desenvolvimento contínuo sob a nova propriedade.

Começando: Instale e Execute Sua Primeira Avaliação

Você pode instalar o promptfoo globalmente ou executá-lo sem instalação usando npx.

Instalação

# Instalação global (recomendado)
npm install -g promptfoo

# Ou execute sem instalar
npx promptfoo@latest

# Usuários de macOS também podem usar Homebrew
brew install promptfoo

# Usuários de Python também podem usar pip
pip install promptfoo

Defina suas chaves de API como variáveis de ambiente:

export OPENAI_API_KEY=sk-abc123
export ANTHROPIC_API_KEY=sk-ant-xxx

Crie Sua Primeira Avaliação

Inicialize um projeto de exemplo:

promptfoo init --example getting-started
cd getting-started

Isso cria um arquivo promptfooconfig.yaml com prompts de exemplo, provedores e casos de teste.

Execute a avaliação:

promptfoo eval

Visualize os resultados na interface web:

promptfoo view

A interface de usuário abre em localhost:3000 e mostra uma comparação lado a lado das saídas de cada modelo, com status de aprovação/falha para cada asserção.

Entendendo o Arquivo de Configuração

O arquivo promptfooconfig.yaml define sua suíte de avaliação:

description: "Minha Primeira Suíte de Avaliação"

prompts:
  - prompts/greeting.txt
  - prompts/farewell.txt

providers:
  - openai:gpt-4o
  - anthropic:claude-sonnet-4-5

tests:
  - vars:
      input: "Hello"
    assert:
      - type: contains
        value: "Hi"
      - type: latency
        threshold: 3000

Você pode escalar isso para centenas de casos de teste. Muitas equipes mantêm as configurações de avaliação em controle de versão e as executam em CI a cada pull request.

Principais Recursos: O Que o Promptfoo Pode Fazer

1. Avaliações Automatizadas

As avaliações automatizadas são a base do promptfoo. Você define os casos de teste com os resultados esperados, e a ferramenta os executa contra os modelos escolhidos.

Tipos de Asserção

Promptfoo inclui mais de 30 tipos de asserção embutidos:

Asserção Propósito
contains A saída inclui uma substring
equals Correspondência exata de string
regex Corresponder a um padrão regex
json-schema Validar estrutura JSON
javascript Função JS personalizada retorna aprovação/falha
python Função Python personalizada
llm-rubric Usar um LLM para classificar a saída
similar Pontuação de similaridade semântica
latency Tempo de resposta abaixo do limite
cost Custo por requisição abaixo do limite

Exemplo com múltiplas asserções:

tests:
  - vars:
      question: "What is the capital of France?"
    assert:
      - type: contains
        value: "Paris"
      - type: javascript
        value: output.length < 100
      - type: latency
        threshold: 2000
      - type: cost
        threshold: 0.001

Este teste verifica se a resposta menciona Paris, tem menos de 100 caracteres, responde em menos de 2 segundos e custa menos de $0.001.

Avaliações Classificadas por LLM

A asserção llm-rubric usa um LLM para classificar a saída de outro. Isso é poderoso para critérios subjetivos como tom ou utilidade:

assert:
  - type: llm-rubric
    value: "A resposta deve ser útil, inofensiva e honesta"

O LLM avaliador lê a saída e a pontua de acordo com sua rubrica. Você pode usar um modelo mais barato para a classificação a fim de reduzir custos.

2. Red Teaming e Testes de Segurança

Promptfoo inclui testes de segurança abrangentes através de seu módulo de "red team". Ele gera automaticamente entradas adversárias para sondar vulnerabilidades.

Vetores de Ataque Suportados

O sistema de "red team" inclui mais de 67 plugins organizados por categoria:

Categoria O Que Ele Testa
Injeção de Prompt Ataques de injeção direta, indireta e de contexto
Jailbreaks DAN, troca de persona, desvios de role-play
Exfiltração de Dados SSRF, extração de prompt do sistema, vazamento de prompt
Conteúdo Nocivo Discurso de ódio, atividades perigosas, pedidos de autoagressão
Conformidade Vazamento de PII, violações HIPAA, exposição de dados financeiros
Áudio/Visual Injeção de áudio e ataques baseados em imagem

Executando uma Varredura de Red Team

Inicialize uma configuração de red team:

promptfoo redteam init

Execute a varredura de segurança:

promptfoo redteam run

Visualize o relatório:

promptfoo redteam report [directory]

O comando redteam run executa duas etapas:

  1. Gera sondas de ataque dinâmicas adaptadas à sua aplicação
  2. Avalia as sondas contra seu alvo e pontua as vulnerabilidades

Os resultados incluem classificações de severidade (Crítico, Alto, Médio, Baixo), casos de teste exploráveis e recomendações de remediação.

Exemplo de Saída do Red Team

Vulnerability Summary:
- Crítico: 2 (vazamento de PII, extração de prompt)
- Alto: 5 (jailbreaks, ataques de injeção)
- Médio: 12 (viés, respostas inconsistentes)
- Baixo: 23 (pequenas violações de política)

Corrija problemas críticos antes da implantação. Reexecute as varreduras após as alterações para verificar as correções.

3. Varredura de Código para Pull Requests

Promptfoo se integra com GitHub Actions para escanear pull requests em busca de problemas de segurança relacionados a LLMs.

# .github/workflows/promptfoo-scan.yml
name: Promptfoo Code Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g promptfoo
      - run: promptfoo eval -c promptfooconfig.yaml
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Isso detecta:

4. Comparação de Modelos

Compare as saídas de múltiplos modelos lado a lado para escolher o melhor para o seu caso de uso.

# Execute a avaliação com múltiplos provedores
promptfoo eval

# Visualize a comparação na interface web
promptfoo view

A interface web exibe:

Essa abordagem orientada a dados evita o viés em relação a modelos familiares. Você pode descobrir que um modelo mais barato supera o GPT-4 em suas avaliações específicas.

Provedores Suportados: Mais de 90 Integrações LLM

Promptfoo suporta mais de 90 provedores de LLM prontos para uso. Você pode testar o mesmo prompt em OpenAI, Anthropic, Google, Amazon e modelos locais sem alterar seu código.

Principais Provedores

Provedor Modelos
OpenAI GPT-4, GPT-4o, GPT-4o-mini, o1, o3
Anthropic Claude 3.5/3.7/4.5/4.6, Modelos Thinking
Google Gemini 1.5/2.0, Vertex AI
Microsoft Azure OpenAI, Phi
Amazon Bedrock (Claude, Llama, Titan)
Meta Llama 3, 3.1, 3.2 (via múltiplos provedores)
Ollama Modelos locais (Llama, Mistral, Phi)

Provedores Personalizados

Você pode escrever provedores personalizados em Python ou JavaScript se seu modelo não for suportado.

Exemplo em Python:

# custom_provider.py
from typing import Any

class CustomProvider:
    async def call_api(self, prompt: str, options: dict, context: dict) -> dict:
        response = await my_async_api.generate(prompt)
        return {
            "output": response.text,
            "tokenUsage": {
                "total": response.usage.total_tokens,
                "prompt": response.usage.prompt_tokens,
                "completion": response.usage.completion_tokens
            }
        }

Exemplo em JavaScript:

// customProvider.js
export default class CustomProvider {
  async callApi(prompt) {
    return {
      output: await myApi.generate(prompt),
      tokenUsage: { total: 50, prompt: 20, completion: 30 }
    };
  }
}

Registre provedores personalizados em sua configuração:

providers:
  - id: file://custom_provider.py
    config:
      api_key: ${MY_API_KEY}

Interface de Linha de Comando: Comandos Essenciais

A CLI do Promptfoo oferece toda a funcionalidade que você precisa para os fluxos de trabalho diários.

Comandos Principais

# Executar avaliações
promptfoo eval -c promptfooconfig.yaml

# Abrir interface web
promptfoo view

# Compartilhar resultados online
promptfoo share

# Teste de red team
promptfoo redteam init
promptfoo redteam run

# Configuração
promptfoo init
promptfoo validate [config]

# Gerenciamento de resultados
promptfoo list
promptfoo show <id>
promptfoo delete <id>
promptfoo export <id>

# Utilitários
promptfoo cache clear
promptfoo retry <id>

Flags Úteis

--no-cache              # Desabilitar cache para resultados atualizados
--max-concurrency <n>   # Limitar chamadas de API paralelas
--output <file>         # Escrever resultados para arquivo JSON
--verbose               # Habilitar log de depuração
--env-file <path>       # Carregar variáveis de ambiente de um arquivo
--filter <pattern>      # Executar casos de teste específicos

Exemplo: Executar Avaliação com Configurações Personalizadas

promptfoo eval \
  -c promptfooconfig.yaml \
  --no-cache \
  --max-concurrency 3 \
  --output results.json \
  --env-file .env

Isso executa avaliações novas (sem cache), limita a concorrência a 3 chamadas paralelas, salva os resultados em JSON e carrega as chaves de API do arquivo .env.

Integração CI/CD: Automatize Testes de LLM

Integre o promptfoo ao seu pipeline de CI/CD para detectar regressões antes da implantação.

Exemplo de GitHub Actions

name: LLM Tests
on: [push, pull_request]
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g promptfoo
      - run: promptfoo eval -c promptfooconfig.yaml
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Portões de Qualidade

Defina limites de aprovação/falha em sua configuração:

commandLineOptions:
  threshold: 0.8  # Requerer 80% de taxa de aprovação

Isso faz com que o CI falhe se as avaliações não atingirem o limite, impedindo que regressões sejam mescladas.

Cache em CI

Habilite o cache para acelerar as execuções de CI:

- uses: actions/cache@v4
  with:
    path: ~/.cache/promptfoo
    key: ${{ runner.os }}-promptfoo-${{ hashFiles('promptfooconfig.yaml') }}

Resultados em cache pulam chamadas de API para testes inalterados, reduzindo o tempo e os custos do CI.

Interface Web: Visualize e Compartilhe Resultados

A interface web integrada (promptfoo view) oferece uma interface interativa para revisar avaliações.

Recursos

Acesso e Segurança

A interface de usuário roda em localhost:3000 por padrão. Ela inclui proteção CSRF usando cabeçalhos Sec-Fetch-Site e Origin para bloquear requisições cross-site de origens não confiáveis.

Não exponha o servidor web local a redes não confiáveis. Para acesso da equipe, use o comando promptfoo share para fazer upload de resultados para a nuvem, ou hospede-o por conta própria com autenticação.

Banco de Dados e Cache

Local do Cache

O cache armazena os resultados da avaliação para acelerar execuções repetidas. Use --no-cache durante o desenvolvimento para garantir resultados atualizados.

Local do Banco de Dados

O banco de dados armazena execuções históricas de avaliação para comparação e análise de tendências. Não exclua este arquivo, a menos que você queira perder dados históricos.

Modelo de Segurança: O Que Você Pode Confiar

Promptfoo opera em um modelo de confiança por configuração. Compreender isso evita surpresas de segurança.

Entradas Confiáveis (Tratadas como Código)

Essas entradas são executadas como código e só devem vir de fontes confiáveis:

Entradas Não Confiáveis (Somente Dados)

Essas entradas são tratadas como dados e não devem desencadear a execução de código:

Recomendações de Endurecimento

Para ambientes de alta segurança:

  1. Execute dentro de um contêiner ou VM com privilégios mínimos
  2. Use chaves de API dedicadas e com privilégios mínimos
  3. Evite colocar segredos em prompts ou arquivos de configuração
  4. Restrinja a saída de rede para código de terceiros
  5. Não exponha o servidor web local a redes não confiáveis

Desempenho: Otimize Suas Avaliações

Dicas de Otimização

  1. Use cache - Comportamento padrão acelera execuções repetidas
  2. Ajuste a concorrência - --max-concurrency equilibra velocidade vs. limites de taxa
  3. Filtre testes - Use --filter para executar casos de teste específicos durante o desenvolvimento
  4. Amostre conjuntos de dados - Use --repeat com subconjuntos para iteração antes de execuções completas

Escalando para Grandes Avaliações

Para avaliações em larga escala com milhares de casos de teste:

Extensibilidade: Construa Recursos Personalizados

Asserções Personalizadas

Escreva asserções personalizadas para verificações específicas do domínio:

// assertions/customCheck.js
export default function customCheck(output, context) {
  const pass = output.includes('expected');
  return {
    pass,
    score: pass ? 1 : 0,
    reason: pass ? 'Output matched' : 'Missing expected content'
  };
}

Use em sua configuração:

assert:
  - type: file://assertions/customCheck.js

Servidor MCP

Promptfoo inclui um servidor Model Context Protocol (MCP) para integração com assistentes de IA como o Claude Code:

promptfoo mcp

Isso permite que agentes de IA:

Casos de Uso do Mundo Real

Chatbot de Suporte ao Cliente

Uma empresa SaaS usa o promptfoo para testar seu chatbot de suporte antes de cada implantação:

Resultado: Redução de 90% nos problemas relatados pelos clientes após a implementação de avaliações automatizadas.

Pipeline de Geração de Conteúdo

Uma equipe de marketing valida conteúdo gerado por IA para a voz da marca:

Resultado: Voz da marca consistente em todo o conteúdo com 40% menos custos de API.

Aplicação de Saúde

Uma startup de healthtech garante conformidade com testes rigorosos:

Resultado: Auditoria SOC 2 aprovada com avaliações promptfoo como evidência.

Conclusão

Promptfoo traz testes sistemáticos para aplicações de LLM. Ele substitui processos manuais e propensos a erros por avaliações automatizadas que detectam regressões, problemas de segurança e problemas de qualidade antes da implantação.

Principais pontos:

O futuro do desenvolvimento de IA é orientado a dados. Com o promptfoo, você tem as ferramentas para construir, testar e proteger aplicações de LLM em escala.

botão

Se você também trabalha com APIs, considere usar o Apidog junto com o promptfoo. O Apidog lida com design, teste e documentação de API, enquanto o promptfoo se concentra na avaliação de LLM. Juntos, eles cobrem toda a pilha de testes de aplicações modernas.

FAQ

Para que serve o promptfoo?

Promptfoo é usado para testar e avaliar aplicações de LLM. Ele executa testes automatizados em prompts, compara saídas entre modelos e realiza avaliações de "red-team" de segurança para encontrar vulnerabilidades.

O promptfoo é gratuito?

Sim, o promptfoo é de código aberto e licenciado sob MIT. Você pode usá-lo gratuitamente para projetos pessoais e comerciais. Recursos de nuvem e suporte empresarial podem exigir planos pagos.

Como faço para instalar o promptfoo?

Execute npm install -g promptfoo para instalação global. Você também pode usar npx promptfoo@latest sem instalar, ou instalar via brew install promptfoo no macOS ou pip install promptfoo para Python.

Quais modelos o promptfoo suporta?

Promptfoo suporta mais de 90 provedores de LLM, incluindo OpenAI (GPT-4, GPT-4o, o1), Anthropic (Claude 3.5/4/4.5), Google (Gemini), Microsoft (Azure OpenAI), Amazon Bedrock e modelos locais via Ollama.

Como faço para executar uma varredura de red team?

Execute promptfoo redteam init para criar uma configuração, então promptfoo redteam run para executar a varredura de segurança. Visualize os resultados com promptfoo redteam report.

Posso usar o promptfoo em CI/CD?

Sim. Instale o promptfoo em seu pipeline de CI e execute promptfoo eval com seu arquivo de configuração. Defina portões de qualidade com a opção threshold para fazer o CI falhar se as avaliações não atingirem as taxas de aprovação.

O promptfoo envia meus dados para servidores externos?

Não. O promptfoo executa 100% localmente por padrão. Seus prompts e dados de teste nunca saem da sua máquina, a menos que você opte explicitamente por recursos de nuvem. Os arquivos de cache e banco de dados são armazenados localmente.

Como faço para comparar modelos com o promptfoo?

Liste múltiplos provedores em seu arquivo de configuração, então execute promptfoo eval. Visualize a comparação na interface web com promptfoo view, que mostra as taxas de aprovação/falha, custos e latência para cada modelo.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar