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.
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:
- Ingestión: un archivo llega a una carpeta,
documents/en este código. - 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.
- 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.
- 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.
- 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.
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, establezcaQDRANT_URLen.envpara apuntar a un servidor Qdrant real. El modo local bloquea el directorio para un solo proceso, por lo que-wy-qno pueden ejecutarse simultáneamente. - Embeddings: el modelo
BAAI/bge-small-en-v1.5se 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.jsonregistra los hashes de los archivos, el estado, los nombres de los índices y la cantidad de fragmentos, lo que hace que-lfy-lifuncionen 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:
.txty.mdfuncionan de inmediato..pdfy.docxrequierenpypdfodocx2txt, ambos ya incluidos en los requisitos.
Leer más
- Un pipeline RAG mínimo en Go con embeddings de langchaingo, Groq y Jina — Crea generación mejorada por recuperación de información en pura Go: un almacén de vectores en memoria, búsqueda por coseno, Groq para obtener respuestas, Jina para los embeddings, y por qué un contexto deficiente genera respuestas deficientes.
- Por qué RAG no encuentra la página con la respuesta: pan, levadura y vectores — Por qué la búsqueda por similitud puede recuperar páginas sobre el tema correcto pero pasar por alto la que contiene la respuesta, cómo las tablas y los límites top-k empeoran la situación, y qué probar primero.