Accueil / Articles

Un pipeline RAG local utilisant Qdrant, fastembed et Gemini en Python

Un petit pipeline RAG en Python : diviser les documents locaux en blocs, les intégrer hors ligne avec fastembed, conserver les vecteurs dans Qdrant, et répondre aux questions avec Gemini depuis la ligne de commande.

Éditeur : REACTAPP.TOP6 min de lecture1485 mots

Sources: How to Build a Simple RAG Pipeline using Qdrant

Une configuration personnalisée de RAG (retrieval-augmented generation) semble plus intimidante qu’elle ne l’est en réalité. Le discours actuel suggère qu’il faut une stack d’entreprise rien que pour permettre à un LLM de lire des fichiers locaux. Ce n’est pas le cas. Un pipeline fonctionnel et incrémental peut être exécuté sur une seule machine avec Qdrant et Gemini, sans framework lourd ni serveur à gérer. Ci-dessous, on explique comment cela fonctionne, ce que fait le code et comment le lancer.

Le problème résolu par RAG

Les modèles de langage ne connaissent que leurs données d’entraînement. Ils n’ont jamais vu vos notes, vos rapports ou le PDF que vous avez enregistré ce matin. RAG comble cette lacune. Au lieu d’espérer que le modèle devine à partir de connaissances générales, le système cherche dans vos documents les passages pertinents, les transmet au modèle et lui demande de répondre uniquement à partir de ce contexte. Il cesse d’inventer des choses car il lit vos documents.

Une recherche par mots-clés classique pourrait trouver ces passages, mais elle échoue rapidement, c’est pourquoi la recherche vectorielle est le choix habituel.

Vecteurs et recherche vectorielle

Un vecteur est une liste de nombres qui représente le sens d’un texte. En transformant « comment allez-vous » et « quel âge avez-vous » en vecteurs, on peut calculer leur degré de similarité. La recherche vectorielle applique cette idée pour trouver des réponses même lorsque la formulation diffère. La question et chaque fragment de document sont intégrés dans le même espace numérique, et ce qui est le plus proche en termes de sens l’emporte. Cela est important car les gens formulent rarement leurs questions de la même manière que les documents. Quelqu’un qui demande « comment puis-je récupérer mon argent » a toujours besoin de la section intitulée « Politique de remboursement ».

