Saltar al contenido principal

Plugins

Libre WebUI utiliza plugins para conectar proveedores externos de IA y capacidades de modelos junto a Ollama local.

Tipos de plugins​

TipoFinalidad
Chat/finalizaciónModelos de texto y chat de API de proveedores
EmbeddingsEmbeddings vectoriales para búsqueda y memoria
Generación de imágenesModelos de imagen y backends similares a ComfyUI
Texto a vozProveedores de síntesis de voz
Voz a textoProveedores de transcripción
Generación de audioProveedores de sonido y audio
Generación de vídeoProveedores de vídeo asíncrono

Los plugins pueden exponer mapas estáticos y, cuando sea posible, actualizar los modelos disponibles desde la API del proveedor.

Familias de proveedores incluidas​

Libre WebUI incluye definiciones para servicios habituales:

  • OpenAI y API compatibles con OpenAI
  • Anthropic
  • Google Gemini
  • Groq
  • Kimi Code de Moonshot AI
  • Mistral
  • OpenRouter
  • Hugging Face
  • GitHub Models
  • MLX LM para inferencia local en Apple Silicon
  • ComfyUI
  • ElevenLabs

Los catálogos cambian con frecuencia. La interfaz debe considerarse la fuente de verdad del descubrimiento en vivo cuando sea compatible.

Propiedad y autorización​

Las definiciones son configuración compartida de la instancia. Todas las rutas /api/plugins exigen autenticación y solo los administradores pueden subir, instalar, actualizar o eliminar una definición. La activación es distinta: cada usuario autenticado puede activar o desactivar un plugin compartido solo para su cuenta. El estado se guarda en SQLite y persiste sin afectar a otros usuarios.

Durante una actualización, la antigua lista global .status.json se copia una vez a las cuentas existentes, pero solo para definiciones que coincidan exactamente con los anclajes de confianza compilados. Las personalizadas o que ocultan otras quedan en cuarentena e inactivas. Las cuentas nuevas empiezan sin plugins activos.

Las definiciones incluidas solo son de confianza cuando su contenido normalizado coincide con un hash compilado. Las escribibles se aprueban en SQLite por ruta normalizada y hash completo. Instalar, actualizar o reimportar como administrador registra la aprobación; modificar el archivo directamente la invalida. La aprobación y actualización borran la activación de todas las cuentas antes de sustituir el archivo para que cada usuario reactive lo revisado. Las definiciones personalizadas anteriores deben reimportarse antes de aparecer, descubrir modelos, aceptar credenciales o ejecutar capacidades.

Las variables se separan por finalidad. Solo los administradores pueden guardar variables reconocidas de enrutamiento:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model y model_id. También se consideran enrutamiento las variables declaradas por una capacidad en config.endpoint_variable, config.models_endpoint_variable o config.voice_clone_endpoint_variable aunque tengan otro nombre.

Los demás usuarios pueden guardar controles de generación, como temperatura y streaming. Las filas antiguas de enrutamiento que les pertenezcan se ignoran, no se devuelven como configuradas y se eliminan al restablecer todas sus variables. Así, un ascenso posterior no revive una ruta latente.

Credenciales​

Pueden proceder de variables de entorno o ajustes del usuario.

Ejemplos:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...

En despliegues compartidos suelen ser mejores las credenciales por usuario porque cada persona controla su facturación y límites. Las claves de entorno son útiles en instalaciones individuales, demostraciones o despliegues administrados.

Una clave de entorno solo sirve de reserva mientras la solicitud utilice el enrutamiento y autenticación de una definición incluida no sombreada. Una definición importada, escribible que oculta un ID incluido o una anulación de conexión exige una credencial guardada por la misma cuenta. Libre WebUI compara raíz, autenticación, endpoints de capacidades, selectores y definiciones/valores de variables antes de permitir la reserva. El hash compilado sigue siendo autoritativo aunque los directorios heredado e incluido compartan ruta, como en el contenedor; sobrescribir el manifiesto no establece confianza.

Esta regla se aplica a descubrimiento, Chat, Work, disponibilidad y catálogos, evitando que un endpoint personalizado o manifiesto antiguo reciba un secreto del operador.

Las credenciales del usuario se vinculan a la fuente y hash efectivos, contrato de autenticación, endpoints y selectores, y valores de enrutamiento al guardarlas. Cambiar ruta o definición las vuelve indisponibles hasta revisar y guardar de nuevo. Las heredadas sin vínculo solo se aceptan en una ruta incluida anclada exacta; el primer uso correcto escribe el vínculo antes de devolver la clave descifrada.

