# Clínica de Diagnóstico de Falhas RAG

> Cole uma descrição de bug real do seu pipeline LLM + RAG. O script pede a um LLM para classificar a falha num dos vários padrões reutilizáveis e sugere uma correção estrutural mínima (não apenas 'adicione mais contexto' ou 'tente um modelo melhor').

- Fonte: https://doutorai.pt/apps/rag-failure-diagnostics-clinic
- Categoria: RAG e Conhecimento
- Dificuldade: Médio
- Modelos: OpenAI, Llama
- Frameworks: LangChain
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY, SECRET_RAG_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# Clínica de Diagnóstico de Falhas RAG

Uma pequena **clínica de diagnóstico de falhas RAG** independente de framework.

Colas uma descrição de bug real do teu pipeline LLM + RAG.  
O script pede a um LLM para classificar a falha num dos vários **padrões reutilizáveis**  
e sugere uma **correção estrutural mínima** (não apenas “adiciona mais contexto” ou “experimenta um modelo melhor”).

O objetivo é mostrar uma forma orientada a padrões para depurar incidentes RAG que pode ser  
adaptada a qualquer stack: LangChain, LlamaIndex, microserviços personalizados ou infra-estrutura interna.

---

## O que vais aprender

Ao executar este exemplo, vais aprender a:

- Descrever **bugs RAG do mundo real** em texto simples para que um LLM possa raciocinar sobre eles.
- Usar uma pequena biblioteca de **padrões de falha** para triagem rápida de incidentes.
- Pedir ao modelo para propor **mudanças estruturais mínimas** em vez de meras alterações de prompt.
- Chamar uma **API compatível com OpenAI** a partir de um pequeno script Python.
- Guardar cada diagnóstico num relatório JSON para análise posterior ou post-mortems.

Isto não é um framework completo.  
É uma compacta **aplicação clínica** que demonstra um padrão que podes adaptar nas tuas próprias stacks.

---

## Estrutura de pastas

Este tutorial espera os seguintes ficheiros em `rag_tutorials/rag_failure_diagnostics_clinic`:

- `README.md` ← este ficheiro  
- `rag_failure_diagnostics_clinic.py` ← script CLI interativo mínimo  
- `requirements.txt` ← dependências Python  

O script é completamente autónomo.  
Todas as definições de padrões e prompts estão dentro desta pasta.

---

## Padrões de falha (P01–P12)

A clínica utiliza um pequeno conjunto opinativo de **12 padrões de falha reutilizáveis**.  
Cada bug é mapeado para exatamente um padrão primário, com candidatos secundários opcionais.

Podes modificar ou estender estes padrões para corresponder aos teus próprios incidentes de produção.

| ID   | Nome do padrão                                       | Sintoma típico                                               |
| ---- | ---------------------------------------------------- | ----------------------------------------------------------- |
| P01  | Alucinação de recuperação / desvio de fundamentação  | Resposta confiante contradiz documentos recuperados.       |
| P02  | Bug de limite de chunk ou segmentação                | Fatos relevantes são divididos ou truncados entre chunks.   |
| P03  | Desajuste de embedding / distância semântica vs vetorial | Similaridade cosseno não corresponde à verdadeira relevância. |
| P04  | Desvio ou obsolescência do índice                    | Dados antigos ou em falta, mesmo que a fonte de verdade esteja atualizada. |
| P05  | Reescrita de consulta ou desalinhamento do router    | Router envia consultas para a ferramenta ou conjunto de dados errados. |
| P06  | Desvio de raciocínio em cadeia longa                  | Tarefas de múltiplos passos perdem gradualmente o controle das restrições anteriores. |
| P07  | Uso indevido de chamadas de ferramentas ou ferramentas sem fundamentação | Ferramentas são chamadas com argumentos errados ou sem fundamentação. |
| P08  | Vazamento de memória de sessão / contexto em falta    | A conversa perde fatos importantes entre turnos ou sessões. |
| P09  | Pontos cegos na avaliação                             | O sistema passa em testes, mas falha em incidentes reais.  |
| P10  | Ordem de arranque / dependência não pronta           | Serviços falham ou 5xx durante os primeiros minutos após o deploy. |
| P11  | Desvio de configuração ou segredos entre ambientes   | Funciona localmente, quebra apenas em staging / produção devido a configurações. |
| P12  | Interferência multi-inquilino / multi-agente         | Pedidos ou agentes interferem no estado ou recursos uns dos outros. |

Os exemplos integrados correspondem aproximadamente a:

- Exemplo 1 → alucinação de recuperação / desvio de fundamentação (estilo P01).  
- Exemplo 2 → ordem de arranque / dependência não pronta (estilo P10).  
- Exemplo 3 → desvio de configuração ou segredos entre ambientes (estilo P11).

És encorajado a substituir estes por excertos dos teus próprios incidentes.

---

## Como funciona a clínica

A um alto nível:

1. O script constrói um **prompt do sistema** que explica os 12 padrões acima.
2. Escolhes um de três exemplos integrados ou colas a tua própria descrição de bug RAG / LLM.
3. O modelo é solicitado a:
   - Escolher um **ID de padrão primário** (P01–P12).  
   - Opcionalmente escolher até **dois candidatos secundários**.  
   - Explicar o raciocínio em breves pontos.  
   - Propor uma **correção estrutural mínima** (mudanças na recuperação, roteamento, avaliação ou infra-estrutura).  