Un pipeline RAG est le mécanisme qui relie tout cela. Il comporte généralement six étapes :

  1. Ingestion : un fichier est placé dans un dossier, documents/ dans ce code.
  2. Fragmentation : le script divise le fichier en petits segments qui se chevauchent. Rechercher un document de 50 pages en tant qu’unité unique ne fonctionne pas, il est donc nécessaire de le diviser.
  3. Incorporation : un petit modèle local transforme chaque segment en un vecteur, de sorte que les passages traitant de sujets similaires se retrouvent proches les uns des autres.
  4. Stockage : les vecteurs sont stockés dans Qdrant, une base de données vectorielle conçue pour accepter un nouveau vecteur et restituer rapidement les correspondances les plus proches parmi des millions d’autres. Elle est rapide, open source et fonctionne localement, sans nécessiter de configuration de serveur ni de compte.
  5. Récupération : une question est également incorporée, et Qdrant renvoie les segments les plus proches d’elle, ceux qui sont le plus susceptibles de contenir la réponse.
  • Génération : les fragments récupérés sont intégrés dans une requête et envoyés à Gemini, qui rédige une réponse basée sur les documents réels.
  • Les étapes 1 à 4 s’exécutent automatiquement grâce au flag -i ou au surveillant -w, de sorte que les documents restent toujours consultables. Les étapes 5 et 6 ont lieu sur demande lorsque le paramètre -q est utilisé.

    L’implémentation en Python

    Le code reste léger et évite les grands frameworks, ce qui permet de voir facilement où vont les données.

    Lecture des fichiers

    Tout d’abord, il faut trouver les fichiers et en extraire le texte brut, qu’il s’agisse de notes Markdown ou de documents Word peu structurés :

    def read_document(path) -> str:
        # dispatches on extension: .txt/.md read directly,
        # .pdf via pypdf, .docx via docx2txt -> returns plain textdef file_status(path, state) -> str:
        # "not_indexed" if never seen, "modified" if file_hash(path)
        # differs from the hash stored in state, else "indexed"
    

    Chunking

    Ensuite, le texte est divisé à l’aide d’une fenêtre glissante simple, de sorte qu’une phrase se trouvant à la limite de cette division conserve son contexte :

    def chunk_text(text, chunk_size=500, overlap=50) -> list:
        words = text.split()
        step = chunk_size - overlap
        return [" ".join(words[i:i+chunk_size])
                for i in range(0, len(words), step)]
    

    Embeddings et IDs stables

    Les embeddings sont générés localement, sans appel à une API externe pour chaque phrase. Chaque morceau de texte reçoit également un ID prévisible, dérivé du hash de son contenu, de sorte que le texte inchangé conserve le même ID d’une exécution à l’autre :

    def chunk_ids_for(chunks) -> dict:
        # id = uuid5(namespace, chunk_text) for each chunk
        # -> same text always gets the same id, across re-indexes
        ...
    

    L’incorporation elle-même a lieu à l’intérieur de l’appel à Qdrant :

    # inside index_file():
    client.add(collection_name=index_name, documents=new_chunks, ids=new_ids)
    # Qdrant's fastembed integration embeds `documents` automatically
    

    Synchronisation des fichiers avec la base de données

    Ici, les fichiers locaux et la base de données sont mis en concordance. La correction d’une faute d’orthographe ne supprime pas l’index ni ne nécessite une redémarrage. Le code compare les IDs, supprime les parties qui ont disparu et en ajoute de nouvelles :

    def index_file(path, state) -> bool:
        chunks = chunk_text(read_document(path))
        new_ids = chunk_ids_for(chunks)
        old_ids = state[path.name].chunk_ids  # from last time
        client.delete(collection_name, ids=old_ids - new_ids)   # removed chunks
        client.add(collection_name, ids=new_ids - old_ids, ...)  # new/changed chunks
        state[path.name] = {...updated record...}
    

    Les fichiers supprimés du dossier sont également nettoyés :

    def prune_deleted(state) -> int:
        # for each file in state no longer present in DOCUMENT_DIR:
        #     delete its Qdrant collection, drop its state entry
    

    Réponse à une requête

    Lorsqu’une question arrive, Qdrant doit identifier les meilleures correspondances parmi les documents sélectionnés. Un outil d’aide détermine d’abord quels index rechercher :

    def resolve_index_names(spec, state) -> list:
        # "all" -> every indexed collection; "a,b" -> ["a","b"], validated
    

    Ensuite, la requête est exécutée sur chacun d’eux et les résultats sont fusionnés :

    def cmd_query(index_spec, question, top_k, show_sources):
        for name in resolve_index_names(index_spec, state):
            hits += client.query(collection_name=name, query_text=question, limit=top_k)
        hits = sorted(hits, key=score, reverse=True)[:top_k]
    

    Génération

    Finalement, les fragments récupérés sont envoyés directement à Gemini, qui est comparé au texte fourni :

    def generate_answer(question, context) -> str:
        prompt = f"Answer using only this context:\n{context}\n\nQuestion: {question}"
        return genai.Client(api_key=...).models.generate_content(
            model=GEMINI_MODEL, contents=prompt
        ).text
    

    Le reste est du code d’accompagnement. get_client() ouvre la connexion à Qdrant, load_state() et save_state() lisent et écrivent .rag_state.json, tandis que sanitize_index_name() transforme les noms de fichiers en noms de collections valides. Les fonctions de commande (cmd_list_files, cmd_index, cmd_watch) relient tout cela aux paramètres en ligne de commande.

    Le faire fonctionner localement

    Clonez le répertoire et naviguez dans le dossier du projet :

    git clone https://github.com/Shivvam/rag-pipeline-qdrant.git
    cd rag-cli
    

    Ensuite, créez un environnement, installez les dépendances nécessaires et configurez le fichier de configuration :

    python3 -m venv venv
    source venv/bin/activate   # on Windows: venv\Scripts\activate
    pip install -r requirements.txt
    cp .env.example .env   # then edit in your GEMINI_API_KEY
    

    Activez à nouveau l’environnement virtuel dans n’importe quel terminal nouveau avant d’exécuter app.py. GEMINI_API_KEY doit être défini pour que -q produise des réponses, tandis que les autres commandes fonctionnent sans lui.

    Utilisation en ligne de commande

    Tout ce qui concerne l’ingestion et la consultation s’effectue depuis le terminal. Pour voir quels fichiers se trouvent dans le dossier des documents et lesquels nécessitent une attention particulière, ou quels index existent :

    python app.py -lf                        # list files in ./documents + status
    python app.py -li                        # list existing indexes
    

    Pour traiter de nouveaux documents ou mettre à jour ceux qui ont été modifiés :

    python app.py -i myfile.md               # index one file (or re-index if changed)
    python app.py -i all                     # index every not_indexed/modified file
    

    Pour un indexation automatique pendant l’édition, maintenez cela en exécution dans un deuxième terminal :

    python app.py -w                          # watch ./documents, auto-index on add/edit
    

    Pour poser des questions concernant un fichier, plusieurs fichiers ou tout le contenu :

    python app.py -q report "What is X?"      # query a single index
    python app.py -q report,notes "What is X?"  # query multiple indexes together
    python app.py -q all "What is X?" --sources # query everything, show retrieved chunks
    python app.py -q report "..." -k 8        # retrieve top 8 chunks instead of default 5
    

    Le statut affiché par -lf peut prendre trois valeurs. not_indexed signifie que le fichier n’a jamais été traité, indexed indique qu’il est à jour, et modified veut dire qu’il a changé depuis la dernière exécution et que -i doit être répété.

    Choix de conception

    Quelques décisions permettent de garder les choses rapides et simples.

    • Qdrant : chaque fichier dispose de sa propre collection, nommée d’après le nom de fichier nettoyé, avec un suffixe numérique ajouté en cas de collision. Par défaut, il utilise le mode local sur disque (./qdrant_storage), ce qui n’exige aucun serveur. Pour un accès concurrent, définissez QDRANT_URL dans .env pour pointer vers un vrai serveur Qdrant. Le mode local verrouille le répertoire pour un seul processus, ce qui empêche -w et -q de fonctionner simultanément.
    • Embeddings : le modèle BAAI/bge-small-en-v1.5 est exécuté via fastembed. Il est téléchargé une seule fois et mémorisé en cache, ce qui évite les frais liés à l’API ainsi que toute dépendance réseau au moment de la requête.
    • Gemini : il ne conserve que la réponse finale issue des fragments récupérés, en utilisant par défaut gemini-3.5-flash.
    • État : le fichier .rag_state.json enregistre les hachages des fichiers, leur statut, les noms des index et le nombre de fragments, ce qui permet aux options -lf et -li de fonctionner instantanément, car Qdrant n’a pas besoin de rescanner les données. Les identifiants des fragments proviennent du texte lui-même, ce qui rend le réindexage incrémental : seuls les fragments modifiés sont réinsérés et mis à jour.
    • Types de fichiers : les formats .txt et .md fonctionnent immédiatement. Les formats .pdf et .docx nécessitent pypdf ou docx2txt, tous deux déjà mentionnés dans les exigences.