Guía LiteLLM Proxy para macOS con UV (Principiantes)

Objetivo: configurar rápidamente LiteLLM Proxy en macOS en 15 a 20 minutos usando UV, sin crear una estructura de proyecto formal. Guía pensada para principiantes y equipos técnicos que desean unificar proveedores de modelos de inteligencia artificial en una sola API. En Q2BSTUDIO, expertos en aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud AWS y Azure, servicios inteligencia de negocio y agentes IA, integramos este tipo de arquitectura en entornos corporativos para escalar de forma segura y eficiente. Si buscas asesoría integral en IA para empresas, puedes conocer más en nuestra página de inteligencia artificial.

Lo que necesitas

- Un Mac con macOS 10.15 o superior

- Conexión a internet

- 20 minutos

- Una clave de API de tu proveedor preferido como OpenAI, Anthropic o Groq

Paso 1: instalar herramientas

1.1 Homebrew

- Verifica brew con: brew --version

- Si no está instalado, sigue las instrucciones oficiales en la web de Homebrew

1.2 UV gestor moderno de paquetes de Python

- Instala: brew install uv

- Verifica: uv --version

1.3 PostgreSQL

- Instala: brew install postgresql@14

- Inicia servicio: brew services start postgresql

- Comprueba que corre: brew services list | grep postgresql

Paso 2: crear base de datos

- Crea DB: createdb litellm_db

- Verifica: psql -l | grep litellm_db

- Anota tu usuario con: whoami porque se usará para la conexión

Paso 3: crear entorno virtual con UV sin proyecto formal

- Ve a tu carpeta de trabajo, por ejemplo: cd ~/Documents

- Crea carpeta: mkdir litellm-setup y entra: cd litellm-setup

- Crea el entorno: uv venv

- Activa: source .venv/bin/activate

- A partir de aquí ejecuta todo con el entorno activado

Paso 4: instalar LiteLLM y dependencias

- Instala: uv pip install litellm[proxy] prisma psycopg2-binary

- Verifica: litellm --version

Paso 5: generar cliente Prisma

