Connettere provider di terze parti e self-hosted

Libre WebUI 0.16.0 aggiunge uno spazio di lavoro dedicato alle Connessioni provider in Impostazioni > Plugin. Usalo per attivare un provider incluso, indirizzare un plugin compatibile verso un'altra API, esaminare il catalogo effettivo dei modelli o connettere un gateway self-hosted su una rete attendibile.

Libre WebUI supporta attualmente questi formati di comunicazione dei provider:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; e
• contenuti e chiamate di funzioni Google Gemini.

Le definizioni incluse per Anthropic e Gemini usano adattatori dedicati, selezionati in base all'identità del provider. Un provider appena importato usa la semantica di OpenAI Chat Completions o OpenAI Responses; indirizzarlo a un'API compatibile con Anthropic o Gemini non seleziona gli adattatori inclusi per questi servizi. Un provider con una forma diversa per richieste, streaming, chiamate agli strumenti o risposte necessita di un adattatore del backend. Il JSON del plugin descrive routing e configurazione; non traduce un protocollo non correlato.

Aprire Connessioni provider

1. Accedi e apri Impostazioni > Plugin.
2. Cerca il provider nell'elenco nel riquadro sinistro.
3. Seleziona un provider per verificarne lo stato di attivazione e il catalogo effettivo dei modelli.
4. Attiva il provider per il tuo account.
5. Seleziona Configura soltanto quando devi salvare una credenziale o sostituire un'impostazione di connessione.

La configurazione del provider è chiusa per impostazione predefinita. Le impostazioni di connessione appaiono per prime agli amministratori, mentre i controlli di campionamento, come temperatura e limiti dei token, restano nella sezione separata e compressa Parametri avanzati. I valori predefiniti ereditati appaiono come suggerimenti, non come sostituzioni già inserite per l'account.

Le definizioni dei plugin sono una configurazione condivisa dell'istanza, quindi soltanto gli amministratori possono importarle, installarle, aggiornarle o eliminarle. Ogni utente autenticato controlla il proprio stato di attivazione, le proprie credenziali e le impostazioni di generazione consentite.

Aggiungere rapidamente una connessione

Impostazioni > Connessioni è un percorso più breve per il caso più comune: un endpoint compatibile con OpenAI e una chiave API. Gli amministratori vedono una scheda per il runtime Ollama locale con stato e versione, un elenco delle connessioni compatibili con OpenAI esistenti e un piccolo modulo per aggiungerne un'altra.

Per aggiungere una connessione servono un nome visualizzato, l'URL completo dei completamenti chat e una chiave API facoltativa. Libre WebUI ricava l'ID della connessione dal nome, installa la definizione del provider, archivia la chiave lato server, attiva la connessione e chiede all'endpoint quali modelli serve. I modelli rilevati sostituiscono il catalogo segnaposto e appaiono nel selettore dei modelli di chat.

Ogni riga mostra endpoint, numero di modelli, presenza di una chiave archiviata, interruttore di attivazione, aggiornamento dei modelli ed eliminazione. Tutto ciò che va oltre, come modalità dell'API Responses, sostituzioni dell'URL di base, cataloghi per funzionalità e criteri per i parametri di generazione, resta nello spazio di lavoro più completo Impostazioni > Plugin descritto sopra.

Codex (accesso con ChatGPT)

Il provider incluso Codex (ChatGPT) non richiede una chiave API. Quando il server dispone di un accesso della CLI Codex (codex login eseguito come utente del sistema operativo del server), il provider appare agli amministratori e offre tramite la sessione ChatGPT la famiglia di modelli Codex documentata. I token di accesso vengono letti dal file auth.json della CLI, aggiornati tramite lo stesso client OAuth usato dalla CLI e riscritti affinché la CLI continui a funzionare; i valori dei token non appaiono mai nei log.

