LlamaIndex en pratique

#LlamaIndex en pratique : à quoi sert-il, et quand l'adopter

LlamaIndex est un framework Python qui prend en charge toute la chaîne d'un RAG : charger des documents, les découper en morceaux (nodes), les transformer en vecteurs, les indexer, puis interroger l'index avec un LLM qui cite ses sources. La version 0.14.25, publiée sur PyPI le 21 septembre 2026, demande Python 3.10 ou plus. Un RAG minimal tient en une dizaine de lignes ; le framework prend son intérêt quand il faut varier les sources, changer de mode de réponse, ajouter un reranker ou brancher un agent. En local, il fonctionne avec Ollama pour le LLM et un modèle d'embeddings de votre choix, à condition de désactiver ses réglages par défaut, qui appellent OpenAI. Ce guide monte un RAG entièrement local, montre les réglages qui comptent et corrige plusieurs exemples périmés que l'on trouve encore en ligne.

Abstractions claires

Document, Node, VectorStoreIndex, retriever, query engine : chaque étape du RAG a un objet dédié, remplaçable.

Connecteurs de données

SimpleDirectoryReader lit PDF, Word, PowerPoint, Markdown, images ou audio ; d'autres lecteurs couvrent Notion, Google Docs, Slack ou Discord.

Modes de requête

Plusieurs stratégies de synthèse et des moteurs plus élaborés (sous-questions, routage entre index) pour dépasser la simple recherche vectorielle.

Local possible

Ollama et les embeddings Hugging Face ou Ollama se branchent via des paquets d'intégration dédiés.

#Les étapes d'un RAG LlamaIndex et leurs réglages par défaut

Avant d'écrire du code, retenez le pipeline et surtout ses valeurs par défaut : c'est là que se cachent la plupart des surprises en local.

#Installation pour un RAG 100 % local

La commande pip install llama-index installe un lot de démarrage qui contient llama-index-core, les intégrations OpenAI pour le LLM et les embeddings, et les lecteurs de fichiers. Pour le local, ajoutez les intégrations Ollama et d'embeddings (llama-index-embeddings-ollama si vous préférez OllamaEmbedding) ; les paquets OpenAI du lot restent installés mais inutilisés tant que vous configurez Settings.

pip install llama-index \
            llama-index-llms-ollama \
            llama-index-embeddings-huggingface

ollama pull mistral

Le nom d'un paquet donne l'import : llama-index-llms-ollama correspond à llama_index.llms.ollama. Côté mémoire, comptez les poids du LLM (environ 5 Go pour un 7-8B en Q4, repère du site), le modèle d'embeddings et le contexte : un poste de 16 Go convient à un petit corpus, davantage donne de la marge.

#Un RAG en dix lignes (avec ses réglages OpenAI par défaut)

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

docs = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(docs)

query = index.as_query_engine()
print(query.query("Résume les points clés du contrat X"))

Ce code est valide, mais il utilise les modèles par défaut d'OpenAI : il échoue sans clé, et avec une clé il envoie vos textes chez le fournisseur. Il sert de squelette. La section suivante ajoute les quelques lignes qui le rendent local.

#Passer en local avec Ollama et des embeddings français

Trois blocs de configuration suffisent : le LLM, le modèle d'embeddings et le découpage. Pour le français, BGE-M3 est un choix courant : sa fiche indique plus de 100 langues et des entrées jusqu'à 8 192 tokens. Le téléchargement du modèle pèse environ 2,3 Go (fichier pytorch_model.bin du dépôt Hugging Face), et il se fait une seule fois.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

# Configuration globale : tout est local
Settings.llm = Ollama(
    model="mistral",
    base_url="http://localhost:11434",
    request_timeout=120.0,   # le défaut est de 30 s
    context_window=8000,     # transmis à Ollama comme num_ctx
)
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-m3")
Settings.chunk_size = 700
Settings.chunk_overlap = 100

# Pipeline
docs = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(docs, show_progress=True)

