ServBay Chinese Full-Text Search: Gebruikshandleiding voor zhparser

zhparser is een krachtige, externe PostgreSQL-extensie, speciaal ontworpen voor efficiënte verwerking van Chinese tekst. Hiermee krijgt de PostgreSQL-database nauwkeurige Chinese woordsegmentatie en full-text zoekmogelijkheden; ideaal voor het bouwen van applicaties waarbij Chinese content-zoekfuncties centraal staan. ServBay, een complete lokale webontwikkelomgeving, heeft zhparser standaard geïntegreerd, samen met de scws (Simple Chinese Word Segmentation) bibliotheek, waardoor zhparser gebruik kan maken van custom woordenboeken.

In dit artikel lees je alles over het installeren (inschakelen) en configureren van zhparser binnen de ServBay-omgeving, hoe je deze gebruikt voor Chinese full-text zoekopdrachten, en hoe je met de ingebouwde scws van ServBay eigen woordenboeken aanmaakt en toepast.

1. Overzicht

Voor toepassingen met veel Chinese tekst—zoals contentmanagementsystemen, forums of e-commerceplatforms—is een snelle en nauwkeurige full-text zoekfunctie essentieel. De standaard full-text search van PostgreSQL biedt hiervoor beperkte ondersteuning omdat deze vooral is gericht op spatiegescheiden talen. De zhparser-extensie biedt een oplossing door Chinese segmentatietechnieken te integreren: PostgreSQL begrijpt zo de woordgrenzen in Chinese teksten, waardoor effectieve full-text search mogelijk wordt.

ServBay levert zhparser voorgeïnstalleerd aan ontwikkelaars, waardoor je niet langer handmatig de extensie hoeft te compileren en installeren. Hierdoor kun je razendsnel lokaal een ontwikkelomgeving opzetten met Chinese zoekfunctionaliteit.

2. Vereisten

Voordat je zhparser gaat gebruiken, zorg je ervoor dat:

1. ServBay correct geïnstalleerd is.
2. Het PostgreSQL-pakket van ServBay is ingeschakeld en draait. Je kunt de status van de pakketten bekijken en beheren via de ServBay-interface.

3. zhparser-extensie installeren (inschakelen)

ServBay heeft het zhparser-modulebestand al geplaatst in de directory waar PostgreSQL deze kan vinden. Je hoeft hem alleen nog aan te zetten via een SQL-commando in je doel-database.

1. Maak verbinding met je PostgreSQL-database: Open je terminal en gebruik de psql opdrachtregeltool om verbinding te maken met de PostgreSQL-database van ServBay. Vervang servbay-demo door je daadwerkelijke databasegebruikersnaam, en your_database_name door de naam van de database waarin je zhparser wilt activeren.

   psql -U servbay-demo -d your_database_name

   Als je verbinding maakt met de standaarddatabase (vaak gelijk aan de gebruikersnaam), kun je de -d parameter weglaten.

2. Extensie zhparser aanmaken: Geef in de interactieve interface van psql het volgende SQL-commando:

   CREATE EXTENSION zhparser;

   Zie je geen foutmelding, dan is het gelukt. Krijg je een melding dat de extensie al bestaat, dan is deze eerder al ingeschakeld.

3. zhparser-installatie verifiëren: Gebruik het volgende commando om de lijst met geïnstalleerde extensies te bekijken:

   \dx

   In de lijst moet je zhparser terugzien inclusief de versie-informatie.

4. zhparser configureren

Na het activeren van zhparser moet je PostgreSQL’s tekstzoekfunctie instellen om daadwerkelijk Chinese segmentatie te gebruiken. Dit gebeurt via Text Search Configurations.

1. Maak een Text Search Configuration: Zo'n configuratie bepaalt hoe documenten worden omgezet naar een tsvector (voor indexering) en hoe zoektermen in een tsquery (voor search) veranderen. Hier maken we een configuratie genaamd chinese die zhparser als parser gebruikt.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);

