Construire un assistant de documentation RAG pour une API à l’aide de LlamaIndex
Créer un assistant de documentation API avec LlamaIndex : charger des documents Markdown, les diviser en blocs avec SentenceSplitter, les incorporer, les stocker dans Chroma et effectuer des requêtes avec un RAG QueryEngine.
Sources: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)
Vous êtes en train de configurer une nouvelle API de paiement. Vous ouvrez la documentation, appuyez sur Ctrl+F, tapez « refund » et obtenez douze résultats répartis sur quatre pages, dont la moitié est irrelevante car elle mentionne simplement ce mot. Un quart d’heure plus tard, vous avez trouvé l’endpoint, mais vous avez perdu le fil de ce que vous faisiez.
Imaginez maintenant taper « Comment effectuer un remboursement ? » et obtenir une réponse claire directement issue de la documentation. C’est l’objectif ici : un petit assistant pour une API d’e-commerce fictive appelée ShopSphere. Il ne s’appuie pas sur les connaissances générales du modèle de langage ni ne invente de réponse. Il recherche dans la véritable documentation de ShopSphere et fournit des réponses à partir d’elle. LlamaIndex s’occupe du travail difficile, et chaque élément est expliqué en détail, y compris les moments où le framework peut sembler magique.
Le problème à résoudre
Les modèles de langage connaissent beaucoup de choses sur le monde, mais rien concernant la documentation API de votre entreprise. Coller des centaines de pages dans chaque demande serait lent, coûteux et source de perturbations. Une meilleure approche consiste d’abord à trouver les passages pertinents, puis à demander au modèle de répondre en s’appuyant sur eux. Lorsqu’on demande comment passer une commande, le système localise la section relative aux commandes, et ce texte est transmis au modèle accompagné de la question.
Cette technique s’appelle la génération augmentée par récupération d’informations (RAG) : d’abord récupérer les données, puis générer la réponse. Tout ce qui suit concerne la mise en place de cette phase de récupération, afin qu’un agent puisse finalement choisir quelle information ou quel outil utiliser.
Quatre idées clés dans LlamaIndex
Cette plateforme organise tout autour de quatre concepts, ce qui permet d’éviter qu’elle ressemble à un labyrinthe de noms de classes. Une petite cuisine de restaurant offre une comparaison utile :
- Composants : ce sont les ingrédients et les appareils, comme le four, le réfrigérateur ou la farine. Ce sont des capacités brutes.
- Outils : ce sont les recettes affichées sur les appareils, rédigées de manière à permettre à un nouveau cuisinier de les suivre sans poser de questions.
- Agents : ce sont le chef, qui décide, étape par étape, quelle recette utiliser et dans quel ordre, en fonction des souhaits du client.
- Flux de travail : ce sont les cartes de recette imprimées, utilisées lorsque l’on ne veut pas d’improvisation et qu’il est nécessaire de suivre une séquence fixe à chaque fois.
L’assistant est construit en superposant ces quatre éléments dans cet ordre.
Composants : transformer les documents Markdown en une base de connaissances consultable
C’est la phase de préparation. Avant que toute réflexion ne commence, cinq fichiers de documentation (authentification, produits, commandes, erreurs et webhooks) doivent être au format permettant à un ordinateur de les rechercher par leur contenu plutôt que seulement par des mots-clés. Cela nécessite cinq étapes.
Étape 1 : chargement
from llama_index.core import SimpleDirectoryReader
def load_documents():
reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
documents = reader.load_data()
return documents
Le lecteur ouvre chaque fichier Markdown situé dans le dossier data/ et l’encadre dans un Document, qui représente le texte selon LlamaIndex ainsi que des informations sur son origine. La partie relative à l’origine est plus utile qu’il n’y paraît : le nom du fichier original est conservé en tant que métadonnées, de sorte que lorsque l’assistant répond plus tard, il peut indiquer que l’information provient de quelque chose comme 03-cart-orders.md sans avoir à tenir de registre manuel.
Étape 2 : segmentation
Un problème : 03-cart-orders.md regroupe les paniers, le processus de paiement, les commandes, les remboursements et les annulations dans un seul fichier. Considéré comme une seule unité recherchable, il pourrait répondre à une question sur un remboursement en incluant des détails d’annulation sans rapport. C’est pourquoi chaque document est divisé en parties plus petites que LlamaIndex appelle des nœuds, un peu comme transformer un livre en une pile de fiches index qui chacune se souvient du livre d’origine.
from llama_index.core.node_parser import SentenceSplitter
splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)
Couper aveuglément tous les 400 caractères pourrait diviser une phrase en deux ou, pire encore, interrompre une commande curl. SentenceSplitter cherche plutôt des limites de phrase naturelles. Une petite superposition de 40 caractères permet également que la fin d’un bloc réapparaisse au début du suivant, ce qui maintient ensemble les éléments liés, comme un exemple de code et la phrase qui le décrit.
Étape 3 : embedding
La recherche par sens dépend de cette étape. Chaque bloc est passé à travers un modèle d’embedding, qui convertit le texte en une longue liste de nombres, appelée vecteur. Les passages ayant un sens similaire se retrouvent sur des vecteurs similaires, même lorsque les mots utilisés sont complètement différents.
Un utilisateur pourrait demander : « Comment puis-je récupérer mon argent ? » tandis que les documents contiennent une section intitulée « Demander un remboursement ». Ces deux phrases ne partagent aucun mot important mais expriment la même idée. Le modèle d’incorporation perçoit ce lien, permettant ainsi à la recherche sémantique de faire apparaître la documentation relative au remboursement.
from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding
embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-en-v1.5",
)
Étape 4 : stockage des embeddings
Embedder chaque morceau de texte prend du temps et peut coûter de l’argent en raison des appels API, et personne ne veut le refaire à chaque démarrage. C’est pourquoi les vecteurs sont stockés dans une base de données vectorielle qui peut être réutilisée. Ici, il s’agit de Chroma, une base de données locale gratuite qui facilite le stockage et la recherche des embeddings.
import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("shopsphere_api_docs")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
LlamaIndex peut regrouper les étapes 2 à 4 en un seul processus, IngestionPipeline. Définissez les étapes une seule fois, et chaque document les traverse automatiquement : il est divisé, intégré, puis enregistré dans Chroma.
from llama_index.core.ingestion import IngestionPipeline
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=400, chunk_overlap=20),
embed_model
],
vector_store=vector_store,
)
Exécutez-le une fois, et un index durable et recherchable sera créé dans le dossier chroma_db. Il n’a besoin d’être recréé que lorsque les documents changent.
Étape 5 : requêtes
C’est là que les avantages apparaissent. Les vecteurs stockés sont encapsulés dans un VectorStoreIndex, qui devient un QueryEngine, l’objet auquel vous posez réellement vos questions :
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
query_engine = index.as_query_engine(llm=llm, similarity_top_k=3)
query_engine.query("How do I create a new order?")
Quatre choses se produisent lorsque une question arrive :
- La question devient un vecteur, en utilisant le même modèle d’incorporation que pour l’ingestion. C’est important car la question et les fragments doivent exister dans le même espace vectoriel. C’est comme mesurer tout en une seule unité, car mélanger des pouces et des centimètres rend les comparaisons sans signification.
- Les fragments les plus similaires sont récupérés dans le stockage vectoriel. Ici, cela signifie les trois fragments dont le sens est le plus proche de la question.
- Ces fragments sont envoyés au LLM en tant que contexte, et le modèle écrit sa réponse à partir d’eux plutôt que de s’appuyer uniquement sur les données d’entraînement.
C’est un pipeline RAG complet, et déjà très utile en soi. Il ne peut cependant faire qu’une seule chose : récupérer des informations, puis y répondre. Il n’a aucun moyen de déterminer qu’une question particulière nécessite une recherche différente. Cela requiert des outils et un agent.
L’exécuter soi-même
Le projet final peut être cloné et exécuté localement. Créez un environnement virtuel, installez les dépendances nécessaires et collez un token Hugging Face dans le fichier .env :
git clone https://github.com/H11199/API-Documentation-Agent.git
cd API-Documentation-Agent
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env # then paste your HF token in as HF_TOKEN=hf_...
python ingestion_pipeline.py # builds the index from the sample docs in data/
python app.py # chat with the assistant
Ce qui vient ensuite
À ce stade, nous disposons d’un moteur de recherche fonctionnel pour la documentation, mais il se contente de récupérer des informations et de répondre. La phase suivante fournit à l’assistant des outils permettant à un agent de choisir ceux à utiliser. Elle révèle également une partie des workflows LlamaIndex qui semble magique au premier abord : la manière dont un workflow sait quel étape doit être exécutée en suivant.