Vector DB
Fitur Vector Database (Vector DB) menyediakan pencarian semantik di seluruh basis pengetahuan organisasi Anda. Ini memungkinkan AI agent dan pengalaman chat mengambil potongan konten bertag yang relevan sehingga jawaban tetap merujuk pada dokumen internal.
Gambaran Umum
Vector DB memungkinkan Anda:
- Mengindeks entri teks terkurasi atau lampiran untuk pencarian semantik
- Menambahkan tag terstruktur agar pencarian dapat difilter ke subset tertentu
- Mendefinisikan scope pencarian reusable yang terkait dengan aplikasi atau audiens tertentu
- Menyambungkan pengambilan pengetahuan ke AI agent dan alur chat hanya dengan beberapa pengaturan
- Memantau kesehatan dan konfigurasi koleksi langsung dari platform
VectorDB Settings
Konfigurasi dijalankan melalui satu dokumen pengaturan ditambah flag level situs seperti tmvectordbenabled dan tmvectordbip. Vector DB hanya aktif ketika konfigurasi situs dan DocType ini sama-sama diaktifkan.
Field Konfigurasi
| Field | Deskripsi |
|---|---|
| Enabled | Saklar utama fitur; validasi gagal jika instance belum dikonfigurasi penuh |
| Chunk Size | Jumlah karakter per chunk ketika membagi konten untuk embedding; harus bilangan bulat positif (default 500) |
| Collection ID | Identifier otomatis (diawali kb-) untuk koleksi; dibuat saat pertama kali menyimpan setelah diaktifkan |
| Tags | Tabel tag metadata yang diizinkan; menggabungkan baris sistem dengan definisi kustom |
Visibilitas Koleksi
Setelah koleksi ada, form pengaturan menampilkan tombol “View Collection” yang membuka dialog dengan metrik langsung (status, ukuran vektor, jumlah shard, statistik penggunaan, dan parameter yang bisa diubah). Admin dapat menyesuaikan replika atau pengaturan optimizer dari dialog ini tanpa keluar aplikasi.
Konfigurasi Tag
Tabel tag menegakkan aturan berikut:
- Tag sistem (Role, User, Application, DocType, Document, Category, Env) selalu ada, hanya baca, dan otomatis dikembalikan bila diubah.
- Tag kustom memerlukan nama unik dan tipe yang dipilih dari
string,bool,int64, ataufloat32. - Baris systemgenerated terkunci; baris buatan pengguna bebas ditambah atau dihapus.
VectorDB Document
Setiap dokumen merepresentasikan item pencarian yang kontennya di-chunk, di-embed, lalu disinkronkan ke layanan Vector DB.
Field Dokumen
| Field | Deskripsi |
|---|---|
| Title | Nama tampilan di hasil pencarian; tidak bisa diubah setelah diset |
| Type | Pilih Text untuk konten editor atau Attachment untuk file upload |
| Status | Indikator siklus hidup (Pending, Syncing, Synced, Error) yang dikelola job sinkronisasi |
| Text Content | Field rich-text, wajib hanya saat Type = Text |
| Attachment | Field file (set-once) untuk Type = Attachment; dibatasi ≤50 MB dan format .txt, .pdf, .docx, .pptx, .md |
| Tags | Tabel child (tagname, tagvalue) sesuai daftar tag; tidak boleh duplikat |
| Document Tags | Teks hanya baca yang digenerate dari nilai tag untuk filter cepat; jangan diedit manual |
| Reference DocType / Document | Field tersembunyi untuk koneksi dokumen sumber |
| System Generated | Flag tersembunyi menandakan pembuatan otomatis |
| Last Synced / Error Message | Metadata sinkronisasi yang diisi job background |
| Chunk Details | Tabel hanya baca yang mencatat indeks chunk dan payload ID dari koleksi |
Aturan Validasi
- Lampiran tidak dapat diubah setelah dokumen dibuat; edit teks atau tag lalu jalankan resync.
- Nilai tag dikonversi/divalidasi sesuai tipe (boolean menerima string true/false, integer mengonversi “5.0”, dll.).
- Menghapus definisi tag dari pengaturan otomatis menghapus tag tersebut dari semua dokumen dan memperbarui user tag.
Alur Status Dokumen
- Pending: Dibuat namun belum masuk antrian
- Syncing: Sedang diproses (chunking/embedding/upsert)
- Synced: Semua chunk tersimpan
- Error: Sinkronisasi gagal; lihat Error Message
Manajemen Dokumen
Membuat Dokumen
- Buka daftar VectorDB Document dan klik “Add”
- Isi title dan pilih Text atau Attachment
- Tambahkan konten (atau upload file sekali saja)
- Isi baris tag sesuai kebutuhan; setiap baris adalah pasangan
{"tagname": "...", "tagvalue": "..."} - Simpan untuk memasukkan ke antrean sinkronisasi
Operasi Massal: Gunakan utilitas import/export standar. VectorDB Admin boleh mengimpor; VectorDB User tidak.
VectorDB Search Scope
Scope menangkap filter reusable dan limit query agar agent/chat tetap dalam domain aplikasi.
Konfigurasi Scope
| Field | Deskripsi |
|---|---|
| Name | Identifier unik; disimpan sebagai nama dokumen |
| Application | Link wajib ke aplikasi pemilik untuk pengelompokan dan perizinan |
| Active | Sakelar untuk mengaktifkan atau menonaktifkan tanpa menghapus scope |
| Filter (JSON) | Payload JSON opsional yang menjelaskan kriteria match/range di field tag; masukkan hanya isi objek filter (tanpa key "filter") |
| Limit | Jumlah maksimum hasil per query (default 10) |
| Score Threshold | Batas kemiripan (isi ≤0 atau kosong untuk menonaktifkan; default 0,15) |
Parameter Pencarian
Jika scope dipakai, nilai Limit dan Score Threshold menggantikan default, dan Filter JSON dikirim langsung ke permintaan pencarian. Tidak ada parameter tambahan seperti reranking atau dense weight.
Contoh Filter
Di form, masukkan isi JSON filter persis seperti pada referensi resmi filtering. Platform otomatis membungkusnya sebagai "filter": {...} saat mengeksekusi query.
Filter boolean (payload eksplisit)
{ "must": [ {"key": "Department", "match": {"any": ["hr", "finance"]}}, {"key": "Year", "range": {"gte": 2021, "lte": 2024}}, {"key": "Confidential", "match": {"value": false}} ] }Shorthand (dikonversi otomatis)
{ "Department": ["hr", "finance"], "Region": "north", "Priority": {"range": {"gte": 1, "lte": 5}} }Integrasi dengan Sistem AI
Integrasi AI Agent
- Edit TM AI Agent
- Aktifkan “Use Vector DB” (field muncul hanya jika Vector DB aktif)
- Pilih Search Scope bila ingin membatasi pengetahuan
- Simpan dan uji; eksekusi otomatis memanggil
aisearchknowledge
Integrasi AI Chat
- Di TM AI Chat Agent, aktifkan “Use Vector DB”
- Pilih Search Scope (opsional untuk pencarian global)
- Simpan; setiap percakapan akan menambahkan hasil pencarian ke konteks agent
Perilaku Pencarian
Pencarian Semantik
- Query di-embed menggunakan model yang sama seperti dokumen dan dibandingkan dengan cosine similarity
- Score Threshold (jika diset) menyaring hasil bernilai rendah; jika tidak, seluruh top-k dikembalikan
- Jumlah hasil = limit yang didefinisikan scope atau default 10
Peringkat Hasil
- Embed query dan pastikan kompatibel dengan koleksi
- Eksekusi pencarian kemiripan tunggal dengan filter/threshold opsional
- Kembalikan chunk berurutan dari skor tertinggi (tidak ada langkah reranking)
Perizinan
Peran VectorDB Admin
- Membuat/mengimpor/memperbarui/menghapus VectorDB Document
- Mengelola VectorDB Search Scope dan pengaturan global (termasuk dialog koleksi)
- Akses baca/tulis penuh ke semua DocType Vector DB
Peran VectorDB User
- Membuat dan mengedit semua VectorDB Document, namun tidak bisa menghapus atau mengimpor
- Akses baca saja ke VectorDB Search Scope
- Tidak memiliki akses ke VectorDB Settings
Praktik Terbaik
Manajemen Dokumen
- Judul Jelas: Gunakan nama singkat namun deskriptif agar jawaban agent lebih baik
- Pentag Konsisten: Selaraskan nama/nilai tag dengan skema di pengaturan
- Pembaruan Bertahap: Edit konten teks atau tag untuk memicu sinkronisasi delta ketimbang upload ulang file
- Monitor Error: Periksa field errormessage jika dokumen tetap “Error”
Optimasi Pencarian
- Granularitas Scope: Buat scope terpisah per departemen atau lini produk agar filter lebih efisien
- Penyesuaian Threshold: Naikkan threshold untuk jawaban presisi; turunkan untuk eksplorasi
- Kebersihan Tag: Standarkan nilai tag (mis. huruf kecil) agar filter konsisten
Pertimbangan Kinerja
- Ukuran Dokumen: Pecah dokumen sangat panjang agar jumlah chunk terkendali
- Import Massal: Gunakan import data untuk backfill besar; pantau antrean job
- Scope Filter: Gunakan filter scope ketimbang filter di sisi klien agar database bekerja lebih ringan
Penanganan Masalah
Dokumen macet di “Pending”
- Pastikan Vector DB aktif di konfigurasi situs dan pengaturan
- Cek log job background untuk error sinkronisasi
Dokumen macet di “Error”
- Periksa errormessage untuk detail validasi/payload
- Pastikan lampiran memenuhi syarat ukuran/format
Hasil pencarian buruk
- Turunkan threshold atau naikkan limit untuk menambah kandidat
- Tinjau distribusi tag agar filter tidak menyingkirkan konten penting
Search scope tidak berfungsi
- Pastikan scope berstatus Active dan JSON valid
- Verifikasi Application sesuai dengan kebutuhan agent/chat
Integrasi tidak menemukan knowledge
- Pastikan “Use Vector DB” aktif di konfigurasi agent/chat
- Uji query yang sama lewat API server script untuk memisahkan masalah prompt
Penggunaan API
# Pencarian dasar results = mantera.aisearchknowledge("pricing policy")
Dengan search scope
results = mantera.aisearchknowledge(
query="vacation policy",
searchscope="HR"
)
Dengan konteks percakapan (messages divalidasi tapi tidak di-rewrite)
results = mantera.aisearchknowledge(
query="follow-up question",
messages=[
{"role": "user", "content": "previous question"},
{"role": "assistant", "content": "previous answer"}
]
)
Konfigurasi Lanjutan
Manajemen Chunk
- Chunk Size: Atur di pengaturan untuk menyeimbangkan recall (chunk kecil) vs konteks (chunk besar)
- Chunk Details: Gunakan tabel hanya baca pada tiap dokumen untuk melihat pembagian konten
Filter Kustom
- Manfaatkan kombinasi klausa
matchdanrangeuntuk penargetan presisi - Gunakan tag boolean untuk filter on/off (mis. Confidential)
- Rujuk tag sistem seperti Application atau Role agar hasil otomatis terbatasi