Hugging Face's logo

Spaces:
guifav
/
rag_template
Sleeping

App Files Community
rag_template / docs /tutorials /01_getting_started.md
Guilherme Favaron
Sync: Complete project update (Phase 6) - API, Metadata, Eval, Docs
a686b1b
preview code
|
raw
history blame contribute delete
7.6 kB

A newer version of the Gradio SDK is available: 6.5.0

Upgrade

RAG do Zero - Primeiros Passos

Guia completo para iniciar com o RAG Template em 15 minutos.

Tempo estimado: 15-20 minutos Nivel: Iniciante Pre-requisitos: Python 3.10+ instalado

O que e RAG?

RAG (Retrieval-Augmented Generation) combina:

  • Retrieval (Recuperacao): Buscar informacao relevante em documentos
  • Augmented (Aumentada): Enriquecer o contexto da IA
  • Generation (Geracao): LLM gera resposta baseada no contexto

Em termos simples: E como dar "memoria" e conhecimento especializado para uma IA.

Exemplo pratico:

  • Sem RAG: "Qual e a politica de ferias da empresa?" → IA chuta ou diz "nao sei"
  • Com RAG: IA busca no manual RH → "Segundo o manual, sao 30 dias apos 1 ano"

Passo 1: Instalacao

1.1 Clonar o Repositorio 

git clone https://github.com/guifav/rag_template.git
cd rag_template

1.2 Criar Ambiente Virtual 

# Linux/Mac
python -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

1.3 Instalar Dependencias 

pip install -r requirements.txt

Isso instala:

  • Gradio (interface web)
  • PostgreSQL driver (banco de dados)
  • Sentence Transformers (embeddings)
  • E outras dependencias

Tempo: ~2-3 minutos

Passo 2: Configurar Banco de Dados

Voce tem 3 opcoes. Recomendamos Neon para iniciantes (10GB gratis).

Opcao A: Neon.tech (Recomendado)

  1. Crie conta em neon.tech
  2. Crie novo projeto
  3. No SQL Editor, execute:
CREATE EXTENSION vector;
  1. Copie a connection string
  2. Use o script de setup:
python scripts/setup_neon.py

Tempo: ~3-5 minutos

Opcao B: Supabase 

python scripts/setup_supabase.py

Opcao C: Docker Local 

docker-compose up -d

Veja guias completos:

Passo 3: Configurar Variave is de Ambiente

3.1 Criar arquivo .env 

cp .env.example .env

3.2 Editar .env

Abra .env e configure:

# Banco de dados (use a connection string do passo 2)
DATABASE_URL=postgresql://user:pass@host:port/db

# Hugging Face (obrigatorio para LLM)
HF_TOKEN=seu_token_aqui

# Opcional: outros providers
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

Como obter HF_TOKEN:

  1. Crie conta em huggingface.co
  2. Va para Settings → Access Tokens
  3. Crie novo token (permissao "read")
  4. Copie e cole no .env

Tempo: ~2 minutos

Passo 4: Executar a Aplicacao 

python app.py

Voce vera:

Running on local URL:  http://127.0.0.1:7860

Abra esse link no navegador!

Tempo de inicio: 10-30 segundos (baixa modelos na primeira vez)

Passo 5: Primeira Ingestao de Documentos

Agora vamos adicionar documentos ao sistema.

5.1 Preparar Documento

Crie um arquivo teste.txt com algum conteudo:

A empresa XYZ foi fundada em 2020.
Nossa missao e tornar a tecnologia acessivel.
Oferecemos 30 dias de ferias apos 1 ano de empresa.
O horario de trabalho e das 9h as 18h.
Temos escritorios em Sao Paulo e Rio de Janeiro.

5.2 Fazer Upload

  1. Na interface, va para aba "Ingestao de Documentos"
  2. Clique em "Browse" e selecione teste.txt
  3. Deixe configuracoes padrao:
    • Estrategia: Tamanho Fixo
    • Chunk Size: 1000
    • Overlap: 200
  4. Clique em "Iniciar Ingestao"

Voce vera o processo:

  1. Extraindo texto (instantaneo para TXT)
  2. Dividindo em chunks (1 chunk para texto pequeno)
  3. Gerando embeddings (~1-2 segundos)
  4. Salvando no banco (instantaneo)

