Menghubungkan Penyedia Pihak Ketiga dan yang Dihosting Sendiri

Libre WebUI 0.16.0 menambahkan ruang kerja Provider connections yang terfokus di dalam Settings > Plugins. Gunakan ruang kerja ini untuk mengaktifkan penyedia terbundel, mengarahkan plugin kompatibel ke API lain, memeriksa katalog model yang berlaku, atau menghubungkan gateway yang Anda hosting sendiri pada jaringan tepercaya.

Libre WebUI saat ini mendukung format komunikasi penyedia berikut:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; dan
• pemanggilan konten serta fungsi Google Gemini.

Definisi Anthropic dan Gemini terbundel memakai adaptor khusus yang dipilih berdasarkan identitas penyedia. Penyedia yang baru diimpor memakai semantik OpenAI Chat Completions atau OpenAI Responses; mengarahkannya ke API kompatibel Anthropic atau Gemini tidak memilih adaptor terbundel tersebut. Penyedia dengan bentuk permintaan, aliran, pemanggilan alat, atau respons lain memerlukan adaptor backend. JSON plugin menjelaskan perutean dan konfigurasi; JSON tidak menerjemahkan protokol yang berbeda.

Membuka Koneksi Penyedia

1. Masuk dan buka Settings > Plugins.
2. Cari penyedia pada daftar di panel kiri.
3. Pilih penyedia untuk memeriksa status aktif dan katalog model yang berlaku.
4. Aktifkan penyedia untuk akun Anda.
5. Pilih Configure hanya saat perlu menyimpan kredensial atau menimpa pengaturan koneksi.

Konfigurasi penyedia tertutup secara bawaan. Pengaturan koneksi tampil lebih dahulu bagi administrator, sedangkan kendali sampling seperti suhu dan batas token tetap berada di bagian Advanced parameters yang terlipat terpisah. Nilai warisan tampil sebagai petunjuk, bukan penimpaan akun yang sudah diisi.

Definisi plugin merupakan konfigurasi bersama instans, sehingga hanya administrator yang dapat mengimpor, memasang, memperbarui, atau menghapusnya. Setiap pengguna terautentikasi mengendalikan status aktif, kredensial, dan pengaturan generasi yang diizinkan untuk dirinya sendiri.

Menambahkan Koneksi dengan Cepat

Settings > Connections adalah jalur singkat untuk kasus umum: satu endpoint kompatibel OpenAI dan satu kunci API. Administrator melihat kartu runtime Ollama lokal beserta kesehatan dan versinya, daftar koneksi kompatibel OpenAI yang ada, serta formulir kecil untuk menambahkan koneksi.

Penambahan koneksi memerlukan nama tampilan, URL lengkap chat completions, dan kunci API opsional. Libre WebUI menurunkan ID koneksi dari nama, memasang definisi penyedia, menyimpan kunci di server, mengaktifkan koneksi, dan menanyakan model yang disajikan endpoint. Model yang ditemukan menggantikan katalog pengganti dan tampil pada pemilih model chat.

Setiap baris menampilkan endpoint, jumlah model, apakah kunci tersimpan, sakelar aktif, penyegaran model, dan penghapusan. Semua hal lain — mode Responses API, penimpaan Base URL, katalog per kemampuan, kebijakan parameter generasi — tetap berada di ruang kerja Settings > Plugins yang lengkap.

Codex (Masuk dengan ChatGPT)

Penyedia terbundel Codex (ChatGPT) tidak memerlukan kunci API. Saat server memiliki sesi Codex CLI (codex login sebagai pengguna sistem operasi server), penyedia muncul bagi administrator dan menawarkan keluarga model Codex melalui sesi ChatGPT. Token akses dibaca dari auth.json milik CLI, disegarkan melalui klien OAuth yang sama, lalu ditulis kembali agar CLI tetap bekerja; nilai token tidak pernah masuk log.

Karena backend yang membuat permintaan — bukan kontainer tugas — model ini juga dapat menjalankan Work dengan siklus alat dalam sandbox biasa. Penyedia hanya tersedia bagi administrator karena setiap panggilan memakai langganan ChatGPT milik operator server. Sembunyikan seluruhnya dengan CODEX_OAUTH_MODELS_ENABLED=false, atau arahkan ke sesi lain dengan CODEX_HOME.

Memilih Penyedia Terbundel atau Impor

Libre WebUI menyertakan definisi untuk OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code dari Moonshot AI, Hugging Face, GitHub Models, MLX LM lokal, dan layanan model atau media lainnya. Mulailah dengan entri terbundel jika protokol serta kontrak autentikasinya cocok dengan layanan Anda.