2. Woordenboektoewijzingen instellen: Je wijst toe hoe tokens (woorden met bepaalde woordsoorten) door een woordenboek verwerkt worden. zhparser voorziet ieder woord van een tag (zoals zelfstandig naamwoord = n, werkwoord = v, bijvoeglijk naamwoord = a, enz.). Hier koppelen we onder andere n (zelfstandig naamwoord), v (werkwoord), a (bijvoeglijk naamwoord), i (interjectie), e (emotioneel woord), l (getalwoord) aan het simple woordenboek. Dit is het basiswoordenboek, waarbij geen verdere conversie van de tokens plaatsvindt.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
   -- Je kunt indien gewenst zelf andere tags of woordenboeken toevoegen of aanpassen.

   Let op: De POS-tags van zhparser kunnen afwijken van de standaard NLP-indeling; bovenstaande zijn de meestgebruikte.

5. Full-text search uitvoeren met zhparser

Na de configuratie kun je met zhparser Chinese full-text search gebruiken. Hieronder een praktische demonstratie.

5.1 Voorbeeldtabel en -data aanmaken

Begin met het aanmaken van een tabel en invoeren van wat voorbeelddata.

1. Tabel aanmaken:

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

2. Voorbeelddata invoegen:

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

5.2 Full-text search index aanmaken

Voor hoge zoekprestaties, zeker met grotere datasets, maak je een index aan op de kolom die je full-text wilt doorzoeken. Voor tsvector velden kun je het best een GIN (Generalized Inverted Index) gebruiken; deze zijn zeer snel bij text search queries.

1. GIN-index aanmaken: We maken een GIN-index op de content kolom. Tijdens het indexeren converteert to_tsvector('chinese', content) de tekst in de content-kolom en gebruikt onze nieuwe chinese configuratie (met zhparser) voor de segmentatie.

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

5.3 Full-text zoekopdrachten uitvoeren

Gebruik to_tsquery om zoektermen om te zetten naar het queryformaat, en de @@ operator om deze te matchen met de tsvector indexkolom.

1. Zoekopdracht uitvoeren: Zoek bijvoorbeeld naar documenten die zowel “中文” als “分词” bevatten:

   SELECT
       id,
       content,
       to_tsvector('chinese', content) AS content_tsvector -- Optioneel: bekijk de segmentatieresultaten
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Deze query geeft de documenten met id 2 en 3 omdat in de content beide woorden staan.

   Andere zoekopdrachten proberen:

   • Zoeken naar documenten die “ServBay” bevatten:

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

     (Geeft het document met id 4)
   • Zoeken naar documenten met “自然语言处理”:

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

     (Geeft het document met id 1. Let erop dat zhparser “自然语言处理” mogelijk als één geheel, of als losse delen segmenteert, afhankelijk van je segmentatiemodus en woordenboek. Voeg het als geheel toe aan een custom woordenboek voor optimale resultaten.)

6. Maak je eigen woordenboek met de ingebouwde scws van ServBay

scws is geïntegreerd in ServBay. Daardoor kan zhparser gebruikmaken van custom woordenboeken voor nog nauwkeurigere segmentatie, bijvoorbeeld voor branchespecifieke termen of nieuwe woorden.

6.1 Eigen woordenboekbestand maken

1. Eigen woordenboekbestand aanmaken/bewerken: ServBay adviseert custom scws-woordenboeken te plaatsen in /Applications/ServBay/etc/scws/. Maak zonodig het bestand custom_dict.txt aan.

   # Bestand aanmaken of bewerken in de terminal
   nano /Applications/ServBay/etc/scws/custom_dict.txt

2. Woorden toevoegen aan het bestand: Voeg elk woord dat je voor segmentatie wilt gebruiken toe op een aparte regel in custom_dict.txt, bijvoorbeeld:

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

   Sla het bestand op en sluit af.

6.2 zhparser configureren met je custom woordenboek

Vertel zhparser dat hij dit zelfgemaakte woordenboek moet gebruiken.

1. Stel de parameter zhparser.dict_path in: In je PostgreSQL-sessie zet je het pad naar het custom woordenboek in via:

   SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
   -- Let op dat het pad juist is en dat de PostgreSQL-gebruiker leesrechten heeft.

   Let op: Het SET-commando is alleen actief voor de huidige sessie. Voor globaal gebruik pas je het postgresql.conf-bestand aan en voeg je toe/of wijzig je zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt'. Start PostgreSQL (via de ServBay-interface) daarna opnieuw. Voor lokaal testen is SET meestal voldoende.

