mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-05-03 00:02:36 +00:00
Add pt-BR docs translation (#3039)
* docs: add pt-br translations Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator * Update mcp/overview.mdx brazilian docs Its en-US counterpart was updated after I did a pass, so now it includes the new section about @CrewBase
This commit is contained in:
Daniel Barreto
250
docs/pt-BR/enterprise/features/hallucination-guardrail.mdx
Normal file
250
docs/pt-BR/enterprise/features/hallucination-guardrail.mdx
Normal file
@@ -0,0 +1,250 @@
|
||||
---
|
||||
title: Proteção contra Alucinações
|
||||
description: "Previna e detecte alucinações de IA nas suas tarefas do CrewAI"
|
||||
icon: "shield-check"
|
||||
---
|
||||
|
||||
## 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
|
||||
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
|
||||
from crewai import LLM
|
||||
|
||||
# Uso básico - utiliza o expected_output da tarefa como contexto
|
||||
guardrail = HallucinationGuardrail(
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
|
||||
# Com contexto de referência explícito
|
||||
context_guardrail = HallucinationGuardrail(
|
||||
context="AI helps with various tasks including analysis and generation.",
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
```
|
||||
|
||||
### Adicionando às Tarefas
|
||||
|
||||
```python
|
||||
from crewai import Task
|
||||
|
||||
# Crie sua tarefa com a proteção
|
||||
task = Task(
|
||||
description="Write a summary about AI capabilities",
|
||||
expected_output="A factual summary based on the provided context",
|
||||
agent=my_agent,
|
||||
guardrail=guardrail # 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
|
||||
# Proteção rigorosa exigindo alta pontuação de fidelidade
|
||||
strict_guardrail = HallucinationGuardrail(
|
||||
context="Quantum computing uses qubits that exist in superposition states.",
|
||||
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
|
||||
# Proteção com contexto de resposta da ferramenta
|
||||
weather_guardrail = HallucinationGuardrail(
|
||||
context="Current weather information for the requested location",
|
||||
llm=LLM(model="gpt-4o-mini"),
|
||||
tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
|
||||
)
|
||||
```
|
||||
|
||||
## 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
|
||||
# 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
|
||||
# Fluxo de validação de saída da tarefa
|
||||
task_output = agent.execute_task(task)
|
||||
validation_result = guardrail(task_output)
|
||||
|
||||
if validation_result.valid:
|
||||
# Tarefa concluída com sucesso
|
||||
return task_output
|
||||
else:
|
||||
# Tarefa falha com feedback de validação
|
||||
raise ValidationError(validation_result.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
|
||||
|
||||
<Steps>
|
||||
<Step title="Forneça Contexto Abrangente">
|
||||
Inclua todas as informações factuais relevantes nas quais a IA deve basear sua saída:
|
||||
|
||||
```python
|
||||
context = """
|
||||
Company XYZ was founded in 2020 and specializes in renewable energy solutions.
|
||||
They have 150 employees and generated $50M revenue in 2023.
|
||||
Their main products include solar panels and wind turbines.
|
||||
"""
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Mantenha o Contexto Relevante">
|
||||
Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão:
|
||||
|
||||
```python
|
||||
# Bom: Contexto focado
|
||||
context = "The current weather in New York is 18°C with light rain."
|
||||
|
||||
# Evite: Informações irrelevantes
|
||||
context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Atualize o Contexto Regularmente">
|
||||
Certifique-se de que seu contexto de referência reflita informações atuais e precisas.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Seleção de Limiar
|
||||
|
||||
<Steps>
|
||||
<Step title="Comece com a Validação Padrão">
|
||||
Inicie sem limiares personalizados para entender a performance inicial.
|
||||
</Step>
|
||||
|
||||
<Step title="Ajuste Conforme as Necessidades">
|
||||
- **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
|
||||
</Step>
|
||||
|
||||
<Step title="Monitore e Itere">
|
||||
Acompanhe os resultados da validação e ajuste os limiares conforme falsos positivos/negativos.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 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
|
||||
|
||||
<Accordion title="Validação Sempre Falha">
|
||||
**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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Falsos Positivos (Conteúdo Válido Marcado como Inválido)">
|
||||
**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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Erros 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
|
||||
</Accordion>
|
||||
|
||||
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nosso suporte para assistência na configuração ou solução de problemas da proteção contra alucinações.
|
||||
</Card>
|
||||
Reference in New Issue
Block a user