Contextos e RAG — Guia do usuário | YoBench

Para que serve o módulo «Contextos e RAG»

O módulo transforma seus documentos em bases de conhecimento disponíveis para o AI Chat. Você cria um contexto, sobe arquivos (PDF, DOCX, XLSX, CSV, imagens) ou texto; o módulo divide automaticamente o conteúdo em chunks, calcula embeddings via o provedor escolhido e armazena os vetores em uma LanceDB local. Ao consultar o chat, o YoBench busca os chunks mais relevantes e os injeta no system prompt — o modelo responde a partir dos seus documentos, não só do conhecimento geral.

O que você obtém:

• Bases de conhecimento nomeadas — um contexto por projeto/tema.
• Formatos suportados — PDF, DOCX, XLSX/XLS, CSV, TXT, MD, imagens (PNG, JPG, GIF, WebP). Imagens e PDFs passam pelo OCR embutido; XLSX/CSV são convertidos em texto plano por planilha.
• LanceDB local — vetores ficam em userData/lancedb/, uma tabela por contexto (ctx_{id}).
• Múltiplos provedores de embeddings — OpenAI, LM Studio, Ollama (qualquer endpoint compatível OpenAI). Exatamente um está ativo; trocá-lo marca todos os contextos como stale e dispara reindexação assíncrona.
• Integração com AI Chat — chunks relevantes são injetados automaticamente no system prompt na primeira mensagem do usuário.

Estrutura de dados

• Contexto — name, embedding_provider_id, embedding_model (snapshot), vectorization_status (ready / stale / indexing / error).
• Itens do contexto — unidades de conteúdo carregado: tipo (text / file / image / module_ref), content, metadados do arquivo, chunk_count.
• Vetores (LanceDB) — tabela ctx_{id} com item_id, chunk_index, text, vector.

Provedores de embeddings

Em Gerenciador de contextos → Provedores de embeddings você adiciona um provedor:

• Nome — rótulo livre.
• Base URL — endpoint /v1/embeddings compatível OpenAI. Exemplos:
  • OpenAI: https://api.openai.com/v1, modelo text-embedding-3-small.
  • LM Studio (local): http://localhost:1234/v1, modelo text-embedding-nomic-embed-text-v1.5.
  • Ollama (local): http://localhost:11434/v1, modelo bge-m3.
• API key — quando preciso (servidores locais geralmente vazio).
• Modelo — nome do modelo de embedding no servidor.

Um provedor é marcado ativo — usado para todos os contextos. Trocar o provedor ou o modelo ativo marca todos os contextos como stale e dispara reindexação em segundo plano.

Chunking e busca

Parâmetros de chunking estão fixos no código:

• Chunking heading-aware — para Markdown e texto estruturado, o divisor usa os títulos como pontos de corte para manter cada chunk como unidade semântica. Para texto puro, recorre a chunks de tamanho fixo.
• Sobreposição entre chunks adjacentes — preserva o contexto na fronteira.
• Top-K na busca — 5 chunks por padrão por consulta.

Não são expostos na UI — estão calibrados para modelos típicos.

Modos de busca

Cada sessão de chat escolhe um dos dois modos de busca:

• Rápido (padrão) — busca híbrida (vetor + palavra-chave) no contexto. Retorna resultados em frações de segundo; ideal para perguntas do dia a dia.
• Preciso — a mesma busca híbrida, seguida de um reranker que reordena os melhores candidatos por relevância. Um pouco mais lento, bem melhor em consultas longas ou ambíguas.

Formatos suportados

Integração com AI Chat

No AI Chat você escolhe um contexto para a conversa. Na primeira mensagem do usuário o módulo:

1. Envia sua consulta como frase de busca para a LanceDB.
2. Obtém os top-K chunks do contexto.
3. Formata-os como bloco Markdown (# Reference context: {name} + ## [N] {title} + texto do chunk).
4. Injeta o bloco no system prompt junto com cabeçalho e instruções.

Nos turnos seguintes o retrieval não se repete (o contexto já está no system prompt).

O retrieval é pulado quando:

• O contexto está em indexing (ainda não pronto).
• Não há provedor de embeddings ativo.
• O snapshot do modelo no contexto não bate com o ativo — aguarde a reindexação terminar.

Nesses casos o chat continua funcionando, só sem injeção de contexto.

Configurações globais

Não há chaves context* dedicadas nas configurações centrais — toda a configuração fica no banco (tabelas embedding_providers e contexts). Gerenciado pelo próprio módulo.

Fluxo de uso

1. Conecte um provedor de embeddings

1. Abra Gerenciador de contextos no menu lateral esquerdo.
2. Vá em Provedores de embeddings.
3. Adicione um provedor: nome, Base URL, API key, modelo.
4. Marque como ativo.

2. Crie um contexto

1. Na página inicial do módulo clique em Novo contexto.
2. Nomeie (por exemplo, «Documentação do produto», «Corpus jurídico»).
3. Salve.

3. Suba documentos

1. No contexto clique em Adicionar arquivo ou arraste um arquivo para o painel.
2. Formatos: PDF, DOCX, XLSX, CSV, TXT, MD, PNG/JPG/GIF/WebP.
3. Você também pode colar texto diretamente ou vincular artigos via o módulo RSS.
4. Aguarde a indexação terminar (o badge muda para «Vetores atualizados»).

4. Conecte o contexto ao chat

No AI Chat escolha o contexto nas configurações da sessão. Pergunte — o modelo responderá a partir dos seus documentos.

5. Gerencie o contexto

• Remover item — tira um documento específico do contexto.
• Reindexar — força a reconstrução dos vetores.
• Excluir contexto — remove junto com sua tabela na LanceDB.

Próximos passos

• Configure provedores de IA para geração de respostas.
• Use o módulo RSS para alimentar contextos com artigos.
• O Web Parser pode raspar sites em JSON que você importa para um contexto.

Ajuda e feedback

Quer embeddings locais por padrão ou chunking configurável pela UI? Escreva para nós pelo formulário de contato.