0Pricing
AI Agents · Lezione

Indicizzare un insieme di documenti

Generi un embedding per ogni chunk e memorizzi i vettori in un indice: la fase di preparazione offline di ogni sistema RAG.

Indicizzare un insieme di documenti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Pipeline di ingestione

La pipeline RAG offline comprende quattro passaggi:

  1. Caricamento dei documenti (PDF, HTML, MD)
  2. Suddivisione in chunk di ogni documento
  3. Creazione degli embedding di ogni chunk
  4. Memorizzazione dei vettori e dei metadati in un indice

Passaggio 1: Caricamento dei documenti

Utilizzi loader specializzati per i diversi formati:

# 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()

Passaggio 2: Suddivisione in chunk

Utilizzi lo splitter della lezione precedente:

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

Passaggio 3: Creazione degli embedding in batch

Crei gli embedding di molti chunk per ogni chiamata 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

Passaggio 4: Memorizzazione

Per 10k-50k chunk, FAISS o Chroma sono sufficienti:

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))]
)

Ingestione idempotente

Renda l'ingestione sicura da rieseguire. Utilizzi ID deterministici (hash del contenuto) in modo che una nuova esecuzione non crei duplicati:

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.'))

Aggiornamenti incrementali

Quando cambia un documento:

  1. Calcoli i nuovi chunk
  2. Li confronti con gli ID esistenti
  3. Elimini quelli rimossi, aggiunga quelli nuovi e mantenga invariati quelli non modificati

L'approccio ingenuo (eliminare tutto e reinserire) va bene per corpus piccoli, ma spreca chiamate all'API di embedding.

Metadati per il filtraggio

Includa ogni campo per il quale potrebbe voler applicare un filtro in seguito:

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}")

Avanzamento e checkpoint

Per ingestioni di grandi dimensioni, registri l'avanzamento e crei checkpoint:

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

Limiti di frequenza

Gli embedding di OpenAI hanno un limite di frequenza elevato, ma reale. Utilizzi semafori o i retry di `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 dell'indice

Dopo l'ingestione, esegua alcune query di prova e controlli manualmente i risultati. Se non emerge nulla di pertinente, la suddivisione in chunk o la creazione degli embedding non funziona: lo scopra prima degli utenti.

Versionamento dell'indice

Versioni l'indice per poter passare a una nuova suddivisione in chunk o a un nuovo modello di embedding senza tempi di inattività:

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

ID idempotenti

Perché usare gli hash del contenuto come ID dei chunk?

Riepilogo

Caricare -> suddividere in chunk -> creare gli embedding -> memorizzare, usando ID idempotenti e metadati. L'indice è la base di ogni passaggio successivo di recupero.

Domande Frequenti

La lezione «Indicizzare un insieme di documenti» è gratuita?

Sì — il testo completo di «Indicizzare un insieme di documenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Indicizzare un insieme di documenti»?

Generi un embedding per ogni chunk e memorizzi i vettori in un indice: la fase di preparazione offline di ogni sistema RAG. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Indicizzare un insieme di documenti»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Cosa risolve RAG (limite di conoscenza e allucinazioni)
  2. Strategie di chunking (fisso, per frasi, semantico)
  3. Indicizzare un insieme di documenti
  4. Creare un RAG ingenuo con FAISS o Chroma
← Torna a AI Agents