Pluginuri

Libre WebUI folosește pluginuri pentru a conecta furnizori AI externi și capabilități de model alături de Ollama local.

Tipuri de pluginuri

Tip	Scop
Chat/completion	Modele text și chat din API-urile furnizorilor
Embeddings	Vectori pentru căutarea documentelor și memorie
Generare imagini	Modele de imagine și backend-uri de tip ComfyUI
Sinteză vocală	Furnizori pentru transformarea textului în voce
Transcriere	Furnizori pentru transformarea vocii în text
Generare audio	Furnizori de sunete și conținut audio
Generare video	Furnizori asincroni pentru conținut video

Pluginurile pot expune hărți statice de modele și, când furnizorul permite, pot actualiza modelele disponibile din API-urile sale.

Familii de furnizori incluse

Libre WebUI include definiții pentru servicii obișnuite:

• API-uri OpenAI și compatibile OpenAI;
• Anthropic;
• Google Gemini;
• Groq;
• Kimi Code de la Moonshot AI;
• Mistral;
• OpenRouter;
• Hugging Face;
• GitHub Models;
• MLX LM pentru inferență locală pe Apple Silicon;
• ComfyUI;
• ElevenLabs.

Cataloagele furnizorilor se schimbă frecvent. Când un plugin acceptă descoperirea live, UI-ul trebuie considerat sursa de adevăr pentru lista curentă.

Proprietate și autorizare

Definițiile pluginurilor sunt configurație partajată a instanței. Fiecare rută /api/plugins necesită autentificare și numai administratorii pot încărca, instala, actualiza sau șterge o definiție. Activarea este diferită: fiecare utilizator autentificat activează sau dezactivează un plugin partajat numai pentru propriul cont. Starea este salvată în SQLite și supraviețuiește repornirii backend-ului fără să afecteze furnizorii activi ai altui utilizator.

La upgrade, lista globală legacy .status.json este copiată o singură dată în conturile existente, dar numai pentru definițiile care corespund exact ancorelor de încredere compilate în Libre WebUI. Definițiile personalizate sau shadow legacy rămân în carantină și inactive. Conturile create după migrare pornesc fără pluginuri active.

O definiție inclusă este de încredere numai când conținutul său normalizat corespunde hash-ului compilat în backend. Definițiile inscriptibile sunt aprobate în SQLite prin calea source normalizată și hash-ul complet. Instalarea, actualizarea sau reimportarea de către administrator înregistrează aprobarea; modificarea directă a fișierului o invalidează. Aprobarea și actualizarea elimină activarea tuturor conturilor înainte de înlocuirea fișierului, astfel încât fiecare utilizator trebuie să reactiveze definiția examinată. Definițiile personalizate dinaintea upgrade-ului trebuie reimportate de un administrator înainte să apară în cataloage, să descopere modele, să primească credentials sau să execute capabilități.

Variabilele pluginului sunt împărțite după scop. Numai administratorii pot stoca variabile de rutare a conexiunii recunoscute:

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. Un config.endpoint_variable, config.models_endpoint_variable sau config.voice_clone_endpoint_variable declarat de o capabilitate este tot rutare, indiferent de nume.

Utilizatorii care nu sunt administratori pot salva în continuare controale de generare, precum temperature și preferința de streaming. Rândurile vechi de rutare ale unui non-admin sunt ignorate, nu sunt returnate ca valori configurate și sunt eliminate la resetarea completă a variabilelor, astfel încât o promovare ulterioară să nu reactiveze implicit o rută latentă.

Date de autentificare

Credentials pot proveni din variabile de mediu sau din setările utilizatorului.

Exemple de mediu:

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

În deployment-urile partajate, credentials per utilizator sunt de obicei mai potrivite, deoarece fiecare utilizator își controlează facturarea și limitele furnizorului. Cheile din mediu sunt utile pentru instalări cu un singur utilizator, demonstrații sau deployment-uri administrate.

O cheie de mediu este fallback numai cât timp cererea folosește proiecția de rutare și autentificare a unei definiții incluse, neumbrite. O definiție importată, una inscriptibilă care umbrește un ID inclus sau un override de rutare salvat de administrator necesită un credential al aceluiași cont. Libre WebUI compară endpoint-ul rădăcină, câmpurile de autentificare, endpoint-urile și selectoarele capabilităților, precum și definițiile și valorile implicite ale variabilelor de rutare înainte de a permite fallback-ul din mediu. Hash-ul manifestului compilat rămâne autoritativ chiar dacă directoarele legacy și incluse împart aceeași cale, ca în imaginea container standard; un manifest din pachet suprascris nu poate deveni singur de încredere.

