Sumber Pengetahuan (Knowledge Sources)
1. Ikhtisar & Nilai Bisnis
Fitur Knowledge Sources merupakan lapisan krusial dalam arsitektur AI DagangBot, yang berfungsi sebagai gerbang utama untuk penyerapan informasi eksklusif milik setiap merchant. Kualitas respons chatbot AI bergantung mutlak pada kualitas dan keberagaman referensi informasi yang Anda sediakan. Melalui modul ini, sistem akan mengonsolidasikan beragam dokumen mentah (seperti panduan produk, kebijakan pengembalian barang, atau FAQ) dan mengubahnya menjadi format matematis yang dapat dipahami oleh mesin Retrieval-Augmented Generation (RAG).
Secara fundamental, sistem ini mengatasi masalah "halusinasi AI" (kondisi di mana model bahasa menghasilkan informasi yang tidak berdasar atau salah) dengan cara memaksa Large Language Model (LLM) untuk mendasarkan seluruh jawabannya pada dokumen yang telah Anda unggah. Nilai bisnis utama dari pendekatan ini adalah kemampuan untuk mendelegasikan pertanyaan spesifik pelanggan kepada bot tanpa kekhawatiran bahwa bot akan memberikan instruksi operasional yang menyesatkan. Hal ini secara langsung mengurangi beban kerja tim Customer Service manusia, meningkatkan kecepatan respons, dan menjaga konsistensi merek.
Dari perspektif teknis, dokumen yang diunggah akan diekstraksi teksnya, dipecah menjadi potongan kecil (chunk), dan
dikonversi menjadi representasi vektor numerik (embedding). Kami mengimplementasikan penyimpanan vektor berbasis
ekstensi pgvector di PostgreSQL. Untuk memastikan skalabilitas dan fleksibilitas tanpa perlu melakukan migrasi skema secara terus-menerus, sistem mendefinisikan modul representasi vektor terpadu dengan tipe data presisi tinggi yang fleksibel. Pemilihan tipe halfvec (16-bit float) sangat penting karena indeks Hierarchical Navigable Small World (HNSW) pada pgvector membatasi tipe full-precision maksimal pada 2000 dimensi, sementara halfvec mengizinkan hingga 4000 dimensi, sehingga mengakomodasi vektor semantik secara optimal.
Setiap penyewa (tenant) dilindungi oleh isolasi data melalui Row-Level Security (RLS) di lapisan basis data, yang menjamin bahwa dokumen knowledge base dari satu merchant tidak akan pernah bocor atau menjadi basis referensi untuk respons pada merchant lainnya. Seluruh proses penyerapan data berjalan secara asinkron (berjalan di latar belakang) menggunakan queue worker, yang menjamin ketersediaan tinggi (high availability) API di sisi frontend saat terjadi lonjakan unggahan dokumen.
2. Alur Visual & Antarmuka
Pengalaman pengguna dalam mengelola Knowledge Sources dirancang untuk meminimalkan kompleksitas teknis dari mesin analitik teks di belakangnya. Antarmuka utama terbagi menjadi beberapa komponen visual yang secara intuitif merepresentasikan siklus hidup sebuah dokumen.

Dashboard Utama Knowledge Base Halaman ini menampilkan seluruh dokumen yang pernah diunggah oleh merchant. Terdapat tabel manajemen dengan kolom yang menunjukkan nama file, ukuran file, jumlah token yang berhasil diekstraksi, waktu unggah, dan status. Sistem manajemen state dokumen mencakup beberapa tahapan indikator visual:
- Pending: Dokumen telah berhasil disimpan ke storage dan entri database telah dibuat, antrean tugas (job) sudah masuk ke dalam broker pesan, namun worker belum memulai proses penyerapan.
- Processing: Dokumen sedang diproses, diekstraksi teks mentahnya, dan sedang berkomunikasi dengan penyedia LLM untuk diubah menjadi vektor.
- Ready/Aktif: Seluruh chunk vektor telah berhasil disimpan dan siap diretriksi oleh mesin RAG.
- Failed: Terjadi kegagalan dalam tahapan processing, baik karena batas kuota, batas ukuran batas waktu model embedding, atau dokumen yang diunggah ternyata kosong (tidak ada teks terbaca).

RAG Sandbox & Playground Kami menyediakan fasilitas simulasi (Sandbox) di mana operator dapat melakukan kueri pencarian teks langsung dan melihat bagaimana algoritma pencarian kemiripan (cosine similarity) mengembalikan blok chunk teks yang paling relevan sebelum diserahkan ke prompt LLM. Ini membantu merchant melakukan fine-tuning atau format ulang atas dokumen mereka apabila hasil yang dikembalikan RAG kurang akurat:

