LlamaIndex sépare plusieurs responsabilités. Comprendre ces objets évite de traiter le RAG comme une boîte noire.
Documents et Nodes
Un Document représente une source chargée : fichier, page, réponse d’API ou enregistrement. L’indexation le découpe en Node, unité plus petite contenant du texte, des métadonnées et des relations vers la source. La taille et le chevauchement des nodes influencent directement la récupération.
Index
Un index organise les nodes pour les rendre interrogeables. VectorStoreIndex calcule ou reçoit leurs embeddings puis les stocke dans une base vectorielle. L’index ne constitue pas nécessairement la source de vérité : conservez les documents originaux et une stratégie de synchronisation.
from llama_index.core import Document, VectorStoreIndex
documents = [
Document(text="Payload est un CMS headless.", metadata={"source": "fiche-payload"}),
Document(text="vLLM sert des modèles via une API.", metadata={"source": "fiche-vllm"}),
]
index = VectorStoreIndex.from_documents(documents)Retriever
Le retriever reçoit une requête et renvoie des nodes classés, sans rédiger la réponse.
retriever = index.as_retriever(similarity_top_k=2)
nodes = retriever.retrieve("Quel outil sert des modèles ?")
for item in nodes:
print(item.score, item.node.metadata)Ce niveau est idéal pour mesurer rappel et précision, appliquer des filtres de métadonnées ou ajouter un reranker.
Query engine
Le query engine combine récupération et synthèse par un modèle. Il est pratique, mais inspectez toujours source_nodes pour comprendre sur quoi repose la réponse.
Choisissez similarity_top_k à partir d’un jeu d’évaluation. Trop peu de nodes omet des preuves ; trop de nodes ajoute du bruit, coûte du contexte et peut dégrader la fidélité. Filtrez les permissions avant la recherche, pas après la génération.