Regula se aplică discovery, Chat, Work, verificărilor de disponibilitate și cataloagelor de capabilități. Ea împiedică un endpoint personalizat sau un manifest personalizat vechi să primească secretul administrat de operator.

Credentials salvate de utilizator sunt legate de sursa efectivă a definiției, hash-ul complet, contractul de autentificare, endpoint-urile și selectoarele capabilităților și valorile efective de rutare de la momentul salvării. O schimbare de rută sau definiție face vechiul credential indisponibil până când utilizatorul examinează noua destinație și îl salvează din nou. Credentials legacy fără binding sunt acceptate numai pe o rută inclusă ancorată exact; prima utilizare reușită scrie binding-ul înainte de a returna cheia decriptată.

Furnizori compatibili OpenAI

Un plugin poate defini:

• URL-ul complet al endpoint-ului API;
• variabila de mediu pentru cheia API;
• comportamentul endpoint-ului Chat;
• suport pentru embeddings;
• comportamentul de discovery al modelelor;
• o hartă de modele opțională ca fallback.

Dacă furnizorul nu acceptă discovery live, Libre WebUI folosește harta de modele configurată. JSON-ul importat configurează furnizori care vorbesc deja unul dintre formatele wire acceptate: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages sau Gemini. JSON-ul singur nu traduce un protocol proprietar arbitrar; un format diferit pentru cerere, streaming, apelarea instrumentelor sau răspuns necesită un adaptor backend mic.

Generarea imaginilor OpenAI

Furnizorul OpenAI inclus expune Image API la https://api.openai.com/v1/images/generations. Modelul curent este gpt-image-2. Catalogul păstrează și ID-urile deprecated gpt-image-1.5, gpt-image-1 și gpt-image-1-mini pentru deployment-urile compatibile existente; configurațiile noi trebuie să aleagă gpt-image-2.

Generarea imaginilor folosește același credential OpenAI efectiv ca Chat: cheia salvată a utilizatorului curent sau fallback-ul de mediu al furnizorului inclus de încredere. Are un override separat image_endpoint, astfel încât un endpoint Chat personalizat să nu primească accidental cereri de imagine. Lăsați image_endpoint gol pentru a moșteni endpoint-ul Image API inclus.

Selecțiile de imagine sunt calificate de furnizor. Când două pluginuri expun același ID de model, Libre WebUI trimite cererea numai furnizorului ales în panoul de imagine. Răspunsurile GPT Image folosesc date base64; Libre WebUI le transformă într-o imagine în aplicație și o salvează în galeria utilizatorului curent. Rutele Image API necesită autentificare, iar cererile directe trebuie să includă atât pluginId, cât și model. Pot seta n la un număr întreg JSON între 1 și 10; șirurile numerice și valorile fracționare sunt respinse înainte de a ajunge la furnizor.

Modurile API Chat Completions și Responses

Pluginurile completion compatibile OpenAI pot folosi semantica chat_completions sau responses. Pluginul OpenAI inclus oferă această alegere în Settings → Plugins.

Setările de conexiune sunt rezolvate în această ordine:

1. Un override complet endpoint, dacă este configurat.
2. base_url plus un api_path opțional.
3. Valoarea legacy endpoint a pluginului.

O valoare endpoint identică exact cu endpoint-ul manifestului este tratată ca valoare implicită, nu ca override. Astfel, valorile implicite legacy stocate nu ascund un Base URL nou după upgrade. Un endpoint complet cu adevărat personalizat păstrează prioritatea maximă.

Calea implicită este /chat/completions în modul Chat Completions și /responses în modul Responses. base_url trebuie să fie rădăcina API, precum https://api.example.com/v1; folosiți api_path când un furnizor compatibil expune operația la altă cale relativă. Un endpoint complet trebuie să conțină calea completă a operației și are prioritate față de ambele câmpuri. Un sufix cunoscut /chat/completions, /completions sau /responses stabilește semantica cererii; căile personalizate păstrează api_mode selectat.

