Üçüncü taraf ve kendi barındırdığınız sağlayıcıları bağlama

Libre WebUI 0.16.0, Ayarlar > Eklentiler bölümüne Sağlayıcı bağlantıları ekler. Burada yerleşik bir sağlayıcıyı etkinleştirebilir, uyumlu bir eklentiyi API’ye yönlendirebilir, sonuç kataloğunu inceleyebilir veya güvenilir ağınızdaki özel ağ geçidine bağlanabilirsiniz.

Şu biçimler desteklenir:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; ve
• Google Gemini içerik ve işlev çağrıları.

Yerleşik Anthropic ve Gemini tanımları, sağlayıcı kimliğine göre seçilen özel bağdaştırıcıları kullanır. Yeni içe aktarılan bir tanım Chat Completions veya Responses anlamını kullanır; Anthropic ya da Gemini uyumlu bir API belirtmek yerleşik bağdaştırıcıyı seçmez. Farklı bir istek, akış, araç çağrısı veya yanıt biçimi sunucu bağdaştırıcısı gerektirir. JSON yönlendirme ve yapılandırmayı açıklar; başka bir protokolü dönüştürmez.

Bağlantıları açma

1. Oturum açın ve Ayarlar > Eklentiler bölümünü açın.
2. Solda sağlayıcıyı bulun.
3. Durum ve katalog için sağlayıcıyı seçin.
4. Hesabınız için etkinleştirin.
5. Yalnızca kimlik bilgileri veya bağlantı geçersiz kılması için Yapılandır seçeneğini açın.

Yapılandırma varsayılan olarak daraltılmıştır. Bağlantı ayarları önce yöneticilere gösterilir; örnekleme parametreleri ayrı, daraltılmış Gelişmiş parametreler bölümündedir. Devralınan değerler önceden doldurulmuş hesap geçersiz kılmaları olarak değil, ipucu olarak görünür.

Tanımlar örneğin ortak yapılandırmasıdır; bu nedenle yalnızca yöneticiler bunları içe aktarabilir, kurabilir, güncelleyebilir ve silebilir. Her kullanıcı kendi etkinleştirmesini, kimlik bilgilerini ve izin verilen üretim parametrelerini yönetir.

Hızlı ekleme

Ayarlar > Bağlantılar, OpenAI uyumlu tek bir uç nokta ve anahtar için kısa yoldur. Yönetici Ollama durumunu ve sürümünü, bağlantı listesini ve ekleme formunu görür.

Görünen ad, tam sohbet tamamlama URL’si ve isteğe bağlı anahtar gerekir. Libre bağlantı ID’sini türetir, tanımı kurar, anahtarı sunucuda saklar, bağlantıyı etkinleştirir ve model listesini ister. Keşfedilen modeller geçici kataloğun yerini alır ve seçicide görünür.

Satırda uç nokta, model sayısı, anahtar varlığı, etkinlik, yenileme ve silme işlemleri gösterilir. Responses modları, temel URL geçersiz kılmaları, ayrı yetenek katalogları ve parametre ilkesi tam eklenti arayüzünde kalır.

Codex (ChatGPT ile giriş)

Codex (ChatGPT) API anahtarı gerektirmez. Sunucunun sistem kullanıcısı olarak codex login çalıştırıldıktan sonra yöneticilere görünür ve ChatGPT oturumu üzerinden belgelenmiş model ailesini sunar. Belirteçler auth.json dosyasından okunur, aynı OAuth istemcisiyle yenilenir ve geri yazılır; değerler günlüklenmez.

İstekleri görev kapsayıcısı değil sunucu yapar; bu nedenle modeller Work içinde de çalışır. Sağlayıcı, sunucu sahibinin ChatGPT aboneliğini kullandığı için yalnızca yöneticilere açıktır. CODEX_OAUTH_MODELS_ENABLED=false ile gizlenebilir; farklı yetkilendirme konumu CODEX_HOME ile belirtilebilir.

Yerleşik veya içe aktarılan sağlayıcı

OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code, Hugging Face, GitHub Models, yerel MLX LM ve diğerleri kullanılabilir. Protokol ve kimlik doğrulama eşleşiyorsa yerleşik seçenekle başlayın.

