Panduan zhparser ServBay: Pencarian Teks Penuh Bahasa Mandarin

zhparser adalah modul ekstensi pihak ketiga untuk PostgreSQL yang sangat kuat, dirancang khusus untuk menangani teks Mandarin secara efisien. Ekstensi ini memberikan kemampuan segmentasi kata yang akurat serta pencarian teks penuh (full-text search) pada database PostgreSQL, menjadikannya pilihan ideal untuk membangun aplikasi yang membutuhkan pencarian konten dalam Bahasa Mandarin. Sebagai lingkungan pengembangan web lokal yang lengkap, ServBay telah memasukkan dan mendukung ekstensi zhparser secara bawaan, serta mengintegrasikan pustaka segmentasi kata scws (Simple Chinese Word Segmentation) yang dapat dimanfaatkan zhparser untuk fungsi custom dictionary (kamus khusus).

Panduan ini akan mengulas langkah-langkah instalasi (aktivasi), konfigurasi zhparser di ServBay, demonstrasi pencarian Mandarin, serta cara membuat dan menerapkan kamus khusus menggunakan scws yang sudah terintegrasi di ServBay.

1. Gambaran Umum

Pada aplikasi yang berisi banyak teks Mandarin—seperti sistem manajemen konten, forum, hingga platform e-commerce—implementasi pencarian teks penuh yang cepat dan akurat sangatlah penting. Fitur pencarian teks penuh bawaan PostgreSQL kurang cocok untuk Bahasa Mandarin karena biasanya berbasis pemisah spasi. Ekstensi zhparser memecahkan masalah ini dengan integrasi teknologi segmentasi kata Mandarin, sehingga PostgreSQL mampu mengenali batas kata dan melakukan pencarian teks penuh yang efektif dalam bahasa tersebut.

ServBay telah melakukan integrasi awal terhadap zhparser, menghilangkan kebutuhan kompilasi serta pemasangan manual, sehingga Anda bisa langsung membangun lingkungan pengembangan lokal yang mendukung full-text search Mandarin dengan praktis.

2. Prasyarat

Sebelum menggunakan zhparser, pastikan:

1. Anda telah menginstal ServBay dengan sukses.
2. Paket PostgreSQL di ServBay sudah diaktifkan dan dijalankan. Statusnya dapat dicek dan diatur melalui antarmuka aplikasi ServBay.

3. Instalasi (Aktivasi) Ekstensi zhparser

ServBay telah menempatkan file modul zhparser di lokasi yang dapat diakses PostgreSQL. Anda cukup mengaktifkannya di database target melalui perintah SQL.

1. Koneksi ke Database PostgreSQL Anda: Buka terminal dan hubungkan ke PostgreSQL ServBay dengan psql. Ganti servbay-demo dengan nama pengguna database Anda, dan your_database_name dengan nama database tempat Anda hendak mengaktifkan zhparser.

   psql -U servbay-demo -d your_database_name

   Jika Anda terhubung ke database default (biasanya sama dengan username), parameter -d dapat diabaikan.

2. Membuat Ekstensi zhparser: Di interface interaktif psql, jalankan SQL berikut:

   CREATE EXTENSION zhparser;

   Jika berhasil, tidak akan muncul pesan error. Jika sudah pernah diaktifkan, akan ada pemberitahuan ekstensi telah ada.

3. Verifikasi Instalasi zhparser: Lihat daftar ekstensi yang terpasang dengan:

   \dx

   Pastikan zhparser dan info versinya tampil di daftar.

4. Konfigurasi zhparser

Setelah diaktifkan, Anda harus mengatur konfigurasi pencarian teks PostgreSQL agar mengenali dan menggunakan zhparser untuk segmentasi Mandarin. Ini meliputi pembuatan konfigurasi Text Search.

1. Membuat Konfigurasi Text Search: Konfigurasi ini mendefinisikan cara dokumen diubah menjadi tsvector (format indeks), dan string kueri diubah ke tsquery (untuk pencarian). Buat konfigurasi bernama chinese dengan parser zhparser.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);

