RAG e Base de Conhecimento

O Eitri Agents oferece suporte nativo a RAG (Retrieval-Augmented Generation), permitindo que seus agentes tenham acesso a uma base de conhecimento específica e respondam perguntas com contexto relevante.

O que é RAG?

RAG (Retrieval-Augmented Generation) é uma técnica que combina:

1. Recuperação de informações: Busca documentos relevantes em uma base de conhecimento
2. Geração de texto: Usa um modelo de linguagem para gerar respostas baseadas nos documentos recuperados

Isso permite que o agente responda perguntas com informações específicas do seu domínio, sem precisar retreinar o modelo.

Como Funciona

1. Você adiciona seus documentos na pasta agents/rag/ do projeto
2. A CLI do Eitri gera os embeddings (representações vetoriais) e salva em public/embeddings/
3. Em runtime, o hook carrega os embeddings pré-computados do arquivo JSON
4. Quando o usuário faz uma pergunta, o sistema:
   • Gera um embedding para a pergunta
   • Busca os documentos mais similares usando similaridade cosseno
   • Enriquece o prompt com o contexto relevante
   • Envia para o modelo gerar a resposta

Configuração

1. Preparar os Documentos

Adicione seus documentos na pasta agents/rag/ do projeto. Os formatos suportados são:

• .json
• .csv
• .txt

agents/
└── rag/
    ├── produtos.json
    ├── faq.txt
    └── catalogo.csv

2. Configurar a Geração de Embeddings (opcional)

Crie o arquivo agents/rag-config.json para controlar como os documentos são divididos em chunks durante a geração dos embeddings:

{
    "csv": { "chunk_size": 1000, "overlap": 10 },
    "txt": { "chunk_size": 500, "overlap": 50 },
    "json": { "chunk_size": 800, "overlap": 20 }
}

Cada chave corresponde a um tipo de arquivo. Os campos disponíveis são:

Campo	Descrição
chunk_size	Tamanho máximo de cada chunk em caracteres. Documentos maiores que esse valor são divididos em pedaços menores antes de gerar o embedding.
overlap	Quantidade de caracteres compartilhados entre chunks consecutivos. Evita que informações no limite entre dois chunks sejam perdidas.

Se o arquivo não existir ou um tipo de arquivo não estiver configurado, a CLI usa valores padrão.

3. Gerar os Embeddings

Com a CLI do Eitri atualizada, execute o comando para gerar os embeddings:

eitri agents generate:rag

Esse comando processa os arquivos em agents/rag/ e gera os embeddings correspondentes em public/embeddings/:

public/
└── embeddings/
    ├── produtos.json
    ├── faq.json
    └── catalogo.json

Os arquivos em public/embeddings/ devem ser commitados junto com o projeto, pois são servidos em runtime.

3. Configurar o Agente

Configure o agente com a opção knowledgeOptions para customizar o comportamento do RAG:

import useAgent from 'eitri-agents';

const agent = useAgent('MeuAgente', {
    llm: 'openai',
    model: 'gpt-4',
    knowledgeOptions: {
        basePrompt: 'Use o contexto abaixo para responder a pergunta de forma precisa:',
        topK: 5,
        minScore: 0.3,
        metric: 'cosine',
    },
});

4. Inicializar a Base de Conhecimento

Use o método initializeKnowledgeBase passando o nome do arquivo de embeddings (sem extensão):

import { useEffect, useState } from 'react';

export default function MyComponent() {
    const [isInitializing, setIsInitializing] = useState(true);
    const agent = useAgent('MeuAgente', {
        llm: 'openai',
        knowledgeOptions: {
            basePrompt: 'Use o contexto abaixo para responder:',
        },
    });

    useEffect(() => {
        const initKnowledge = async () => {
            try {
                setIsInitializing(true);
                await agent.initializeKnowledgeBase('produtos'); // carrega public/embeddings/produtos.json
                console.log('Base de conhecimento inicializada!');
            } catch (error) {
                console.error('Erro ao inicializar:', error);
            } finally {
                setIsInitializing(false);
            }
        };

        initKnowledge();
    }, []);

    // ... resto do componente
}

5. Fazer Perguntas

Após a inicialização, use o agente normalmente. O sistema automaticamente enriquecerá as perguntas com contexto relevante:

const handleQuestion = async (question: string) => {
    try {
        const response = await agent.call({
            content: question,
        });
        console.log('Resposta:', response.message);
    } catch (error) {
        console.error('Erro:', error);
    }
};

Exemplo Completo

