DEV Community

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

Posted on • Edited 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

🔗 Recursos y Enlaces

Repositorio del Proyecto

  • GitHub: lus-laboris-py - Sistema completo de procesamiento de datos legales con observabilidad

Top comments (0)