DEV Community

Cover image for LLPY-02: Configurando un Entorno de Desarrollo Moderno con UV
Jesus Oviedo Riquelme
Jesus Oviedo Riquelme

Posted on

LLPY-02: Configurando un Entorno de Desarrollo Moderno con UV

#tutorial #rag #python #tooling

🎯 El Desafío del Desarrollo Moderno

Imagina que estás comenzando un proyecto de IA complejo como nuestro sistema RAG. Necesitas:

  • Múltiples entornos (desarrollo, testing, producción)
  • Dependencias específicas para cada componente (API, procesamiento, notebooks)
  • Versiones exactas de Python y paquetes para reproducibilidad
  • Gestión eficiente de dependencias sin conflictos
  • Colaboración fluida entre desarrolladores

El problema tradicional: pip + requirements.txt + virtualenv se vuelve un caos con proyectos complejos. Dependencias conflictivas, versiones inconsistentes, y tiempo perdido resolviendo problemas de compatibilidad.

📊 La Magnitud del Problema en Proyectos RAG

En un sistema RAG como el nuestro, manejamos múltiples componentes con dependencias muy diferentes:

Stack Tecnológico Complejo:

  • FastAPI para la API REST
  • Qdrant para la base de datos vectorial
  • OpenAI/Gemini para modelos de lenguaje
  • Sentence-Transformers para embeddings
  • Google Cloud para infraestructura
  • Terraform para IaC
  • Docker para containerización

Los Problemas Específicos:

  1. 🔀 Conflictos de Dependencias: Diferentes versiones de numpy, torch, o transformers entre componentes
  2. ⏱️ Tiempo de Resolución: Resolver dependencias puede tomar 10-15 minutos en proyectos complejos
  3. 🐍 Versiones de Python: Diferentes componentes requieren diferentes versiones de Python
  4. 📦 Gestión de Paquetes: Instalación, actualización y eliminación de paquetes es propensa a errores
  5. 🔄 Reproducibilidad: Dificultad para replicar exactamente el mismo entorno en diferentes máquinas

💡 La Solución: UV - El Gestor de Dependencias del Futuro

UV es un gestor de paquetes Python extremadamente rápido escrito en Rust que resuelve todos estos problemas:

¿Por Qué UV es Perfecto para Proyectos RAG?

  • ⚡ Velocidad Extrema: 10-100x más rápido que pip
  • 🔒 Resolución Determinística: Garantiza entornos idénticos
  • 📦 Gestión Multi-Proyecto: Maneja múltiples componentes independientes
  • 🐍 Gestión de Python: Instala y gestiona versiones de Python automáticamente
  • 🔧 Compatibilidad Total: Funciona con pip, pip-tools, poetry, y más

La Arquitectura de la Solución: 

📁 lus-laboris-py/
├── 📦 src/lus_laboris_api/pyproject.toml (API)
├── 📦 src/processing/pyproject.toml (Procesamiento)
├── 📦 notebooks/pyproject.toml (Jupyter)
├── 📦 utils/pyproject.toml (Utilidades)
└── 🔐 .env (variables de entorno)
Enter fullscreen mode Exit fullscreen mode

🚀 Configuración Paso a Paso

1. Instalación de UV 

# Instalación con curl (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# O con pip
pip install uv

# Verificar instalación
uv --version
Enter fullscreen mode Exit fullscreen mode

2. Estructura del Proyecto Multi-Componente

Nuestro proyecto está organizado en 4 componentes independientes, cada uno con su propio pyproject.toml:

Componente API (FastAPI) 

# src/lus_laboris_api/pyproject.toml
[project]
name = "lus-laboris-api"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.116.2",
    "qdrant-client>=1.15.1",
    "openai>=1.109.1",
    "sentence-transformers>=5.1.0",
    "pydantic>=2.11.9",
    "uvicorn>=0.35.0",
]
Enter fullscreen mode Exit fullscreen mode

Componente Procesamiento 

# src/processing/pyproject.toml
[project]
name = "processing"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "beautifulsoup4>=4.13.5",
    "requests>=2.32.5",
    "google-cloud-storage>=3.3.1",
    "ftfy>=6.3.1",
]
Enter fullscreen mode Exit fullscreen mode

3. Configuración de Variables de Entorno

El archivo .env centraliza toda la configuración:

# ==========================================================
# Configuración Básica de Docker
# ==========================================================
DOCKER_HUB_USERNAME=tu_usuario
DOCKER_IMAGE_NAME_RAG_API=legal-rag-api

# ==========================================================
# Configuración GCP
# ==========================================================
GCP_PROJECT_ID=tu-proyecto-gcp
GCP_REGION=us-central1
GCP_BUCKET_NAME=tu-bucket-legal

# ==========================================================
# Configuración de Qdrant
# ==========================================================
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=tu_clave_api

# ==========================================================
# Credenciales de LLM
# ==========================================================
OPENAI_API_KEY=sk-tu-clave-openai
GEMINI_API_KEY=tu-clave-gemini

