Σύνδεση τρίτων και self-hosted παρόχων

Το Libre WebUI 0.16.0 προσθέτει το Provider connections στο Settings > Plugins. Ενεργοποιήστε bundled provider, στρέψτε συμβατό plugin σε άλλο API, ελέγξτε τον effective κατάλογο ή συνδέστε self-hosted gateway σε έμπιστο δίκτυο.

Υποστηρίζονται τα wire formats:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; και
• Google Gemini contents και function calling.

Οι bundled ορισμοί Anthropic/Gemini χρησιμοποιούν dedicated adapters βάσει identity. Νέος imported πάροχος χρησιμοποιεί semantics OpenAI Chat Completions ή Responses· ένα Anthropic/Gemini-compatible URL δεν επιλέγει αυτόματα τους adapters. Διαφορετικό request, streaming, tool-call ή response shape χρειάζεται backend adapter. Το JSON περιγράφει routing/config, δεν μεταφράζει άσχετο protocol.

Άνοιγμα Provider connections

1. Συνδεθείτε και ανοίξτε Settings > Plugins.
2. Αναζητήστε πάροχο αριστερά.
3. Επιλέξτε για active state και effective catalog.
4. Ενεργοποιήστε για τον λογαριασμό.
5. Configure μόνο για credential ή override.

Η διαμόρφωση είναι κλειστή από προεπιλογή. Οι admins βλέπουν πρώτα connection settings, ενώ sampling όπως temperature/token limits είναι στο ξεχωριστό Advanced parameters. Inherited defaults εμφανίζονται ως hints, όχι προγεμισμένα overrides.

Οι ορισμοί μοιράζονται στην instance, άρα import/install/update/delete μόνο admins. Κάθε πιστοποιημένος χρήστης ελέγχει activation, credential και allowed generation.

Γρήγορη προσθήκη σύνδεσης

Το Settings > Connections είναι συντόμευση: ένα OpenAI-compatible endpoint και ένα API key. Ο admin βλέπει κάρτα τοπικού Ollama με health/version, υπάρχουσες συνδέσεις και φόρμα.

Χρειάζονται display name, πλήρες Chat Completions URL και προαιρετικό key. Το Libre παράγει connection ID, εγκαθιστά definition, αποθηκεύει key server-side, ενεργοποιεί και ρωτά το endpoint για μοντέλα. Τα discovered αντικαθιστούν placeholders και εμφανίζονται στο Chat.

Κάθε σειρά έχει endpoint, model count, stored-key state, toggle, refresh και delete. Responses modes, Base URL overrides, capability catalogs και generation policy μένουν στο πλήρες Plugins.

Codex (σύνδεση ChatGPT)

Ο bundled Codex (ChatGPT) δεν χρειάζεται API key. Με Codex CLI login (codex login ως OS user του server) εμφανίζεται στους admins και προσφέρει documented Codex μέσω ChatGPT session. Tokens διαβάζονται από auth.json, ανανεώνονται με ίδιο OAuth client και γράφονται πίσω. Οι τιμές δεν γίνονται log.

Τα αιτήματα γίνονται από backend, όχι task container, άρα λειτουργεί στο Work με sandboxed tools. Είναι admin-only επειδή χρεώνει subscription ιδιοκτήτη. Κρύψτε με CODEX_OAUTH_MODELS_ENABLED=false ή δείξτε άλλο login μέσω CODEX_HOME.

Bundled ή imported πάροχος

Περιλαμβάνονται OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code, Hugging Face, GitHub Models, τοπικό MLX LM και άλλα. Χρησιμοποιήστε bundled όταν ταιριάζουν protocol/auth.

Για άλλη υπηρεσία, admin εισάγει JSON. Ελάχιστο παράδειγμα:

{
  "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"]
}

Import από Settings > Plugins, ενεργοποίηση και αποθήκευση key του account. Προσθέστε variables για editable Base URL, path, discovery ή capability endpoint. Το plugins/openai.json είναι πλήρες παράδειγμα.

Για authless gateway σε trusted network, ορίστε auth.header και auth.key_env κενά και παραλείψτε auth.prefix. Το Libre δεν απαιτεί ή στέλνει key.

Chat Completions ή Responses

API mode	Default request path	Τυπικό πεδίο
chat_completions	/chat/completions	messages
responses	/responses	input

Ο bundled OpenAI εκθέτει API Mode. Το Libre μετατρέπει completed/streamed Responses σε Chat/Work, μαζί με bounded replay state για reasoning και tools.

Η αλλαγή mode αλλάζει default path, όχι upstream protocol. Επιλέξτε Responses μόνο με compatible shapes.

Base URL ή πλήρες endpoint

Σειρά επίλυσης:

1. Μη default πλήρες endpoint override.
2. base_url και προαιρετικό api_path.
3. Endpoint του definition.

Base URL για root:

https://gateway.example/v1

Chat Completions χωρίς custom path:

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

Responses:

https://gateway.example/v1/responses

API Path για άλλη σχετική operation. Legacy Full Endpoint μόνο για πλήρες URL, που έχει προτεραιότητα. Γνωστά suffix /chat/completions, /completions, /responses ορίζουν semantics· άγνωστο custom path κρατά api_mode.