Untuk layanan kompatibel lain, administrator dapat mengimpor definisi JSON plugin. Contoh minimal gateway kompatibel 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"]
}

Impor berkas dari Settings > Plugins, aktifkan, dan simpan kunci API untuk akun yang akan memakai koneksi. Tambahkan variabel koneksi ke definisi saat administrator memerlukan kolom Base URL, jalur, penemuan, atau endpoint per kemampuan yang dapat disunting. plugins/openai.json terbundel adalah contoh lengkap.

Untuk gateway tanpa autentikasi yang disengaja pada jaringan tepercaya, tetapkan auth.header dan auth.key_env menjadi string kosong serta hilangkan auth.prefix. Libre WebUI kemudian tidak meminta atau mengirim kunci API untuk plugin tersebut.

Memilih Chat Completions atau Responses

Plugin completion kompatibel OpenAI dapat memakai salah satu mode API:

Mode API	Jalur permintaan bawaan	Kolom permintaan umum
chat_completions	/chat/completions	messages
responses	/responses	input

Penyedia OpenAI terbundel menampilkan API Mode dalam konfigurasi. Libre WebUI memetakan keluaran Responses yang lengkap dan mengalir kembali ke Chat serta Work, termasuk status replay terbatas untuk penalaran dan pemanggilan alat.

Mengubah mode memengaruhi jalur operasi bawaan. Perubahan ini tidak mengubah protokol server hulu, jadi pilih Responses hanya jika server menerapkan bentuk permintaan dan peristiwa Responses yang kompatibel.

Mengonfigurasi Base URL atau Endpoint Lengkap

Libre WebUI menyelesaikan rute completion dalam urutan berikut:

1. Penimpaan endpoint lengkap yang bukan bawaan.
2. base_url ditambah api_path opsional.
3. Endpoint yang dinyatakan definisi plugin.

Gunakan Base URL untuk akar API:

https://gateway.example/v1

Tanpa jalur khusus, mode Chat Completions mengirim ke:

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

Mode Responses mengirim ke:

https://gateway.example/v1/responses

Gunakan API Path saat penyedia menyajikan operasi kompatibel pada jalur lain relatif terhadap akar. Gunakan Legacy Full Endpoint hanya saat harus memberikan URL operasi lengkap; endpoint lengkap mendahului Base URL dan API Path.

Akhiran /chat/completions, /completions, dan /responses yang dikenal juga menentukan semantik permintaan. Jalur operasi khusus yang tidak dikenali mempertahankan mode API yang dipilih secara eksplisit.

Setelah mengubah rute atau kunci API, simpan penyedia kembali sebelum menguji Chat. Bila plugin menyatakan autentikasi, rute koneksi khusus memerlukan kredensial yang disimpan akun yang sama. Plugin tanpa autentikasi dapat membiarkan kedua kolom kosong. Libre WebUI tidak mengirim kunci lingkungan milik operator ke tujuan yang ditentukan pengguna; cadangan lingkungan hanya berlaku untuk rute terbundel tepercaya.

Menemukan atau Memelihara ID Model

Pilih penyedia chat aktif lalu gunakan Refresh models untuk menjalankan penemuan. Libre WebUI memuat ulang katalog penyedia dan daftar model Chat.

Penemuan juga berjalan otomatis saat katalog hilang atau lebih tua daripada PLUGIN_MODEL_DISCOVERY_TTL_MS. Refresh models memaksa pemeriksaan segera dan melaporkan hasil:

Hasil	Arti
Katalog diperbarui	Daftar baru berbeda
Katalog sudah terbaru	Daftar sama
Kunci API diperlukan	Tidak ada kunci; katalog lama tetap tampil
Katalog gagal dimuat	Endpoint tidak tercapai atau data tidak berguna

Kunci yang hanya ada di lingkungan tidak dipakai untuk definisi terpasang yang menggantikan definisi terbundel; pesan menjelaskan keadaan ini. Model ucapan, gambar, dan embedding tampil dengan label kemampuan, tetapi tidak masuk pemilih model chat.

Untuk rute kompatibel OpenAI, URL daftar model dipilih sebagai berikut:

• rute berakhiran /models dipakai apa adanya;
• akhiran /chat/completions, /completions, /responses, /embeddings, atau /messages diganti dengan /models; atau
• jika tidak, /models ditambahkan.

Contoh kedua rute menghasilkan URL penemuan yang sama:

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

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

Jika penurunan URL tidak tepat, tampilkan models_endpoint dalam larik variables plugin:

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

Nilai warisan atau simpanan administrator mendahului alamat turunan. Properti models_endpoint tingkat atas tidak dibaca. Penemuan mengharapkan respons kompatibel OpenAI dengan objek model dalam larik data:

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

