RAG Avanzado en Python

Este proyecto implementa un pipeline de Retrieval-Augmented Generation (RAG) modular y extensible orientado a entornos productivos. Se apoya en embeddings de SentenceTransformers, almacenamiento vectorial persistente con Chroma, re-ranking con CrossEncoder y un generador configurable que puede usar modelos locales o APIs externas.

Características principales

• Ingesta multimodal: soporta ficheros .txt, .md y .pdf, con normalización y metadatos.
• Chunking adaptativo: división configurable por tokens o caracteres, con solapamiento optimizado para preservar contexto.
• Embeddings de alta calidad: usa sentence-transformers/all-MiniLM-L6-v2 por defecto, con caché en disco.
• Vector store persistente: almacenamiento incremental sobre ChromaDB, permite reindexado y refresco parcial.
• Re-ranking semántico: reranker basado en cross-encoder/ms-marco-MiniLM-L-6-v2 para mejorar la precisión de recuperación.
• Generador flexible: interfaz común para transformers locales, OpenAI, Gemini, NVIDIA y otros proveedores (integración mediante configuración).
• CLI unificada: comandos para ingestar, reconstruir el índice y ejecutar consultas con seguimiento en consola.
• Configuración centralizada: parámetros agrupados en config/default.yaml, sobreescribibles mediante CLI.

Requisitos

• Python 3.10 o superior.
• Dependencias listadas en requirements.txt. Se recomienda crear un entorno virtual:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Para usar modelos de transformers se recomienda tener instalado git y una cuenta en Hugging Face si se quieren descargar modelos privados. El pipeline funciona sin GPU, pero aprovechará CUDA/Metal si está disponible.

Uso rápido

1. Ingestar documentos (busca archivos en data/raw por defecto):

   python -m rag_advanced.cli ingest --source ./data/raw

2. Reconstruir el índice (embeddings + vector store + reranker):

   python -m rag_advanced.cli build-index

3. Consultar:

   python -m rag_advanced.cli query "¿Qué dice la documentación sobre el preprocesamiento?"

El comando query admite opciones como --top-k, --with-rerank/--no-rerank, --max-context-tokens y --config para cargar distintos perfiles.

Pruebas

Las pruebas básicas (carga de configuración) se ejecutan con pytest. Instala la dependencia (pip install pytest) y ejecuta:

pytest

Estructura del proyecto

.
├── config/
│   └── default.yaml
├── data/
│   ├── processed/
│   └── raw/
├── src/
│   └── rag_advanced/
│       ├── __init__.py
│       ├── cli.py
│       ├── config.py
│       ├── ingestion.py
│       ├── preprocessing.py
│       ├── embeddings.py
│       ├── vector_store.py
│       ├── reranker.py
│       ├── generator.py
│       └── pipeline.py
└── tests/
    └── ...

Configuración

Los parámetros por defecto residen en config/default.yaml. Se pueden sobreescribir desde la CLI con --config otro_archivo.yaml o con flags individuales como --chunk-size 700. Entre los parámetros clave:

• chunk_size, chunk_overlap: controlan el splitter.
• embedding_model.name: define el modelo de embeddings.
• vector_store.persist_path: ruta del índice persistente.
• generator.provider: transformers, openai, gemini, nvidia o mock.
• reranker.enabled: activa/desactiva el re-ranking semántico.

Uso con Google Gemini

1. Instala la dependencia (ya incluida en requirements.txt): pip install google-generativeai.
2. Define la variable de entorno antes de ejecutar la CLI:

   export GEMINI_API_KEY="tu_api_key_de_gemini"

3. Asegúrate de que en config/default.yaml (o tu archivo de configuración) generator.provider sea gemini y ajusta generator.gemini.model si deseas otro modelo (por ejemplo models/gemini-1.5-pro). El valor por defecto usa models/gemini-1.5-flash-latest; puedes listar tus opciones con:

   python - <<'PY'
   import google.generativeai as genai, os
   genai.configure(api_key=os.environ["GEMINI_API_KEY"])
   for m in genai.list_models():
       if "generateContent" in m.supported_generation_methods:
           print(m.name)
   PY

4. Ejecuta los comandos habituales (build-index, query).

Nota: nunca compartas tu API key en texto plano dentro del repositorio ni en archivos versionados.

Uso con NVIDIA NIM / Integrate API

1. Instala dependencias (pip install -r requirements.txt) para asegurarte de tener requests.
2. Exporta tu clave antes de usar la CLI:

   export NVIDIA_API_KEY="tu_api_key_de_nvidia"

3. En config/default.yaml, coloca generator.provider: nvidia y ajusta el bloque generator.nvidia si deseas otro modelo o endpoint. Por ejemplo, puedes usar meta/llama3-70b-instruct o cualquier otro listado en NVIDIA API Catalog.
4. Ejecuta los comandos habituales (build-index, query).

Si la API devuelve un error, la CLI mostrará el status_code y el cuerpo de la respuesta para que puedas diagnosticarlo (verifica cuotas, nombre del modelo y la validez de la API key).

Extensión

• Añade nuevos loaders implementando BaseLoader y registrándolos en ingestion.py.
• Sustituye el vector store creando otra implementación de BaseVectorStore.
• Integra un LLM distinto heredando de BaseGenerator.
• Para evaluación de retrieval se incluye un esqueleto en tests/test_pipeline.py que se puede ampliar con datasets controlados.

Próximos pasos sugeridos

• Automatizar pipelines con make o invoke.
• Añadir un panel FastAPI + Streamlit para front interactivo.
• Incorporar métricas RAG (p.ej. Faithfulness con ragas).

Licencia

Este repositorio se publica sin licencia explícita. Ajusta este archivo según tus necesidades antes de distribuir.