Μετά route/key αλλαγή αποθηκεύστε πριν δοκιμή. Custom authenticated route χρειάζεται credential του ίδιου account. Authless αφήνει fields κενά. Environment key του operator δεν στέλνεται σε user-defined destination, μόνο στη trusted bundled route.

Ανακάλυψη ή συντήρηση Model IDs

Επιλέξτε active chat provider και Refresh models. Φορτώνεται catalog και Chat list. Αυτόματα επαναλαμβάνεται όταν λείπει ή είναι παλιότερο από PLUGIN_MODEL_DISCOVERY_TTL_MS. Refresh αναφέρει:

Αποτέλεσμα	Σημασία
Catalog updated	Άλλαξε η λίστα
Catalog already up to date	Ίδια λίστα
API key needed	Δεν στάλθηκε αίτημα, παραμένει προηγούμενος catalog
Catalog could not be loaded	Μη προσβάσιμος ή άχρηστη απόκριση

Key μόνο στο environment δεν χρησιμοποιείται με installed definition αντί bundled και το μήνυμα το εξηγεί. Speech/image/embedding εμφανίζονται με labels αλλά όχι στο Chat selector.

Η URL /models προκύπτει:

• route που τελειώνει /models όπως είναι·
• γνωστά suffix /chat/completions, /completions, /responses, /embeddings ή /messages αντικαθίστανται με /models·
• αλλιώς προστίθεται /models.

Και οι δύο routes:

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

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

Αν δεν προκύπτει σωστά, εκθέστε models_endpoint στο variables:

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

Inherited/admin value έχει προτεραιότητα. Top-level property δεν διαβάζεται. Αναμένεται data:

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

Τα IDs αποθηκεύονται ανά χρήστη και δεν αλλάζουν shared JSON. Χωρίς compatible discovery, διατηρήστε model_map. Ο catalog είναι read-only και capability labels δεν είναι health checks.

IDs δεν είναι global unique. Το Chat αποθηκεύει raw ID και ακριβή Ollama/plugin identity. Μη διαθέσιμος αποθηκευμένος πάροχος φαίνεται unavailable αντί σιωπηρή δρομολόγηση.

Ξεχωριστή δημιουργία εικόνας

Ο bundled OpenAI χρησιμοποιεί https://api.openai.com/v1/images/generations και default gpt-image-2. Παλιά GPT Image IDs μένουν fallback.

Chat και image routes είναι απομονωμένα. Custom Chat Base URL δεν παίρνει αυτόματα εικόνες. Κενό image_endpoint χρησιμοποιεί definition, αλλιώς πλήρες compatible Image API URL.

Οι επιλογές είναι provider-qualified. Δύο plugins με ίδιο ID στέλνουν μόνο στον επιλεγμένο.

Ασφαλής HTTP gateway

Endpoints δέχονται absolute HTTP/HTTPS. HTTP είναι χρήσιμο σε trusted LAN/Tailscale/container network αλλά στέλνει keys, prompt, results, content χωρίς encryption. Προτιμήστε HTTPS με TLS.

Τα αιτήματα ξεκινούν από backend:

Θέση backend	Παράδειγμα root
Native process, ίδιο μηχάνημα	http://127.0.0.1:8081/v1
Docker Compose service	http://ai-gateway:8080/v1
Container προς host	http://host.docker.internal:8081/v1
Trusted LAN/Tailscale	http://192.168.1.20:8081/v1

Σε container, localhost είναι το Libre container, όχι άλλη υπηρεσία ή host. Γίνονται δεκτά μόνο HTTP/HTTPS, η τελική destination ελέγχεται πριν credential και δεν ακολουθούνται redirects.

Επαλήθευση gateway

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

Μετά την επιτυχία, ρυθμίστε ίδια route/mode/credential/model, ενεργοποιήστε, Refresh models και επιλέξτε στο Chat. Work μόνο με αξιόπιστα tool calls.

Αντιμετώπιση προβλημάτων

Σύμπτωμα	Έλεγχος
Πηγαίνει ακόμη bundled endpoint	Καθαρίστε παλιό full override, σώστε Base URL/API Path
Λάθος payload	Ταιριάξτε API Mode και suffix
Refresh χωρίς IDs	/models, data[].id, models_endpoint ή model_map
Παλιό μοντέλο μετά route	Αποθηκεύστε· καθαρίζεται ο παλιός catalog
Λείπει key	User credential για custom route
Docker δεν φτάνει localhost	Compose service, host alias ή private address
Chat ναι, image όχι	Ξεχωριστό πλήρες image_endpoint
Chat ναι, Work όχι	Compatible tool calls απαιτούνται
Redirect	Τελικό validated URL· δεν ακολουθείται

Δείτε Plugins και Αντιμετώπιση προβλημάτων.

Ευχαριστίες κοινότητας

Ο οδηγός και το Provider connections 0.16.0 διαμορφώθηκαν από ZhengJin (@fangzhengjin) και το feedback/AI UX στο #163.

Σχετική τεκμηρίωση

• Plugins
• Εργασία με μοντέλα
• MLX LM σε Apple Silicon
• Work: απομονωμένοι χώροι
• Αντιμετώπιση προβλημάτων