Conectarea furnizorilor terți și self-hosted

Libre WebUI 0.16.0 adaugă Provider connections în Settings > Plugins. Activați un furnizor inclus, indicați alt API unui plugin compatibil, inspectați catalogul efectiv sau conectați un gateway propriu într-o rețea de încredere.

Formate suportate:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; și
• Google Gemini contents și function calling.

Definițiile Anthropic/Gemini folosesc adaptoare dedicate după identitate. Un import nou folosește semantica OpenAI Chat Completions sau Responses; un URL compatibil Anthropic nu selectează adaptorul. Alt request/stream/tool/response shape cere adaptor backend. JSON descrie routing/config, nu traduce protocol neînrudit.

Deschiderea Provider connections

1. Autentificați-vă și deschideți Settings > Plugins.
2. Căutați furnizorul în stânga și selectați pentru stare/catalog.
3. Activați pentru cont.
4. Folosiți Configure numai pentru credentiale sau override.

Configurația este închisă implicit. Adminii văd întâi conexiunea, iar sampling precum temperature/token limits în Advanced parameters separat. Valorile moștenite apar ca hint, nu override precompletat.

Definițiile sunt comune instanței, deci import/install/update/delete doar admins. Fiecare utilizator controlează activarea, credentialele și generarea permisă.

Conexiune rapidă

Settings > Connections este calea scurtă: un endpoint compatibil OpenAI și o cheie. Adminul vede runtime Ollama local cu health/version, lista și formular.

Sunt necesare nume, URL complet Chat Completions și cheie opțională. Libre derivă ID, instalează definiția, salvează cheia server-side, activează și întreabă endpointul. Modelele găsite înlocuiesc placeholder catalog și apar în Chat.

Fiecare rând are endpoint, count, stare key, toggle, refresh, delete. Responses mode, Base URL overrides, catalog per capability și policy rămân în Plugins complet.

Codex (autentificare ChatGPT)

Codex (ChatGPT) nu cere cheie. Cu login Codex CLI (codex login ca OS user), apare adminilor și oferă familia documentată prin sesiunea ChatGPT. Tokenurile se citesc din auth.json, se reîmprospătează cu același OAuth și se scriu înapoi; valorile nu se loghează.

Cererile vin din backend, nu task container, deci funcționează cu Work. Este admin-only fiindcă folosește abonamentul proprietarului. Ascundeți cu CODEX_OAUTH_MODELS_ENABLED=false sau indicați alt login prin CODEX_HOME.

Furnizor inclus sau importat

Sunt incluse OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code, Hugging Face, GitHub Models, MLX LM local și altele. Folosiți inclus când protocol/auth se potrivesc.

Exemplu minim importat:

{
  "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ți din Settings > Plugins, activați și salvați cheia contului. Adăugați variabile pentru Base URL, path, discovery sau endpoint capability. Exemplul complet: plugins/openai.json.

Pentru gateway fără auth în rețea de încredere, setați auth.header și auth.key_env goale și omiteți auth.prefix. Libre nu cere/trimite key.

Chat Completions sau Responses

API mode	Path implicit	Câmp
chat_completions	/chat/completions	messages
responses	/responses	input

OpenAI inclus expune API Mode. Libre normalizează output completed/streamed spre Chat/Work, cu replay limitat pentru reasoning/tools. Schimbarea mode schimbă path, nu protocol upstream.

Base URL sau endpoint complet

Ordine:

1. Override complet endpoint non-default.
2. base_url plus api_path opțional.
3. Endpointul definiției.

https://gateway.example/v1

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

https://gateway.example/v1/responses

API Path pentru altă operație relativă. Legacy Full Endpoint doar URL complet, cu prioritate. Sufixele /chat/completions, /completions, /responses determină semantica.

După route/key salvați înainte de test. Ruta custom cu auth cere credentiale ale aceluiași cont. Plugin fără auth lasă câmpuri goale. Cheia de mediu a operatorului nu merge la destinație user, doar bundled trusted.

Discovery și Model IDs

Selectați provider activ și Refresh models. Discovery rulează automat dacă lipsește sau e mai vechi decât PLUGIN_MODEL_DISCOVERY_TTL_MS.

Rezultat	Sens
Catalog updated	Lista s-a schimbat
Catalog already up to date	Aceeași listă
API key needed	Nu s-a trimis; rămâne catalog anterior
Catalog could not be loaded	Indisponibil sau răspuns inutil

Cheia doar env nu se folosește cu installed definition; mesajul explică. Speech/image/embedding apar cu labels, nu în Chat picker.

URL /models:

• ruta /models neschimbată;
• sufixele /chat/completions, /completions, /responses, /embeddings, /messages înlocuite;
• altfel /models adăugat.

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

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

Pentru URL explicit, declarați models_endpoint în variables:

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

Valoarea moștenită/admin are prioritate. Proprietatea top-level nu se citește. Se așteaptă data:

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

ID-urile sunt per utilizator, fără rescriere JSON. Fără discovery, păstrați model_map. Catalogul read-only și labels nu sunt health checks. ID-urile nu sunt global unice; Chat salvează provider identity și marchează indisponibil în loc de rutare silențioasă.

Generare imagini separată

OpenAI inclus folosește https://api.openai.com/v1/images/generations și implicit gpt-image-2, păstrând ID-uri vechi ca fallback. Chat Base URL custom nu primește imagini. Lăsați image_endpoint gol sau setați URL complet. Se trimite doar furnizorului selectat.

Gateway HTTP sigur

Endpointurile pot fi HTTP/HTTPS. HTTP este pentru LAN/Tailscale/container network de încredere și trimite chei/prompturi necriptat. Preferabil HTTPS/TLS.

Locație backend	Exemplu
Proces nativ	http://127.0.0.1:8081/v1
Compose service	http://ai-gateway:8080/v1
Container spre host	http://host.docker.internal:8081/v1
LAN/Tailscale	http://192.168.1.20:8081/v1

În container, localhost este containerul Libre. Sunt acceptate doar HTTP/HTTPS, destinația finală este validată înainte de credentiale și redirecturile nu sunt urmate.

Verificarea gatewayului

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

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
  }'

După succes, configurați aceeași rută, mode, credential și ID, activați, Refresh models și selectați în Chat. Work cere tool calls compatibile.

Depanare

Simptom	Verificare
Încă bundled endpoint	Ștergeți override, salvați Base URL/API Path
Payload greșit	Potriviți API Mode și sufix
Refresh fără ID	/models, data[].id, models_endpoint, model_map
Model vechi	Salvați conexiunea pentru curățare
Key lipsă	Credential per user pe ruta custom
Docker nu ajunge localhost	Service Compose, alias host, adresă privată
Chat da, imagini nu	image_endpoint separat
Chat da, Work nu	Tool calls compatibile
Redirect	URL final validat

Detalii în Plugins și Depanare.

Mulțumiri

Ghidul și experiența 0.16.0 au fost modelate de ZhengJin (@fangzhengjin) și feedback-ul din #163.

Documentație asociată

• Plugins
• Lucrul cu modele
• MLX LM pe Apple Silicon
• Work: spații izolate
• Depanare