DEV Community

Cover image for Como Testar Aplicações LLM: Guia Completo do Promptfoo (2026)
Lucas
Lucas

Posted on • Originally published at apidog.com

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

#ai #testing #llm #opensource

Em Resumo

Promptfoo é um framework open source para avaliação e red-teaming de LLMs, projetado para desenvolvedores que precisam testar aplicações de IA de forma sistemática. Suporta mais de 90 provedores de modelos, conta com 67+ plugins de ataque de segurança e roda 100% localmente para garantir privacidade. Já são mais de 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. Para começar, execute:

npm install -g promptfoo
promptfoo init --example getting-started
Enter fullscreen mode Exit fullscreen mode

Experimente o Apidog hoje mesmo

Introdução

Após semanas construindo seu chatbot de suporte com IA, ele parece perfeito no desenvolvimento. Mas, quando usuários reais começam a usar, surgem vazamentos de dados, bypass nas proteções e respostas inconsistentes.

Esse cenário é comum: aplicações de LLM são lançadas após testes manuais ou baseados em intuição, só para quebreiras e falhas apareçam em produção. O custo para corrigir depois é muito maior do que detectar durante o desenvolvimento.

Promptfoo resolve isso trazendo testes automatizados e sistemáticos para aplicações LLM. Permite avaliar prompts em múltiplos modelos, executar red-teaming de segurança e detectar regressões antes do deploy.

Neste guia prático, você vai aprender a configurar avaliações, executar checagens de segurança, integrar com CI/CD e evitar armadilhas comuns — tudo com exemplos e comandos prontos para uso.

No final, você terá um conjunto de testes funcional para sua aplicação LLM e confiança para lançar em produção.

💡 Se você também valida APIs junto dos testes de LLM, o Apidog entrega uma plataforma unificada para design, teste e documentação de API. Use promptfoo para LLMs e Apidog para camada de API — juntos cobrem toda a stack de testes.

O Que É Promptfoo e Por Que Usar

Promptfoo é uma ferramenta CLI e biblioteca Node.js para avaliação e red-teaming de aplicações LLM. Ele funciona como um framework de testes adaptado para IA.

Promptfoo matrix

Ferramentas tradicionais falham ao testar LLMs — as saídas não são determinísticas. Não dá para fazer comparação de string exata quando o mesmo prompt gera respostas distintas. Promptfoo resolve com:

  • Asserções semânticas: valida sentido, não só texto.
  • Avaliação por LLM: um modelo avalia a saída de outro.
  • Comparação multi-modelo: rode o mesmo prompt em GPT-4, Claude, etc.
  • Plugins de segurança: detecta vulnerabilidades automaticamente.

Tudo roda localmente. Nenhum dado sai do seu ambiente, a menos que você ative recursos de nuvem — ideal para dados sensíveis.

O Problema

A maioria das equipes faz testes manuais em aplicações LLM: envia prompts, lê respostas e toma decisões subjetivas. Isso gera três falhas graves:

  1. Sem detecção de regressão: atualizações podem quebrar funções existentes sem aviso.
  2. Cobertura fraca: testes manuais ignoram casos de borda e entradas adversas.
  3. Sem métricas: não há acompanhamento de melhorias ou comparativos entre modelos.

Promptfoo automatiza tudo. Você define casos de teste uma vez, roda em qualquer modelo, obtém taxas de aprovação/falha, comparativos de custo e latência.

Quem Usa Promptfoo

Com 1.6M+ downloads, promptfoo está em aplicações LLM que atendem mais de 10 milhões de usuários. Casos típicos:

  • Chatbots de suporte que exigem respostas consistentes
  • Pipelines de geração de conteúdo com tom/voz definidos
  • Aplicações de saúde e fintech com exigências de compliance
  • Sistemas sensíveis à segurança contra vazamentos de dados

Desde março de 2026, promptfoo integra o portfólio OpenAI, mas permanece open source/MIT e com desenvolvimento ativo.

Começando: Instalação e Primeira Avaliação

Você pode instalar promptfoo globalmente ou usar via npx.

Instalação 

# Global (recomendado)
npm install -g promptfoo

