██FR█████ █INTELL███████████

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


This content originally appeared on DEV Community and was authored by Jesus Oviedo Riquelme

🎯 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/
├── 🔧 pyproject.toml (configuración global)
├── 📦 src/lus_laboris_api/pyproject.toml (API)
├── 📦 src/processing/pyproject.toml (Procesamiento)
├── 📦 notebooks/pyproject.toml (Jupyter)
├── 📦 utils/pyproject.toml (Utilidades)
└── 🔐 .env (variables de entorno)

🚀 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

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",
]

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",
]

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

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

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

🎯 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




### **Para DevOps:**
> *"Necesito desplegar solo la API en producción"*
> 
> **Solución UV**: Construcción de imagen Docker optimizada
>

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

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

Instalar todos los componentes

uv sync –all




## **🚀 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.


This content originally appeared on DEV Community and was authored by Jesus Oviedo Riquelme