3. Panduan Langkah-demi-Langkah
Proses menambahkan pengetahuan baru ke dalam otak AI Anda membutuhkan beberapa tahapan berurutan. Panduan ini menjelaskan operasi di balik layar (bagaimana API bekerja) bersamaan dengan langkah operasionalnya.
- 1
Persiapan dan Format Dokumen
Pastikan dokumen yang akan Anda unggah memiliki struktur teks yang jelas. Mesin parsing bekerja paling efisien jika dokumen memiliki hierarki header yang terstruktur. Jika mengunggah CSV, pastikan baris pertama berisi header yang mendefinisikan masing-masing kolom dengan jelas, sehingga model AI dapat memahami konteks nilai pada baris di bawahnya.
- 2
Estimasi Kuota dan Token (API Estimate)
Sebelum memproses pengunggahan fisik file, platform melakukan penghitungan kasarnya melalui fungsi
EstimateTokens. Fungsi ini menggunakan heuristik pembagian panjang karakter untuk mengukur token (secara matematis,(len([]rune(strings.TrimSpace(text))) + 3) / 4). Hal ini penting karena operasi konversi ke vektor akan memotong saldo koin merchant. FungsicheckQuotadipanggil untuk memverifikasi apakah saldo merchant saat ini memadai untuk menutupi proyeksi pemotongan dari besaran token yang ada di dokumen. Jika kuota tidak mencukupi, unggahan dibatalkan bahkan sebelum diproses oleh worker. - 3
Pengunggahan File Melalui KB Handler
File dikirim melalui permintaan
multipart/form-datakeKBHandler.Upload. Di lapisan ini, backend segera melakukan validasi jenis ekstensi file terhadap daftar ekstensi file yang diizinkan, serta mengecek batasan maksimal bytes memori. Sistem tidak langsung memecah teks pada tahap unggah ini; sebaliknya, sistem menyimpannya di cloud storage (seperti AWS S3), membuat rekam jejakkb_documentsdengan statuspending, lalu mengirimkan beban kerja berupaEmbedDocumentPayloadke dalam sistem queue asinkron. - 4
Proses Asinkron (Embed Worker)
Pekerjaan latar belakang diambil oleh pekerja antrean pemrosesan dokumen (Embed Worker). Alur teknis di dalam worker meliputi:
- Mengunduh file secara fisik dari storage (Signed URL).
- Mengekstraksi teks menggunakan parser (seperti pengenalan karakter optik untuk gambar di dalam PDF, atau membaca XML pada DOCX).
- Melakukan pemotongan teks (chunking) berbasis parameter konfigurasi panjang chunk dan tumpang-tindih (overlap). Pemotongan ini penting agar tidak melewati context window LLM saat sesi RAG nanti.
- Jika di tahap ini didapati file gagal diekstraksi, fungsi
markNoTextataumarkFailedakan mencatatkan pesan error ke baris dokumen. - Mengecek ulang kecukupan balance kuota menggunakan fungsi pencegahan
markInsufficientBalance. Jika kuota lolos, pemanggilan jaringan (network call) ke model pihak ketiga dieksekusi secara terpisah.
- 5
Homogenisasi Dimensi Vektor (Zero-Padding)
Tahap ini merupakan aspek penting dalam standardisasi vektor semantik. Karena lebar kolom indeks basis data telah ditetapkan berkapasitas dimensi standar (3072 sumbu representasi), maka seluruh luaran embedding diselaraskan ke format tersebut. Apabila arsitektur model menghasilkan dimensi lebih rendah (misalnya 1024 atau 1536 sumbu), sistem secara otomatis menerapkan penyelarasan (zero-padding) hingga mencapai panjang dimensi standar. Modifikasi matematis ini tidak mengubah kalkulasi jarak sudut (cosine distance) dan menjamin keseragaman pencarian.
- 6
Penulisan Akhir dan Pembaruan Status
Setelah vektor berdimensi standar lengkap, seluruh data disisipkan dalam satu operasi transaksi (ACID) ke dalam penyimpanan vektor pangkalan data. Setelah berhasil diverifikasi, status dokumen diperbarui menjadi aktif (ready), dan penggunaan kuota komputasi dicatat secara permanen.
4. Konfigurasi & Parameter
Pengalaman Knowledge Sources sangat bergantung pada rangkaian variabel penyetelan yang dikontrol melalui konfigurasi platform. Parameter-parameter ini dapat disesuaikan per tingkat merchant jika penyewa menginginkan performa RAG yang spesifik. Di bawah ini adalah rincian fungsional dan teknis parameter utamanya:
-
rag.top_k(Default: 5) Menentukan batas maksimum kuantitas keping dokumen (chunks) teratas yang akan diambil dalam satu kali eksekusi pencarian vektor. Jika nilai ini terlalu kecil, chatbot mungkin kekurangan konteks; jika terlalu besar, dapat membengkakkan konsumsi token prompt LLM. -
rag.chunk_size_tokens(Default: 600) Menentukan batas proyektif jumlah token dalam satu kepingan teks saat parser membelah dokumen. Nilai 600 secara empiris optimal karena memastikan satu keping mewakili satu paragraf hingga dua paragraf penuh konseptual, cukup panjang untuk mempertahankan konteks independen tanpa memasukkan informasi sampah yang tidak relevan. -
rag.chunk_overlap_tokens(Default: 100) Menentukan ukuran token yang menduplikasi (beririsan) antara bagian akhir kepingan sebelum dengan kepingan sesudahnya. Ini mencegah kalimat penting terpotong di tengah jalan secara canggung, sehingga algoritma HNSW tetap dapat melacak kontinuitas kata antar keping. -
kb.max_upload_size_mb(Default: 10) Membatasi limit ukuran file statis yang dikirim merchant melalui jaringan ke server pada satu waktu. Nilai bawaan di tingkat platform global ditetapkan sebesar 10 Megabyte demi perlindungan serangan pengurasan bandwidth. -
kb.allowed_file_types(Default:["pdf", "docx", "txt", "csv"]) Daftar ekstensi file yang dapat diterima oleh penyaring filter prapemrosesan padaKBHandler. Selain keempat daftar ini, file akan segera ditolak (rejected). -
bot_configs.cosine_threshold(Default: 0.75) Ambang batas batas kemiripan (similarity threshold). Karena pencarian pgvector menggunakan operator kemiripan kosinus (vector_cosine_opsatauhalfvec_cosine_ops), jika skor kosinus di antara kueri pengguna dan chunk dokumen berada di bawah angka 0.75, chunk tersebut dieliminasi karena dianggap informasinya tidak cukup relevan untuk menjawab kueri pelanggan.
5. Penanganan Masalah
Selama siklus operasional penggunaan fitur ini, pengelola bot sering kali akan menemui beberapa hambatan yang diindikasikan melalui pesan status error atau tanggapan bot yang kurang presisi. Berikut adalah panduan mitigasi dan penyelesaian untuk setiap skenario permasalahan operasional yang paling dominan:
-
Dokumen Selalu Macet Pada Status Pending Jika sebuah file PDF masuk dalam status Pending secara terus menerus selama lebih dari 30 menit, ini biasanya mengindikasikan masalah pada ketersediaan koneksi worker node. Operator sistem di balik layar (sysadmin) wajib memeriksa apakah layanan
embed_workermasih beroperasi (health check), dan memvalidasi saluran pesan (seperti RabbitMQ atau Redis Queue) apakah antrean tersumbat akibat file dokumen raksasa sebelumnya (head-of-line blocking). Sebagai langkah penyelesaian bagi merchant, Anda dapat menekan tombolCoba Lagidi antarmuka agar beban pemrosesan ditambahkan ulang ke antrean. -
Kegagalan Ekstraksi Teks (No Text Extracted Error) Sering kali pengguna mengunggah dokumen berbentuk PDF hasil proses pemindaian fisik (scanned file), sehingga seluruh konten aslinya hanyalah blok gambar statis alih-alih set karakter sejati (string data). Ketika worker menjalankan perintah
parseContent, total karakter yang didapat menjadi 0. Sistem merespons ini dengan memanggilmarkNoText. Solusinya, pengguna harus menggunakan perangkat lunak Optical Character Recognition (OCR) eksternal untuk melahirkan layer teks pada PDF tersebut atau mengetik ulang panduannya pada dokumen teks standar (Word / TXT) sebelum mengunggah. -
Limitasi Kuota Koin / Saldo Tidak Mencukupi Sistem arsitektur AI kami mengimplementasikan model pay-as-you-go berlandaskan konsumsi token vektor. Jika pemanggilan pencegah defisit
checkQuotaTxmendeklarasikan kegagalan danmarkInsufficientBalanceterekam, proses pemotongan (chunking) dan komunikasi dengan LLM embedding dibekukan seketika untuk menghindarkan merchant dari jeratan penagihan overage. Merchant harus masuk ke halaman manajemen tagihan, mengisi ulang dompet saldo mereka, kemudian menekan tombol ulang (Retry) pada rekaman dokumen terkait. -
Kualitas Jawaban Bot (RAG) Terasa Kacau Meski File Sudah Aktif Jika sebuah file sukses diproses (status berubah menjadi Ready), namun bot tetap berhalusinasi atau memberikan balasan yang meraba-raba (tidak merujuk kepada sumber akurat), hal ini mengindikasikan letak permasalahan bukan pada tahapan perolehan (ingestion), melainkan tahapan retrival (pencarian vektor kosinus). Cara memperbaiki retrival yang paling mudah adalah dengan merevisi struktur paragraf file tersebut, mengatur ulang konstanta overlap token atau menurunkan tingkat
cosine_thresholdjika bahasanya menggunakan diksi teramat bebas. Pengguna juga dapat memeriksa fungsionalitas murni melalui antarmuka RAG Sandbox sebelum mengudara ke dalam percakapan nyata.
6. FAQ
Q: Mengapa Knowledge Base tidak mendukung secara native pengunggahan file spreadsheet berekstensi XLSX/XLS melainkan hanya CSV? A: Format XLSX membutuhkan overhead parsing struktur memori yang kompleks yang mengakibatkan tingkat pemotongan chunk menjadi kehilangan relasi spasial kolom dan barisnya (kehilangan makna). Ekstensi CSV memaksakan dokumen berada dalam satu sheet tunggal, direpresentasikan dalam bentuk barisan koma, yang memungkinkan model pembacaan teks baris demi baris lebih rapi, terhindar dari pemotongan token sel yang memutus keterkaitan objek.
Q: Bagaimana mekanisme sebenarnya dari indeks pencarian pgvector kami dan mengapa memilih halfvec ketimbang tipe
standar vector?
A: Platform kami di-deploy untuk mampu mencakup ribuan penyewa dengan pencarian latensi-rendah. Algoritma HNSW
(Hierarchical Navigable Small World) mengonstruksi graf multi-layer yang jauh lebih cepat daripada metrik indeks
IVFFlat. Namun, dokumentasi pgvector memaparkan bahwa indeks HNSW tipe standar (vector) hanya dapat menelan hingga
maksimum ukuran 2000 dimensi untuk tingkat presisi rasional. Dikarenakan aplikasi membutuhkan fleksibilitas mendukung representasi vektor berdimensi tinggi, tipe presisi 16-bit (halfvec) menjadi pilihan terbaik karena memperbesar rentang indeks graf semantik hingga batasan aman 4000 dimensi, menghasilkan performa prima, presisi kosinus terjaga ketat tanpa penurunan kualitas temu-balik (retrieval), dan menjamin stabilitas basis data secara permanen.
Q: Bisakah saya menautkan dan memasukkan isi website saya (Scraping/URL) secara otomatis, daripada mengunggah dokumen statis? A: Fitur tersebut sedang berada pada peta jalan perancangan platform kami di versi berikutnya, di mana Web Crawler Worker akan disematkan guna mengakuisisi halaman HTML publik dan meleburnya menjadi markdown sebelum ditransfer ke dalam ekosistem perakitan tokenisasi. Untuk sementara ini, semua situs web wajib dikonversikan ke mode format PDF lalu diunggah.
Q: Apakah aman jika dua penyewa mengunggah dokumen rahasia dengan isi identik? A: Sepenuhnya aman dan tak kasatmata. Penyelidikan RLS pada tabel menjabarkan operasi filter (FOR ALL USING merchant_id = current_setting). Semua vektor memiliki penanda kriptografi kepemilikan. Algoritma pencarian metrik vektor tak akan memindai atau membaca kedekatan jarak (distance computation) blok data dari tenant independen yang tidak setara kepemilikannya dengan pelaku pemanggilan (caller).
Q: Apakah terjadi perubahan biaya jika saya merevisi dokumen yang sama lalu mengunggah versi terbarunya?
A: Ya. Pengunggahan baru dianggap proses perhitungan embedding yang baru seutuhnya, API Embed Worker tidak melakukan
pembacaan diff atau penambahan delta dari dokumen prasejarah. Karenanya kalkulasi potongan koin sepenuhnya mengukur
jumlah volume token bersih yang ditransfer melalui saluran pengunggahan, Anda juga tidak akan dikenakan biaya apabila
menghapus (Delete) dokumen lama.
7. Referensi Terkait
Dasar Algoritma Vector Search
Analisis mendalam arsitektur algoritma pgvector, jarak kosinus, indeks HNSW, dan parameter threshold untuk retrieval RAG yang maksimal.
Pusat Notifikasi Bot
Pelajari alur manajemen peringatan dan notifikasi kegagalan latar belakang dari layanan webhook internal.
Model Perhitungan Token & Koin
Memahami transparansi potong harga dompet saat operasional embed_worker dan kalkulasi kuota teks estimasi.
Pengarahan Bot & Prompts
Cara mengoptimalkan perpaduan modul Knowledge Sources eksklusif ke dalam percakapan pelaporan instruksi bot chatbot AI.