# Persister sur disque
index.storage_context.persist(persist_dir="./storage")

# Requêter
query_engine = index.as_query_engine(similarity_top_k=5)
reponse = query_engine.query("Quels sont les risques identifiés ?")
print(reponse)
for src in reponse.source_nodes:
    print(f"  - {src.metadata.get('file_name')} ({src.score:.2f})")

from llama_index.core import load_index_from_storage, StorageContext

storage = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage)

#Pourquoi context_window et request_timeout comptent

Le code source de l'intégration Ollama de LlamaIndex transmet la valeur de context_window à Ollama sous le nom num_ctx. Sans cela, Ollama applique sa fenêtre par défaut, de 4 000 tokens environ sous 24 Gio de VRAM d'après sa documentation. Le calcul est vite fait : cinq passages de 700 tokens représentent 3 500 tokens, avant la question, les consignes du modèle de prompt et la réponse. Avec 4 000 tokens, le prompt déborde et le contexte est tronqué, souvent sans erreur visible. Avec 8 000, la marge existe.

Le délai est l'autre piège : le client Ollama de LlamaIndex fixe 30 secondes par défaut. Un premier appel qui charge le modèle en mémoire et traite un long prompt peut le dépasser. Les 120 secondes de l'exemple sont un point de départ à ajuster selon votre matériel.

#Charger vos fichiers : réglages de SimpleDirectoryReader

SimpleDirectoryReader lit un dossier entier et gère de nombreux formats : PDF, Word, PowerPoint, Markdown, images, audio et vidéo. Quelques paramètres évitent d'indexer n'importe quoi.

from llama_index.core import SimpleDirectoryReader

docs = SimpleDirectoryReader(
    input_dir="./docs",
    required_exts=[".pdf", ".docx"],  # ne charger que ces formats
    num_files_limit=100,              # plafond pour un premier essai
).load_data()

Les connecteurs vers des services (Notion, Google Docs, Slack, Discord) vont chercher les données en ligne : c'est inévitable, puisqu'elles y résident. Une fois les documents chargés, l'indexation et l'interrogation restent locales, avec vos embeddings et votre LLM Ollama. Faites un premier essai sur quelques fichiers : un PDF scanné sans couche de texte ne donnera rien tant qu'il n'est pas passé par un OCR, comme le décrit le guide Tesseract.

#Choisir un mode de requête et le coût en appels LLM

Le mode de synthèse détermine combien de fois le LLM est appelé, donc le temps de réponse local. Le tableau reprend les modes documentés et leur coût, avec un exemple à cinq passages de 700 tokens et une fenêtre de 8 000 tokens (estimation).

Pour une question factuelle, gardez compact. Pour résumer un long document, tree_summarize est prévu, au prix de plusieurs appels : sur une machine locale, prévoyez plusieurs fois la durée d'une réponse simple. no_text est précieux pour vérifier ce que la recherche ramène, sans attendre le LLM.

#Ajouter un reranker local

Quand la bonne réponse est dans les 20 premiers passages mais pas dans les 5 premiers, un reranker réordonne les candidats avant l'envoi au LLM. La documentation de LlamaIndex recommande, comme défaut sans clé API et exécuté localement, SentenceTransformerRerank, un cross-encoder via sentence-transformers, et cite Qwen3-Reranker-0.6B pour une meilleure qualité multilingue.

from llama_index.core.postprocessor import SentenceTransformerRerank

reranker = SentenceTransformerRerank(
    model="cross-encoder/ms-marco-MiniLM-L2-v2",
    top_n=3,
)
query_engine = index.as_query_engine(
    similarity_top_k=15,             # large pour rattraper la bonne réponse
    node_postprocessors=[reranker],  # puis resserre à 3
)

Le modèle donné ici est celui de l'exemple officiel, choisi pour sa rapidité ; il est conçu pour l'anglais : pour des documents français, testez un reranker multilingue. Le guide dédié détaille le choix et l'évaluation.

#Sous-questions et routage

SubQuestionQueryEngine

