Plugin

Libre WebUI usa plugin per collegare provider esterni e capacità di modelli insieme a Ollama locale.

Tipi di plugin

Tipo	Scopo
Chat/completion	Modelli testuali e chat da API
Embedding	Vettori per ricerca e memoria
Generazione immagini	Modelli e backend stile ComfyUI
Sintesi vocale	Provider di voce
Trascrizione	Provider speech-to-text
Generazione audio	Provider di suono
Generazione video	Provider asincroni

I plugin possono esporre mappe statiche e aggiornare i modelli disponibili dalle API.

Famiglie incluse

• OpenAI e API compatibili
• Anthropic
• Google Gemini
• Groq
• Kimi Code di Moonshot AI
• Mistral
• OpenRouter
• Hugging Face
• GitHub Models
• MLX LM per Apple Silicon locale
• ComfyUI
• ElevenLabs

I cataloghi cambiano spesso; la scoperta live della UI è la fonte attendibile.

Proprietà e autorizzazione

Le definizioni sono configurazione condivisa. Ogni rotta /api/plugins richiede autenticazione e solo gli amministratori possono caricare, installare, aggiornare o eliminare. L'attivazione è per utente: ogni account modifica soltanto la propria, salvata in SQLite e persistente ai riavvii.

Durante l'upgrade, l'elenco globale legacy .status.json viene copiato una volta agli account esistenti, ma solo per definizioni che corrispondono alle trust anchor compilate. Definizioni custom o shadow restano in quarantena. Account successivi partono senza plugin.

Le definizioni incluse sono attendibili solo se il contenuto normalizzato coincide con un hash compilato. Quelle scrivibili vengono approvate in SQLite per percorso e hash. Installazione, aggiornamento o reimport registrano l'approvazione; modifiche dirette la invalidano. Aggiornare cancella le attivazioni di ogni account prima di sostituire, richiedendo riattivazione. Le definizioni precedenti devono essere reimportate prima di apparire, scoprire modelli, accettare credenziali o eseguire capacità.

Le variabili sono divise per scopo. Solo admin salvano il routing riconosciuto:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model, model_id; anche config.endpoint_variable, config.models_endpoint_variable, config.voice_clone_endpoint_variable.

Gli altri utenti salvano controlli di generazione. Le vecchie righe di routing non admin vengono ignorate, non restituite e rimosse da un reset completo, evitando riattivazione dopo una promozione.

Credenziali

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

In installazioni condivise, credenziali per utente sono preferibili; chiavi ambientali servono installazioni singole, demo o gestite.

Una chiave d'ambiente è fallback soltanto mentre la richiesta usa routing e autenticazione di una definizione inclusa non shadowed. Definizioni importate, scrivibili con ID incluso o route custom richiedono credenziale dello stesso account. Libre confronta endpoint, autenticazione, capacità, selettori e default. L'hash compilato resta autorevole anche quando directory legacy e incluse condividono il percorso.

Vale per discovery, Chat, Work, disponibilità e cataloghi, impedendo che destinazioni custom ricevano segreti dell'operatore.

Le credenziali salvate sono legate a origine, hash, contratto, endpoint/selettori e valori effettivi. Cambiare rotta le rende indisponibili finché l'utente non le risalva. Credenziali legacy senza legame sono accettate solo sulla rotta inclusa esatta e legate al primo uso.

Provider compatibili OpenAI

Un plugin può definire URL completo, variabile della chiave, comportamento Chat, embedding, discovery e mappa fallback. Se non supporta discovery, usa la mappa.

JSON importato configura provider che già parlano OpenAI Chat Completions, OpenAI Responses, Anthropic Messages o Gemini. Non traduce protocolli proprietari; formati diversi richiedono un adattatore backend.

Generazione immagini OpenAI

Il provider incluso espone Image API in https://api.openai.com/v1/images/generations. gpt-image-2 è attuale; gpt-image-1.5, gpt-image-1, gpt-image-1-mini restano per compatibilità ma nuove configurazioni usano gpt-image-2.

