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:
- ServBay sia stato installato correttamente.
- 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.
Collegati al database PostgreSQL: Apri il terminale e collegati al database PostgreSQL in esecuzione su ServBay tramite il tool a linea di comando
psql
. Sostituisciservbay-demo
con il nome utente del tuo database eyour_database_name
con il nome del database su cui vuoi abilitarezhparser
.bashpsql -U servbay-demo -d your_database_name
1Se vuoi collegarti al database predefinito (solitamente avente il nome utente), puoi omettere il parametro
-d
.Crea l’estensione
zhparser
: Nella shell interattiva dipsql
, esegui il seguente comando SQL:sqlCREATE EXTENSION zhparser;
1Se 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.
Verifica installazione di
zhparser
: Puoi vedere l’elenco delle estensioni installate con:sql\dx
1Nell’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).
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 intsquery
(per la ricerca). Creiamo una configurazione chiamatachinese
e specifichiamo di usarezhparser
come parser.sqlCREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
1Aggiungi 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 dizionariosimple
, che preserva le parole segmentate dazhparser
senza alterarle.sqlALTER 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.
1
2Nota: 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 dazhparser
.
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.
Crea la tabella:
sqlCREATE TABLE documents ( id SERIAL PRIMARY KEY, content TEXT );
1
2
3
4Inserisci dati di esempio:
sqlINSERT INTO documents (content) VALUES ('我爱自然语言处理'), ('中文分词是文本处理的重要步骤'), ('zhparser 是一个很好的中文分词工具'), ('ServBay 让本地开发更便捷');
1
2
3
4
5
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.
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 ricercachinese
appena creata (e quindi useràzhparser
per la segmentazione).sqlCREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));
1
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.
Esegui una query di ricerca: Per esempio, cerca i documenti che contengono sia "中文" che "分词":
sqlSELECT 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', '中文 & 分词');
1
2
3
4
5
6Questa query restituirà i record con
id
2 e 3, perché i relativicontent
contengono entrambi "中文" e "分词".Prova anche altre query, ad esempio:
- Cercare i documenti che contengono "ServBay":sql(Restituirà il documento con id 4)
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay');
1 - Cercare i documenti con "自然语言处理":sql(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.)
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '自然语言处理');
1
- Cercare i documenti che contengono "ServBay":
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
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 chiamatocustom_dict.txt
.bash# Crea o modifica il file dal terminale nano /Applications/ServBay/etc/scws/custom_dict.txt
1
2Aggiungi termini al dizionario: Inserisci una parola per riga, cioè i termini che vuoi vengano riconosciuti come unità dalla segmentazione e da
zhparser
:plaintext自然语言处理 中文分词 ServBay 本地开发环境
1
2
3
4Salva 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.
Imposta il parametro
zhparser.dict_path
: Nella tua sessione PostgreSQL, esegui:sqlSET 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.
1
2Nota: Il comando
SET
vale solo per la sessione corrente. Per applicare la modifica a tutte le future connessioni occorre modificare il file di configurazionepostgresql.conf
aggiungendo la rigazhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt'
e riavviare PostgreSQL tramite la GUI di ServBay. Per sviluppo e test locale, il comandoSET
è solitamente sufficiente.
6.3 Ricarica del dizionario
Dopo aver modificato il file dizionario, è necessario ricaricarlo affinché le modifiche abbiano effetto su zhparser
.
Chiama la funzione di ricarica:
sqlSELECT zhprs_reload_dict();
1Dopo 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
- 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 "自然", "语言", "处理", "自然语言", "语言处理".sqlSET zhparser.seg_with_duality = true;
1 - 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.sqlSET zhparser.seg_with_duality = false;
1
postgresql.conf
. - Se impostato su
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 dizhparser
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:
- Il parametro
zhparser.dict_path
è impostato correttamente sul percorso del dizionario (/Applications/ServBay/etc/scws/custom_dict.txt
)? Ricorda che il percorso è case-sensitive. - Dopo aver impostato
zhparser.dict_path
, hai eseguitoSELECT zhprs_reload_dict();
per ricaricare il dizionario? - Il formato del file dizionario è corretto (una parola per riga)?
- Se lavori su una nuova sessione, ripeti il comando
SET zhparser.dict_path = ...;
oppure rendi la modifica permanente inpostgresql.conf
e riavvia PostgreSQL. - L’utente PostgreSQL ha i permessi di lettura sul file dizionario?
- Il parametro
- 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 parametrozhparser.seg_with_duality
per vedere se la segmentazione cambia. Puoi anche testare la segmentazione di una frase conSELECT 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.