Ricerca Full-Text Cinese in ServBay: Guida all'Uso di zhparser

zhparser è una potente estensione di terze parti per PostgreSQL, progettata appositamente per l'elaborazione efficiente di testi in cinese. Permette di offrire al database PostgreSQL capacità precise di segmentazione delle parole cinesi e ricerca full-text, rappresentando la scelta ideale per applicazioni che richiedono la ricerca su contenuti in cinese. ServBay, piattaforma completa per lo sviluppo web locale, integra nativamente l’estensione zhparser e la libreria di segmentazione scws (Simple Chinese Word Segmentation), consentendo l’utilizzo di dizionari personalizzati in combinazione con zhparser.

Questa guida spiega come installare (abilitare) e configurare zhparser nell'ambiente ServBay, come effettuare ricerche full-text in cinese, nonché creare e utilizzare dizionari personalizzati tramite scws incluso in ServBay.

1. Panoramica

Per applicazioni che gestiscono grandi quantità di testo cinese—come CMS, forum, piattaforme e-commerce—offrire una ricerca full-text efficiente e precisa è fondamentale. PostgreSQL include di base la ricerca full-text; tuttavia, il supporto per il cinese è limitato, poiché il sistema predefinito si basa sulla suddivisione delle parole tramite spazi, poco adatto alle lingue come il cinese. L’estensione zhparser integra una tecnologia di segmentazione del cinese, risolvendo questo limite e permettendo a PostgreSQL di riconoscere i confini semantici tra le parole, realizzando così una ricerca full-text realmente efficace per la lingua cinese.

Con ServBay, gli sviluppatori trovano zhparser già pre-integrato, eliminando le difficoltà di compilazione e installazione manuale dell’estensione, e rendendo veloce il setup di un ambiente di sviluppo capace di supportare la ricerca full-text cinese.

2. Prerequisiti

Prima di usare zhparser, assicurarsi che:

1. ServBay sia stato installato correttamente.
2. Il pacchetto PostgreSQL in ServBay sia abilitato e in esecuzione. Puoi gestire e verificare lo stato dei pacchetti direttamente dalla GUI di ServBay.

3. Installazione (abilitazione) dell’estensione zhparser

ServBay ha già posizionato i file del modulo zhparser nelle directory corrette di PostgreSQL. Per abilitarlo, basta eseguire un semplice comando SQL sul database di destinazione.

1. Collegati al database PostgreSQL: Apri il terminale e collegati al database PostgreSQL in esecuzione su ServBay tramite il tool a linea di comando psql. Sostituisci servbay-demo con il nome utente del tuo database e your_database_name con il nome del database su cui vuoi abilitare zhparser.

   psql -U servbay-demo -d your_database_name

   Se vuoi collegarti al database predefinito (solitamente avente il nome utente), puoi omettere il parametro -d.

2. Crea l’estensione zhparser: Nella shell interattiva di psql, esegui il seguente comando SQL:

   CREATE EXTENSION zhparser;

   Se il comando va a buon fine, non verrà mostrato alcun errore. Se invece ricevi un messaggio che l’estensione esiste già, significa che era stata abilitata in precedenza.

3. Verifica installazione di zhparser: Puoi vedere l’elenco delle estensioni installate con:

   \dx

   Nell’output, dovresti vedere zhparser elencata assieme alla sua versione.

4. Configurazione di zhparser

Dopo aver abilitato zhparser, occorre configurare la funzionalità di ricerca testuale di PostgreSQL affinché utilizzi zhparser per la segmentazione in cinese. Questo richiede prevalentemente la creazione di una configurazione di ricerca testuale (Text Search Configuration).

1. Crea una configurazione di ricerca: Una text search configuration stabilisce come i documenti vengano convertiti in tsvector (per l’indicizzazione) e come le query vengano trasformate in tsquery (per la ricerca). Creiamo una configurazione chiamata chinese e specifichiamo di usare zhparser come parser.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);