Poiché le richieste vengono effettuate dal backend, mai dall'interno di un container di attività, questi modelli possono anche alimentare Work tramite il normale ciclo di strumenti in sandbox. Il provider è riservato agli amministratori perché ogni chiamata usa l'abbonamento ChatGPT del proprietario del server. Nascondilo completamente con CODEX_OAUTH_MODELS_ENABLED=false oppure indirizzalo a un accesso diverso con CODEX_HOME.

Scegliere un provider incluso o importato

Libre WebUI include definizioni per OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code di Moonshot AI, Hugging Face, GitHub Models, MLX LM locale e altri servizi per modelli o contenuti multimediali. Parti da una voce inclusa quando il relativo protocollo e contratto di autenticazione corrispondono al servizio che vuoi usare.

Per un altro servizio compatibile, un amministratore può importare una definizione JSON di plugin. Questo esempio minimo descrive un gateway compatibile con OpenAI:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Importa il file da Impostazioni > Plugin, attivalo e salva la chiave API per l'account che userà la connessione. Aggiungi variabili di connessione alla definizione quando gli amministratori devono poter modificare URL di base, percorso, rilevamento o campi degli endpoint specifici per funzionalità. Il file incluso plugins/openai.json è un esempio completo.

Per un gateway intenzionalmente privo di autenticazione su una rete attendibile, imposta sia auth.header sia auth.key_env come stringhe vuote e ometti auth.prefix. Libre WebUI non richiederà né invierà una chiave API per quel plugin.

Scegliere Chat Completions o Responses

I plugin di completamento compatibili con OpenAI possono usare una delle due modalità API:

Modalità API	Percorso predefinito della richiesta	Campo tipico della richiesta
chat_completions	/chat/completions	messages
responses	/responses	input

Il provider OpenAI incluso espone Modalità API nella propria configurazione. Libre WebUI riconduce l'output Responses completato e in streaming a Chat e Work, compreso uno stato di riproduzione limitato per ragionamento e chiamate agli strumenti.

La modifica della modalità influisce sul percorso predefinito dell'operazione. Non cambia il protocollo parlato dal server upstream, quindi seleziona Responses soltanto quando tale server implementa forme compatibili per richieste ed eventi Responses.

Configurare un URL di base o un endpoint completo

Libre WebUI risolve una route di completamento nel seguente ordine:

1. Una sostituzione completa e non predefinita di endpoint.
2. base_url più un api_path facoltativo.
3. L'endpoint dichiarato dalla definizione del plugin.

Usa URL di base per la radice dell'API:

https://gateway.example/v1

Senza un percorso personalizzato, la modalità Chat Completions invia le richieste a:

https://gateway.example/v1/chat/completions

La modalità Responses le invia invece a:

https://gateway.example/v1/responses

Usa Percorso API quando il provider espone un'operazione compatibile in un altro percorso relativo alla radice. Usa Endpoint completo precedente soltanto quando devi fornire l'URL completo dell'operazione; un vero endpoint completo ha la precedenza su URL di base e Percorso API.

Anche i suffissi noti /chat/completions, /completions e /responses degli endpoint identificano la semantica della richiesta. Un percorso operativo personalizzato e non riconosciuto mantiene la modalità API selezionata esplicitamente.

Dopo la modifica di una route o di una chiave API, salva nuovamente il provider prima di provare Chat. Quando il plugin dichiara l'autenticazione, una route di connessione personalizzata richiede una credenziale salvata dallo stesso account. Un plugin intenzionalmente privo di autenticazione può lasciare vuoti entrambi i campi di autenticazione. Libre WebUI non invia una chiave di ambiente gestita dall'operatore a una destinazione definita dall'utente; il fallback all'ambiente è riservato alla route inclusa e attendibile.

Rilevare o gestire gli ID dei modelli

Seleziona un provider di chat attivo e usa Aggiorna modelli per avviare il rilevamento. Libre WebUI ricarica sia il catalogo del provider selezionato sia l'elenco dei modelli di Chat.

