Plugins

O Libre WebUI usa plugins para conectar provedores externos e capacidades de modelos ao lado do Ollama local.

Tipos de plugin

Tipo	Finalidade
Chat/completion	Modelos de texto e chat de APIs
Embeddings	Vetores para busca em documentos e memória
Geração de imagens	Modelos e backends no estilo ComfyUI
Texto em fala	Provedores de síntese de voz
Fala em texto	Provedores de transcrição
Geração de áudio	Provedores de som
Geração de vídeo	Provedores assíncronos

Plugins podem expor mapas estáticos e atualizar modelos disponíveis pelas APIs quando compatível.

Famílias de provedores incluídas

O Libre WebUI inclui definições para:

• OpenAI e APIs compatíveis
• Anthropic
• Google Gemini
• Groq
• Kimi Code da Moonshot AI
• Mistral
• OpenRouter
• Hugging Face
• GitHub Models
• MLX LM para Apple Silicon local
• ComfyUI
• ElevenLabs

Os catálogos mudam com frequência; trate a descoberta ao vivo da interface como fonte da verdade.

Propriedade e autorização

Definições são configuração compartilhada. Toda rota /api/plugins exige autenticação e somente administradores podem enviar, instalar, atualizar ou excluir. A ativação é por usuário: cada pessoa ativa ou desativa apenas na própria conta. O estado fica no SQLite e sobrevive a reinícios sem afetar outros.

Na atualização, a lista global antiga .status.json é copiada uma vez para contas existentes, mas somente para definições que coincidem exatamente com as âncoras compiladas. Definições personalizadas ou shadow ficam em quarentena e inativas. Contas posteriores começam sem plugins ativos.

Definições incluídas só são confiáveis quando o conteúdo normalizado coincide com um hash compilado. Definições graváveis são aprovadas no SQLite por caminho normalizado e hash completo. Instalar, atualizar ou reimportar registra aprovação; editar o arquivo diretamente invalida. Aprovação e atualização limpam a ativação de todas as contas antes da substituição, exigindo reativação. Definições personalizadas anteriores precisam ser reimportadas antes de aparecer, descobrir modelos, aceitar credenciais ou executar capacidades.

Variáveis são separadas por finalidade. Somente administradores guardam variáveis reconhecidas de roteamento:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model e model_id. Também são roteamento os seletores config.endpoint_variable, config.models_endpoint_variable e config.voice_clone_endpoint_variable.

Outros usuários podem salvar controles de geração, como temperatura e streaming. Linhas antigas de roteamento de não administradores são ignoradas, não retornadas e removidas por uma redefinição completa. Assim, uma promoção futura não reativa uma rota adormecida.

Credenciais

Podem vir do ambiente ou das configurações:

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=...

Em implantações compartilhadas, credenciais por usuário costumam ser melhores para cobrança e limites. Chaves de ambiente servem a instalações individuais, demos ou gerenciadas.

Uma chave do ambiente só é fallback enquanto a solicitação usa a projeção de roteamento e autenticação de uma definição incluída não shadowed. Definição importada, gravável que reutiliza ID incluído ou rota personalizada salva exige credencial da mesma conta. O Libre compara endpoint raiz, autenticação, endpoints e seletores de capacidade, definições e padrões de variáveis antes de permitir fallback. O hash compilado continua soberano mesmo quando diretórios antigos e incluídos compartilham caminho; sobrescrever um manifesto não cria confiança.

Isso vale para descoberta, Chat, Work, disponibilidade e catálogos, impedindo que um destino personalizado receba segredo do operador.

Credenciais salvas são vinculadas à origem e hash efetivos, contrato de autenticação, endpoints/seletores e valores de roteamento no momento do salvamento. Uma mudança torna a antiga indisponível até nova revisão. Credenciais legadas sem vínculo só são aceitas em rota incluída exata e têm o vínculo gravado no primeiro uso.

Provedores compatíveis com OpenAI

Um plugin pode definir:

• URL completa da API
• Variável de ambiente da chave
• Comportamento de chat
• Embeddings
• Descoberta
• Mapa de modelos alternativo

Sem descoberta, usa o mapa. JSON importado configura provedores que já falam OpenAI Chat Completions, OpenAI Responses, Anthropic Messages ou Gemini. JSON não traduz protocolo proprietário; formatos diferentes exigem adaptador no backend.

Geração de imagens OpenAI

O provedor incluído expõe a Image API em https://api.openai.com/v1/images/generations. gpt-image-2 é o modelo atual; gpt-image-1.5, gpt-image-1 e gpt-image-1-mini permanecem para compatibilidade, mas novas configurações devem usar gpt-image-2.