Proveedores compatibles con OpenAI​

Muchos proveedores exponen API compatibles. Un plugin puede definir:

  • URL completa del endpoint
  • Variable de entorno de la clave
  • Comportamiento del endpoint de chat
  • Compatibilidad con embeddings
  • Descubrimiento de modelos
  • Mapa de modelos de reserva opcional

Si no hay descubrimiento en vivo, Libre WebUI utiliza el mapa. Un JSON importado configura proveedores que ya hablan uno de los formatos admitidos: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages o Gemini. El JSON no traduce un protocolo propietario arbitrario; una forma diferente de solicitudes, streaming, herramientas o respuestas necesita un pequeño adaptador en el backend.

Generación de imágenes de OpenAI​

El proveedor incluido expone la API Image en https://api.openai.com/v1/images/generations. El modelo actual es gpt-image-2. El catálogo conserva los ID obsoletos gpt-image-1.5, gpt-image-1 y gpt-image-1-mini para despliegues existentes; las configuraciones nuevas deben usar gpt-image-2.

La generación utiliza la misma credencial efectiva que Chat: clave guardada del usuario o reserva de entorno del proveedor de confianza. Tiene un image_endpoint opcional separado para que un endpoint de Chat personalizado no reciba imágenes. Déjalo vacío para heredar la API incluida.

Las selecciones se califican por proveedor. Si dos plugins exponen el mismo ID, solo recibe la solicitud el seleccionado en el panel. Las respuestas GPT Image usan base64; Libre las convierte y guarda en la galería del usuario. Las rutas requieren autenticación y las solicitudes directas deben incluir pluginId y model. Pueden definir n como entero JSON de 1 a 10; las cadenas numéricas y fracciones se rechazan antes del proveedor.

Modos Chat Completions y Responses API​

Los plugins compatibles pueden usar semántica chat_completions o responses. El plugin OpenAI ofrece la elección en Ajustes → Plugins.

La conexión se resuelve así:

  1. Anulación completa endpoint.
  2. base_url más api_path opcional.
  3. endpoint heredado del plugin.

Un valor idéntico al manifiesto se trata como predeterminado, no anulación, para que valores antiguos no oculten una URL base nueva. Un endpoint verdaderamente personalizado sigue prevaleciendo.

La ruta predeterminada es /chat/completions en Chat Completions y /responses en Responses. base_url debe ser la raíz, como https://api.example.com/v1; utiliza api_path para otra ruta relativa. Un endpoint completo incluye toda la operación y prevalece. Los sufijos conocidos /chat/completions, /completions o /responses determinan la semántica; las rutas personalizadas conservan api_mode.

El JSON importado puede aportar los mismos valores:

{
  "endpoint": "https://api.example.com/v1/chat/completions",
  "api_mode": "responses",
  "base_url": "https://api.example.com/v1",
  "api_path": "/responses"
}

Las solicitudes Responses utilizan input, max_output_tokens, herramientas de funciones aplanadas, store: false y solicitan razonamiento cifrado para continuar sin estado. Las salidas se normalizan a eventos de Chat y Work. El estado de repetición solo se conserva si la matriz ordenada completa no supera 64 Items y 90 KB; los Items permanecen exactos y nunca se truncan por campo. Requieren ID y tipos únicos no vacíos, y se validan mensajes, razonamiento y llamadas antes de emitir herramientas. Un estado de Chat grande vuelve al historial visible normalizado. Chat también descarta Items de llamadas porque no persiste sus resultados. Work rechaza estados con herramientas sin repetición exacta y acotada antes de cualquier efecto.

El almacenamiento SQLite cifra el estado del proveedor con el mensaje; Work guarda estado de herramientas en filas ocultas no devueltas por API. Un ámbito con hash liga la repetición al proveedor, modelo, modo Responses, endpoint final y huella unidireccional de la credencial. Si cambia, incluso al rotar la clave, Libre vuelve al historial normalizado para no cruzar límites. Una ejecución de Work también comprueba su huella antes de cada ronda; cambiar modo, endpoint o clave la detiene antes de enviar estado anterior.

El estado con herramientas debe caber en el límite de repetición y la envoltura completa persistente de 100 KB antes de un efecto. Si se interrumpió un lote, cada resultado ausente se restaura con su ID exacto y aviso de resultado desconocido para que el proveedor inspeccione el espacio en vez de repetir a ciegas. Un resultado Responses incompleto no es un turno correcto; se conserva y muestra incomplete_details.reason.