2. Aggiungi mappature dei dizionari: Nella configurazione di ricerca, occorre specificare per ciascuna categoria di token prodotta da zhparser quale dizionario usare. Ad esempio, zhparser assegna etichette grammaticali come nome (n), verbo (v), aggettivo (a), espressioni indipendenti (i), parole emozionali (e) e numerali (l). Qui, associamo tutte queste categorie al dizionario simple, che preserva le parole segmentate da zhparser senza alterarle.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
   -- Puoi aggiungere o modificare le categorie e i dizionari in base alle tue esigenze.

   Nota: Le etichette delle part-of-speech supportate da zhparser potrebbero non coincidere esattamente con le convenzioni NLP standard; quelle sopra sono tra le più usate da zhparser.

5. Ricerca full-text con zhparser

Dopo la configurazione, puoi iniziare a eseguire ricerche full-text in cinese! Ecco una breve dimostrazione.

5.1 Creazione di una tabella di esempio e inserimento dati

Crea una tabella di esempio per contenere del testo cinese, e inserisci alcuni valori di test.

1. Crea la tabella:

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

2. Inserisci dati di esempio:

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

5.2 Creazione dell’indice per la ricerca full-text

Per migliorare le prestazioni di ricerca—specialmente su grandi insiemi di dati—è vivamente raccomandato creare un indice sulla colonna di testo utilizzata per la ricerca. Per le colonne di tipo tsvector, l’indice GIN (Generalized Inverted Index) è la scelta standard per le query full-text.

1. Crea l'indice GIN: Creeremo un indice GIN sulla colonna content. L’indice userà to_tsvector('chinese', content) per convertire il testo usando la configurazione di ricerca chinese appena creata (e quindi userà zhparser per la segmentazione).

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

5.3 Esecuzione di query per la ricerca full-text

Ora puoi comporre ricerche usando to_tsquery per generare la chiave di ricerca, e l’operatore @@ per confrontare con le colonne indicizzate.

1. Esegui una query di ricerca: Per esempio, cerca i documenti che contengono sia "中文" che "分词":

   SELECT
       id,
       content,
       to_tsvector('chinese', content) AS content_tsvector -- Facoltativo: visualizza il risultato della segmentazione
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Questa query restituirà i record con id 2 e 3, perché i relativi content contengono entrambi "中文" e "分词".

   Prova anche altre query, ad esempio:

   • Cercare i documenti che contengono "ServBay":

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

     (Restituirà il documento con id 4)
   • Cercare i documenti con "自然语言处理":

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

     (Restituirà il documento con id 1. Nota: se "自然语言处理" è presente come singola voce nel dizionario personalizzato, la ricerca risulterà più precisa; se no, la segmentazione dipenderà dal dizionario e dalla modalità impostata.)

6. Creazione di dizionari personalizzati tramite scws incluso in ServBay

ServBay integra la libreria di segmentazione scws, e puoi configurare zhparser per utilizzare dizionari scws personalizzati, migliorando l’accuratezza della segmentazione—soprattutto con termini di settore o neologismi.

6.1 Creazione di un dizionario personalizzato

1. Crea o modifica un file dizionario personalizzato: ServBay consiglia di salvare i dizionari personalizzati scws nella cartella /Applications/ServBay/etc/scws/. Crea, se non esiste già, un file chiamato custom_dict.txt.

   # Crea o modifica il file dal terminale
   nano /Applications/ServBay/etc/scws/custom_dict.txt

2. Aggiungi termini al dizionario: Inserisci una parola per riga, cioè i termini che vuoi vengano riconosciuti come unità dalla segmentazione e da zhparser:

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

   Salva e chiudi il file.

6.2 Configurazione di zhparser per l’uso del dizionario personalizzato

Ora devi informare zhparser che deve usare il dizionario appena creato.

1. Imposta il parametro zhparser.dict_path: Nella tua sessione PostgreSQL, esegui:

   SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
   -- Verifica che il percorso sia corretto e che l’utente di PostgreSQL abbia permessi di lettura.

   Nota: Il comando SET vale solo per la sessione corrente. Per applicare la modifica a tutte le future connessioni occorre modificare il file di configurazione postgresql.conf aggiungendo la riga zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt' e riavviare PostgreSQL tramite la GUI di ServBay. Per sviluppo e test locale, il comando SET è solitamente sufficiente.