A geração usa a mesma credencial efetiva do Chat: chave do usuário ou fallback confiável. Há image_endpoint separado para não enviar imagens a um endpoint personalizado de Chat. Deixe vazio para herdar.

Seleções incluem o provedor. Se dois plugins expõem o mesmo ID, a solicitação vai somente ao selecionado. Respostas GPT Image usam base64; o Libre converte e salva na galeria do usuário. As rotas exigem autenticação e solicitações diretas incluem pluginId e model. n aceita inteiro JSON de 1 a 10; strings e frações são rejeitadas.

Modos Chat Completions e Responses API

Plugins compatíveis usam semântica chat_completions ou responses, selecionável em Configurações → Plugins.

Ordem da conexão:

1. Substituição completa endpoint.
2. base_url com api_path opcional.
3. endpoint legado.

Um valor igual ao manifesto é tratado como padrão, evitando que valores antigos ocultem nova Base URL. Um endpoint realmente personalizado prevalece.

O caminho padrão é /chat/completions ou /responses. base_url deve ser a raiz, como https://api.example.com/v1; api_path define outro caminho relativo. Endpoint completo inclui a operação. Sufixos conhecidos /chat/completions, /completions, /responses determinam a semântica; caminhos não reconhecidos mantêm api_mode.

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

Solicitações Responses usam input, max_output_tokens, ferramentas achatadas, store: false e conteúdo de raciocínio criptografado para continuidade sem estado. Saídas concluídas e em streaming são normalizadas. O estado de replay só é mantido se o array ordenado completo tiver no máximo 64 Items e 90 KB; os Items permanecem exatos, sem truncar campos. Exigem IDs e tipos únicos e estruturas válidas antes de qualquer ferramenta. Estado grande volta ao histórico visível. Chat descarta Items brutos de função porque não persiste suas saídas. Respostas Work com ferramentas e sem replay exato são rejeitadas antes de efeitos.

O Chat no SQLite criptografa o estado com a mensagem; Work guarda estado só de ferramentas em linhas ocultas. Um escopo hash vincula replay ao mesmo provedor, modelo, modo, endpoint e impressão unidirecional da credencial. Mudanças, inclusive rotação, voltam ao histórico normalizado. Uma execução Work também verifica roteamento e credencial antes de cada rodada; mudar modo, endpoint ou chave interrompe antes de receber estado anterior.

Estado com ferramentas deve caber no limite de replay e no wrapper completo de 100 KB antes de efeitos. Em lote interrompido, resultados ausentes são restaurados com ID exato e aviso de resultado desconhecido para inspecionar em vez de repetir. Um resultado Responses incompleto não é sucesso; incomplete_details.reason é retido e exibido.

A descoberta deriva /models da operação: https://api.example.com/v1/responses vira https://api.example.com/v1/models. Sem endpoint compatível, use model_map. Resultados são por usuário. Descoberta ocorre após ativação, atualização, mudança de chave ou conexão e redefinição; salvar geração não chama a rede.

Também ocorre automaticamente quando o catálogo está ausente ou mais velho que PLUGIN_MODEL_DISCOVERY_TTL_MS. Backoff evita sondagens repetidas e prazo impede atraso; resultados tardios aparecem na próxima solicitação.

O URL final é validado antes de ler credencial ou montar Authorization, inclusive em manifestos importados. Descoberta e capacidades não seguem redirecionamentos. Configure diretamente endpoints de Chat, Work, modelos, imagem, embedding, transcrição, fala, clonagem, áudio e vídeo.

Endpoints podem usar HTTP ou HTTPS. HTTP não criptografa chaves, prompts, resultados e conteúdo; use somente em rede confiável e prefira HTTPS. Solicitações saem do backend; em contêiner, use http://ai-gateway:8080/v1, enquanto localhost é o próprio contêiner. Rotas resolvem variáveis e credenciais do usuário autenticado. Não há modo de usuário único sem autenticação.

Endpoints por capacidade

Substituições de Chat são isoladas de imagem, embedding, transcrição, TTS, áudio e vídeo. Plugins podem expor image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint ou variável de config.endpoint_variable; clonagem pode nomear config.voice_clone_endpoint_variable. Vazios usam o manifesto; endpoint genérico nunca substitui capacidade.

O GitHub Models herda models.github.ai/inference/chat/completions quando vazio. Hugging Face usa rotas hf-inference/models/{model} específicas para embeddings, imagens e TTS, não o Chat.

Substituições de endpoint

endpoint é o URL completo com operação, como https://provider.example/v1/chat/completions, e não somente https://provider.example. Configurações legadas podem chamá-lo api_url; endpoint não vazio prevalece.