El descubrimiento deriva /models de la ruta. Por ejemplo, https://api.example.com/v1/responses usa https://api.example.com/v1/models. Un proveedor sin lista compatible puede usar model_map. El descubrimiento se limita a variables y credenciales del usuario y sus resultados se guardan por usuario, no en el manifiesto. Se ejecuta tras activación, actualización, cambios de clave o conexión y restablecimientos; guardar variables de generación no relacionadas no genera red.

También se ejecuta automáticamente al leer un proveedor activo cuyo catálogo falte o sea anterior a PLUGIN_MODEL_DISCOVERY_TTL_MS. Un intervalo evita sondeos constantes y un plazo impide que un proveedor lento retrase la respuesta; lo que termina tarde se sirve después. La URL final se valida antes de leer credenciales o crear Authorization, incluso si procede de un manifiesto importado. Descubrimiento y capacidades no siguen redirecciones. Configura directamente los endpoints finales de Chat, Work, lista, imágenes, embeddings, transcripción, voz, clonación, audio y vídeo.

Los endpoints admiten HTTP o HTTPS. HTTP envía claves, prompts, resultados y contenido sin cifrado de transporte, por lo que solo debe usarse con una puerta autoalojada en una red fiable; prefiere HTTPS. Las solicitudes se originan en el backend: en contenedores usa una URL de servicio como http://ai-gateway:8080/v1, mientras localhost identifica el contenedor Libre WebUI. Las capacidades resuelven variables y credenciales para la cuenta autenticada. No existe modo de un solo usuario sin autenticar.

Endpoints específicos de capacidades​

Las anulaciones de Chat están aisladas de imágenes, embeddings, transcripción, texto a voz, audio y vídeo. Los plugins pueden exponer image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint u otra variable de config.endpoint_variable. La clonación puede nombrar config.voice_clone_endpoint_variable. En blanco se usa el endpoint declarado; un endpoint genérico nunca anula capacidades.

GitHub Models hereda models.github.ai/inference/chat/completions si la anulación está vacía. Hugging Face utiliza rutas y cargas hf-inference/models/{model} específicas para embeddings, imágenes y voz en vez de su endpoint de Chat.

Anulaciones de endpoints​

endpoint es la URL completa, incluida la operación. Un plugin compatible suele usar https://provider.example/v1/chat/completions, no solo https://provider.example. Configuraciones antiguas pueden llamarla api_url; se acepta, pero endpoint no vacío prevalece.

Se aceptan HTTP y HTTPS absolutos; otros protocolos se rechazan. HTTP se reserva a redes fiables. Dejar en blanco usa el endpoint del manifiesto; una anulación inválida se rechaza en vez de volver silenciosamente.

Las solicitudes no siguen redirecciones. Configura la URL final validada; una redirección se informa como error sin reenviar credenciales ni contenido.

Recuerda que las solicitudes vienen del backend. En un contenedor, localhost es el propio contenedor. Usa el nombre del servicio o host.docker.internal cuando esté disponible.

Descubrimiento de modelos​

Ajustes → Plugins incluye un espacio Conexiones de proveedores. Busca a la izquierda, selecciona y revisa estado y catálogo a la derecha. La configuración permanece plegada hasta pulsar Configurar, ocultando endpoints, credenciales y controles avanzados de la vista normal.

Para chat y finalización, Actualizar modelos ejecuta el descubrimiento y recarga catálogo y lista de Chat. El catálogo es de solo lectura: sus filas proceden de los ID descubiertos del usuario y mapas de capacidades. Las etiquetas indican qué ruta lista el modelo, no son comprobaciones de estado. Añade ID manuales al model_map JSON.

Al activar, Libre WebUI intenta descubrir con el endpoint y credencial efectivos. Una ruta personalizada exige credencial de esa cuenta; la reserva de entorno solo se usa con el manifiesto de confianza. Para API compatibles, deriva la lista:

  • una URL que termina en /models se usa tal cual;
  • sufijos como /chat/completions, /completions, /responses, /embeddings o /messages se sustituyen por /models;
  • de lo contrario, se añade /models.

Un plugin puede exponer models_endpoint como lista explícita. Prevalece, sigue la misma política y no redirige. Guardar o restablecer endpoint, api_url, models_endpoint, base_url, api_path o api_mode borra y actualiza el catálogo del usuario.

Todas las rutas personalizadas se validan antes de seleccionar credenciales. Nunca se recurre a una clave de entorno en una ruta guardada; configura una clave por usuario. La reserva se limita al endpoint de la definición de confianza.