JSON-ul importat poate furniza aceleași valori implicite:

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

Cererile Responses folosesc input, max_output_tokens, instrumente function aplatizate, store: false și conținut de reasoning criptat pentru continuare fără stare. Rezultatul complet și transmis în flux este normalizat înapoi în formatele de evenimente Chat și Work. Starea de replay este păstrată numai când întregul șir ordonat de Items are cel mult 64 Items și 90 KB; elementele sunt păstrate exact și câmpurile nu sunt trunchiate. Items redate necesită ID-uri și tipuri unice, ne-goale, iar structurile message, reasoning și function-call sunt validate înainte de emiterea oricărui apel de instrument. Starea Chat supradimensionată revine la istoricul vizibil normalizat. Chat elimină și Items brute de tip function-call, deoarece nu persistă rezultatele instrumentelor corespunzătoare. Răspunsurile Work cu instrumente, fără stare exactă și limitată pentru replay, sunt respinse înaintea oricărui efect secundar.

Stocarea Chat pe SQLite criptează starea păstrată a furnizorului împreună cu mesajul; Work stochează starea numai pentru instrumente în rânduri de context ascunse, care nu sunt returnate de API-urile de mesaje. Un scope hash-uit leagă replay-ul de același furnizor, model, mod Responses, endpoint final configurat și o amprentă opacă unidirecțională a credential-ului selectat. Când acel scope se schimbă, inclusiv după rotația cheii API, Libre WebUI revine la istoricul normalizat, în loc să trimită Items specifice furnizorului peste o limită de autentificare. O execuție Work activă își amprentează ruta și credential-ul și le revalidează imediat înaintea fiecărui tur al furnizorului; schimbarea modului, endpoint-ului sau cheii API oprește execuția înainte ca altă cerere să primească starea veche a instrumentelor.

Starea cu instrumente trebuie să încapă atât în limita de replay, cât și în wrapper-ul complet de metadata persistentă de 100 KB înainte ca Work să producă un efect secundar. Dacă un batch Work persistent a fost întrerupt, fiecare rezultat lipsă al instrumentului este restaurat cu ID-ul exact al apelului și un avertisment că rezultatul este necunoscut, astfel încât furnizorul să poată inspecta workspace-ul în loc să repete orbește un posibil efect secundar. Un rezultat Responses incomplet nu este tratat ca tur Chat sau Work reușit; incomplete_details.reason este păstrat și afișat apelantului.

Discovery derivă /models din calea operației. De exemplu, https://api.example.com/v1/responses caută modelele la https://api.example.com/v1/models. Furnizorii fără un endpoint compatibil pentru listare pot folosi în continuare un model_map manual. Discovery este limitat la variabilele și credentials utilizatorului curent. Rezultatele sunt stocate per utilizator, nu scrise în manifestul comun. Discovery rulează după activare, refresh explicit, schimbarea cheii API, schimbarea variabilelor de conexiune și resetare; salvarea altor variabile de generare nu declanșează o cerere de rețea.

Discovery rulează și automat. Citirea listei de pluginuri reface discovery pentru orice furnizor completion activ al cărui catalog lipsește sau este mai vechi decât PLUGIN_MODEL_DISCOVERY_TTL_MS. Un backoff per furnizor evită verificarea repetată a unuia inaccesibil, iar un deadline împiedică un furnizor lent să întârzie răspunsul; un refresh care depășește limita este servit la următoarea cerere. URL-ul final derivat este verificat înainte de citirea credential-ului utilizatorului sau construirea antetului Authorization, inclusiv dacă URL-ul provine dintr-un manifest importat. Cererile de discovery și capabilități nu urmează redirect-uri HTTP. Configurați direct endpoint-ul final Chat, Work, model-list, image, embedding, transcription, speech, voice-clone, audio sau video; astfel, credentials nu sunt retransmise de la un URL validat către o destinație redirect nevalidată.

Endpoint-urile furnizorilor pot folosi HTTP sau HTTPS. HTTP transmite chei API, prompturi, rezultate ale instrumentelor și conținut generat fără criptarea transportului, deci folosiți-l numai pentru un gateway self-hosted într-o rețea de încredere; preferați HTTPS când gateway-ul acceptă TLS. Cererile pornesc din backend. În deployment-uri cu containere, aceasta înseamnă un URL de serviciu precum http://ai-gateway:8080/v1, iar localhost identifică însuși containerul Libre WebUI. Rutele de capabilități ale pluginului rezolvă variabilele endpoint și credentials pentru contul autentificat care face cererea. Libre WebUI nu are un mod single-user neautentificat.