2. Menambahkan Mapping Kamus: Anda perlu menetapkan mapping dari tipe token (hasil parser) ke kamus tertentu. zhparser memberi label pada kata berdasarkan jenisnya (nomina/n, verba/v, adjektiva/a, dsb). Untuk tips penggunaan dasar, map label seperti nomina (n), verba (v), adjektiva (a), independent (i), emotion (e), numeral (l), ke kamus simple—tanpa modifikasi, kata dari parser zhparser akan dipertahankan.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
   -- Anda bisa tambah/ubah mapping label dan kamus sesuai kebutuhan.

   Catatan: Label tipe kata di zhparser bisa sedikit berbeda dari standar NLP — di atas adalah label umumnya.

5. Menggunakan zhparser untuk Full-Text Search

Setelah konfigurasi, Anda dapat mulai menggunakan zhparser untuk full-text search Mandarin. Berikut contoh langkah-langkahnya.

5.1 Membuat Tabel & Data Contoh

Buat tabel sederhana untuk penyimpanan teks Mandarin dan tambahkan beberapa data.

1. Buat Tabel:

   CREATE TABLE documents (
       id SERIAL PRIMARY KEY,
       content TEXT
   );

2. Masukkan Data Contoh:

   INSERT INTO documents (content) VALUES
   ('我爱自然语言处理'),
   ('中文分词是文本处理的重要步骤'),
   ('zhparser 是一个很好的中文分词工具'),
   ('ServBay 让本地开发更便捷');

5.2 Membuat Indeks Full-Text Search

Untuk performa maksimal, terutama pada dataset besar, sangat disarankan membuat indeks di kolom yang digunakan untuk pencarian full-text. Untuk tipe tsvector, gunakan indeks GIN (Generalized Inverted Index) yang sangat efisien untuk kueri pencarian teks.

1. Buat Indeks GIN: Buat indeks di kolom content dengan mengkonversi teks menjadi tsvector memakai konfigurasi chinese.

   CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));

5.3 Menjalankan Kueri Full-Text Search

Selanjutnya, gunakan to_tsquery untuk mengonversi kata kunci, dan operator @@ untuk pencocokan dengan tsvector.

1. Contoh Kueri Pencarian: Cari dokumen yang mengandung baik “中文” maupun “分词”:

   SELECT
       id,
       content,
       to_tsvector('chinese', content) AS content_tsvector -- Opsional: lihat hasil segmentasi
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Kueri di atas akan mengembalikan dokumen dengan id 2 dan 3 karena mengandung kedua kata tersebut.

   Coba juga pencarian lain:

   • Cari dokumen dengan “ServBay”:

     SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay');

     (akan mengembalikan dokumen id 4)
   • Cari dokumen dengan “自然语言处理”:

     SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '自然语言处理');

     (akan mengembalikan dokumen id 1. Perhatikan bahwa segmentasi untuk frasa ini dapat bervariasi tergantung mode segmentasi dan kamus—custom dictionary ikut membantu.)

6. Membuat Kamus Khusus dengan scws di ServBay

ServBay sudah terintegrasi dengan pustaka scws. Anda dapat mengatur zhparser agar menggunakan file kamus scws, termasuk kamus khusus untuk meningkatkan akurasi segmentasi, terutama pada istilah baru atau khusus bidang tertentu.

6.1 Membuat File Kamus Khusus

1. Buat atau Edit File Kamus Khusus: Direkomendasikan menyimpan kamus scws di /Applications/ServBay/etc/scws/. Buat file bernama custom_dict.txt (jika belum ada).

   # Buat atau edit file via terminal
   nano /Applications/ServBay/etc/scws/custom_dict.txt

2. Tambahkan Kata ke File: Di custom_dict.txt, tambahkan satu kata/frasa per baris yang ingin diakui sebagai satuan kata oleh zhparser. Contoh:

   自然语言处理
   中文分词
   ServBay
   本地开发环境

   Simpan dan tutup file.

6.2 Konfigurasi zhparser agar Pakai Kamus Khusus

Beritahu zhparser untuk menggunakan file kamus ini.

