Inicio / Artículos

Un pipeline local de RAG con Qdrant, fastembed y Gemini en Python

Un pequeño pipeline RAG en Python: divide los documentos locales en fragmentos, los incrusta sin conexión con fastembed, almacena los vectores en Qdrant y responde a preguntas con Gemini desde la línea de comandos.

Editor: REACTAPP.TOP6 min de lectura1485 palabras

Fuentes: How to Build a Simple RAG Pipeline using Qdrant

Una configuración personalizada de RAG (generación ampliada por recuperación de información) parece más complicada de lo que es en realidad. La exageración sugiere que se necesita una plataforma empresarial solo para permitir que un modelo de lenguaje lea archivos locales. Pero no es así. Un pipeline funcional e incremental puede ejecutarse en una sola máquina con Qdrant y Gemini, sin necesidad de frameworks pesados ni servidores para gestionar. A continuación se explica cómo funciona, qué hace el código y cómo ejecutarlo.

El problema que resuelve RAG

Los modelos de lenguaje solo conocen los datos con los que fueron entrenados. Nunca han visto tus notas, tus informes ni el PDF que guardaste esta mañana. RAG cierra esa brecha. En lugar de esperar que el modelo adivine a partir del conocimiento general, el sistema busca en tus documentos las partes relevantes, les pasa esas secciones al modelo y le indica que responda únicamente a partir de ese contexto. Deja de inventar cosas porque está leyendo tu material.

La búsqueda simple por palabras clave podría encontrar esos pasajes, pero falla rápidamente, por lo que la búsqueda vectorial es la opción habitual.

Vectores y búsqueda vectorial

Un vector es una lista de números que representa el significado de un fragmento de texto. Al convertir “how are you” y “how old are you” en vectores, se puede calcular cuán similares son. La búsqueda vectorial aplica esa idea para encontrar respuestas incluso cuando la redacción difiere. La pregunta y cada fragmento de documento se incrustan en el mismo espacio numérico, y gana aquello cuyo significado sea más cercano. Esto es importante porque las personas rara vez formulan una pregunta de la misma manera que lo hace el documento. Quien pregunte “how do I get my money back” aún necesita la sección titulada “Política de reembolsos”.

