Ce que vous saurez faire
A la fin de ce tutoriel, vous saurez utiliser LlamaIndex pour transformer la base documentaire de votre PME (PDF, Word, Excel, emails Outlook, pages web internes) en un index intelligent interrogeable en langage naturel. Cas d’usage concrets pour le Sénégal : assistant juridique qui retrouve la bonne clause dans 200 contrats, support technique qui répond depuis 1500 fiches produits, RH qui consulte la convention collective. Vous deploierez un script Python opérationnel en moins de 2 heures, pour un coût API mensuel d’environ 8000 FCFA pour 500 requetes par jour.
Étape 1 : Comprendre LlamaIndex en 1 minute
LlamaIndex (anciennement GPT Index) est une bibliotheque Python qui orchestre 3 étapes : ingestion (lecture des fichiers), indexation (decoupage et vectorisation), et requete (recherche + réponse par un LLM). Différence avec LangChain : LlamaIndex est specialise documents, plus simple, plus rapide a mettre en place quand le but est purement RAG documentaire.
Étape 2 : Installer LlamaIndex
python -m venv venv
source venv/bin/activate
pip install llama-index==0.11.7
pip install llama-index-llms-anthropic==0.3.1
pip install llama-index-embeddings-huggingface==0.3.1
pip install llama-index-readers-file==0.2.1
pip install python-dotenv==1.0.1Étape 3 : Organiser votre base documentaire
Créez une structure claire :
mon-projet/
documents/
contrats/
contrat-orange-2023.pdf
contrat-sonatel-2024.pdf
procedures/
manuel-rh.docx
reglement-interieur.pdf
catalogues/
produits-2025.xlsx
index_storage/
main.py
.envÉtape 4 : Configurer la cle Anthropic et le modèle
Dans .env :
ANTHROPIC_API_KEY=sk-ant-api03-VOTRECLEDans main.py, on configuré Claude comme LLM par défaut et un embedding local pour réduire les coûts :
from llama_index.core import Settings
from llama_index.llms.anthropic import Anthropic
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from dotenv import load_dotenv
load_dotenv()
Settings.llm = Anthropic(model="claude-3-5-sonnet-20241022", max_tokens=1024)
Settings.embed_model = HuggingFaceEmbedding(
model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)
Settings.chunk_size = 800
Settings.chunk_overlap = 100Étape 5 : Charger tous les documents en une commande
SimpleDirectoryReader lit recursivement tous les PDF, DOCX, XLSX, TXT et MD :
from llama_index.core import SimpleDirectoryReader
documents = SimpleDirectoryReader(
input_dir="./documents",
recursive=True,
required_exts=[".pdf", ".docx", ".xlsx", ".txt", ".md"]
).load_data()
print(f"{len(documents)} documents charges")Pour une PME avec 500 fichiers, comptez 30 secondes de chargement.
Étape 6 : Construire l’index vectoriel
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(
documents,
show_progress=True
)
print("Index construit")Sur 500 documents (environ 10 000 chunks), comptez 5 minutes sur CPU. Avec un GPU, moins d’une minute.
Étape 7 : Persister l’index sur disque
Indispensable : sans cette étape, vous reconstruisez tout a chaque démarrage et payez des appels API inutiles :
index.storage_context.persist(persist_dir="./index_storage")
print("Index sauvegarde")L’index occupe environ 50 Mo pour 500 documents.
Étape 8 : Recharger un index existant
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="./index_storage")
index = load_index_from_storage(storage_context)
print("Index recharge depuis disque")Le rechargement prend moins de 3 secondes, même pour 100 000 documents.
Étape 9 : Lancer une première requete
query_engine = index.as_query_engine(
similarity_top_k=4,
response_mode="compact"
)
reponse = query_engine.query(
"Quelle est la duree de preavis pour un employe en CDI selon notre reglement interieur ?"
)
print(reponse)Réponse type : « Selon le règlement intérieur, le préavis pour un CDI est d’un mois pour les employes et de trois mois pour les cadres. »
Étape 10 : Afficher les sources citées
Indispensable pour un usage professionnel et juridique :
print("\nSources :")
for node in reponse.source_nodes:
fichier = node.metadata.get("file_name", "inconnu")
page = node.metadata.get("page_label", "")
score = node.score
print(f"- {fichier} (page {page}) score {score:.2f}")Étape 11 : Affiner avec un prompt métier
Le prompt par défaut est générique. Pour un cabinet juridique sénégalais :
from llama_index.core import PromptTemplate
template = """Tu es un assistant juridique pour un cabinet a Dakar.
Reponds uniquement en t'appuyant sur les documents fournis.
Cite la source (nom du fichier et page) entre crochets.
Si l'information n'est pas dans les documents, reponds "Information non trouvee".
Contexte :
---
{context_str}
---
Question : {query_str}
Reponse argumentee :"""
prompt = PromptTemplate(template)
query_engine = index.as_query_engine(similarity_top_k=4)
query_engine.update_prompts({"response_synthesizer:text_qa_template": prompt})Étape 12 : Mettre a jour l’index quand un document change
Au lieu de tout reconstruire, on insere ou on supprime selectivement :
# Ajouter un nouveau contrat
nouveau = SimpleDirectoryReader(input_files=["./documents/contrats/contrat-tigo-2025.pdf"]).load_data()
for doc in nouveau:
index.insert(doc)
# Supprimer un document obsolete
index.delete_ref_doc("ancien_doc_id", delete_from_docstore=True)
# Persister les changements
index.storage_context.persist(persist_dir="./index_storage")Étape 13 : Mode chat avec mémoire de conversation
Pour des échanges suivis, utilisez chat_engine au lieu de query_engine :
chat_engine = index.as_chat_engine(
chat_mode="condense_plus_context",
verbose=False
)
while True:
question = input("Vous : ")
if question.lower() in ["quit", "exit"]:
break
reponse = chat_engine.chat(question)
print(f"Assistant : {reponse}\n")Le chat se souvient du contexte : « Et la garantie ? » comprend qu’on parle du produit précédemment evoque.
Étape 14 : Optimiser les coûts en production
Trois leviers pour réduire la facture Anthropic :
# 1. Cache des reponses pour questions frequentes
from llama_index.core import set_global_handler
set_global_handler("simple")
# 2. Modele moins cher pour les requetes simples
from llama_index.llms.anthropic import Anthropic
llm_eco = Anthropic(model="claude-3-haiku-20240307", max_tokens=512)
# 3. Limiter le contexte recupere
query_engine = index.as_query_engine(
similarity_top_k=3, # 3 chunks au lieu de 10
response_mode="compact" # Compactage avant envoi a Claude
)Résultat : passage de 8000 FCFA a 2500 FCFA par mois pour 500 requetes par jour.
Erreurs
Erreur 1 : Reconstruire l’index a chaque exécution. Vérifiez avec os.path.exists(« ./index_storage ») avant de reconstruire. Sinon vous brulez votre quota API.
Erreur 2 : Charger des fichiers Excel mal formates. LlamaIndex lit feuille par feuille. Si vos cellules fusionnees sont nombreuses, exportez d’abord en CSV propre.
Erreur 3 : Oublier les metadonnees. Ajoutez doc.metadata[« catégorie »] = « RH » pour pouvoir filtrer ensuite. Sans cela, impossible de cibler une recherche.
Erreur 4 : similarity_top_k trop eleve. Au-dessus de 8, vous envoyez trop de contexte a Claude (coût x5) sans gain de qualité.
Erreur 5 : Documents avec OCR rate. Si votre PDF est un scan, LlamaIndex extrait du charabia. Pretraitez avec Tesseract OCR avant indexation.
Checklist
- Python 3.11+ et environnement virtuel actif
- Cle API Anthropic configurée dans .env et exclue de git
- Structure documents/ organisée par catégories métier
- Modèle d’embedding multilingue installe en local
- Chunk size entre 600 et 1000 selon densite documentaire
- Index persiste dans index_storage/ et exclu de git si volumineux
- Test de rechargement de l’index sans reconstruction valide
- Prompt template adapte au métier (juridique, RH, technique)
- Sources citées affichees a chaque réponse
- Procédure d’ajout et suppression incrementale documentée
- Mode chat teste avec 10 échanges enchaines
- Coût API mesure et plafond mensuel configuré dans console Anthropic
- Sauvegarde quotidienne d’index_storage/ sur disque externe
- Documentation utilisateur final remise aux équipes (RH, juridique, technique)
Étape 1 — Comprendre la différence de philosophie
LangChain et LlamaIndex visent tous deux à orchestrer des appels au modèle Claude depuis Python ou TypeScript, mais leur centre de gravité diffère. LangChain est un framework généraliste d’agents et de chaînes — pensé pour combiner outils, mémoire, raisonnement multi-étapes. LlamaIndex se concentre sur la retrieval augmented generation (RAG) — indexer vos documents, les chunker proprement, et nourrir Claude avec le bon contexte.
Choisir l’un ou l’autre dépend du problème. Si vous construisez un assistant qui appelle plusieurs APIs métier, allez vers LangChain. Si vous bâtissez un moteur de question-réponse sur 5000 PDFs internes (catalogue produit Auchan Dakar par exemple), LlamaIndex sera plus direct.
Étape 2 — Installer les dépendances dans un environnement isolé
Avant tout, créez un environnement Python virtuel pour éviter les conflits. Sur Linux ou macOS, utilisez venv. Sur Windows, la même commande fonctionne via PowerShell.
python -m venv venv
source venv/bin/activate # Linux / macOS
venv\Scripts\activate # Windows PowerShell
pip install --upgrade pip
pip install anthropic langchain langchain-anthropic
pip install llama-index llama-index-llms-anthropicL’isolement vous évitera de polluer votre Python système et facilite la reproduction sur un autre poste à Abidjan ou Lomé. Si vous voyez la liste des packages installée sans erreur, vous êtes prêt à coder.
Étape 3 — Configurer la clé API Claude
La clé API Anthropic se génère sur console.anthropic.com. Stockez-la dans une variable d’environnement, jamais en dur dans le code source — c’est la cause numéro un des fuites de clés sur GitHub.
# Dans .env (à ajouter au .gitignore)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Charger en Python
from dotenv import load_dotenv
load_dotenv()
import os
print(bool(os.getenv("ANTHROPIC_API_KEY"))) # doit afficher TrueLe retour True confirme que la clé est lue. Si vous obtenez False, vérifiez que le fichier .env est bien dans le dossier d’exécution. Ajoutez aussi .env à votre .gitignore avant le premier commit.
Étape 4 — Premier appel via LangChain
LangChain encapsule Claude dans une classe ChatAnthropic. Ce wrapper expose une interface unifiée commune avec OpenAI, Mistral, Gemini — pratique si vous voulez pouvoir basculer de modèle plus tard sans réécrire la logique métier.
from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage
llm = ChatAnthropic(
model="claude-opus-4-5",
max_tokens=1024,
temperature=0.2,
)
reponse = llm.invoke([
HumanMessage(content="Résume le rôle de la BCEAO en 3 phrases.")
])
print(reponse.content)Vous devriez obtenir un paragraphe propre sur la Banque Centrale des États de l’Afrique de l’Ouest. Si une erreur 401 surgit, votre clé est invalide ou expirée. Une erreur 429 signale un dépassement de quota — vérifiez votre compte sur la console Anthropic.
Étape 5 — Premier RAG via LlamaIndex
LlamaIndex brille dès qu’il faut interroger un corpus. Préparez un dossier ./docs/ avec quelques fichiers Markdown ou PDFs (catalogue produit, FAQ interne, documentation technique). LlamaIndex va les indexer en quelques secondes.
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.anthropic import Anthropic
llm = Anthropic(model="claude-opus-4-5")
docs = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(docs)
query_engine = index.as_query_engine(llm=llm)
reponse = query_engine.query("Quel est le délai de livraison à Pikine ?")
print(reponse)Le moteur extrait les passages pertinents puis les soumet à Claude pour formuler la réponse. Sur un corpus de 200 fichiers, l’indexation prend moins d’une minute. Conservez l’index sur disque avec index.storage_context.persist() pour éviter de réindexer à chaque lancement.
Étape 6 — Construire un agent multi-outils avec LangChain
L’agent LangChain permet à Claude d’appeler des outils Python — recherche web, calcul, requête base de données. Voici un agent minimal qui sait calculer et chercher la météo à Dakar.
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate
@tool
def meteo(ville: str) -> str:
"""Retourne la météo actuelle pour une ville."""
return f"Soleil 28°C à {ville}"
prompt = ChatPromptTemplate.from_messages([
("system", "Tu es un assistant utile."),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, [meteo], prompt)
exe = AgentExecutor(agent=agent, tools=[meteo])
print(exe.invoke({"input": "Quel temps fait-il à Dakar ?"}))Claude reçoit la liste des outils, choisit meteo, l’invoque avec « Dakar » puis formule la réponse. Cette boucle d’orchestration est le cœur de LangChain — vous ajoutez vos propres outils métier (Wave, Mixx by Yas, ERP interne) avec le décorateur @tool.
Étape 7 — Choisir selon le cas d’usage réel
Pour un chatbot service client e-commerce ouest-africain interrogeant FAQ et catalogue, partez de LlamaIndex — la mise en place du RAG sera plus rapide. Pour un assistant interne qui consulte plusieurs systèmes (Slack, Trello, Google Sheets), partez de LangChain — l’écosystème d’intégrations est plus large.
Les deux frameworks coexistent souvent dans un même projet. Vous pouvez très bien utiliser LlamaIndex pour l’indexation documentaire et appeler son query engine comme un outil LangChain dans un agent plus large.
Étape 8 — Mesurer les coûts en FCFA
Claude est facturé au token. Au tarif public 2026 d’Anthropic pour Claude Opus 4.5 (15 USD / million de tokens entrée, 75 USD / million sortie), une conversation moyenne de 4 000 tokens entrée + 1 000 sortie coûte environ 0,135 USD soit 88 FCFA par échange.
import anthropic
client = anthropic.Anthropic()
resp = client.messages.create(
model="claude-opus-4-5",
max_tokens=200,
messages=[{"role":"user","content":"Bonjour"}]
)
print(resp.usage.input_tokens, resp.usage.output_tokens)Loggez ces compteurs dans un tableur ou une base SQLite. Au bout d’une semaine, vous saurez précisément combien coûte chaque feature de votre app — donnée indispensable pour facturer un client à Dakar ou Abidjan sans perdre d’argent.
Étape 9 — Aller plus loin avec le caching et les agents
Activez le prompt caching d’Anthropic pour réduire les coûts récurrents jusqu’à 90 %. Pour structurer un projet React qui consomme votre API Claude, voyez notre guide React débutants et notre décryptage de l’algorithme Google 2026 pour faire ranker votre démo.
Étape 10 — Mettre en production et observer
Une fois votre prototype validé, conteneurisez-le avec Docker et déployez sur un VPS Hetzner (à partir de 4 EUR par mois soit environ 2 600 FCFA). Ajoutez une couche d’observabilité avec Langfuse ou Helicone pour tracer chaque appel Claude — latence, tokens, coût, erreur.
# Dockerfile minimal
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]Ces traces vous serviront à débuguer les régressions, à facturer vos clients et à arbitrer entre LangChain et LlamaIndex sur les futurs projets. Sans données réelles d’usage, toute décision d’architecture reste une opinion — avec, elle devient une preuve.
Étape 11 — Documenter votre stack pour l’équipe
Un README clair vaut mieux que mille messages Slack. Listez la version exacte des paquets, les variables d’environnement requises, la commande de lancement, et une checklist de validation. Une nouvelle recrue à Abidjan doit pouvoir cloner le repo et lancer le projet en moins de 30 minutes sans vous solliciter une seule fois sur les fondamentaux du setup.