Usa la stessa credenziale effettiva del Chat: chiave utente o fallback incluso. image_endpoint separato evita di inviare immagini a Chat custom; lascialo vuoto per ereditare.

La selezione include il provider. Con ID uguali, invia soltanto al selezionato. Le risposte base64 vengono convertite e salvate in galleria. Le richieste dirette richiedono pluginId e model; n è intero JSON 1–10, non stringa o frazione.

Modalità Chat Completions e Responses

I plugin usano chat_completions o responses, selezionabile in Impostazioni → Plugin.

Ordine:

1. endpoint completo.
2. base_url più api_path.
3. endpoint legacy.

Un valore uguale al manifesto è considerato default, non override; un endpoint realmente custom prevale.

Il percorso default è /chat/completions o /responses. base_url è la radice, come https://api.example.com/v1; api_path un relativo diverso. Suffix /chat/completions, /completions, /responses determina la semantica; percorsi sconosciuti mantengono api_mode.

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

Responses usa input, max_output_tokens, funzioni appiattite, store: false e contenuto reasoning cifrato. L'output viene normalizzato. Lo stato replay è mantenuto solo con array ordinato completo massimo 64 Items e 90 KB; Items esatti, nessun campo troncato. Richiede ID/tipi unici e strutture valide prima di tool call. Stato Chat troppo grande usa cronologia visibile; Chat elimina function-call raw senza output. Work con strumenti e senza replay esatto viene rifiutato prima degli effetti.

Chat SQLite cifra lo stato con il messaggio; Work lo conserva in righe nascoste. Un hash scope lega replay a provider, modello, modalità, endpoint e fingerprint della credenziale. Cambiamenti, inclusa rotazione, tornano alla cronologia. Work verifica routing/credenziale prima di ogni round e si ferma se cambiano.

Lo stato con strumenti deve entrare anche nel wrapper persistente completo da 100 KB. Se un batch è interrotto, i risultati mancanti vengono ripristinati con call ID e avviso outcome-unknown per ispezionare invece di ripetere. Un risultato incompleto non è successo; incomplete_details.reason viene mostrato.

La discovery deriva /models: https://api.example.com/v1/responses diventa https://api.example.com/v1/models. Senza compatibilità usa model_map. Risultati per utente. Si esegue dopo attivazione, refresh, chiave/connessione/reset; salvare generazione non chiama la rete.

Si esegue anche automaticamente quando manca o supera PLUGIN_MODEL_DISCOVERY_TTL_MS; backoff evita sonde ripetute e deadline evita ritardi. Risultati tardivi compaiono dopo.

L'URL finale viene validato prima di leggere credenziali o Authorization. Nessuna richiesta segue redirect. Configura direttamente Chat, Work, modelli, immagini, embedding, trascrizione, voce, clonazione, audio e video.

HTTP non cifra chiavi, prompt, risultati e contenuto; usalo solo in rete affidabile. Le richieste originano dal backend: in container usa http://ai-gateway:8080/v1, mentre localhost è il container. Non esiste modalità single-user non autenticata.

Endpoint specifici per capacità

Gli override Chat sono isolati da immagine, embedding, STT, TTS, audio e video. Plugin possono esporre image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint o config.endpoint_variable; clonazione può usare config.voice_clone_endpoint_variable. Vuoti usano il manifesto; endpoint generico non sostituisce capacità.

GitHub Models eredita models.github.ai/inference/chat/completions; Hugging Face usa hf-inference/models/{model} per embedding, immagini e TTS.

Override endpoint

endpoint è URL completo con operazione, come https://provider.example/v1/chat/completions, non solo https://provider.example. api_url è alias legacy; endpoint non vuoto prevale.

Solo HTTP(S) assoluto è accettato. Vuoto usa la definizione; invalido viene rifiutato. Nessun redirect. In container localhost è il container; usa nome servizio o host.docker.internal.