ID yang ditemukan disimpan per pengguna dan tidak menulis ulang berkas plugin bersama. Jika penyedia tidak mendukung penemuan kompatibel, pertahankan ID cadangan dalam model_map. Katalog hanya-baca; label kemampuan bukan pemeriksaan kesehatan.

ID model tidak unik secara global. Chat menyimpan ID mentah bersama identitas penyedia Ollama atau plugin yang tepat. Jika penyedia tersimpan tidak tersedia, Libre WebUI menampilkan pilihan sebagai tidak tersedia alih-alih mengalihkannya diam-diam.

Mengonfigurasi Pembuatan Gambar Secara Terpisah

Penyedia OpenAI terbundel memakai https://api.openai.com/v1/images/generations dan konfigurasi baru menggunakan gpt-image-2. ID lama tetap ada sebagai cadangan.

Rute chat dan gambar sengaja dipisahkan. Base URL Chat khusus tidak menerima permintaan gambar otomatis. Biarkan image_endpoint kosong untuk endpoint definisi plugin, atau tetapkan URL operasi Image API lengkap yang kompatibel.

Pilihan gambar terikat penyedia seperti pilihan Chat. Bila dua plugin menawarkan ID sama, permintaan hanya dikirim ke penyedia yang dipilih pada panel gambar.

Menghubungkan Gateway HTTP dengan Aman

Endpoint dapat memakai URL HTTP atau HTTPS absolut. HTTP berguna untuk LAN, Tailscale, atau jaringan kontainer tepercaya, tetapi mengirim kunci, perintah, hasil alat, dan isi tanpa enkripsi transport. Utamakan HTTPS saat melintasi batas jaringan.

Permintaan berasal dari backend Libre WebUI, bukan peramban. Pilih alamat yang dapat dijangkau backend:

Lokasi backend	Contoh akar penyedia
Proses lokal, mesin sama	http://127.0.0.1:8081/v1
Layanan Compose	http://ai-gateway:8080/v1
Kontainer ke host	http://host.docker.internal:8081/v1
LAN/Tailscale tepercaya	http://192.168.1.20:8081/v1

Di dalam kontainer, localhost merujuk ke kontainer Libre WebUI sendiri, bukan layanan Compose lain atau host.

Libre WebUI hanya menerima URL HTTP/HTTPS, memvalidasi tujuan akhir sebelum memilih kredensial, dan tidak mengikuti pengalihan untuk permintaan penyedia atau penemuan. Konfigurasikan URL akhir secara langsung.

Memverifikasi Gateway Sebelum Aktivasi

Uji penemuan model dari mesin atau kontainer backend:

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

Uji operasi yang sesuai dengan mode API.

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

Setelah semua panggilan berfungsi, konfigurasikan rute, mode, kredensial, dan ID model yang sama dalam Provider connections. Aktifkan penyedia, pilih Refresh models, lalu pilih modelnya di Chat. Work juga dapat memakai model jika dukungan pemanggilan alatnya andal.

Pemecahan Masalah

Gejala	Pemeriksaan
Permintaan masih menuju endpoint terbundel	Hapus penimpaan endpoint lama, simpan Base URL dan API Path yang benar.
Penyedia menerima payload salah	Cocokkan API Mode dengan protokol dan periksa akhiran.
Refresh models tidak memberi ID	Uji /models, bentuk data[].id, models_endpoint, atau model_map.
Model lama tersisa setelah rute diubah	Simpan perubahan; katalog lama dibersihkan.
Kunci API dilaporkan hilang	Simpan kredensial per pengguna; cadangan lingkungan tidak mengikuti penimpaan.
Docker tidak mencapai localhost	Gunakan nama layanan, alias host, atau alamat privat.
Chat bekerja, gambar tidak	Konfigurasikan image_endpoint terpisah.
Chat bekerja, Work menolak model	Pastikan model mendukung pemanggilan alat.
Penyedia mengalihkan	Konfigurasikan URL akhir; pengalihan tidak diikuti.

Untuk perutean dan kredensial, baca Plugin. Untuk kegagalan penerapan, lihat Pemecahan Masalah.

Pengakuan Komunitas

Panduan dan pengalaman Provider connections Libre WebUI 0.16.0 dibentuk oleh ZhengJin (@fangzhengjin), yang umpan balik penyedia pihak ketiga dan konsep UX berbantuan AI dalam #163 membantu menentukan alur kerja ini.

Dokumentasi Terkait

• Plugin
• Bekerja dengan Model
• MLX LM di Apple Silicon
• Work: Ruang Kerja Terisolasi
• Pemecahan Masalah