Knowledge Gateway

Knowledge gateway memungkinkan agent mencari di knowledge base yang tetap berada di dalam jaringan Anda sendiri. Contohnya vector database, mesin pencari intranet, atau penyimpanan dokumen yang tidak boleh disalin ke cloud dan tidak boleh dibuka ke internet.

Anda menjalankan program kecil, Qlar Knowledge Gateway, di sebuah server di jaringan Anda. Program ini membuka koneksi keluar ke Qlar dan tidak pernah membuka port inbound. Saat agent mencari, Qlar menyerahkan pencarian itu ke gateway Anda. Gateway lalu memanggil layanan pencarian milik Anda dengan request HTTP sederhana dan mengirim hasilnya kembali.

Knowledge gateway adalah salah satu dari tiga jenis provider Knowledge Eksternal, di samping Search API agent lain dan REST API.

Cara kerjanya

Agent (Qlar) ──▶ Qlar Knowledge Hub ──▶ Knowledge Gateway (server Anda) ──▶ layanan pencarian Anda (webhook)
                       ▲                  hanya koneksi keluar                 POST {query, permissions, limit}
                       └────────────────── hasil ◀────────────────────────────────────────┘

1. Selama percakapan, agent memutuskan bahwa sebuah pertanyaan berkaitan dengan cakupan provider ini, lalu mencari di sana.
2. Qlar mengirim kata pencarian, kode permission provider, dan jumlah hasil pencariannya ke Qlar Knowledge Hub.
3. Hub meneruskan pencarian ke gateway Anda melalui koneksi yang dibuka oleh gateway.
4. Gateway memanggil layanan pencarian Anda (webhook) di alamat yang dikonfigurasi pada gateway, lalu mengembalikan jawabannya.
5. Agent menjawab dari hasil itu, sama seperti dengan provider lain: rerank, sitasi, dan permission bekerja dengan cara yang sama.

Layanan pencarian adalah milik Anda dan Anda yang membangunnya. Layanan itu bisa berada di depan knowledge base apa pun. Syaratnya hanya satu: menjawab satu panggilan HTTP yang dijelaskan di bagian Webhook di bawah.

Yang tetap berada di server Anda