6.3 Ricarica del dizionario

Dopo aver modificato il file dizionario, è necessario ricaricarlo affinché le modifiche abbiano effetto su zhparser.

1. Chiama la funzione di ricarica:

   SELECT zhprs_reload_dict();

   Dopo questa operazione, la segmentazione considererà i nuovi termini aggiunti.

7. Regolazione della modalità di segmentazione

zhparser supporta diverse modalità di segmentazione, che influiscono sul livello di granularità della suddivisione delle parole. Il parametro più importante da gestire a riguardo è zhparser.seg_with_duality.

7.1 Impostare la modalità di segmentazione

1. Imposta il parametro zhparser.seg_with_duality:
   • Se impostato su true: viene attivata la modalità "segmentazione a coppie" (bigram), generando segmentazioni più fini e aumentando il recall nelle ricerche (ovvero, trovare più risultati). Per esempio, "自然语言处理" verrà segmentato in "自然", "语言", "处理", "自然语言", "语言处理".

     SET zhparser.seg_with_duality = true;

   • Se impostato su false: segmentazione più grossolana, tipicamente utilizzando il massimo matching dal dizionario, aumentando la precisione delle ricerche. "自然语言处理" verrà segmentato come unica parola, se presente in dizionario.

     SET zhparser.seg_with_duality = false;

   Scegli la modalità più adatta alle tue esigenze applicative. Anche questo parametro può essere impostato globalmente via postgresql.conf.

8. Domande Frequenti (FAQ)

• D: CREATE EXTENSION zhparser; restituisce errore che l’estensione non si trova? R: Verifica che il pacchetto PostgreSQL in ServBay sia installato e in esecuzione correttamente. ServBay dovrebbe aver collocato i file di zhparser nella cartella estensioni di PostgreSQL. Se il problema persiste, controlla che le installazioni di ServBay e PostgreSQL siano complete o prova a riavviare ServBay.
• D: Il dizionario personalizzato non viene riconosciuto? R: Controlla i seguenti aspetti:
  1. Il parametro zhparser.dict_path è impostato correttamente sul percorso del dizionario (/Applications/ServBay/etc/scws/custom_dict.txt)? Ricorda che il percorso è case-sensitive.
  2. Dopo aver impostato zhparser.dict_path, hai eseguito SELECT zhprs_reload_dict(); per ricaricare il dizionario?
  3. Il formato del file dizionario è corretto (una parola per riga)?
  4. Se lavori su una nuova sessione, ripeti il comando SET zhparser.dict_path = ...; oppure rendi la modifica permanente in postgresql.conf e riavvia PostgreSQL.
  5. L’utente PostgreSQL ha i permessi di lettura sul file dizionario?
• D: I risultati della ricerca full-text non sono quelli attesi? R: Controlla la configurazione di ricerca (chinese) e che la mappatura categoria/dizionario sia corretta. Prova a variare il parametro zhparser.seg_with_duality per vedere se la segmentazione cambia. Puoi anche testare la segmentazione di una frase con SELECT to_tsvector('chinese', 'tuo testo cinese'); per capire come viene effettuato il parsing. Controlla che le query full-text (to_tsquery) impieghino i termini/operazioni logiche giusti (&, |, !).
• D: La ricerca full-text è lenta? R: Assicurati di avere creato un indice GIN sulla colonna restituita da to_tsvector(...). Su dataset molto ampi, considera anche l’ottimizzazione della configurazione di PostgreSQL o l’uso di tecniche di indicizzazione avanzata.

9. Conclusioni

Usando ServBay, abilitare la ricerca full-text in cinese su PostgreSQL tramite zhparser diventa estremamente semplice. Bastano pochi step per attivare l’estensione, configurare la ricerca testuale e sfruttare la libreria scws inclusa per aumentarne l’accuratezza con dizionari personalizzati. Apprendere i fondamenti di zhparser e delle sue impostazioni permette di potenziare decisive capacità di trattamento dati testuali in cinese nel tuo ambiente di sviluppo locale—gettando le basi per applicazioni sofisticate e davvero multilingue.