Il rilevamento viene eseguito anche automaticamente: il catalogo di un provider attivo viene rilevato di nuovo quando manca o è più vecchio di PLUGIN_MODEL_DISCOVERY_TTL_MS, così i modelli visualizzati seguono il provider anziché riflettere soltanto il momento dell'attivazione. Aggiorna modelli forza un controllo immediato e comunica il risultato:

Risultato	Significato
Catalogo aggiornato	Il provider ha risposto e l'elenco dei modelli differisce da quello archiviato
Catalogo già aggiornato	Il provider ha risposto con lo stesso elenco
Chiave API necessaria	Non è disponibile una chiave utilizzabile, quindi non è stata effettuata alcuna richiesta e continua a essere mostrato il catalogo precedente
Impossibile caricare il catalogo	Il provider non era raggiungibile o non ha restituito dati utilizzabili

Una chiave impostata soltanto nell'ambiente non viene usata per un provider che esegue una definizione installata anziché quella inclusa; il messaggio lo specifica quando si verifica questa situazione. I modelli per voce, immagini ed embedding trovati nel catalogo di un provider sono elencati qui con le etichette delle funzionalità, ma vengono esclusi dal selettore dei modelli di chat.

Per una route compatibile con OpenAI, il rilevamento sceglie l'URL dell'elenco dei modelli nel seguente modo:

• una route che termina in /models viene usata senza modifiche;
• un suffisso operativo noto come /chat/completions, /completions, /responses, /embeddings o /messages viene sostituito con /models; e
• negli altri casi, /models viene aggiunto alla route.

Ad esempio, entrambe queste route di completamento producono lo stesso URL di rilevamento:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Quando non è possibile ottenere l'URL completo corretto, esponi models_endpoint nell'array variables del plugin:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

Il valore predefinito ereditato o quello salvato dall'amministratore ha la precedenza sull'indirizzo derivato. Una proprietà models_endpoint di primo livello nel manifesto non viene letta. Il rilevamento si aspetta una risposta compatibile con OpenAI contenente oggetti modello in un array data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Gli ID rilevati vengono archiviati per utente e non riscrivono il file condiviso del plugin. Se il provider non implementa un rilevamento compatibile, mantieni gli ID dei modelli di riserva in model_map nel JSON del plugin. Il catalogo in Connessioni provider è di sola lettura; le etichette delle funzionalità descrivono quale route del plugin elenca un modello e non costituiscono controlli dello stato.

Gli ID dei modelli non sono univoci a livello globale. Chat archivia l'ID del modello non elaborato insieme all'identità esatta del relativo provider Ollama o plugin, quindi un modello Ollama e più plugin possono esporre in sicurezza lo stesso nome. Se il provider salvato non è più disponibile, Libre WebUI mostra la selezione come non disponibile anziché instradare silenziosamente la richiesta a un altro provider.

Configurare separatamente la generazione di immagini

Il provider OpenAI incluso espone la generazione di immagini tramite https://api.openai.com/v1/images/generations e attualmente usa gpt-image-2 come valore predefinito per le nuove configurazioni. Gli ID GPT Image precedenti restano nel catalogo di riserva per i deployment esistenti compatibili.

Le route di chat e immagini sono intenzionalmente isolate. Un URL di base personalizzato per Chat non riceve automaticamente le richieste per immagini. Lascia vuoto image_endpoint per usare l'endpoint immagini dichiarato dal plugin oppure impostalo sull'URL completo e compatibile dell'operazione Image API quando il provider ne offre uno.

Le scelte delle immagini sono qualificate per provider, proprio come quelle della Chat. Se due plugin attivi espongono lo stesso ID di modello per immagini, Libre WebUI invia la richiesta soltanto al provider selezionato nel pannello delle immagini.

Connettere in sicurezza un gateway HTTP

