0Pricing
AI Agents · Aula

Indexando um conjunto de documentos

Gere embeddings para cada parte e armazene os vetores em um índice — a etapa de preparação offline de qualquer sistema RAG.

Indexando um conjunto de documentos é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Fluxo de ingestão

O fluxo RAG off-line tem quatro etapas:

  1. Carregue os documentos (PDF, HTML, MD)
  2. Divida em trechos cada documento
  3. Gere a incorporação de cada trecho
  4. Armazene os vetores + metadados em um índice

Etapa 1: carregar documentos

Use carregadores especializados para formatos diferentes:

# PDFs
from pypdf import PdfReader
text = ''
for page in PdfReader('doc.pdf').pages:
    text += page.extract_text()

# HTML
from bs4 import BeautifulSoup
text = BeautifulSoup(html, 'html.parser').get_text()

# Markdown — just read the file
text = open('doc.md').read()

Etapa 2: dividir em trechos

Use o divisor da lição anterior:

from langchain.text_splitter import RecursiveCharacterTextSplitter
splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=100)
chunks = splitter.split_text(text)

Etapa 3: gerar incorporações em lotes

Gere incorporações de vários trechos por chamada à API:

from openai import OpenAI
client = OpenAI()

def embed_batch(texts, batch_size=100):
    vectors = []
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        resp = client.embeddings.create(model='text-embedding-3-small', input=batch)
        vectors.extend(d.embedding for d in resp.data)
    return vectors

Etapa 4: armazenar

Para 10 mil a 50 mil trechos, FAISS ou Chroma é suficiente:

import chromadb
client = chromadb.Client()
collection = client.create_collection('docs')

collection.add(
    ids=[f'doc-{i}' for i in range(len(chunks))],
    embeddings=vectors,
    documents=chunks,
    metadatas=[{'source': 'doc.pdf', 'page': i} for i in range(len(chunks))]
)

Ingestão idempotente

Faça com que a ingestão possa ser executada novamente com segurança. Use identificadores determinísticos (resumo do conteúdo) para que uma nova execução não crie duplicatas:

import hashlib

def chunk_id(source, text):
    h = hashlib.sha256(text.encode()).hexdigest()[:16]
    return f'{source}:{h}'

print(chunk_id('handbook.pdf', 'Employees get 20 vacation days per year.'))
print(chunk_id('handbook.pdf', 'Employees get 20 vacation days per year.'))

Atualizações incrementais

Quando um documento mudar:

  1. Calcule os novos trechos
  2. Compare-os com os identificadores existentes
  3. Exclua os removidos, adicione os novos e mantenha os inalterados

A abordagem ingênua (excluir tudo + inserir novamente) funciona bem para corpora pequenos, mas desperdiça chamadas à API de incorporação.

Metadados para filtragem

Inclua qualquer campo pelo qual você possa querer filtrar mais tarde:

metadata = {
    'source': '/docs/handbook.pdf',
    'page': 42,
    'department': 'engineering',
    'updated_at': '2024-08-12',
    'access_level': 'internal'
}
for k, v in metadata.items():
    print(f"{k}: {v}")

Progresso e pontos de verificação

Para ingestões grandes, registre o progresso e crie pontos de verificação:

for i, batch in enumerate(batches):
    embed_and_store(batch)
    if i % 10 == 0:
        save_checkpoint(i)
        print(f'Processed {i * 100} chunks')

Limites de taxa

As incorporações da OpenAI têm um limite de taxa alto, mas real. Use semáforos ou repetições com `tenacity`:

from asyncio import Semaphore
sem = Semaphore(10)  # 10 concurrent embed calls max

async def safe_embed(batch):
    async with sem:
        return await client.embeddings.create(...)

Verificação de integridade do índice

Após a ingestão, execute algumas consultas de teste e inspecione os resultados manualmente. Se nada relevante aparecer, a divisão em trechos ou a incorporação está com problema — descubra isso antes que os usuários descubram.

Versionamento do índice

Versione o índice para poder trocar o método de divisão em trechos ou o modelo de incorporação sem indisponibilidade:

collection = client.create_collection(f'docs-v2-{date.today()}')
# old collection stays live until new one is validated

Identificadores idempotentes

Por que usar resumos do conteúdo como identificadores dos trechos?

Recapitulação

Carregue -> divida em trechos -> gere incorporações -> armazene, usando identificadores idempotentes e metadados. O índice é a base de todas as etapas posteriores de recuperação.

Perguntas Frequentes

A aula “Indexando um conjunto de documentos” é grátis?

Sim — o texto completo de “Indexando um conjunto de documentos” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Indexando um conjunto de documentos”?

Gere embeddings para cada parte e armazene os vetores em um índice — a etapa de preparação offline de qualquer sistema RAG. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Indexando um conjunto de documentos”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. O que o RAG resolve (limite de conhecimento, alucinações)
  2. Estratégias de divisão em partes (fixa, por frase, semântica)
  3. Indexando um conjunto de documentos
  4. Construindo um RAG ingênuo com FAISS ou Chroma
← Voltar para AI Agents