Evals, Red Teaming e Geração de Testes para Sistemas Agênticos

Modular, Leve, Dinâmico e Async-first

Docs • Website • Comunidade

[!IMPORTANT] Giskard v3 é uma reescrita completa projetada para testes dinâmicos e multi-turno de agentes de IA. Esta versão elimina dependências pesadas para maior eficiência, ao mesmo tempo que introduz um scanner de vulnerabilidades de IA mais poderoso e uma avaliação RAG aprimorada — ambos agora disponíveis nativamente no giskard-scan, sem dependência da v2. Apenas o scan legado para modelos tabulares/ML permanece exclusivo da v2. Giskard v2 permanece disponível, mas não é mais mantido ativamente. Acompanhe o progresso → Leia o Anúncio da v3 · Roadmap

Instalação

pip install giskard           # checks (+ agents, llm, core)
pip install "giskard[scan]"   # + scan de vulnerabilidade / qualidade
pip install "giskard[openai]" # SDK do provedor para LLM judges / generators

Requer Python 3.12+.

Telemetria: análises agregadas opcionais via giskard-core. Nenhum prompt ou saída é enviado. Para desativar antes de importar o Giskard: export DO_NOT_TRACK=1 ou export GISKARD_TELEMETRY_DISABLED=1. Detalhes: giskard-core README.

Giskard é uma biblioteca Python de código aberto para testar e avaliar sistemas agênticos. A arquitetura v3 é um conjunto modular de pacotes focados — cada um carregando apenas as dependências de que precisa — construídos do zero para envolver qualquer coisa: um LLM, um agente de caixa-preta ou um pipeline de múltiplas etapas.

Estes são construídos sobre três bibliotecas fundamentais — giskard-core (utilitários compartilhados e telemetria), giskard-llm (roteamento de LLM agnóstico de provedor) e giskard-agents (orquestração de agentes e workflows) — que são instaladas automaticamente e raramente usadas diretamente.

Giskard Checks — crie e aplique evals para testar agentes

pip install giskard-checks

Giskard Checks é uma biblioteca leve para criar avaliações (evals) que testam sistemas baseados em LLM — desde asserções simples até avaliações LLM-as-judge. Diferentemente de testes unitários tradicionais, os evals são projetados para saídas não determinísticas, onde a mesma entrada pode produzir diferentes respostas válidas.

Use o Giskard Checks para:

• Detectar regressões — verifique se o seu sistema ainda se comporta corretamente após alterações
• Validar a qualidade do RAG — verifique se as respostas estão fundamentadas no contexto recuperado
• Aplicar regras de segurança — garanta que as saídas estejam em conformidade com suas políticas de conteúdo
• Avaliar agentes multi-turno — teste conversas completas, não apenas trocas individuais

Os evals integrados incluem correspondência de strings, comparações, regex, similaridade semântica e checks LLM-as-judge (Groundedness, Conformity, LLMJudge).

Conceitos

• Target — seu sistema sob teste: qualquer callable síncrono/assíncrono (inputs) -> outputs (opcionalmente com trace)
• Scenario — um eval: interações + checks
• Check — asserção ou LLM judge sobre o trace
• Suite — muitos cenários executados juntos

giskard.agents.Generator é um cliente LLM para workflows/judges — não é o mesmo que os geradores de entrada do giskard.checks (LLMGenerator) que sintetizam mensagens de usuário.

Início rápido

import asyncio
from giskard.checks import Scenario, Groundedness


def get_answer(inputs: str) -> str:
    return "Paris"  # substitua pelo seu modelo / agente


async def main() -> None:
    scenario = (
        Scenario("test_france_capital")
        .interact(inputs="What is the capital of France?", outputs=get_answer)
        .check(
            Groundedness(
                name="answer is grounded",
                context="France is in Western Europe. Its capital is Paris.",
            )
        )
    )
    result = await scenario.run()
    result.print_report()


asyncio.run(main())

Groundedness é um LLM judge — instale um extra de provedor (ex.: pip install "giskard[openai]") e defina a chave de API correspondente. Modelo padrão: openai/gpt-4o-mini.

Consulte a documentação completa para Suites, LLMJudge, cenários multi-turno e muito mais.

Giskard Scan — scanner de vulnerabilidades para agentes de IA