Un pipeline RAG es el mecanismo que conecta todo esto. Por lo general, consta de seis pasos:

  1. Ingestión: un archivo llega a una carpeta, documents/ en este código.
  2. Fragmentación: el script divide el archivo en secciones más pequeñas y superpuestas. Buscar un documento de 50 páginas como una sola unidad no funciona, por lo que es necesario dividirlo.
  3. Incrustación: un pequeño modelo local convierte cada fragmento en un vector, de modo que las secciones sobre temas similares terminan cerca unas de otras.
  4. Almacenamiento: los vectores se guardan en Qdrant, una base de datos vectorial diseñada para recibir un nuevo vector y devolver rápidamente las coincidencias más cercanas entre millones de ellos. Es rápido, de código abierto y funciona localmente, sin necesidad de configurar servidores ni cuentas.
  5. Recuperación: también se incrusta una pregunta, y Qdrant devuelve los fragmentos más cercanos a ella, aquellos que con mayor probabilidad contienen la respuesta.
  • Generación: los fragmentos recuperados se incluyen en un prompt y se envían a Gemini, que redacta una respuesta basada en los documentos reales.
  • Los pasos del 1 al 4 se ejecutan automáticamente mediante la bandera -i o el monitor -w, por lo que los documentos siempre están listos para ser buscados. Los pasos 5 y 6 se realizan bajo demanda cuando se utiliza -q.

    La implementación en Python

    El código es sencillo y evita frameworks complejos, lo que facilita conocer hacia dónde van los datos.

    Leer archivos

    Primero, se localizan los archivos y se extrae su texto en bruto, ya sean notas en Markdown o documentos de Word desorganizados:

    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"
    

    Fragmentación

    A continuación, el texto se divide mediante una ventana deslizante sencilla, de modo que una oración que atraviesa el límite mantiene su contexto:

    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)]
    

    Embebidos e IDs estables

    La embebición se realiza localmente, sin ninguna llamada a una API externa por oración. Cada fragmento también recibe un ID predecible derivado del hash de su texto, de modo que el texto sin cambios mantiene el mismo ID de una ejecución a otra:

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

    La incrustación en sí tiene lugar dentro de la llamada a Qdrant:

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

    Sincronización de archivos con la base de datos

    Aquí se armonizan los archivos locales con la base de datos. Corregir un error tipográfico no elimina el índice ni requiere reiniciar. El código compara los IDs, elimina los fragmentos que han desaparecido y agrega nuevos ones:

    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...}
    

    También se eliminan los archivos que se quitan de la carpeta:

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

    Responder a una consulta

    Cuando llega una pregunta, a Qdrant se le solicitan las mejores coincidencias entre los documentos seleccionados. Un asistente determina primero en qué índices buscar:

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

    Luego, la consulta se ejecuta contra cada uno de ellos y se fusionan los resultados:

    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]
    

    Generación

    Finalmente, los fragmentos recuperados se envían directamente a Gemini, el cual se basa en el texto proporcionado:

    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
    

    El resto es código de soporte. get_client() abre la conexión a Qdrant, load_state() y save_state() leen y escriben en .rag_state.json, y sanitize_index_name() convierte los nombres de los archivos en nombres de colección válidos. Las funciones de comando (cmd_list_files, cmd_index, cmd_watch) vinculan todo con las opciones de la línea de comandos.

    Ejecutarlo localmente

    Clona el repositorio e ingresa a la carpeta del proyecto:

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

    Luego cree un entorno, instale los requisitos y configure el archivo de configuración:

    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
    

    Active nuevamente el entorno virtual en cualquier terminal nueva antes de ejecutar app.py. Es necesario establecer GEMINI_API_KEY para que -q genere respuestas, mientras que los demás comandos funcionan sin él.

    Uso en la línea de comandos

    Todo lo relacionado con la ingesta y las consultas se gestiona desde la terminal. Para ver qué archivos se encuentran en la carpeta de documentos y cuáles requieren atención, o qué índices existen:

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

    Para procesar nuevos documentos o actualizar los modificados:

    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
    

    Para un indexado automático mientras se edita, mantenga esto en ejecución en una segunda terminal:

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

    Para hacer preguntas sobre un archivo, varios archivos o todo:

    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
    

    El estado que muestra -lf puede tener tres valores. not_indexed indica que el archivo nunca ha sido procesado, indexed significa que está actualizado, y modified indica que ha cambiado desde la última ejecución, por lo que se debe repetir -i.

    Decisiones de diseño

    Algunas decisiones permiten mantener todo rápido y sencillo.

    • Qdrant: cada archivo cuenta con su propia colección, cuyo nombre proviene del nombre del archivo una vez limpio, al que se le agrega un sufijo numérico en caso de colisión. Por defecto utiliza el modo local en disco (./qdrant_storage), por lo que no se necesita servidor. Para acceso concurrente, establezca QDRANT_URL en .env para apuntar a un servidor Qdrant real. El modo local bloquea el directorio para un solo proceso, por lo que -w y -q no pueden ejecutarse simultáneamente.
    • Embeddings: el modelo BAAI/bge-small-en-v1.5 se ejecuta a través de fastembed. Se descarga una vez y se almacena en caché, por lo que no hay costos de API ni dependencia de red en el momento de la consulta.
    • Gemini: solo escribe la respuesta final a partir de los fragmentos recuperados, y utiliza por defecto gemini-3.5-flash.
    • Estado: .rag_state.json registra los hashes de los archivos, el estado, los nombres de los índices y la cantidad de fragmentos, lo que hace que -lf y -li funcionen de inmediato, ya que Qdrant no necesita volver a escanear. Los IDs de los fragmentos provienen del propio texto, por lo que el reindexado es incremental y solo se vuelven a incrustar y actualizar los fragmentos modificados.
    • Tipos de archivo: .txt y .md funcionan de inmediato. .pdf y .docx requieren pypdf o docx2txt, ambos ya incluidos en los requisitos.

    Leer más