# Ou rodar sem instalar
npx promptfoo@latest

# macOS via Homebrew
brew install promptfoo

# Python
pip install promptfoo
Enter fullscreen mode Exit fullscreen mode

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

export OPENAI_API_KEY=sk-abc123
export ANTHROPIC_API_KEY=sk-ant-xxx
Enter fullscreen mode Exit fullscreen mode

Criar Primeira Avaliação

Inicialize um projeto de exemplo:

promptfoo init --example getting-started
cd getting-started
Enter fullscreen mode Exit fullscreen mode

Isso cria promptfooconfig.yaml com exemplos de prompts, provedores e testes.

Execute a avaliação:

promptfoo eval
Enter fullscreen mode Exit fullscreen mode

Visualize os resultados na interface web:

promptfoo view
Enter fullscreen mode Exit fullscreen mode

A interface web abre em localhost:3000: veja comparações lado a lado das saídas de cada modelo, aprovados/reprovados por asserção.

Estrutura do Arquivo de Configuração

Exemplo de promptfooconfig.yaml:

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
Enter fullscreen mode Exit fullscreen mode
  • prompts: arquivos ou texto inline para testar
  • providers: modelos LLM (mais de 90 disponíveis)
  • tests: casos de teste com variáveis e asserções

Mantenha sua configuração versionada e execute em CI/CD a cada pull request.

Principais Recursos do Promptfoo

1. Avaliações Automatizadas

Defina casos de teste e resultados esperados, execute contra múltiplos modelos.

Tipos de Asserção

Promptfoo oferece 30+ tipos de asserção nativos:

Asserção Propósito
contains Saída contém substring
equals Match exato de string
regex Validação regex
json-schema Validação de estrutura JSON
javascript Função JS customizada aprova/reprova
python Função Python customizada
llm-rubric LLM avalia saída
similar Similaridade semântica
latency Resposta abaixo de limite
cost Custo por requisição abaixo de 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
Enter fullscreen mode Exit fullscreen mode

Avaliação por LLM

Use o tipo llm-rubric para avaliações subjetivas (ex: tom, utilidade):

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

Você pode configurar um modelo mais econômico como avaliador.

2. Red Teaming e Testes de Segurança

Promptfoo automatiza testes adversariais com mais de 67 plugins de ataque.

Promptfoo Red Team

Vetores de Ataque

Categoria O Que Testa
Injeção de Prompt Ataques diretos, indiretos, de contexto
Jailbreaks DAN, troca de persona, desviando roles
Exfiltração de Dados SSRF, vazamento de prompt
Conteúdo Nocivo Discurso de ódio, atividades perigosas, autoagressão
Conformidade Vazamento de PII, violações HIPAA, dados financeiros
Áudio/Visual Injeção e ataques multimodais

Como Executar 

promptfoo redteam init
promptfoo redteam run
promptfoo redteam report [diretório]
Enter fullscreen mode Exit fullscreen mode

Fluxo:

  1. Gera ataques dinâmicos para sua aplicação
  2. Avalia e pontua vulnerabilidades

Resultados incluem severidade (Crítico, Alto, Médio, Baixo), exemplos exploráveis e recomendações.

Exemplo de saída:

Vulnerability Summary:
- Crítico: 2 (vazamento de PII, extração de prompt)
- Alto: 5 (jailbreaks, injeção)
- Médio: 12 (viés, inconsistências)
- Baixo: 23 (violações menores)
Enter fullscreen mode Exit fullscreen mode

Corrija falhas críticas antes do deploy. Repita o redteam após correções.

3. Escaneamento de Pull Requests

Integre em GitHub Actions para escanear PRs e prevenir problemas de segurança:

# .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 }}
Enter fullscreen mode Exit fullscreen mode

Detecta:

  • Chaves de API hardcoded
  • Prompts inseguros
  • Falta de validação de entrada
  • Vetores de injeção de prompt

4. Comparação de Modelos

Compare outputs de diferentes modelos lado a lado.

# Avaliação multi-modelo
promptfoo eval

# Visualização web
promptfoo view
Enter fullscreen mode Exit fullscreen mode