Yönetici JSON tanımını içe aktarır. En küçük ağ geçidi örneği:

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

Tanımı içe aktarın, etkinleştirin ve anahtarı saklayın. Düzenlenebilir temel URL, yol, keşif ve ayrı yetenek uç noktaları için değişkenler ekleyin. Tam örnek için plugins/openai.json dosyasına bakın.

Güvenilir ağda bilerek kimlik doğrulaması istemeyen bir ağ geçidi için auth.header ve auth.key_env alanlarını boş bırakın ve auth.prefix alanını kaldırın; anahtar gerekmez ve gönderilmez.

Chat Completions veya Responses

Mod	Yol	Alan
chat_completions	/chat/completions	messages
responses	/responses	input

Yerleşik OpenAI, API modu seçeneğini sunar. Libre tamamlanmış ve akışlı Responses çıktısını Chat ve Work için dönüştürür; sınırlı muhakeme durumu ve araç çağrısı yeniden oynatımı da buna dâhildir.

Mod, varsayılan yolu değiştirir; üst sunucunun protokolünü değiştirmez. Responses’ı yalnızca istek ve olay biçimi uyumluysa seçin.

Temel URL veya tam uç nokta

Öncelik sırası:

1. Özel tam endpoint.
2. base_url + api_path.
3. Eklenti tanımındaki uç nokta.

Temel URL:

https://gateway.example/v1

Chat Completions:

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

Responses:

https://gateway.example/v1/responses

API yolu, göreli işlem içindir. Eski tam uç nokta, tam URL içindir; tam uç noktanın önceliği daha yüksektir.

/chat/completions, /completions ve /responses son ekleri anlamı belirler. Bilinmeyen bir yol seçilen modu korur.

Rotayı veya anahtarı değiştirdikten sonra sınamadan önce sağlayıcıyı kaydedin. Kimlik doğrulamalı kullanıcı rotası, aynı hesabın kimlik bilgilerini ister. Kimlik doğrulamasız seçenek alanları boş bırakır. İşletmecinin ortam anahtarı kullanıcı uç noktasına gönderilmez; yedek değer yalnızca güvenilir yerleşik rotaya uygulanır.

Model ID’lerini keşfetme

Etkin sağlayıcıyı seçip Modelleri yenile seçeneğine basın. Libre kataloğu ve Chat’i yeniden yükler.

Katalog yoksa veya PLUGIN_MODEL_DISCOVERY_TTL_MS değerinden eskiyse otomatik yenilenir. Elle yenileme şu sonuçlardan birini bildirir:

Sonuç	Anlam
Katalog güncellendi	Yanıt farklı bir liste içerdi
Zaten güncel	Aynı liste alındı
API anahtarı gerekli	İstek gönderilmedi, önceki katalog görünür kalır
Yüklenemedi	Uç nokta erişilemedi veya veri döndürmedi

Yalnızca ortamda bulunan anahtar, yerleşik tanım yerine kurulu bir tanım için kullanılmaz; ileti bunu açıklar. Konuşma, görüntü ve embedding modelleri yetenek rozetleriyle görünür, ancak sohbet seçicisinde yer almaz.

Model listesi URL’si şu şekilde türetilir:

• /models ile biten URL olduğu gibi kullanılır;
• /chat/completions, /completions, /responses, /embeddings veya /messages son eki /models ile değiştirilir; ya da
• diğer durumlarda yola /models eklenir.

Örnek:

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

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

Türetme yanlışsa variables içinde models_endpoint ayarlayın:

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

Devralınan veya yönetici tarafından kaydedilen değer önceliklidir. Üst düzey models_endpoint özelliği okunmaz. data dizisi içeren OpenAI uyumlu bir yanıt beklenir:

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

ID’ler kullanıcı için saklanır ve dosyanın üzerine yazmaz. Uyumlu keşif yoksa model_map listesini koruyun. Katalog salt okunurdur; rozetler çalışırlık kanıtı değildir.

ID’ler genel olarak benzersiz değildir. Chat, özgün ID’yi sağlayıcının tam kimliğiyle birlikte saklar. Kullanılamayan sağlayıcı, başka rotaya yönlendirilmeden kullanılamaz olarak gösterilir.