Gli endpoint dei provider possono usare URL HTTP o HTTPS assoluti. HTTP è utile per un gateway self-hosted su una LAN attendibile, una rete Tailscale o una rete privata di container, ma invia chiavi API, prompt, risultati degli strumenti e contenuti generati senza crittografia del trasporto. Preferisci HTTPS ogni volta che la route attraversa un confine di rete o il gateway supporta TLS.

Le richieste provengono dal backend di Libre WebUI, non dal browser. Scegli un indirizzo raggiungibile da tale backend:

Posizione del backend	Esempio di radice del provider
Processo nativo, stessa macchina	http://127.0.0.1:8081/v1
Servizio Docker Compose	http://ai-gateway:8080/v1
Dal container all'host supportato	http://host.docker.internal:8081/v1
Host LAN o Tailscale attendibile	http://192.168.1.20:8081/v1

All'interno di un container, localhost identifica il container Libre WebUI stesso. Non identifica un altro servizio Compose e non raggiunge automaticamente l'host.

Libre WebUI accetta soltanto URL HTTP e HTTPS per i provider, convalida la destinazione finale prima di selezionare una credenziale e non segue i reindirizzamenti per le richieste ai provider o di rilevamento. Configura direttamente l'URL finale dell'operazione.

Verificare il gateway prima di attivarlo

Prova il rilevamento dei modelli dalla macchina o dal container che esegue il backend di Libre WebUI:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Prova quindi l'operazione corrispondente alla modalità API selezionata.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Dopo che entrambe le chiamate funzionano, configura in Connessioni provider la stessa route, modalità, credenziale e ID del modello. Attiva il provider, seleziona Aggiorna modelli, quindi scegli in Chat il modello qualificato per provider. Anche Work può usarlo quando il modello supporta in modo affidabile le chiamate agli strumenti.

Risoluzione dei problemi

Sintomo	Verifica
Le richieste raggiungono ancora l'endpoint incluso	Rimuovi una sostituzione obsoleta dell'endpoint completo, quindi salva l'URL di base e il Percorso API desiderati.
Il provider riceve il payload errato	Abbina Modalità API al protocollo Chat Completions o Responses upstream e verifica il suffisso finale.
Aggiorna modelli non restituisce ID	Prova /models, verifica la forma data[].id, esponi/configura la variabile models_endpoint oppure mantieni model_map.
Un modello precedente resta dopo la modifica della route	Salva la modifica della connessione; Libre WebUI cancella il catalogo rilevato obsoleto di quell'utente prima dell'aggiornamento.
La chiave API risulta mancante	Salva una credenziale per utente per la route personalizzata; il fallback all'ambiente incluso non segue le sostituzioni.
Un deployment Docker non raggiunge localhost	Usa il nome del servizio Compose del gateway, un alias host supportato o un indirizzo di rete privata raggiungibile.
La Chat funziona ma la generazione di immagini no	Configura l'image_endpoint completo separato e seleziona un modello esposto da tale funzionalità immagine.
La Chat funziona ma Work rifiuta il modello	Verifica che il modello supporti chiamate agli strumenti compatibili; il normale completamento di testo non basta.
Il provider restituisce un reindirizzamento	Configura direttamente l'URL finale convalidato; Libre WebUI non segue intenzionalmente i reindirizzamenti dei provider.

Per il comportamento dettagliato di routing, credenziali, stato di riproduzione e autorizzazione, consulta Plugin. Per errori specifici del deployment, consulta Risoluzione dei problemi.

Ringraziamento alla comunità

Questa guida e l'esperienza Connessioni provider introdotta in Libre WebUI 0.16.0 sono state plasmate da ZhengJin (@fangzhengjin), il cui feedback dettagliato sui provider di terze parti e il cui concetto di UX assistito dall'IA in #163 hanno contribuito a definire il flusso di lavoro.

Documentazione correlata

• Plugin
• Lavorare con i modelli
• MLX LM su Apple Silicon
• Work: spazi di lavoro isolati
• Risoluzione dei problemi