import React, { useState, useEffect } from 'react';
import useAgent from 'eitri-agents';

export default function RAGExample() {
    const [question, setQuestion] = useState('');
    const [answer, setAnswer] = useState('');
    const [isInitializing, setIsInitializing] = useState(true);

    const agent = useAgent('DocumentationAgent', {
        llm: 'openai',
        model: 'gpt-4',
        knowledgeOptions: {
            basePrompt: 'Use o contexto abaixo para responder de forma precisa e detalhada:',
        },
    });

    useEffect(() => {
        const init = async () => {
            try {
                setIsInitializing(true);
                await agent.initializeKnowledgeBase('minha-base'); // carrega public/embeddings/minha-base.json
            } catch (error) {
                console.error('Erro ao inicializar:', error);
            } finally {
                setIsInitializing(false);
            }
        };
        init();
    }, []);

    const handleAsk = async () => {
        if (!question.trim()) return;

        try {
            const response = await agent.call({
                content: question,
            });
            setAnswer(response.message);
        } catch (error) {
            console.error('Erro ao processar pergunta:', error);
        }
    };

    if (isInitializing) {
        return <View>Carregando base de conhecimento...</View>;
    }

    return (
        <View>
            <h1>Sistema de Perguntas e Respostas</h1>
            <input
                type="text"
                value={question}
                onChange={(e) => setQuestion(e.target.value)}
                placeholder="Faça uma pergunta..."
            />
            <button onClick={handleAsk}>Perguntar</button>
            {answer && <View>{answer}</View>}
        </View>
    );
}

Propriedades do Knowledge

O agente expõe o objeto knowledge com informações úteis:

const agent = useAgent('MyAgent');

// Verificar se está inicializado
if (agent.knowledge.isInitialized) {
    console.log('Base de conhecimento pronta!');
}

// Verificar se está carregando
if (agent.knowledge.isLoading) {
    console.log('Carregando...');
}

// Obter quantidade de documentos
const total = agent.knowledge.size();
console.log(`Total de documentos: ${total}`);

// Limpar a base de conhecimento
agent.knowledge.clearKnowledgeBase();

Gerenciamento de Estado

Exemplo de componente com controle completo do estado:

export default function RAGApp() {
    const agent = useAgent('MyAgent', {
        llm: 'openai',
        knowledgeOptions: {
            basePrompt: 'Responda baseado no contexto:',
        },
    });

    return (
        <View>
            {agent.knowledge.isLoading && <p>Carregando base de conhecimento...</p>}

            {agent.knowledge.isInitialized && (
                <View>
                    <Text>Base pronta com {agent.knowledge.size()} documentos</Text>
                    <Button onClick={agent.knowledge.clearKnowledgeBase}>Limpar Base</Button>
                </View>
            )}
        </View>
    );
}

Opções de Configuração (knowledgeOptions)

Opção	Tipo	Padrão	Descrição
basePrompt	string	'Use the context below to answer the question accurately:'	Texto prefixado ao contexto recuperado antes da pergunta
topK	number	5	Número de documentos mais similares a recuperar
metric	'cosine' | 'l2'	'cosine'	Métrica de similaridade usada na busca vetorial
minScore	number	0.3	Score mínimo de similaridade para incluir um resultado no contexto

Busca por Similaridade

O sistema usa similaridade cosseno por padrão para encontrar os documentos mais relevantes:

• Busca os top 5 documentos mais similares (topK)
• Filtra resultados com score acima de 0.3 (minScore)
• Combina os documentos encontrados em um único contexto

Melhores Práticas

1. Inicialize uma vez: Inicialize a base de conhecimento apenas uma vez no useEffect
2. Documentos granulares: Divida informações grandes em documentos menores para melhor precisão
3. Regenere ao alterar dados: Sempre rode eitri agents generate:rag após modificar os arquivos em agents/rag/
4. Controle de estado: Sempre controle o estado de inicialização para melhor UX
5. Tratamento de erros: Implemente tratamento de erros robusto na inicialização
6. Texto limpo: Use texto claro e bem estruturado nos documentos
7. Prompt customizado: Ajuste o basePrompt para seu caso de uso específico

Limitações

• Os embeddings são pré-computados via CLI — é necessário ter a CLI do Eitri atualizada e rodar eitri agents generate:rag sempre que os documentos mudarem
• Formatos de arquivo suportados em agents/rag/: .json, .csv e .txt
• A base de conhecimento é carregada em memória em runtime (usa cache no storage do Eitri entre sessões)
• Ideal para conjuntos de dados pequenos a médios (centenas a milhares de documentos)