Ayrı görüntü üretimi

OpenAI görüntü uç noktası https://api.openai.com/v1/images/generations adresidir; yeni yapılandırmalar varsayılan olarak gpt-image-2 kullanır, eski ID’ler yedek olarak kalır.

Sohbet ve görüntü rotaları birbirinden yalıtılmıştır. Kullanıcının sohbet temel URL’si görüntü isteği almaz. Boş image_endpoint eklenti tanımını kullanır; tam URL, uyumlu Image API işlemini belirtir.

Seçim belirli sağlayıcıya bağlıdır; aynı ID yalnızca seçilen sağlayıcıya yönlendirilir.

Güvenli HTTP ağ geçidi

HTTP ve HTTPS kabul edilir. HTTP; güvenilir LAN, Tailscale veya kapsayıcı ağı için uygundur, ancak anahtarları, istemleri, araç sonuçlarını ve içeriği aktarım şifrelemesi olmadan taşır. TLS ile HTTPS’yi tercih edin.

İstekler sunucudan çıktığı için sunucunun erişebildiği adresi seçin:

Konum	Örnek
Yerel, aynı ana bilgisayar	http://127.0.0.1:8081/v1
Compose hizmeti	http://ai-gateway:8080/v1
Kapsayıcı → ana bilgisayar	http://host.docker.internal:8081/v1
Güvenilir LAN/Tailscale	http://192.168.1.20:8081/v1

Kapsayıcı içindeki localhost, hizmeti veya ana bilgisayarı değil kapsayıcının kendisini gösterir.

Yalnızca HTTP ve HTTPS kabul edilir; kimlik bilgileri seçilmeden önce son adres doğrulanır ve yönlendirmeler izlenmez. Son URL’yi doğrudan yapılandırın.

Ağ geçidini sınama

Ana bilgisayardan veya sunucu kapsayıcısından:

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

Sınamalar başarılı olduktan sonra aynı rotayı, modu, kimlik bilgilerini ve model ID’sini ayarlayın; sağlayıcıyı etkinleştirin, modelleri yenileyin ve sağlayıcıyı seçin. Araç desteği güvenilir olduğunda Work modeli kullanabilir.

Sorun giderme

Belirti	Denetim
İstekler yerleşik uç noktaya gidiyor	Eski tam geçersiz kılmayı silin; gereken temel URL ve API yolunu kaydedin.
İstek verileri yanlış	API modunu protokolle eşleştirin ve son eki denetleyin.
Model ID’si yok	/models, data[].id biçimi, models_endpoint veya model_map değerini denetleyin.
Rota değişiminden sonra eski model kaldı	Değişikliği kaydedin; eski keşif kataloğu temizlenir.
Anahtar bulunamadı	Kullanıcının kimlik bilgilerini kaydedin; yerleşik ortam yedeği geçersiz kılmalara uygulanmaz.
Docker localhost’a erişemiyor	Hizmet adı, ana bilgisayar diğer adı veya erişilebilir özel adres kullanın.
Chat çalışıyor, görüntü çalışmıyor	Tam image_endpoint ve bu yeteneğin modelini yapılandırın.
Chat çalışıyor, Work çalışmıyor	Uyumlu araç çağrısı desteğini doğrulayın.
Sağlayıcı yönlendiriyor	Son ve doğrulanmış URL’yi yapılandırın; yönlendirmeler izlenmez.

Ayrıntılar için Eklentiler, hatalar için Sorun giderme bölümüne bakın.

Topluluğa teşekkür

0.16.0 kılavuzu ve arayüzü ZhengJin (@fangzhengjin) sayesinde biçimlendi: üçüncü taraf sağlayıcılar hakkındaki ayrıntılı geri bildirim ve #163 içindeki yapay zekâ destekli arayüz kavramı bu akışın tanımlanmasına yardımcı oldu.

İlgili belgeler

• Eklentiler
• Modellerle çalışma
• Apple Silicon üzerinde MLX LM
• Work: yalıtılmış çalışma alanları
• Sorun giderme