1. Set Parameter zhparser.dict_path: Dalam session PostgreSQL, jalankan:

   SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
   -- Pastikan path benar & user PostgreSQL punya izin baca file.

   Catatan: Setting via SET hanya berlaku di session aktif. Untuk aktif secara global, edit postgresql.conf tambahkan zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt' dan restart PostgreSQL (dapat dilakukan via antarmuka ServBay). Untuk pengembangan/testing lokal, SET biasanya sudah cukup.

6.3 Reload Kamus

Setelah mengubah file kamus, instruct zhparser untuk memuat ulang.

1. Panggil Fungsi Reload:

   SELECT zhprs_reload_dict();

   Dengan ini, segmentasi berikutnya akan memakai kamus baru, termasuk kata dari kamus custom Anda.

7. Mengatur Mode Segmentasi

zhparser mendukung beberapa mode segmentasi yang mempengaruhi tingkat detail hasil segmentasi. Parameter penting yang bisa diatur salah satunya adalah zhparser.seg_with_duality.

7.1 Pengaturan Parameter Mode Segmentasi

1. Set Parameter zhparser.seg_with_duality:
   • true: Mengaktifkan mode “bigram segmentation”, hasil segmentasi lebih detail & dapat meningkatkan recall pencarian (tembus lebih banyak dokumen relevan). Contoh: “自然语言处理” dapat dipecah menjadi “自然”, “语言”, “处理”, “自然语言”, “语言处理”.

     SET zhparser.seg_with_duality = true;

   • false: Mode segmentasi kasar—menggunakan pencocokan terpanjang menurut kamus utama. Cocok untuk presisi tinggi. Contoh: “自然语言处理” bisa di-segmentasi sebagai satu frasa (jika ada di kamus).

     SET zhparser.seg_with_duality = false;

   Pilih mode sesuai kebutuhan aplikasi Anda. Pengaturan ini juga bisa dibuat permanen via postgresql.conf.

8. Tanya Jawab (FAQ)

• Q: Kenapa CREATE EXTENSION zhparser; gagal—ekstensi tidak ditemukan? A: Pastikan paket PostgreSQL di ServBay sudah terpasang dan berjalan. ServBay seharusnya sudah menaruh file lib zhparser di direktori ekstensi PostgreSQL. Jika masih gagal, cek instalasi ServBay & PostgreSQL atau coba restart ServBay.

• Q: Kamus khusus tidak berpengaruh? A: Lakukan cek berikut:

  1. Sudahkah zhparser.dict_path diarahkan ke file kamus custom (/Applications/ServBay/etc/scws/custom_dict.txt)? Path case sensitive!
  2. Apakah Anda sudah menjalankan SELECT zhprs_reload_dict(); setelah update pengaturan atau file?
  3. Format file kamus sudah benar? (Satu kata/frasa per baris)
  4. Jika session baru, ulangi SET zhparser.dict_path = ...; atau sudah masukkan ke postgresql.conf serta restart?
  5. Akses file—user PostgreSQL bisa baca file kamus?

• Q: Hasil pencarian tidak sesuai harapan? A: Cek konfigurasi (mapping label to dictionary di chinese) sudah benar; coba ubah zhparser.seg_with_duality; gunakan SELECT to_tsvector('chinese', 'teks Mandarin Anda'); untuk debug segmentasi. Pastikan query to_tsquery memakai keyword/operator logika (&, |, !) yang tepat.

• Q: Performa pencarian lambat? A: Pastikan sudah ada GIN index untuk kolom to_tsvector(...). Untuk dataset sangat besar, optimasi tambahan pada PostgreSQL atau teknologi indeks lain mungkin dibutuhkan.

9. Kesimpulan

Dengan ServBay, aktivasi dan konfigurasi zhparser untuk pencarian teks penuh Bahasa Mandarin pada PostgreSQL menjadi sangat mudah. Cukup beberapa langkah untuk mengaktifkan ekstensi, mengatur konfigurasi pencarian teks, dan memanfaatkan fitur custom dictionary scws. Menguasai penggunaan dan pengaturan dasar zhparser secara signifikan akan meningkatkan kapabilitas lingkungan pengembangan lokal Anda dalam memproses data teks Mandarin dan menjadi fondasi kokoh membangun aplikasi Mandarin berkualitas tinggi.