Scoperta modelli

Impostazioni → Plugin offre Connessioni provider. Seleziona a sinistra e rivedi stato/catalogo a destra. La configurazione è chiusa finché Configura, nascondendo endpoint, credenziali e parametri avanzati.

Aggiorna modelli esegue discovery e ricarica catalogo e Chat. Il catalogo è read-only, unendo ID utente e mappe. Le etichette indicano la rotta, non health. Mantieni fallback in model_map.

All'attivazione usa endpoint/credenziale effettivi. Route custom richiede credenziale account; fallback ambientale solo su manifesto trusted. Derivazione:

• /models usa as-is;
• /chat/completions, /completions, /responses, /embeddings, /messages diventano /models;
• altrimenti aggiunge /models.

models_endpoint prevale ed è validato senza redirect. Salvare/resettare endpoint, api_url, models_endpoint, base_url, api_path, api_mode cancella e aggiorna.

La discovery attende array data e risultati per utente, senza riscrivere JSON o esporre ad altri. Attivazione normale conserva il catalogo precedente; cambiando connessione lo cancella prima e usa model_map se fallisce. Stato, Work e capacità condividono contesto e credenziale.

Selezione esatta del provider nel Chat

Gli ID non sono globali. Ollama e più plugin possono esporre example-model. Chat salva ID grezzo e:

• providerType: "ollama";
• providerType: "plugin" più providerId.

Valori codificati sono solo chiavi del selettore; le richieste inviano l'ID grezzo. Duplicati restano separati e riaprire ripristina.

Identità esplicita fallisce in modo sicuro. Se plugin/modello sparisce, resta indisponibile e non passa a omonimo. Riattiva o scegli altro.

Record legacy possono avere providerType/providerId mancanti o null; mantengono routing per nome e mostrano "provider non registrato". Seleziona una voce per fissare. Le personas mantengono persona:<id> e nuove sono Ollama-backed.

Impostazioni e ereditarietà

Apri Impostazioni → Plugin → Configura. Gli admin gestiscono definizioni/routing; gli altri attivano, salvano chiavi e generazione, senza controlli di installazione/esportazione/eliminazione/rotta.

Connessione appare prima, sampling in Parametri avanzati, entrambi chiusi. Valori ereditati sono campi vuoti con suggerimento, non copiati.

Salvare invia solo modifiche. Cancellare valore non sensibile rimuove override; campo sensibile mascherato vuoto non cambia. Ripristina predefiniti rimuove gli override permessi. In caso di errore i valori restano.

Endpoint vuoto eredita; URL completo sostituisce.

Plugin in Work

Work usa plugin completion e chat attivi quando:

• plugin attivo;
• modello nel catalogo o mappa;
• credenziale disponibile all'amministratore.

Tipo e ID sono salvati in attività ed esecuzione. Nomi uguali non dirottano. Work adatta formati OpenAI, Anthropic, Gemini. Il modello deve supportare strumenti; rifiuto/incompatibilità fallisce senza fallback.

Una esecuzione remota può fare molte richieste e inviare prompt di sistema, conversazione, definizioni e risultati con file/directory/comandi. C'è un avviso per utente, ma valuta prezzi, retention e training.

Embedding

Plugin compaiono nelle impostazioni. Libre rileva anche Ollama nomic-embed-text, bge, e5, gte; senza modello usa nomic-embed-text come candidato.

Note per sviluppatori

Descrivi capacità reali, mantieni mappe piccole e preferisci discovery affidabile.

1. Aggiungi definizione.
2. Definisci credenziali.
3. Implementa discovery.
4. Mappa chat, embedding, immagine, TTS o STT.
5. Testa chiave mancante, errata ed errori.

Documenti correlati

• Variabili d'ambiente
• Lavorare con i modelli
• Work: spazi isolati
• Kimi Code
• MLX LM su Apple Silicon