FreeLLMAPI

¿Qué es FreeLLMAPI?

FreeLLMAPI es un servidor proxy compatible con OpenAI que consolida el acceso de nivel gratuito de múltiples proveedores de LLM detrás de una sola superficie de API. En lugar de configurar SDKs separados y manejar diferentes límites de tasa para cada proveedor, apuntas un cliente compatible con OpenAI a tu proxy y envías solicitudes a un solo endpoint.

El proyecto está diseñado para experimentación personal. Agrega claves de ~14 proveedores (vía adaptadores de proveedores), enruta cada solicitud a un modelo disponible y realiza failover automático cuando un proveedor está limitado por tasa o genera errores.

Características principales

• Endpoints compatibles con OpenAI: Implementa POST /v1/chat/completions y GET /v1/models para que los SDK de OpenAI y otros clientes compatibles con OpenAI funcionen cambiando base_url.
• Soporte para streaming: Cuando stream: true, el servidor devuelve respuestas usando Server-Sent Events (SSE); de lo contrario, devuelve una respuesta JSON estándar.
• Passthrough de llamadas a herramientas: Soporta solicitudes de tools / tool_choice al estilo OpenAI y reenvía tool_calls del asistente más mensajes posteriores de rol tool a través de adaptadores de proveedores.
• Failover automático y reintentos: Si el proveedor seleccionado devuelve 429, 5xx o expira el tiempo, el enrutador marca esa clave como temporalmente no disponible y reintenta con el siguiente proveedor en la cadena de fallback (hasta 20 intentos).
• Seguimiento de uso por clave contra límites de proveedores: Rastrea RPM, RPD, TPM y TPD por (platform, model, key) y selecciona claves que están por debajo de sus límites de nivel gratuito.
• Enrutamiento multi-turn sticky: Mantiene una conversación en el mismo modelo durante 30 minutos para reducir cambios en medio de la conversación.
• Almacenamiento cifrado de claves: Cifra las claves de proveedores upstream con AES-256-GCM antes de almacenarlas en SQLite; la desencriptación ocurre en memoria justo antes del uso.
• Autenticación unificada del proxy: Tu cliente se autentica con el proxy usando un solo token bearer freellmapi-... en lugar de usar claves de proveedores upstream.
• Comprobaciones de salud y controles de admin: Sondas periódicas etiquetan las claves como saludables/limitadas por tasa/inválidas/error; el dashboard de admin incluido (React + Vite) te permite gestionar claves, reordenar prioridad de fallback, inspeccionar analíticas y ejecutar un playground de prompts.

Cómo usar FreeLLMAPI

1. Instala requisitos: Usa Node.js 20+ y npm.
2. Clona e instala:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Configura el entorno:
   • Copia el env de ejemplo: cp .env.example .env
   • Genera un ENCRYPTION_KEY y colócalo en .env (el repo proporciona un comando que genera una clave hex aleatoria de 32 bytes).
4. Inicia el proxy: Ejecuta el servidor como se describe en el quick start / README del repositorio (el extracto de contenido de la página incluye los pasos de setup, y la documentación del repositorio cubre el comando de inicio exacto).
5. Configura tu cliente compatible con OpenAI:
   • Establece el base_url de tu cliente en tu servidor local FreeLLMAPI.
   • Autentícate con el token bearer del proxy (freellmapi-...) y llama a POST /v1/chat/completions (opcionalmente con stream: true).

Casos de uso

• Pruebas de chat en una sola base de código entre proveedores: Apunta una app existente compatible con OpenAI (o librería) al proxy para experimentar con muchos modelos sin gestionar SDKs de proveedores separados.
• Reducción de fallos manuales por límites de tasa: Usa el failover automático para saltar proveedores que responden con 429/5xx/timeouts y continúa la solicitud vía el siguiente modelo disponible en tu orden de fallback configurado.
• Flujos de chat con uso de herramientas: Ejecuta solicitudes de llamadas a herramientas al estilo OpenAI donde tool_calls y mensajes de resultado de herramientas se enrutan a través del mismo flujo de proxy subyacente.
• Consistencia en conversaciones largas: Mantén sesiones de chat en el mismo modelo durante uso activo (sesiones sticky por 30 minutos) mientras sigues beneficiándote del fallback si el proveedor se vuelve no disponible.
• Experimentación local con manejo cifrado de claves: Centraliza claves upstream dentro del proxy con almacenamiento cifrado en reposo, para que tus apps cliente no necesiten exponer claves de proveedores.

Preguntas frecuentes

• ¿FreeLLMAPI soporta la API completa de OpenAI? No. El proyecto se enfoca en completaciones de chat y la lista de modelos (/v1/chat/completions, /v1/models). Embeddings, imágenes, audio/voz e inputs multimodales no están soportados, al igual que /v1/completions legacy, moderación y múltiples completaciones por solicitud.

• ¿Cómo maneja FreeLLMAPI los límites de tasa? Rastrea contadores de uso por clave (RPM/RPD/TPM/TPD) y selecciona claves por debajo de los límites. Si un proveedor aún devuelve 429 (o 5xx/timeouts), el enrutador reintenta con el siguiente proveedor en la cadena de fallback.

• ¿El streaming funcionará con mi cliente? Sí. El proxy soporta streaming vía SSE cuando stream: true en el endpoint de chat.

• ¿Puedo usar librerías existentes compatibles con OpenAI? El proxy está diseñado para funcionar con SDKs oficiales de OpenAI y otros clientes compatibles con OpenAI apuntándolos al base_url del proxy.

• ¿Está pensado para uso en producción? El repositorio indica explícitamente que es “solo para experimentación personal”.

Alternativas

• Usar un proveedor único directamente: Muchos servicios ofrecen su propia API con semántica consistente, pero no obtendrías agregación multi-proveedor, failover automático ni apilamiento de tiers gratuitos en un solo endpoint.
• Construir tu propio router/capa de fallback: Un proxy personalizado puede implementar failover y rotación de claves, pero tendrías que gestionar SDKs específicos de proveedores, límites y manejo de errores tú mismo.
• Usar un framework de orquestación que soporte múltiples backends LLM: Algunas herramientas enrutan solicitudes entre diferentes proveedores de modelos, pero el flujo de trabajo puede diferir (y puede no ofrecer el mismo comportamiento de proxy compatible con OpenAI en /v1/chat/completions descrito aquí).
• Cambio manual de claves y modelos: Puedes seleccionar proveedores manualmente en tu aplicación, pero pierdes el reintento/failover automático y el control de límites por clave que proporciona FreeLLMAPI.