LlamaIndex YouTube Transcripts: Query un Set di Video

Una pipeline LlamaIndex di trascrizioni YouTube è tre step: recupera trascrizioni come oggetti Document, costruisci un VectorStoreIndex, fai domande su tutti i video contemporaneamente. Ecco il tutto in uno script, più il gotcha di chunking che rovina la maggior parte dei primi tentativi.

Recupera trascrizioni come Documents

Gestisco youtube2text.org, un'API REST che restituisce trascrizioni YouTube come JSON — nessun scraping dal tuo IP, che importa nel momento in cui questo viene eseguito da qualsiasi parte al di là del tuo laptop (vedi perché i scraper locali vengono bloccati se sei curioso). Un GET per video:

import requests
from llama_index.core import Document, VectorStoreIndex

API_KEY = "yt_your_key_here"

VIDEOS = [
    "https://www.youtube.com/watch?v=VIDEO_ID_1",
    "https://www.youtube.com/watch?v=VIDEO_ID_2",
    "https://www.youtube.com/watch?v=VIDEO_ID_3",
]

def fetch_transcript(url: str) -> dict:
    resp = requests.get(
        "https://youtube2text.org/api/transcribe",
        params={"url": url},
        headers={"x-api-key": API_KEY},
        timeout=90,
    )
    resp.raise_for_status()
    return resp.json()["result"]

docs = []
for url in VIDEOS:
    r = fetch_transcript(url)
    docs.append(Document(
        text=r["content"],
        metadata={"videoId": r["videoId"], "title": r["title"]},
    ))

Per una chiave, accedi con Google su youtube2text.org/app/keys, o estrai la chiave demo condivisa da GET https://youtube2text.org/api/demo-key (5 video/mese per IP — va bene per questo esempio di tre video, non per un canale).

Il gotcha di chunking: le didascalie auto-generate non hanno punteggiatura

Il parser di nodi predefinito di LlamaIndex è SentenceSplitter, che trova i confini dei chunk alle terminazioni delle frasi. Le didascalie caricate manualmente ne hanno. Le didascalie generate automaticamente frequentemente no — ottieni quaranta minuti di testo minuscolo senza periodi, SentenceSplitter non trova nulla su cui dividere, e finisci con chunk gonfi e goffi.

La divisione basata su token aggira completamente il problema:

from llama_index.core.node_parser import TokenTextSplitter

splitter = TokenTextSplitter(chunk_size=512, chunk_overlap=64)

512 token con 64 di sovrapposizione è stato il sweet spot nei miei test: abbastanza grande che un chunk trasporta un pensiero completo, abbastanza piccolo che il recupero rimane preciso.

Costruisci l'indice e interrogalo

index = VectorStoreIndex.from_documents(docs, transformations=[splitter])
query_engine = index.as_query_engine(similarity_top_k=4)

response = query_engine.query("What did they say about pricing changes?")
print(response)

for node in response.source_nodes:
    meta = node.metadata
    print(f'- {meta["title"]} (https://www.youtube.com/watch?v={meta["videoId"]})')

Perché ogni Document trasporta videoId e title in metadata, ogni chunk recuperato sa da quale video proveniva — source_nodes ti dà link funzionanti alle fonti. Questo usa qualunque modello di incorporamento e LLM hai configurato in Settings; la configurazione OpenAI predefinita funziona out-of-the-box se OPENAI_API_KEY è impostato.

La limitazione che dovresti conoscere

L'API restituisce trascrizioni come testo semplice senza timestamp, quindi le tue citazioni si risolvono in un video, non in un momento all'interno di esso. "Questo reclamo proviene dal video della panoramica degli utili Q3" è realizzabile; "alle 14:32" non lo è. Per la maggior parte dei casi d'uso di Q&A l'attribuzione a livello di video è sufficiente, e onestamente, il testo del chunk più un link video porta un umano nel punto giusto in meno di un minuto.

Nota anche i due codici di errore che meritano di essere gestiti nel loop di recupero: TRANSCRIPT_UNAVAILABLE (404, video senza didascalie — salta), e RATE_LIMIT_EXCEEDED (429, viene con retryAfterSeconds nel corpo dell'errore).

Scalare oltre una manciata di video

Tre video è una demo. Per un intero canale desideri il feed RSS per la scoperta di video, il recupero consapevole della quota e un vector store persistente — tratto quella pipeline in RAG su un canale YouTube. Utente di LangChain invece? Stesso modello di loader, diverso framework.

Il livello gratuito copre 5 video al mese; il piano pro ne fa 500 per $ 9,99, che indicizza comodamente la maggior parte dei canali. Chiavi su youtube2text.org/app/keys.