# ==========================================================
# Configuración de la API
# ==========================================================
API_HOST=0.0.0.0
API_PORT=8000
API_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
API_LLM_PROVIDER=openai
Enter fullscreen mode Exit fullscreen mode

4. Scripts de Automatización

Creamos scripts para automatizar tareas comunes:

Script de Desarrollo de la API 

#!/bin/bash
# src/lus_laboris_api/start_api_dev.sh

echo "🚀 Iniciando API en modo desarrollo..."

# Activar entorno virtual
uv venv
source .venv/bin/activate

# Instalar dependencias
uv sync

# Iniciar servidor de desarrollo
uv run uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
Enter fullscreen mode Exit fullscreen mode

Script de Procesamiento de Datos 

#!/bin/bash
# src/processing/run_processing.sh

echo "📊 Procesando datos legales..."

# Activar entorno virtual
uv venv
source .venv/bin/activate

# Instalar dependencias
uv sync

# Ejecutar procesamiento
uv run python extract_law_text.py --mode gcs --bucket-name $GCP_BUCKET_NAME
Enter fullscreen mode Exit fullscreen mode

🎯 Casos de Uso Reales

Para Desarrolladores:

"Necesito trabajar en la API pero también en el procesamiento de datos"

Solución UV: Cada componente tiene su entorno independiente

# Trabajar en la API
cd src/lus_laboris_api/
uv sync
uv run python -m api.main

# Trabajar en procesamiento
cd src/processing/
uv sync
uv run python extract_law_text.py
Enter fullscreen mode Exit fullscreen mode

Para DevOps:

"Necesito desplegar solo la API en producción"

Solución UV: Construcción de imagen Docker optimizada

# Dockerfile para API
FROM python:3.13-slim
WORKDIR /app
COPY src/lus_laboris_api/pyproject.toml .
RUN uv sync --locked
COPY src/lus_laboris_api/ .
CMD ["uv", "run", "uvicorn", "api.main:app", "--host", "0.0.0.0"]
Enter fullscreen mode Exit fullscreen mode

Para Colaboradores:

"¿Cómo configuro el proyecto en mi máquina?"

Solución UV: Un solo comando para todo

# Clonar repositorio
git clone https://github.com/jesusoviedo/lus-laboris-py.git
cd lus-laboris-py

# Configurar variables de entorno
cp .env_example .env
# Editar .env con tus credenciales

# Ir a la carpeta donde está pyproject.toml 

# Instalar todos los componentes
uv sync --all
Enter fullscreen mode Exit fullscreen mode

🚀 El Impacto Transformador

Antes de UV:

  • ⏱️ 15 minutos para configurar el entorno
  • 🔀 Conflictos frecuentes entre dependencias
  • 🐍 Problemas de versiones de Python
  • 📦 Gestión manual de paquetes

Después de UV:

  • ⚡ 2 minutos para configurar el entorno
  • 🔒 Resolución automática de conflictos
  • 🐍 Gestión automática de Python
  • 📦 Instalación determinística de paquetes

🔧 Características Técnicas Destacadas

Resolución de Dependencias Inteligente:

  • Algoritmo SAT: Resuelve conflictos de dependencias de forma óptima
  • Caché Global: Reutiliza paquetes entre proyectos
  • Lock Files: Garantiza reproducción exacta de entornos

Gestión Multi-Proyecto:

  • Workspaces: Múltiples proyectos en un repositorio
  • Dependencias Compartidas: Evita duplicación de paquetes
  • Configuración Centralizada: Un solo lugar para configurar todo

Integración con Herramientas Existentes:

  • Docker: Construcción de imágenes optimizadas
  • CI/CD: Integración con GitHub Actions
  • IDEs: Soporte completo para VS Code, PyCharm, etc.

📊 Métricas de Rendimiento

Comparación de Velocidad:

  • pip: 45 segundos para instalar dependencias
  • uv: 3 segundos para instalar las mismas dependencias
  • Mejora: 15x más rápido

Gestión de Memoria:

  • pip: 200MB de RAM durante instalación
  • uv: 50MB de RAM durante instalación
  • Mejora: 4x menos memoria

🎯 El Propósito Más Grande

Esta configuración no es solo sobre herramientas - es sobre productividad del desarrollador. Al eliminar la fricción en la configuración del entorno, los desarrolladores pueden:

  • Enfocarse en el código en lugar de resolver dependencias
  • Colaborar eficientemente sin problemas de "funciona en mi máquina"
  • Desplegar con confianza sabiendo que el entorno es idéntico
  • Escalar el equipo sin perder tiempo en configuración

🚀 ¿Qué Viene Después?

Con nuestro entorno de desarrollo moderno configurado, estamos listos para el siguiente paso: extraer y procesar datos legales. En la próxima publicación exploraremos cómo automatizar la descarga y estructuración del Código del Trabajo paraguayo, transformando HTML crudo en datos estructurados listos para nuestro sistema RAG.

¿Estás listo para ver la magia del procesamiento de datos? El siguiente post mostrará cómo convertir 410 artículos legales en una base de datos vectorial inteligente.

Top comments (0)