Noções Básicas de RAG
10 exemplos para você começar com Agentes de IA e RAG - 7 básicos e 3 intermediários.
Pré-requisitos
uv venv && source .venv/bin/activate
uv pip install "openai>=1.60" "chromadb>=0.5" "tiktoken>=0.8"
export OPENAI_API_KEY="sk-..."Exemplos Básicos
1. Dividir um Documento
Divida texto longo em pedaços de tamanho adequado para recuperação.
def chunk_text(text: str, size: int = 500, overlap: int = 50) -> list[str]:
chunks = []
start = 0
while start < len(text):
chunks.append(text[start:start + size])
start += size - overlap
return chunks- 500 caracteres com 50 de sobreposição é um ponto de partida para prosa.
- A sobreposição preserva o contexto entre os limites dos pedaços.
Relacionado: Chunking & Ingestion
2. Incorporar e Armazenar Pedaços
Crie vetores e salve em uma coleção.
import chromadb
from openai import OpenAI
client = OpenAI()
chroma = chromadb.Client()
collection = chroma.create_collection("docs")
texts = ["FastAPI é um framework web Python.", "pytest executa testes Python."]
emb = client.embeddings.create(model="text-embedding-3-small", input=texts)
collection.add(ids=["1","2"], documents=texts, embeddings=[e.embedding for e in emb.data])3. Recuperar Pedaços Relevantes
Consulte por similaridade semântica.
query = "Como eu testo Python?"
q_emb = client.embeddings.create(model="text-embedding-3-small", input=[query])
results = collection.query(query_embeddings=[q_emb.data[0].embedding], n_results=2)
print(results["documents"])4. Construir um Prompt Fundamentado
Injete o contexto recuperado no prompt do LLM.
context = "\n".join(results["documents"][0])
prompt = f"Responda usando APENAS este contexto:\n{context}\n\nPergunta: {query}"5. Gerar uma Resposta
Envie o prompt fundamentado para o LLM.
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
temperature=0,
)
print(response.choices[0].message.content)6. Função RAG de Ponta a Ponta
Combine recuperar + gerar.
def rag_answer(query: str, collection, k: int = 3) -> str:
q_emb = client.embeddings.create(model="text-embedding-3-small", input=[query])
hits = collection.query(query_embeddings=[q_emb.data[0].embedding], n_results=k)
context = "\n---\n".join(hits["documents"][0])
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Responda apenas com base no contexto. Diga 'Não sei' se não for encontrado."},
{"role": "user", "content": f"Contexto:\n{context}\n\nPergunta: {query}"},
],
temperature=0,
)
return resp.choices[0].message.content or ""7. Citar Fontes
Inclua IDs dos pedaços na resposta.
for i, (doc, meta) in enumerate(zip(hits["documents"][0], hits["metadatas"][0])):
print(f"[{i+1}] {doc[:80]}...")Exemplos Intermediários
8. Filtragem de Metadados
Filtre a recuperação por tipo de documento ou data.
collection.query(
query_embeddings=[q_emb.data[0].embedding],
n_results=3,
where={"source": "docs"},
)9. Conceito de Busca Híbrida
Combine pontuações de palavras-chave e semânticas.
- BM25 captura termos exatos; embeddings capturam paráfrases.
- Veja Retrieval & Re-ranking.
10. Avaliar Qualidade da Recuperação
Verifique se o pedaço correto aparece no top-k.
def recall_at_k(query: str, expected_text: str, k: int = 5) -> bool:
hits = collection.query(query_embeddings=[embed(query)], n_results=k)
return any(expected_text in doc for doc in hits["documents"][0])Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.