- Localiza el schema de Prisma dentro del paquete: find .venv -name schema.prisma -path */litellm/*

- Genera el cliente indicando la ruta localizada: python -m prisma generate --schema .venv/lib/python3.12/site-packages/litellm/proxy/schema.prisma

Nota: la versión de Python de tu .venv puede variar, usa la ruta que te devuelva el comando find.

Paso 6: configuración

6.1 Crea config.yaml

Contenido recomendado:

litellm_settings:

drop_params: true

general_settings:

model_list:

- model_name: groq-llama3-fast

litellm_params:

model: groq/llama3-8b-8192

api_key: os.environ/GROQ_API_KEY

- model_name: gpt-3.5-turbo

litellm_params:

model: gpt-3.5-turbo

api_key: os.environ/OPENAI_API_KEY

6.2 Crea archivo de variables de entorno .env

Reemplaza USERNAME por el resultado de whoami si difiere de tu usuario habitual

LITELLM_MASTER_KEY=sk-1234

LITELLM_SALT_KEY=sk-1234

LITELLM_DROP_PARAMS=True

PORT=4000

STORE_MODEL_IN_DB=True

DATABASE_URL=postgresql://USERNAME@localhost:5432/litellm_db

GROQ_API_KEY=your-groq-api-key-here

OPENAI_API_KEY=your-openai-key-here

ANTHROPIC_API_KEY=your-anthropic-key-here

Paso 7: iniciar LiteLLM

- Inicia el proxy: litellm --config config.yaml --port 4000

- En el primer arranque se crearán automáticamente las tablas en la base de datos

Paso 8: verificación

- Abre en el navegador: https://localhost:4000

- En la interfaz, entra en Test Key, elige groq-llama3-fast, escribe un mensaje de prueba y envía para validar respuesta

- Prueba de API sin complicarte con comandos: usa Postman o Insomnia. Método POST a la ruta https://localhost:4000/chat/completions con cabeceras Authorization Bearer sk-1234 y Content-Type application/json. En el cuerpo JSON indica el modelo groq-llama3-fast y un array messages con rol user y un contenido de prueba

Gestión de base de datos de LiteLLM

- Conexión a tu DB: psql -U USERNAME -h localhost -p 5432 litellm_db

- Listado de tablas: \dt

- Esquema de una tabla: \d NOMBRE_TABLA tal como aparece en el listado

- Ver algunos registros: SELECT * FROM NOMBRE_TABLA LIMIT 5;

Eliminar por completo la base de datos cuidado, operación irreversible

- Conéctate a la base postgres: psql -U USERNAME -h localhost -p 5432 postgres

- Ejecuta: DROP DATABASE litellm_db;

- Al reiniciar LiteLLM se recreará la estructura y migraciones

Limpiar datos concretos logs, gasto, tokens sin borrar la base

- Detén el proxy LiteLLM antes de hacer cambios

- Conéctate a litellm_db y usa TRUNCATE TABLE NOMBRE_TABLA RESTART IDENTITY en las tablas que desees limpiar por ejemplo tablas de logs o gasto

Paso 9: alias práctico opcional

- Abre tu configuración de shell zsh: nano ~/.zshrc

- Añade una función sin comillas para arrancar rápido y ajusta la ruta a tu carpeta

litellm-start() { cd /Users/USERNAME/Documents/litellm-setup && source .venv/bin/activate && litellm --config config.yaml --port 4000; }

- Recarga configuración: source ~/.zshrc y ya podrás ejecutar litellm-start desde cualquier carpeta

Solución de problemas

- Error command not found litellm Activa el entorno: source .venv/bin/activate

- ModuleNotFoundError No module named prisma Instala en el entorno activo: uv pip install prisma y vuelve a generar el cliente de Prisma

- The Client hasnt been generated yet Ejecuta de nuevo python -m prisma generate con la ruta correcta del schema

- Database connection failed Verifica que PostgreSQL esté activo con brew services list | grep postgresql, que la base exista con psql -l | grep litellm_db y que tu DATABASE_URL tenga el usuario y nombre correctos

- Config file not found Asegúrate de ejecutar el comando en la carpeta donde está config.yaml

- Invalid API key Revisa las claves en tu archivo .env

- Port 4000 already in use Ejecuta con otro puerto: litellm --config config.yaml --port 4001

Lo que has logrado

- Proxy LiteLLM en localhost:4000

- Interfaz web para gestión de modelos, claves y estadísticas

- API unificada compatible con OpenAI para múltiples proveedores

- Entorno reproducible con UV

- Integración con base de datos para control de gasto, auditoría y administración

- Alias para uso diario

Por qué este setup es potente

- Interfaz unificada para OpenAI, Anthropic, Groq y más de cien modelos

- Control y trazabilidad de costes con presupuestos y límites

- Rate limiting y seguridad sobre el consumo

- Tooling moderno y rápido con UV

- Preparado para producción con backend PostgreSQL

- Ideal para equipos de desarrollo que buscan consistencia y escalabilidad

Siguientes pasos

- Añade más modelos en config.yaml

- Crea claves con permisos y límites distintos

- Activa monitorización y alertas

- Integra la API en tus aplicaciones a medida y en tus agentes IA

- Escala en la nube con contenedores y orquestadores, y aprovecha nuestra experiencia en servicios cloud AWS y Azure

Sobre Q2BSTUDIO

Somos una empresa de desarrollo de software que crea aplicaciones a medida y software a medida para compañías que buscan ventaja competitiva con inteligencia artificial, ciberseguridad, automatización de procesos, servicios cloud y servicios inteligencia de negocio. Diseñamos arquitecturas seguras, implantamos agentes IA y analítica con power bi, y acompañamos a tu equipo desde el prototipo hasta la operación 24x7. Si quieres acelerar tu roadmap de ia para empresas o necesitas pentesting y hardening, cuenta con nuestro equipo.

Palabras clave recomendadas para tu proyecto y este enfoque técnico de LiteLLM: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi, automatización de procesos.