Endpoint-uri specifice capabilităților

Override-urile endpoint-ului Chat sunt izolate de capabilitățile image, embedding, transcription, text-to-speech, audio și video. Pluginurile cu mai multe capabilități pot expune image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint sau altă variabilă nominalizată de config.endpoint_variable. Rutele de clonare vocală pot nominaliza și config.voice_clone_endpoint_variable. Dacă aceste câmpuri rămân goale, este folosit endpoint-ul capabilității declarat de plugin; un endpoint Chat generic nu este niciodată folosit ca override de capabilitate.

Pluginul GitHub Models inclus moștenește endpoint-ul curent models.github.ai/inference/chat/completions când override-ul său opțional este gol. Pluginul Hugging Face folosește rute și payload-uri specifice task-ului hf-inference/models/{model} pentru embeddings, imagini și TTS, în loc să trimită acele cereri către endpoint-ul Chat.

Override-uri pentru endpoint

Variabila endpoint este URL-ul complet al cererii, inclusiv calea operației. De exemplu, un plugin chat compatibil OpenAI folosește de obicei https://provider.example/v1/chat/completions, nu doar https://provider.example. Configurațiile plugin legacy importate pot numi variabila api_url; Libre WebUI acceptă aliasul, dar un endpoint ne-gol are întotdeauna prioritate când sunt prezente ambele.

Sunt acceptate URL-uri HTTP și HTTPS absolute; alte protocoale sunt respinse. HTTP este destinat gateway-urilor self-hosted din rețele de încredere, deoarece transmite credentials și conținutul cererii fără criptarea transportului. Preferați HTTPS pentru orice rută care părăsește limita unui deployment privat. Un override gol folosește endpoint-ul definiției; o valoare explicită invalidă este respinsă fără revenire implicită.

Cererile furnizorilor nu urmează redirect-uri. Configurați direct URL-ul final validat; un redirect este raportat ca eroare, în loc să retransmită credentials sau conținut.

Cererile pornesc din backend. Într-un container, localhost înseamnă acel container, nu host-ul sau alt serviciu. Folosiți numele serviciului sau host.docker.internal acolo unde este oferit.

Descoperirea modelelor

În Settings → Plugins există Provider connections. Căutați furnizorul în stânga și verificați în dreapta starea activă și catalogul. Configurația rămâne restrânsă până când selectați Configure, ascunzând implicit endpoint-ul, credential-ul și parametrii avansați de generare.

Pentru pluginurile chat/completion, Refresh models rulează discovery și reîncarcă atât catalogul, cât și lista Chat. Catalogul este doar pentru citire și combină ID-urile furnizorului cu hărțile capabilităților. Etichetele indică ruta, nu sănătatea endpoint-ului. ID-urile fallback/manual se editează numai în model_map din JSON.

Activarea rulează discovery cu endpoint-ul și credential-ul efectiv al contului. O rută personalizată de administrator necesită credential-ul aceluiași cont; fallback-ul de mediu este permis numai pentru manifestul de încredere. URL-ul este derivat astfel:

• un URL care se termină în /models este folosit ca atare;
• sufixurile cunoscute /chat/completions, /completions, /responses, /embeddings și /messages sunt înlocuite;
• altfel se adaugă /models.

Un plugin poate declara explicit models_endpoint, care are prioritate, urmează aceeași politică outbound și nu permite redirect-uri. Salvarea sau resetarea endpoint, api_url, models_endpoint, base_url, api_path ori api_mode golește și reîncarcă catalogul înainte de reîmprospătarea UI-ului.

Rutele personalizate sunt rezolvate și validate înainte de citirea credential-ului. O cheie din mediul serverului nu este permisă pentru o rută personalizată stocată; salvați cheia per utilizator. Fallback-ul de mediu este numai pentru definiția de încredere.

Este așteptat un răspuns compatibil OpenAI cu data. Activarea așteaptă, astfel încât prima reîmprospătare să poată include catalogul. Rezultatele sunt per utilizator și nu rescriu JSON-ul sau expun lista altui cont. Dacă endpoint-ul este incompatibil, inaccesibil sau are alt format, activarea normală păstrează catalogul anterior. O schimbare intenționată a conexiunii îl golește mai întâi și folosește model_map la eșec.