Décompose une question complexe en sous-questions envoyées à des outils de requête, puis synthétise. « Compare les stratégies 2024 et 2025 » devient deux recherches séparées.

RouterQueryEngine

Choisit, pour chaque question, le bon moteur parmi plusieurs (par exemple un index de résumés ou un index vectoriel).

Ces deux moteurs multiplient les appels au LLM : une décomposition en trois sous-questions ajoute la génération des sous-questions, trois réponses et la synthèse finale, soit au moins cinq appels. Sur du matériel local, réservez-les aux questions qui le justifient.

#Agents : l'API actuelle n'est plus celle des anciens tutoriels

Beaucoup de tutoriels utilisent ReActAgent.from_tools. Cette classe n'existe plus dans les sources actuelles : le module agent/react/base.py qui la portait a disparu du dépôt. Les agents sont désormais des workflows asynchrones : FunctionAgent (un agent qui appelle des fonctions ou outils), ReActAgent version workflow, et AgentWorkflow pour orchestrer plusieurs agents. Le tutoriel local officiel construit l'agent avec AgentWorkflow.from_tools_or_functions et l'exécute avec await agent.run.

import asyncio
from llama_index.core import Settings
from llama_index.core.agent.workflow import AgentWorkflow

async def search_documents(query: str) -> str:
    """Répond aux questions sur les contrats clients."""
    response = await query_engine.aquery(query)
    return str(response)

agent = AgentWorkflow.from_tools_or_functions(
    [search_documents],
    llm=Settings.llm,
    system_prompt="Tu réponds uniquement à partir des contrats indexés.",
)

async def main():
    reponse = await agent.run("Y a-t-il une clause de non-concurrence chez Acme Corp ?")
    print(str(reponse))

asyncio.run(main())

Le nom, la description et les arguments de la fonction (sa docstring) sont transmis au LLM, qui choisit s'il doit l'appeler : soignez donc cette description. Le fonctionnement de FunctionAgent repose sur des appels de fonctions natifs ; avec un modèle local, choisissez un modèle qui prend en charge les outils dans Ollama, et gardez le RAG simple si le vôtre n'en est pas capable.

#LlamaIndex, LangChain ou RAG maison : comment choisir

Règle pratique : un RAG documentaire avec sources citées, des formats variés et quelques options de requête se construit vite avec LlamaIndex. Si vous voulez d'abord comprendre le mécanisme, écrivez la version maison une fois : le guide ChromaDB montre les étapes. Pour un agent qui pilote de nombreux outils externes, LangChain ou les workflows de LlamaIndex se comparent selon vos habitudes.

#Les pièges qui coûtent du temps

Réindexer à chaque exécution

Sans persist, l'index est en mémoire et disparaît à la fermeture du script. Persistez, puis rechargez avec load_index_from_storage.

Changer de modèle sans réindexer

Les vecteurs de deux modèles d'embeddings ne sont pas comparables : modifier embed_model ou le découpage impose de reconstruire l'index.

Contexte tronqué en silence

Un prompt plus long que la fenêtre d'Ollama est coupé : vérifiez context_window si les réponses ignorent les derniers passages.

Copier un ancien tutoriel

Les API d'agents ont changé : vérifiez que les imports d'un exemple existent dans la version installée (0.14.25 au moment de la rédaction).

Ne jamais mesurer

Un RAG sans évaluation dérive sans que vous le sachiez : le guide Ragas montre comment le chiffrer.

• RAG en local avec ChromaDB et Ollama : tutoriel Python
• Ajouter un reranker à son pipeline
• Les meilleurs modèles d'embeddings FR
• Stratégies de chunking
• Ragas : évaluer son RAG local avec des chiffres
• Créer un agent IA local en Python avec LangChain et Ollama

• Source : tutoriel de démarrage avec modèles locaux
• Source : installation de LlamaIndex
• Source : modes de synthèse de réponse
• Source : persistance et rechargement d'un index
• Source : fiche du modèle BGE-M3