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.

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

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:

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

2. Navega até à pasta do projeto:

cd awesome-llm-apps

3. Instala as dependências:

npm install

Execução

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

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:

git commit -m "Adiciona nova funcionalidade"

4. Faz push da tua branch:

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.

cd rag_tutorials/rag_failure_diagnostics_clinic
pip install -r requirements.txt

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.

openai>=1.6.0

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

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"

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:

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.