4. A resposta completa é impressa no console e também guardada em  
   `rag_failure_report.json` juntamente com o texto original do bug e o nome do modelo.

A intenção é mostrar como um pequeno **vocabulário de padrões + prompt** pode transformar um LLM  
num ajudante leve para triagem de incidentes.

---

## Pré-requisitos

- Python 3.9 ou mais recente.
- Uma chave de API para qualquer endpoint de conclusão de chat **compatível com OpenAI**:
  - Por exemplo, `OPENAI_API_KEY` para `https://api.openai.com/v1`.
  - Ou a tua própria URL de proxy definida através de `OPENAI_BASE_URL`.
- Familiaridade básica com pipelines RAG, logs e modos de falha.

---

## Configuração

```markdown
# Instruções de Instalação

## Pré-requisitos

Antes de começares, certifica-te de que tens os seguintes pré-requisitos instalados:

- `Node.js` (versão 14 ou superior)
- `npm` (versão 6 ou superior)

## Instalação

1. Clona o repositório:

   ```bash
   git clone https://github.com/username/awesome-llm-apps.git
   ```

2. Navega até à pasta do projeto:

   ```bash
   cd awesome-llm-apps
   ```

3. Instala as dependências:

   ```bash
   npm install
   ```

## Execução

Para executar a aplicação, utiliza o seguinte comando:

```bash
npm start
```

A aplicação estará disponível em `http://localhost:3000`.

## Estrutura do Projeto

A estrutura do projeto é a seguinte:

```
awesome-llm-apps/
├── src/
│   ├── components/
│   ├── pages/
│   └── utils/
├── public/
│   └── index.html
├── package.json
└── README.md
```

## Contribuição

Se desejas contribuir para este projeto, segue os seguintes passos:

1. Cria um fork do repositório.
2. Cria uma nova branch para a tua funcionalidade:

   ```bash
   git checkout -b minha-funcionalidade
   ```

3. Faz as tuas alterações e commit:

   ```bash
   git commit -m "Adiciona nova funcionalidade"
   ```

4. Faz push da tua branch:

   ```bash
   git push origin minha-funcionalidade
   ```

5. Cria um Pull Request.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro [LICENSE](LICENSE) para mais informações.
```

```bash
cd rag_tutorials/rag_failure_diagnostics_clinic
pip install -r requirements.txt
```

```markdown
# Minimal `requirements.txt`

Para criar um ficheiro `requirements.txt` mínimo, basta incluir as bibliotecas que precisas para o teu projeto. Aqui está um exemplo básico:

```
flask
requests
numpy
```

## Como criar o `requirements.txt`

1. Cria um novo ficheiro chamado `requirements.txt` na raiz do teu projeto.
2. Adiciona as bibliotecas que necessitas, uma por linha.
3. Guarda o ficheiro.

## Instalar as dependências

Para instalar as dependências listadas no `requirements.txt`, utiliza o seguinte comando:

```
pip install -r requirements.txt
```

## Exemplo de `requirements.txt`

Aqui está um exemplo de um ficheiro `requirements.txt` mais completo:

```
flask==2.0.1
requests>=2.25.1
numpy<1.20
```

Neste exemplo, especificamos versões exatas ou intervalos de versões para garantir que o teu projeto funcione corretamente.

## Conclusão

Um `requirements.txt` bem definido é essencial para a gestão de dependências em projetos Python. Certifica-te de que o manténs atualizado à medida que adicionas ou removes bibliotecas do teu projeto.
```

```text
openai>=1.6.0
```

```markdown
Define a tua chave de API como uma variável de ambiente (recomendado):
```

```bash
export OPENAI_API_KEY="sk-..."
# optional, if you use a custom endpoint
# export OPENAI_BASE_URL="https://your-proxy.example.com/v1"
# export OPENAI_MODEL="gpt-4o-mini"
```

```markdown
> Dica: Se preferires o Colab, também podes copiar o ficheiro inteiro `rag_failure_diagnostics_clinic.py` para uma única célula do Colab e executá-lo lá.

---

## Executar a clínica

A partir de dentro de `rag_tutorials/rag_failure_diagnostics_clinic`:
```

```bash
python rag_failure_diagnostics_clinic.py
```

You will see a simple text UI:

* Se `OPENAI_API_KEY` não estiver definido, o script irá pedir uma chave de API.
* Podes manter a URL base por defeito (`https://api.openai.com/v1`) e o modelo (`gpt-4o`) ou substituí-los.
* Depois, escolhes:

  * `1` → exemplo de alucinação de recuperação incorporada (estilo P01).
  * `2` → exemplo de ordenação de startups (estilo P10).
  * `3` → exemplo de desvio de configuração / segredos (estilo P11).
  * `p` → cola a tua própria descrição de bug.

Cada execução imprime um diagnóstico e escreve um ficheiro `rag_failure_report.json` contendo o texto do bug, as definições do modelo e a resposta do assistente.

Podes comprometer vários relatórios no teu próprio repositório como uma leve **biblioteca de incidentes RAG**.

---

## Extender este tutorial

Algumas ideias para estender este padrão:

* Substituir os exemplos por incidentes anonimizados dos teus próprios registos.
* Adicionar mais padrões ou dividir os existentes para corresponder à tua stack.
* Emitir um esquema JSON mais rico (gravidade, proprietários, componentes suspeitos).
* Integrar os relatórios num painel de avaliação ou rastreador de incidentes.

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/rag-failure-diagnostics-clinic