pip install "giskard[scan]"   # ou: pip install giskard-scan

Giskard Scan é a camada de red teaming e varredura de vulnerabilidades para sistemas agênticos. Ele gera suítes de testes adversariais automaticamente a partir de uma descrição em linguagem natural do seu agente, cobrindo injeção de prompt, conteúdo prejudicial, estereótipos, desinformação e muito mais.

Use o Giskard Scan para:

• Fazer red team no seu agente — gere automaticamente entradas adversariais nas categorias de ameaças do OWASP LLM Top-10
• Executar sondas de injeção de prompt — dataset integrado de payloads de injeção pronto para uso
• Estender com geradores personalizados — passe suas próprias instâncias de ScenarioGenerator para generate_suite, ou registre-as em vulnerability_suite_generator_registry

Início rápido

import asyncio
from giskard.scan import vulnerability_scan


async def my_agent(inputs: str) -> str:
    # Substitua pela chamada do seu agente / modelo
    return f"Echo: {inputs}"


async def main() -> None:
    await vulnerability_scan(
        target=my_agent,
        description="A customer support chatbot for an e-commerce platform.",
        languages=["en"],
    )


asyncio.run(main())

Os geradores de scan também precisam de um extra de provedor LLM e chave de API (igual aos judges do Checks acima).

Procurando pelo Giskard v2?

O Giskard v2 incluía Scan (detecção automática de vulnerabilidades) e RAGET (geração de conjuntos de teste para avaliação RAG).

Para agentes LLM, ambos são substituídos na v3 pelo giskard-scan: use vulnerability_scan no lugar do scan LLM da v2, e quality_scan (com KnowledgeBase) no lugar do RAGET.

A v3 também funciona com modelos de ML — envolva um como target e avalie-o com giskard-checks ou giskard-scan. O que os exemplos abaixo cobrem é o scan tabular automático exclusivo da v2 — a suíte de detectores que inspeciona um giskard.Model + giskard.Dataset para detectar automaticamente problemas de desempenho, viés e robustez — juntamente com a suíte de testes de ML giskard.testing e o Giskard Hub. Estes não estão planejados para a v3.

pip install "giskard[llm]>2,<3"

Scan — detecte automaticamente problemas de desempenho, viés e segurança

Envolva seu modelo e execute o scan:

import giskard
import pandas as pd


# Substitua my_llm_chain pela sua lógica real de cadeia LLM ou inferência de modelo
def model_predict(df: pd.DataFrame):
    """A função recebe um DataFrame e deve retornar uma lista de saídas (uma por linha)."""
    return [my_llm_chain.run({"query": question}) for question in df["question"]]


giskard_model = giskard.Model(
    model=model_predict,
    model_type="text_generation",
    name="My LLM Application",
    description="A question answering assistant",
    feature_names=["question"],
)

scan_results = giskard.scan(giskard_model)
display(scan_results)

RAGET — gere conjuntos de dados de avaliação para aplicações RAG

Gere automaticamente perguntas, respostas de referência e contexto a partir da sua base de conhecimento:

import pandas as pd
from giskard.rag import generate_testset, KnowledgeBase

# Carregue os documentos da sua base de conhecimento
df = pd.read_csv("path/to/your/knowledge_base.csv")
knowledge_base = KnowledgeBase.from_pandas(df, columns=["column_1", "column_2"])

testset = generate_testset(
    knowledge_base,
    num_questions=60,
    language="en",
    agent_description="A customer support chatbot for company X",
)

Documentação completa da v2

👋 Comunidade

Aceitamos contribuições da comunidade de IA! Leia este guia para começar e junte-se à nossa próspera comunidade no Discord.

Acompanhe o progresso e compartilhe feedback: Anúncio da v3 · Roadmap

🌟 Deixe-nos uma estrela, isso ajuda o projeto a ser descoberto por outras pessoas e nos mantém motivados a construir ferramentas open-source incríveis! 🌟

❤️ Se você achar nosso trabalho útil, considere nos patrocinar no GitHub. Com um patrocínio mensal, você pode obter um selo de patrocinador, exibir sua empresa neste readme e ter seus relatórios de bugs priorizados. Também oferecemos patrocínio único se você quiser que nos envolvamos em um projeto de consultoria, realizemos um workshop ou façamos uma palestra na sua empresa.