> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Proteção contra Alucinações
> Previna e detecte alucinações de IA nas suas tarefas do CrewAI
## Visão Geral
A Proteção contra Alucinações é um recurso empresarial que valida o conteúdo gerado por IA para garantir que esteja fundamentado em fatos e não contenha alucinações. Ela analisa as saídas das tarefas em relação ao contexto de referência e fornece feedback detalhado quando é detectado conteúdo potencialmente alucinado.
## O que são Alucinações?
Alucinações em IA ocorrem quando modelos de linguagem geram conteúdos que parecem plausíveis, mas estão factualmente incorretos ou não são suportados pelo contexto fornecido. A Proteção contra Alucinações ajuda a prevenir esses problemas por meio de:
* Comparação das saídas com o contexto de referência
* Avaliação da fidelidade ao material de origem
* Fornecimento de feedback detalhado sobre conteúdo problemático
* Suporte a limiares personalizados para rigor da validação
## Uso Básico
### Configurando a Proteção
```python theme={null}
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
from crewai import LLM
# Uso básico - utiliza o expected_output da tarefa como contexto
protecao = HallucinationGuardrail(
llm=LLM(model="gpt-4o-mini")
)
# Com contexto de referência explícito
protecao_com_contexto = HallucinationGuardrail(
context="IA ajuda em várias tarefas, incluindo análise e geração.",
llm=LLM(model="gpt-4o-mini")
)
```
### Adicionando às Tarefas
```python theme={null}
from crewai import Task
# Crie sua tarefa com a proteção
minha_tarefa = Task(
description="Escreva um resumo sobre as capacidades da IA",
expected_output="Um resumo factual baseado no contexto fornecido",
agent=meu_agente,
guardrail=protecao # Adiciona a proteção para validar a saída
)
```
## Configuração Avançada
### Validação com Limiar Personalizado
Para validação mais rigorosa, é possível definir um limiar de fidelidade personalizado (escala de 0-10):
```python theme={null}
# Proteção rigorosa exigindo alta pontuação de fidelidade
protecao_rigorosa = HallucinationGuardrail(
context="Computação quântica utiliza qubits que existem em estados de superposição.",
llm=LLM(model="gpt-4o-mini"),
threshold=8.0 # Requer pontuação >= 8 para validar
)
```
### Incluindo Contexto da Resposta de Ferramentas
Se sua tarefa utiliza ferramentas, você pode incluir as respostas das ferramentas para validação mais precisa:
```python theme={null}
# Proteção com contexto de resposta da ferramenta
protecao_clima = HallucinationGuardrail(
context="Informações meteorológicas atuais para o local solicitado",
llm=LLM(model="gpt-4o-mini"),
tool_response="API do Clima retornou: Temperatura 22°C, Umidade 65%, Céu limpo"
)
```
## Como Funciona
### Processo de Validação
1. **Análise de Contexto**: A proteção compara a saída da tarefa com o contexto de referência fornecido
2. **Pontuação de Fidelidade**: Usa um avaliador interno para atribuir uma pontuação de fidelidade (0-10)
3. **Determinação do Veredito**: Determina se o conteúdo é fiel ou contém alucinações
4. **Verificação de Limiar**: Se um limiar personalizado for definido, valida contra essa pontuação
5. **Geração de Feedback**: Fornece motivos detalhados caso a validação falhe
### Lógica de Validação
* **Modo Padrão**: Utiliza validação baseada em veredito (FIÉL vs ALUCINADO)
* **Modo com Limiar**: Requer que a pontuação de fidelidade atinja ou supere o limiar especificado
* **Tratamento de Erros**: Lida com erros de avaliação de forma elegante e fornece feedback informativo
## Resultados da Proteção
A proteção retorna resultados estruturados indicando o status da validação:
```python theme={null}
# Exemplo de estrutura de resultado da proteção
{
"valid": False,
"feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
}
```
### Propriedades do Resultado
* **valid**: Booleano indicando se a saída passou na validação
* **feedback**: Explicação detalhada quando a validação falha, incluindo:
* Pontuação de fidelidade
* Classificação do veredito
* Motivos específicos para a falha
## Integração com o Sistema de Tarefas
### Validação Automática
Quando uma proteção é adicionada à tarefa, ela valida automaticamente a saída antes da tarefa ser marcada como concluída:
```python theme={null}
# Fluxo de validação de saída da tarefa
task_output = meu_agente.execute_task(minha_tarefa)
resultado_validacao = protecao(task_output)
if resultado_validacao.valid:
# Tarefa concluída com sucesso
return task_output
else:
# Tarefa falha com feedback de validação
raise ValidationError(resultado_validacao.feedback)
```
### Rastreamento de Eventos
A proteção se integra ao sistema de eventos do CrewAI para fornecer observabilidade:
* **Validação Iniciada**: Quando a avaliação da proteção começa
* **Validação Concluída**: Quando a avaliação termina com resultados
* **Falha na Validação**: Quando ocorrem erros técnicos durante a avaliação
## Melhores Práticas
### Diretrizes para o Contexto
Inclua todas as informações factuais relevantes nas quais a IA deve basear sua saída:
```python theme={null}
contexto = """
Empresa XYZ foi fundada em 2020 e é especializada em soluções de energia renovável.
Possui 150 funcionários e faturou R$ 50 milhões em 2023.
Seus principais produtos incluem painéis solares e turbinas eólicas.
"""
```
Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão:
```python theme={null}
# Bom: Contexto focado
contexto = "O clima atual em Nova York é 18°C com chuva leve."
# Evite: Informações irrelevantes
contexto = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
```
Certifique-se de que seu contexto de referência reflita informações atuais e precisas.
### Seleção de Limiar
Inicie sem limiares personalizados para entender a performance inicial.
* **Conteúdo crítico**: Use limiar 8-10 para máxima precisão
* **Conteúdo geral**: Use limiar 6-7 para validação equilibrada
* **Conteúdo criativo**: Use limiar 4-5 ou validação padrão baseada em veredito
Acompanhe os resultados da validação e ajuste os limiares conforme falsos positivos/negativos.
## Considerações de Performance
### Impacto no Tempo de Execução
* **Sobrecarga de Validação**: Cada proteção adiciona \~1-3 segundos por tarefa
* **Eficiência do LLM**: Escolha modelos eficientes para avaliação (ex: gpt-4o-mini)
### Otimização de Custos
* **Seleção de Modelo**: Utilize modelos menores e eficientes para avaliação da proteção
* **Tamanho do Contexto**: Mantenha o contexto de referência conciso, mas abrangente
* **Cache**: Considere armazenar resultados de validação para conteúdos repetidos
## Solução de Problemas
**Possíveis Causas:**
* Contexto muito restrito ou não relacionado à saída da tarefa
* Limiar configurado alto demais para o tipo de conteúdo
* Contexto de referência desatualizado
**Soluções:**
* Revise e atualize o contexto para corresponder aos requisitos da tarefa
* Reduza o limiar ou utilize validação padrão baseada em veredito
* Certifique-se de que o contexto esteja atual e correto
**Possíveis Causas:**
* Limiar alto demais para tarefas criativas ou interpretativas
* Contexto não cobre todos os aspectos válidos da saída
* Modelo de avaliação excessivamente conservador
**Soluções:**
* Reduza o limiar ou utilize validação padrão
* Expanda o contexto para incluir um espectro maior do conteúdo aceitável
* Teste com diferentes modelos de avaliação
**Possíveis Causas:**
* Problemas de conexão de rede
* Modelo LLM indisponível ou com limite de uso
* Saída ou contexto da tarefa em formato inadequado
**Soluções:**
* Verifique a conectividade de rede e o status do serviço LLM
* Implemente lógica de retentativas para falhas transitórias
* Valide o formato da saída da tarefa antes da avaliação da proteção
Entre em contato com nosso suporte para assistência na configuração ou solução de problemas da proteção contra alucinações.