• Alamat layanan pencarian dan key-nya. Anda mengonfigurasinya di gateway itu sendiri. Qlar hanya melihat host-nya (misalnya http://kb.internal:8080) dan apakah pencarian terakhir berhasil. Tidak ada orang di Qlar yang bisa mengarahkan gateway Anda ke alamat lain.
• Key identitas gateway. Key ini dibuat di server dan tidak pernah keluar dari server itu.
• Log setiap pencarian di folder log/ milik gateway: pertanyaan, permission, hasil akhir, jumlah hasil, dan waktunya. Isi hasilnya sendiri tidak pernah ditulis ke log.

Sebelum mulai

• Server atau PC di jaringan Anda yang bisa menjangkau layanan pencarian dan membuat koneksi HTTPS keluar ke Qlar. Sistem yang didukung:
  • Windows x64
  • Linux x64 atau arm64
  • macOS dengan Apple silicon
• Layanan pencarian yang mengikuti kontrak webhook. Untuk mencoba dulu, Anda bisa memakai contoh layanan di repository qlar-knowledge-gateway (samples/FakeKnowledgeBase).
• Hak untuk mengelola knowledge agent: contributor agent, serta Owner dan Admin organisasi.

Menghubungkan gateway

1. Di CMS, buka Knowledge → External, lalu pilih Add provider.

2. Pilih Knowledge gateway, lalu Continue.

3. Isi Name, What information to look up here, Permissions, dan Search results (lihat Kolom bersama). Pilih Server operating system.

4. Pilih Connect gateway. Qlar menampilkan perintah install satu baris yang berisi kode sekali pakai. Kode ini berlaku 15 menit.

5. Jalankan perintah itu di server Anda:

   # Windows (PowerShell 5.1 atau 7)
   & ([scriptblock]::Create((irm 'https://<hub>/install.ps1'))) -Code 'XXXX-XXXX-XXXX' -Force
   

   # Linux / macOS
   curl -fsSL 'https://<hub>/install.sh' | sh -s -- --code 'XXXX-XXXX-XXXX' --force
   

   Script ini mengunduh gateway, memeriksa checksum SHA-256-nya, menginstalnya untuk user saat ini, lalu mendaftarkannya (enrol). Di terminal, script menanyakan alamat dan key layanan pencarian Anda (lihat Mengonfigurasi layanan pencarian). Setelah itu script mencetak fingerprint sebanyak empat baris.

6. Kembali ke CMS. Provider menampilkan A server has enrolled. Confirm it is yours. beserta sebuah fingerprint. Bandingkan dengan fingerprint di terminal Anda. Jika sama persis, pilih It matches, approve.

7. Biarkan perintah tetap berjalan. Gateway mulai melayani begitu disetujui, dan provider menampilkan Connected beserta host layanan pencarian Anda.

8. Gunakan Run test di bagian Test provider untuk mencoba pertanyaan sungguhan.

Pemeriksaan fingerprint inilah yang membuat kode yang bocor tidak berguna. Jika fingerprint di CMS berbeda dengan yang di terminal, berarti orang lain memakai kode Anda. Jangan menyetujuinya; pilih It differs, get a new code.

Tetap berjalan setelah logout dan reboot

Mengonfigurasi layanan pencarian

Alamat dan key layanan pencarian diatur di gateway, bukan di Qlar:

qlar-knowledge-gateway configure endpoint --url http://kb.internal:8080/search --auth x-api-key
qlar-knowledge-gateway test "Berapa hari cuti tahunan saya?"

• --auth none|x-api-key|bearer menentukan cara key dikirim:
  • x-api-key mengirim X-Api-Key: <key>.
  • bearer mengirim Authorization: Bearer <key>.
• Key diketik tersembunyi dan disimpan terenkripsi di server. Bila memungkinkan, gateway memakai penyimpanan key milik sistem: Windows DPAPI, macOS Keychain, atau systemd-creds atau keyring desktop di Linux. Key juga bisa dibaca dari environment variable dengan --api-key-env NAMA.
• http:// biasa dan alamat privat diperbolehkan, karena layanan itu berada di jaringan Anda sendiri. Untuk sertifikat self-signed, tambahkan --insecure-skip-tls-verify.
• test menjalankan satu pencarian tanpa melalui Qlar, sehingga Anda bisa memeriksa layanannya secara terpisah.
• Gateway yang sedang berjalan memakai konfigurasi baru dalam 30 detik.

Webhook

Untuk setiap pencarian, gateway mengirim:

POST {layanan pencarian Anda}
Content-Type: application/json
X-Api-Key: {key}                   (atau Authorization: Bearer {key}, atau tanpa key)
X-Qlar-Agent-Id: {id agent}
X-Qlar-Conversation-Id: {id percakapan}
X-Qlar-Request-Id: {id korelasi}

{ "query": "Berapa hari cuti tahunan saya?", "permissions": ["HR"], "limit": 5 }

Layanan Anda menjawab:

{
  "results": [
    {
      "title": "Kebijakan cuti karyawan",
      "section": "Cuti tahunan",
      "text": "Karyawan tetap mendapat 15 hari cuti tahunan per tahun...",
      "chunkCode": "HR-007-1",
      "contentId": "HR-007",
      "distance": 0.18
    }
  ]
}

• Field request:
  • query: maksimal 1.000 karakter.
  • permissions: maksimal 50 kode. Kembalikan hanya dokumen yang boleh dilihat oleh kode-kode itu; tanpa kode, kembalikan hanya dokumen publik.
  • limit: 1 sampai 20.
• Field response: di setiap hasil hanya text yang wajib. title dan section muncul di sitasi. Field lain diabaikan.
• Batas: jawaban harus lebih kecil dari 1 MB dan tiba dalam 10 detik. Usahakan di bawah 2 detik, karena pengguna sedang menunggu di chat. Redirect tidak diikuti.
• Error: jawab dengan status non-2xx, boleh disertai { "code": "...", "message": "..." }. Status 401 atau 403 dilaporkan sebagai key yang ditolak.

Kontrak ini sama dengan provider REST API, jadi satu layanan bisa melayani keduanya.

Log di gateway

Gateway menulis log ke folder log/ di direktori state-nya. Folder lain bisa dipilih dengan --log-dir.

Direktori state:

qlar-knowledge-gateway status menampilkan lokasi log, apakah gateway terhubung, dan layanan pencarian mana yang dipanggilnya.

Status di CMS

Untuk memindahkan gateway ke server lain, buka provider dan pilih Move to another server. Anda mendapat kode baru, dan fingerprint server baru harus disetujui. Provider, pengaturannya, dan riwayatnya tetap sama.

Menghapus provider memutus gateway. Program di server Anda berhenti dan tidak menyala lagi. Uninstall di server dengan qlar-knowledge-gateway uninstall-service, lalu hapus file-filenya.

Biaya

Setiap pencarian yang berhasil melalui knowledge gateway dikenai 1 credit, ditagihkan ke organisasi agent Anda. Pencarian yang gagal (gateway offline, layanan pencarian tidak terjangkau, timeout) tidak ditagih. Jika reranker agent aktif, rerank ditagih sama seperti untuk knowledge milik agent sendiri.

Pemecahan masalah

Halaman terkait

• Knowledge Eksternal
• Referensi layar Knowledge Eksternal
• On-Premise Data Gateway: ide yang sama, untuk database SQL.