Salvarea sau resetarea rutării golește catalogul anterior, astfel încât modelele vechii destinații să nu rămână după schimbare.

Statusul, disponibilitatea Work, cataloagele și rutele folosesc același context de utilizator și aceeași limită pentru credentials. Modelele de imagine, variabilele și credentials sunt rezolvate pentru apelant.

Selectarea exactă a furnizorului în Chat

ID-urile de model nu sunt unice global. Ollama și mai multe pluginuri pot expune același example-model. Chat păstrează ID-ul brut și o identitate opțională:

• providerType: "ollama" pentru Ollama;
• providerType: "plugin" împreună cu providerId pentru pluginul exact.

Valorile calificate și codificate în URL sunt numai chei fără coliziuni. Cererile trimit ID-ul brut. Duplicatele rămân separate, iar redeschiderea restabilește selecția exactă.

O identitate explicită închide accesul la eșec. Un plugin dezactivat/eliminat sau un model lipsă rămâne vizibil ca indisponibil, fără schimbare implicită. Reactivați-l sau selectați altul.

Sesiunile legacy pot avea providerType/providerId unset sau null și păstrează rutarea numai după nume, deoarece furnizorul nu poate fi reconstruit. Ele afișează „provider not recorded”. Selectarea unui furnizor concret scrie identitatea exactă. Personajele noi păstrează persona:<id> și modelul Ollama suport.

Setările furnizorului și moștenirea

Deschideți Settings → Plugins și Configure. Panourile sunt închise implicit. Administratorii controlează definițiile și rutarea. Ceilalți utilizatori pot activa, salva chei și regla generarea, fără opțiuni UI pentru upload/install/export/delete sau rutare.

Administratorii văd mai întâi override-urile. Sampling-ul se află în panoul închis Advanced parameters. Valorile moștenite sunt goale și au un indiciu; simpla deschidere a panoului nu copiază valorile implicite ale manifestului în cont.

Salvarea trimite numai câmpurile schimbate. Golirea unui câmp nesensibil elimină override-ul și restabilește valoarea implicită; un câmp sensibil mascat și gol nu se schimbă. Reset to Defaults elimină override-urile permise. La eșec, valorile nesalvate sunt păstrate pentru retry.

Pentru un endpoint personalizat, administratorul lasă câmpul gol pentru URL-ul inclus sau introduce URL-ul complet compatibil.

Pluginuri în Work

Work folosește pluginurile active completion/chat alături de Ollama numai când:

• pluginul este activ, modelul apare în catalog/hartă și administratorul are credentials disponibile.

Work păstrează tipul și ID-ul furnizorului în sarcină și execuție, deci rutarea folosește furnizorul exact, nu numele. Un plugin cu același nume nu redirecționează o sarcină existentă.

Work adaptează instrumentele prin OpenAI, Anthropic și Gemini. Modelul trebuie să accepte instrumente. Un răspuns respins sau incompatibil eșuează fără fallback.

O execuție la distanță poate face multe cereri, iar furnizorul primește promptul de sistem, contextul și definițiile/rezultatele instrumentelor, care pot include source, directoare sau ieșirea comenzilor. Libre afișează o notificare per utilizator, dar operatorii trebuie să verifice politica de prețuri, retenție și antrenare.

Embeddings

Pluginurile de embeddings apar în setările documentelor. Libre detectează modele Ollama precum nomic-embed-text, bge, e5 și gte.

Fără discovery, UI-ul folosește candidatul local implicit nomic-embed-text.

Note pentru dezvoltarea pluginurilor

Definiția trebuie să descrie precis capabilitatea, fără funcții false. Păstrați hărțile mici ca fallback și preferați discovery când furnizorul are un API de listare fiabil.

Când adăugați un furnizor:

1. Adăugați definiția și câmpurile credential-ului.
2. Implementați discovery dacă există un endpoint de listare.
3. Adăugați mapping pentru chat, embeddings, imagini, TTS și STT.
4. Testați cheia lipsă/incorectă și erorile furnizorului.

Documentație asociată

• Variabile de mediu
• Lucrul cu modele
• Work: spații izolate
• Kimi Code
• MLX LM pe Apple Silicon