A interface mostra:

  • Taxa de aprovação/falha por modelo
  • Custo por 1000 requisições
  • Latência média
  • Diferenças qualitativas de saída

Baseie sua escolha de modelo em dados, não em achismos.

Provedores Suportados: +90 Integrações LLM

Teste o mesmo prompt em OpenAI, Anthropic, Google, Amazon, modelos locais sem trocar código.

Provedores Populares

Provedor Modelos
OpenAI GPT-4, GPT-4o, GPT-4o-mini, o1, o3
Anthropic Claude 3.5/3.7/4.5/4.6, 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
Ollama Modelos locais (Llama, Mistral, Phi)

Provedores Customizados

Implemente provedores em Python ou JS se necessário.

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
            }
        }
Enter fullscreen mode Exit fullscreen mode

JavaScript:

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

Registre em sua config:

providers:
  - id: file://custom_provider.py
    config:
      api_key: ${MY_API_KEY}
Enter fullscreen mode Exit fullscreen mode

CLI: Comandos Essenciais

Comandos 

# Avaliações
promptfoo eval -c promptfooconfig.yaml

# Interface web
promptfoo view

# Compartilhar resultados
promptfoo share

# 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>
Enter fullscreen mode Exit fullscreen mode

Flags Úteis 

--no-cache              # Desabilita cache (sempre resultado novo)
--max-concurrency <n>   # Limita chamadas paralelas
--output <file>         # Salva resultado em JSON
--verbose               # Log detalhado
--env-file <path>       # Carrega variáveis de ambiente
--filter <pattern>      # Roda testes específicos
Enter fullscreen mode Exit fullscreen mode

Exemplo: Avaliação Customizada 

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

Integração CI/CD: Teste LLMs em Pipeline

Inclua promptfoo em seu CI/CD para detectar regressões automaticamente.

Exemplo 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 }}
Enter fullscreen mode Exit fullscreen mode

Portões de Qualidade

Defina limites mínimos de aprovação:

commandLineOptions:
  threshold: 0.8  # Exige 80% de aprovação
Enter fullscreen mode Exit fullscreen mode

CI falha se não atingir o threshold.

Cache em CI

Acelere execuções com cache:

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

Interface Web: Visualização e Compartilhamento

A interface web (promptfoo view) permite:

  • Matriz de avaliação: outputs lado a lado
  • Filtragem: encontre testes por status ou provedor
  • Visualização de diferenças: compare execuções
  • Compartilhamento: gere links para revisão em equipe
  • Atualização em tempo real: veja execuções ao vivo

Roda em localhost:3000 com proteção CSRF por padrão. Não exponha a redes não confiáveis. Para equipe, use promptfoo share para upload na nuvem ou hospede com autenticação.

Banco de Dados e Cache

Localização do Cache

  • macOS/Linux: ~/.cache/promptfoo
  • Windows: %LOCALAPPDATA%\promptfoo

Use --no-cache no desenvolvimento para garantir resultados sempre atualizados.

Localização do Banco de Dados

  • Todas as plataformas: ~/.promptfoo/promptfoo.db (SQLite)

O banco de dados registra execuções históricas para comparação/análise. Exclua apenas se quiser perder histórico.

Modelo de Segurança

Promptfoo adota modelo de confiança por configuração.

Entradas Confiáveis (executam código)

  • Arquivos de configuração (promptfooconfig.yaml)
  • Asserções JS/Python/Ruby customizadas
  • Configs de provedores
  • Funções de transformação

Entradas Não Confiáveis (apenas dados)

  • Texto de prompt
  • Variáveis de teste
  • Saídas dos modelos
  • Conteúdo remoto acessado

Recomendações de Segurança

Para ambientes críticos:

  1. Execute em container/VM isolada
  2. Use chaves de API mínimas
  3. Não armazene segredos em prompts/configuração
  4. Restrinja saída de rede para código de terceiros
  5. Não exponha o servidor web local

Desempenho: Otimizando Avaliações

Dicas

  1. Use cache para acelerar execuções repetidas
  2. Ajuste concorrência com --max-concurrency
  3. Filtre testes com --filter durante desenvolvimento
  4. Amostre dados com --repeat e subconjuntos antes de rodar tudo