El descubrimiento espera una respuesta compatible con una matriz data de ID. La activación espera el intento para incluir el catálogo. Los resultados se superponen por usuario sin reescribir JSON ni exponerlos a otros. Si no hay lista compatible, no se alcanza o cambia la forma, una activación ordinaria conserva el resultado anterior. Cambiar expresamente la conexión lo borra primero y usa model_map si falla.

Guardar o restablecer el enrutamiento borra el catálogo previo para que los modelos de un destino no permanezcan tras cambiarlo.

El estado del plugin, Work, catálogos y capacidades utilizan el mismo contexto y límite de credenciales. Las imágenes también se resuelven para el usuario solicitante.

Selección exacta del proveedor en Chat​

Los ID no son únicos. Ollama y varios plugins pueden exponer example-model. Chat guarda el ID bruto y la identidad opcional:

  • providerType: "ollama" identifica la ruta Ollama;
  • providerType: "plugin" más providerId identifica un plugin.

Las claves calificadas y codificadas en URL solo evitan colisiones en selectores. Las solicitudes envían el ID bruto. Los nombres duplicados son opciones independientes y al reabrir se restaura la exacta.

La identidad explícita falla de forma segura. Si el plugin se desactiva, elimina o deja de anunciar el modelo, la selección sigue visible como no disponible y no cambia a otro con el mismo nombre. Reactívalo o elige otro.

Los registros anteriores pueden tener providerType y providerId sin definir o null. Conservan el enrutamiento por nombre para compatibilidad porque el proveedor no se puede reconstruir. Se muestran como «proveedor no registrado». Seleccionar una entrada concreta la fija. Las personas conservan persona:<id> y las nuevas se registran sobre Ollama.

Ajustes y herencia​

Abre Ajustes → Plugins y Configurar. Los paneles están cerrados de forma predeterminada. Los administradores gestionan definiciones y rutas; otros usuarios activan, guardan claves y controles de generación, pero no ven subida, instalación, exportación, eliminación ni rutas.

Para administradores, las conexiones aparecen primero. Muestreo y controles especializados están bajo Parámetros avanzados, también cerrado. Los valores heredados se muestran como campos vacíos con una pista del proveedor; abrir no copia valores del manifiesto.

Guardar envía solo campos modificados. Vaciar un valor no sensible elimina la anulación y recupera el predeterminado; un campo sensible enmascarado vacío no cambia. Restablecer valores predeterminados quita todas las anulaciones permitidas. Si falla, los valores sin guardar permanecen visibles.

Para endpoints personalizados, el administrador deja en blanco para heredar la URL incluida o introduce una URL compatible completa.

Plugins en Work​

Work puede usar plugins completion y chat activos además de Ollama y Ollama Cloud. Solo acepta una ejecución cuando:

  • el plugin está activo;
  • su modelo aparece en el catálogo del usuario o mapa configurado;
  • hay credenciales para el administrador actual.

Work conserva tipo e ID con tarea y ejecución, así que enruta por proveedor exacto. Activar un plugin con nombre igual a Ollama no redirige una tarea existente.

Adapta herramientas a formatos nativos de OpenAI, Anthropic y Gemini. El modelo debe admitir llamadas aunque ofrezca finalización ordinaria. Si rechaza herramientas o responde de forma incompatible, falla sin cambiar de proveedor.

Una ejecución remota puede hacer varias solicitudes. El proveedor recibe el prompt del sistema, contexto, definiciones y resultados solicitados, que pueden contener fuentes, listados o comandos. Libre WebUI muestra una divulgación descartable por usuario; los operadores deben revisar precios, retención y entrenamiento antes de usar servicios con proyectos sensibles.

Embeddings​

Los plugins compatibles aparecen en los ajustes documentales. Libre WebUI también detecta modelos Ollama probables como nomic-embed-text, bge, e5, gte y nombres similares.

Si no se descubre ninguno, la interfaz usa nomic-embed-text como candidato local predeterminado.

Notas para desarrollar plugins​

Una definición debe describir claramente la capacidad sin afirmar funciones inexistentes. Mantén mapas pequeños y útiles como reserva, y prefiere el descubrimiento para API rápidas y fiables.

Al añadir un proveedor:

  1. Añade la definición.
  2. Define la clave o campos de credencial.
  3. Implementa descubrimiento si hay lista.
  4. Añade asignación de solicitudes para chat, embeddings, imágenes, TTS o STT.
  5. Prueba ausencia y error de clave y errores del proveedor.

Documentación relacionada​