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

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

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.

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

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

export OPENAI_API_KEY=sk-abc123

export ANTHROPIC_API_KEY=sk-ant-xxx

Criar Primeira Avaliação

Inicialize um projeto de exemplo:

promptfoo init --example getting-started

cd getting-started

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

Execute a avaliação:

promptfoo eval

Visualize os resultados na interface web:

promptfoo view

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

• 
  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:

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

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"

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.

Vetores de Ataque

Como Executar

promptfoo redteam init

promptfoo redteam run

promptfoo redteam report [diretório]

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)

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 }}

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

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

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

            }

        }

JavaScript:

// customProvider.js

export default class CustomProvider {

  async callApi(prompt) {

    return {

      output: await myApi.generate(prompt),

      tokenUsage: { total: 50, prompt: 20, completion: 30 }

    };

  }

}

Registre em sua config:

providers:

  - id: file://custom_provider.py

    config:

      api_key: ${MY_API_KEY}

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>

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

Exemplo: Avaliação Customizada

promptfoo eval \

  -c promptfooconfig.yaml \

  --no-cache \

  --max-concurrency 3 \

  --output results.json \

  --env-file .env

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 }}

Portões de Qualidade

Defina limites mínimos de aprovação:

commandLineOptions:

  threshold: 0.8  # Exige 80% de aprovação

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') }}

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'

  };

}

Use na config:

assert:

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

Servidor MCP

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

promptfoo mcp

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

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.