Escalando

Para milhares de testes:

  • Use o scheduler (src/scheduler/) para execuções distribuídas
  • Geração remota para offload de processamento
  • Exporte resultados para Google Sheets para visibilidade

Extensibilidade: Recursos Customizados

Asserções Customizadas

Exemplo em JS:

// 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'
  };
}
Enter fullscreen mode Exit fullscreen mode

Use na config:

assert:
  - type: file://assertions/customCheck.js
Enter fullscreen mode Exit fullscreen mode

Servidor MCP

Rode servidor Model Context Protocol para integração com assistentes de IA:

promptfoo mcp
Enter fullscreen mode Exit fullscreen mode

Permite:

  • Executar avaliações via chat
  • Acessar red team
  • Consultar resultados
  • Gerar novos testes

Casos de Uso Reais

Chatbot de Suporte

  • 500+ testes de perguntas comuns
  • Avaliação entre GPT-4 e Claude
  • Red team para PII e jailbreaks
  • CI bloqueia deploy com falhas

Resultado: 90% menos problemas relatados após automação.

Pipeline de Conteúdo

  • Avaliação por LLM de tom/estilo
  • Limites de latência
  • Monitoramento de custos
  • Comparação de modelos

Resultado: voz da marca consistente e 40% menos custo.

Aplicação de Saúde

  • Red team para HIPAA
  • Asserções médicas customizadas
  • Execução local para privacidade
  • Trilhas de auditoria

Resultado: aprovação SOC 2 usando promptfoo.

Conclusão

Promptfoo automatiza testes para aplicações LLM, substituindo processos manuais e inseguros por avaliações sistemáticas que detectam regressões, falhas de segurança e problemas de qualidade antes do deploy.

Resumo de ações:

  • Instale com npm install -g promptfoo e inicie com promptfoo init
  • Use asserções semânticas, não só match exato
  • Rode red team para segurança
  • Integre com CI/CD para garantir qualidade
  • Compare modelos de forma objetiva
  • Estenda funcionalidade com provedores/asserções customizadas

O desenvolvimento de IA precisa ser orientado a dados — promptfoo oferece as ferramentas para construir, testar e proteger aplicações LLM em produção.

Se você também testa APIs, use o Apidog junto com promptfoo. O Apidog cobre design, teste e documentação de APIs, enquanto promptfoo foca em LLM — juntos, cobrem toda a camada de testes de aplicações modernas.

FAQ

Para que serve o promptfoo?

Promptfoo é para testar e avaliar aplicações LLM: executa testes automatizados em prompts, compara saídas de diferentes modelos e realiza red-teaming para identificar vulnerabilidades.

O promptfoo é gratuito?

Sim, é open source sob licença MIT. Uso livre para projetos pessoais e comerciais. Recursos de nuvem e suporte empresarial podem ser pagos.

Como instalar promptfoo?

Execute npm install -g promptfoo (global). Ou use npx promptfoo@latest, brew install promptfoo (macOS) ou pip install promptfoo (Python).

Quais modelos o promptfoo suporta?

Mais de 90 provedores: OpenAI (GPT-4, GPT-4o, o1), Anthropic (Claude 3.5/4/4.5), Google (Gemini), Microsoft (Azure), Amazon Bedrock, modelos locais via Ollama, entre outros.

Como executar um red team?

Rode:

promptfoo redteam init
promptfoo redteam run
promptfoo redteam report
Enter fullscreen mode Exit fullscreen mode

Posso usar promptfoo em CI/CD?

Sim. Instale no pipeline e execute promptfoo eval com seu arquivo de config. Use threshold para definir portão de qualidade.

Promptfoo envia meus dados para fora?

Não. Por padrão, roda 100% local/localhost. Dados só saem se você ativar recursos de nuvem manualmente. Cache e banco de dados são locais.

Como comparar modelos no promptfoo?

Adicione múltiplos provedores na config e execute promptfoo eval. Veja a comparação na web (promptfoo view), com taxas de aprovação/falha, custo e latência por modelo.

Top comments (0)