Resultado: "Ingestao concluida! 1 documento(s) processado(s)"

Passo 6: Primeira Consulta

Agora vamos buscar informacao nos documentos.

6.1 Busca Simples

  1. Va para aba "Exploracao da Base"
  2. Digite uma query: ferias da empresa
  3. Clique em "Buscar"

Voce vera:

  • Documento encontrado
  • Score de similaridade (~0.7-0.9)
  • Conteudo: "Oferecemos 30 dias de ferias..."

O que aconteceu:

  1. Sua query foi transformada em embedding
  2. Sistema buscou embeddings similares no banco
  3. Retornou documentos mais relevantes

Passo 7: Primeiro Chat com RAG

Hora de conversar com seus documentos!

7.1 Configurar Chat

  1. Va para aba "Chat RAG"
  2. Configuracoes:
    • LLM Provider: HuggingFace
    • Top K: 3
    • Temperature: 0.3
    • Max Tokens: 256

7.2 Fazer Pergunta

Digite: Quantos dias de ferias a empresa oferece?

Clique em "Enviar"

Resposta esperada:

A empresa oferece 30 dias de ferias apos 1 ano de trabalho.

Contextos recuperados:
1. "Oferecemos 30 dias de ferias apos 1 ano de empresa." (score: 0.85)

O que aconteceu:

  1. Sistema buscou contextos relevantes (top 3)
  2. Montou um prompt com contexto + pergunta
  3. Enviou para LLM (HuggingFace API)
  4. LLM gerou resposta baseada no contexto

Tempo de resposta: 2-5 segundos (dependendo da API)

Passo 8: Experimentar Parametros

Agora vamos entender o impacto dos parametros.

8.1 Testar Top K

  1. Va para aba "Playground de Parametros"
  2. Config A: top_k = 1
  3. Config B: top_k = 5
  4. Query: horario de trabalho
  5. Compare resultados

Observacao: Mais contexto (top_k maior) pode ajudar, mas tambem pode trazer ruido.

8.2 Testar Temperature

  1. Config A: temperature = 0.1 (deterministico)
  2. Config B: temperature = 0.9 (criativo)
  3. Mesma query
  4. Compare

Observacao: Temperature baixa = respostas mais precisas. Temperature alta = respostas mais variadas/criativas.

Passo 9: Monitorar Uso

  1. Va para aba "Monitoramento"
  2. Veja estatisticas:
    • Documentos no banco: 1
    • Queries realizadas: ~3
    • Latencias medias

Proximos Passos

Parabens! Voce criou seu primeiro sistema RAG. Agora:

  1. Adicione mais documentos: PDFs, mais TXTs
  2. Teste estrategias de chunking: Veja Tutorial 2
  3. Experimente features avancadas: Hybrid search, reranking
  4. Deploy: Tutorial 3

Troubleshooting

"Unable to connect to database"

Problema: DATABASE_URL incorreto

Solucao:

  1. Verifique .env
  2. Teste conexao: python scripts/setup_neon.py
  3. Certifique-se que banco esta ativo

"HF_TOKEN invalid"

Problema: Token HuggingFace invalido

Solucao:

  1. Gere novo token em huggingface.co/settings/tokens
  2. Certifique-se de copiar token completo
  3. Atualize .env

"Model download failed"

Problema: Erro ao baixar modelo de embedding

Solucao:

  1. Verifique conexao com internet
  2. Aguarde alguns minutos e tente novamente
  3. Modelos sao baixados apenas na primeira vez

App muito lento

Causas comuns:

  • HuggingFace API em horario de pico
  • Database remoto com latencia alta
  • Modelo de embedding ainda baixando

Solucao:

  • Use modelo de embedding menor (384d)
  • Configure connection pooling
  • Considere usar OpenAI/Anthropic para LLM

Recursos Adicionais

Resumo

Neste tutorial voce:

  • Instalou o RAG Template
  • Configurou banco de dados (Neon/Supabase)
  • Fez primeira ingestao de documento
  • Realizou primeira busca semantica
  • Conversou com seus documentos usando LLM
  • Experimentou com parametros

Tempo total: ~15-20 minutos

Proximo: Otimizando seu RAG