6.3 Woordenboek herladen

Na wijzigen van het woordenboek, moet je zhparser laten herladen.

1. Herlaad-functie aanroepen:

   SELECT zhprs_reload_dict();

   Hierna werkt zhparser met het bijgewerkte woordenboek voor alle volgende segmentaties.

7. Segmentatiemodus aanpassen

zhparser biedt verschillende segmentatiemethoden die de fijnheid van de segmentatie beïnvloeden. De belangrijkste regelaar is de parameter zhparser.seg_with_duality.

7.1 Segmentatiemodus instellen

1. Parameter zhparser.seg_with_duality instellen:
   • Zet op true: Activeer "twee-gram segmentatie"; de segmentatie is fijner (meer tokens), wat de recall van zoekopdrachten vergroot (je vindt meer relevante documenten). Bijvoorbeeld, “自然语言处理” wordt gesegmenteerd in “自然”, “语言”, “处理”, “自然语言”, “语言处理”.

     SET zhparser.seg_with_duality = true;

   • Zet op false: Gebruik een grovere segmentatie (meestal de langste match in het woordenboek). Dit verhoogt de precisie van zoekopdrachten. Bijvoorbeeld, “自然语言处理” wordt slechts als geheel gesegmenteerd (als het in het woordenboek staat).

     SET zhparser.seg_with_duality = false;

   Kies de modus die het best past bij jouw toepassing. Je kunt deze parameter ook globaal instellen in postgresql.conf.

8. Veelgestelde vragen (FAQ)

• Q: Krijg ik een foutmelding bij CREATE EXTENSION zhparser;? A: Kijk of het PostgreSQL-pakket van ServBay goed is geïnstalleerd en draait. De zhparser-bibliotheek moet in de juiste extensiedirectory van PostgreSQL aanwezig zijn. Controleer eventueel de installatie/integriteit van zowel ServBay als PostgreSQL en start ServBay opnieuw.
• Q: Mijn custom woordenboek wordt niet gebruikt – hoe kan dit? A: Controleer deze punten:
  1. Staat de parameter zhparser.dict_path goed ingesteld op het pad van jouw woordenboek (/Applications/ServBay/etc/scws/custom_dict.txt)? Pad is hoofdlettergevoelig!
  2. Heb je na het instellen van zhparser.dict_path ook SELECT zhprs_reload_dict(); uitgevoerd?
  3. Is het woordenboekformaat correct (één woord per regel)?
  4. Is de parameter opnieuw ingesteld voor elke nieuwe databasesessie, of heb je postgresql.conf aangepast en PostgreSQL herstart?
  5. Heeft de PostgreSQL-gebruiker leesrechten op het woordenboekbestand?
• Q: Mijn zoekresultaten komen niet overeen met de verwachting? A: Kijk of je Text Search Configuration (chinese) POS-tags juist aan woordenboeken koppelt. Experimenteer met de parameter zhparser.seg_with_duality. Gebruik SELECT to_tsvector('chinese', 'je Chinese testtekst'); om te zien hoe tekst precies gesegmenteerd wordt (handig voor debuggen). Controleer of je query (to_tsquery) de juiste termen en logische operatoren (&, |, !) bevat.
• Q: Slechte performance bij full-text search? A: Zorg ervoor dat je een GIN-index hebt op je to_tsvector(...) kolom. Voor zeer grote datasets zijn er extra optimalisaties mogelijk binnen PostgreSQL of (eventueel) andere zaailing-zoektechnologieën.

9. Samenvatting

Dankzij ServBay is het implementeren van Chinese full-text search met zhparser in PostgreSQL efficiënter dan ooit. Met enkele eenvoudige stappen schakel je de extensie in, configureer je tekstsearch, én kun je direct profiteren van custom woordenboeken via de ingebouwde scws-bibliotheek. Door vertrouwd te raken met basisgebruik en configuratie van zhparser, verhoog je de Chinese tekstverwerkingsmogelijkheden van je lokale ontwikkelomgeving ingrijpend—en leg je een solide fundament voor het bouwen van krachtige, meertalige toepassingen.