Somente URLs HTTP(S) absolutos são aceitos. HTTP é para gateways confiáveis. Vazio usa a definição; inválido é rejeitado, não redirecionado silenciosamente ao padrão. Solicitações não seguem redirects; configure o destino final.

No contêiner, localhost é o contêiner. Use o nome de serviço ou host.docker.internal quando disponível.

Descoberta de modelos

Configurações → Plugins tem o espaço Conexões de provedores. Selecione à esquerda e veja estado e catálogo à direita. A configuração fica fechada até Configurar, escondendo endpoint, credencial e parâmetros avançados.

Atualizar modelos executa descoberta e recarrega catálogo e lista do Chat. O catálogo é somente leitura, combinando IDs do usuário e mapas de capacidades. Rótulos indicam a rota, não saúde. Mantenha IDs alternativos em model_map.

Na ativação, usa endpoint e credencial efetivos. Rota personalizada exige credencial da conta; fallback ambiental só na rota confiável. Derivação:

• termina em /models: usa como está;
• sufixos /chat/completions, /completions, /responses, /embeddings, /messages: substitui por /models;
• caso contrário, anexa /models.

Plugins podem expor models_endpoint, sujeito à mesma política e sem redirects. Salvar/redefinir endpoint, api_url, models_endpoint, base_url, api_path, api_mode limpa e atualiza o catálogo.

Rotas são validadas antes da credencial; não há fallback ambiental para rota armazenada. A descoberta espera array data compatível. A ativação aguarda a tentativa. Resultados são por usuário e não reescrevem o JSON nem vazam para outra conta. Falha comum mantém o resultado anterior; mudança intencional limpa primeiro e usa model_map se falhar.

Estado, disponibilidade Work, catálogos e capacidades usam o mesmo usuário e fronteira.

Seleção exata de provedor no Chat

IDs não são globais. Ollama e plugins podem expor example-model. O Chat salva o ID bruto com identidade opcional:

• providerType: "ollama" identifica a rota Ollama;
• providerType: "plugin" com providerId identifica o plugin.

Valores codificados servem apenas como chaves no seletor; solicitações enviam o ID bruto. Duplicatas permanecem separadas e reabrir restaura a escolha exata.

Identidade explícita falha de forma segura. Se o plugin for desativado, removido ou deixar de anunciar o modelo, a seleção fica indisponível e não muda para homônimo. Reative ou escolha outro.

Registros antigos podem ter providerType e providerId ausentes ou null; mantêm roteamento histórico por nome e aparecem como "provedor não registrado". Escolher entrada concreta fixa o futuro. Personas novas mantêm persona:<id> na interface e são registradas como Ollama.

Configurações e herança

Abra Configurações → Plugins → Configurar. Painéis vêm fechados. Administradores gerenciam definições e roteamento; outros ativam, salvam chaves e geração, sem controles de instalação, exportação, exclusão ou rota.

Para administradores, conexão aparece primeiro; amostragem fica em Parâmetros avançados, também fechada. Valores herdados são campos vazios com dica padrão; abrir não copia padrões.

Salvar envia apenas campos alterados. Limpar valor não sensível remove a substituição; campo sensível mascarado vazio não muda. Restaurar padrões remove as variáveis permitidas. Em falha, valores não salvos permanecem.

Para endpoint personalizado, vazio herda o incluído; URL completo substitui.

Plugins no Work

Work usa plugins completion e chat ativos além de Ollama. Uma execução só é aceita quando:

• plugin ativo;
• modelo no catálogo do usuário ou mapa configurado; e
• credencial disponível ao administrador.

Tipo e ID são guardados na tarefa e execução. Nome igual não redireciona. Work adapta ferramentas em formatos OpenAI, Anthropic e Gemini. O modelo deve suportá-las; recusa ou resposta incompatível falha sem fallback.

Uma execução remota faz várias chamadas e envia prompt de sistema, conversa, definições e resultados, que podem conter arquivos, diretórios e comandos. Há um aviso por usuário, mas operadores devem revisar preço, retenção e treinamento.

Embeddings

Plugins aparecem nas configurações. O Libre também detecta nomes Ollama como nomic-embed-text, bge, e5, gte. Sem descoberta, usa nomic-embed-text como candidato local.

Notas de desenvolvimento

Defina capacidades com clareza e não alegue recursos inexistentes. Mantenha mapas pequenos como fallback e prefira descoberta confiável.

Ao adicionar:

1. Adicione a definição.
2. Defina credenciais.
3. Implemente descoberta quando disponível.
4. Mapeie chat, embeddings, imagem, TTS ou STT.
5. Teste chave ausente, inválida e erros.

Documentos relacionados

• Variáveis de ambiente
• Trabalhando com modelos
• Work: espaços isolados
• Kimi Code
• MLX LM no Apple Silicon