Busca Textual em Chinês no ServBay: Guia de Uso do zhparser

O zhparser é uma poderosa extensão de terceiros para o PostgreSQL, projetada especificamente para o processamento eficiente de textos em chinês. Ela adiciona ao banco de dados PostgreSQL recursos precisos de segmentação de palavras e busca textual em chinês, tornando-se a escolha ideal ao construir aplicativos que envolvem busca de conteúdos nesse idioma. O ServBay, como ambiente local completo para desenvolvimento web, já vem com suporte integrado ao zhparser, além de incluir a biblioteca de segmentação de palavras scws (Simple Chinese Word Segmentation), que pode ser aproveitada pelo zhparser para criar dicionários personalizados.

Este guia detalha como instalar (habilitar) e configurar o zhparser no ambiente do ServBay, demonstra como utilizá-lo para busca textual em chinês e explica o uso do scws interno do ServBay para criar e aplicar dicionários personalizados.

1. Visão Geral

Para aplicativos que lidam com grandes volumes de textos em chinês — tais como sistemas de gerenciamento de conteúdo, fóruns, plataformas de e-commerce, entre outros — ter uma solução eficiente e precisa de busca textual é fundamental. O PostgreSQL já oferece recursos nativos de busca textual, mas seu suporte ao chinês é limitado por padrão, pois ele foi concebido principalmente para idiomas baseados em separação por espaço. A extensão zhparser resolve essa limitação ao integrar uma tecnologia de segmentação de palavras para o chinês, capacitando o PostgreSQL a compreender os limites das palavras e realizando buscas textuais em chinês de forma eficiente.

O ServBay já integra previamente o zhparser, eliminando a necessidade de compilar ou instalar manualmente a extensão. Assim, você pode rapidamente configurar um ambiente de desenvolvimento local com suporte à busca textual em chinês.

2. Pré-requisitos

Antes de usar o zhparser, verifique se:

1. O ServBay está instalado com sucesso.
2. O pacote PostgreSQL dentro do ServBay está ativado e em execução. Você pode verificar e gerenciar o status dos pacotes pela interface do aplicativo ServBay.

3. Instalando (Habilitando) a Extensão zhparser

O ServBay posiciona automaticamente o arquivo do módulo zhparser onde o PostgreSQL pode acessá-lo. Você só precisa executar um comando SQL no banco de dados desejado para habilitá-lo.

1. Conecte-se ao seu banco de dados PostgreSQL:
   Abra o terminal e utilize o cliente de linha de comando psql para se conectar ao PostgreSQL rodando no ServBay. Substitua servbay-demo pelo seu nome de usuário real e your_database_name pelo nome do banco que deseja habilitar o zhparser.

   psql -U servbay-demo -d your_database_name

   Se for conectar ao banco de dados padrão (normalmente com o mesmo nome do usuário), pode omitir o parâmetro -d.

2. Crie a extensão zhparser:
   No prompt do psql, execute o comando SQL abaixo:

   CREATE EXTENSION zhparser;

   Se o comando executar sem erro, está tudo certo. Caso retorne que a extensão já existe, significa que ela já está habilitada.

3. Verifique a instalação do zhparser:
   Confira os módulos de extensão disponíveis no banco rodando:

   \dx

   Você deve ver o zhparser e suas informações de versão listadas.

4. Configurando o zhparser

Após habilitar a extensão, é necessário configurar a busca textual do PostgreSQL para utilizar o zhparser na segmentação de textos em chinês. Isso envolve criar uma configuração de busca textual (Text Search Configuration).

1. Crie a configuração de busca textual:
   Ela define como os documentos são convertidos para tsvector (para índice) e como as strings de busca são convertidas para tsquery (para consulta). Vamos criar uma configuração chamada chinese, usando o zhparser como analisador (PARSER).

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);

2. Adicione mapeamento de dicionários:
   É necessário especificar qual dicionário (dictionary) deve ser utilizado para diferentes tipos de tokens que o parser gera. O zhparser classifica as palavras de acordo com as classes gramaticais: substantivos (n), verbos (v), adjetivos (a), frases independentes (i), termos emotivos (e), numerais (l) etc. Aqui, mapeamos esses tipos para o dicionário simple, que faz a correspondência direta sem transformação.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
   -- Você pode adicionar ou ajustar os rótulos conforme necessário.

   Nota: As etiquetas de classes gramaticais do zhparser podem diferir ligeiramente dos padrões NLP. Acima estão os mais usados pelo zhparser.

5. Usando o zhparser para Busca Textual

Depois da configuração, você já pode usar o zhparser para buscas textuais em chinês. Veja um exemplo prático.

5.1 Criando tabela e dados de exemplo

Primeiro, crie uma tabela para armazenar texto em chinês e insira alguns registros.

1. Crie a tabela:

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

2. Insira dados de exemplo:

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

5.2 Criando Índice para Busca Textual

Para melhorar a performance da busca, especialmente em grandes volumes de dados, é altamente recomendado criar um índice na coluna usada para busca textual. No caso do tipo tsvector, o índice GIN (Generalized Inverted Index) é o mais adequado.

1. Crie o índice GIN:
   Faremos o índice sobre a coluna content, usando to_tsvector('chinese', content) para converter o texto utilizando a configuração criada anteriormente e ativando o uso do zhparser.

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

5.3 Realizando Consultas de Busca Textual

Agora, você pode utilizar to_tsquery para transformar o termo buscado e usar o operador @@ em consultas à coluna indexada.

1. Exemplo de busca:
   Para buscar documentos que contenham simultaneamente “中文” e “分词”:

   SELECT
       id,
       content,
       to_tsvector('chinese', content) AS content_tsvector -- Opcional: veja os tokens segmentados
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   A consulta retorna os documentos com id 2 e 3, pois ambos possuem “中文” e “分词” no conteúdo.

   Experimente outras buscas:

   • Buscar documentos contendo “ServBay”:

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

     (Retorna o documento de id 4)
   • Buscar documentos sobre “自然语言处理”:

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

     (Retorna o documento de id 1. Observação: o zhparser pode tratar “自然语言处理” como palavra única ou subdividir, dependendo do modo de segmentação e do dicionário. A configuração de dicionários personalizados melhora esse resultado.)

6. Criando Dicionários Personalizados com o scws Interno do ServBay

O ServBay integra a biblioteca scws, assim permitindo que o zhparser utilize arquivos de dicionário, inclusive personalizados. Isso aumenta a precisão na segmentação, principalmente para terminologias técnicas ou neologismos.

6.1 Criando o arquivo de dicionário personalizado

1. Crie ou edite o dicionário personalizado:
   Recomenda-se salvar o arquivo do dicionário em /Applications/ServBay/etc/scws/. Crie ou edite o arquivo custom_dict.txt (crie caso não exista).

   # Crie ou edite o arquivo via terminal
   nano /Applications/ServBay/etc/scws/custom_dict.txt

2. Adicione vocabulário personalizado:
   No arquivo, adicione uma palavra/frase por linha que deseja que o zhparser reconheça. Exemplo:

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

   Salve e feche o arquivo.

6.2 Configurando o zhparser para uso do dicionário personalizado

É necessário instruir o zhparser a utilizar o novo arquivo de dicionário.

1. Defina o parâmetro zhparser.dict_path:
   Na sua sessão do PostgreSQL, rode:

   SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
   -- Certifique-se de que o caminho está correto e o usuário PostgreSQL tem permissão de leitura.

   Nota: O comando SET afeta apenas a sessão atual. Para tornar global, ajuste isso no arquivo de configuração postgresql.conf, adicionando zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt' e reinicie o PostgreSQL (pode ser pelo aplicativo do ServBay). Para desenvolvimento local/testes, SET já é suficiente.

6.3 Recarregando o dicionário

Após editar o dicionário, é preciso informar ao zhparser para recarregar o arquivo.

1. Chame a função de recarga:

   SELECT zhprs_reload_dict();

   Após executar, as segmentações passarão a aplicar as novas palavras do dicionário personalizado.

7. Ajustando o Modo de Segmentação

O zhparser suporta diferentes modos de segmentação, o que altera o grau de detalhamento. O parâmetro mais utilizado é zhparser.seg_with_duality.

7.1 Definindo o modo de segmentação

1. Ajuste o parâmetro zhparser.seg_with_duality:
   • Defina como true para ativar o “modo binário”, que gera segmentos mais detalhados, melhorando a cobertura da busca (encontrando mais documentos relevantes). Por exemplo, “自然语言处理” pode ser quebrado em “自然”, “语言”, “处理”, “自然语言”, “语言处理”.

     SET zhparser.seg_with_duality = true;

   • Defina como false para uma segmentação mais ampla, geralmente usando a correspondência mais longa via dicionário, o que aumenta a precisão. Por exemplo, “自然语言处理” será tratado como um termo único (desde que exista no dicionário).

     SET zhparser.seg_with_duality = false;

   Escolha o modo de acordo com sua necessidade de aplicação. O parâmetro também pode ser globalizado via postgresql.conf.

8. Perguntas Frequentes (FAQ)

• P: O comando CREATE EXTENSION zhparser; retorna extensão não encontrada?
  R: Confirme se o pacote PostgreSQL do ServBay está instalado e rodando corretamente. O ServBay já inclui os arquivos do zhparser no diretório certo do PostgreSQL. Se persistir, verifique a integridade das instalações do ServBay e PostgreSQL ou tente reiniciar o ServBay.
• P: Dicionário personalizado não está funcionando?
  R: Analise os pontos abaixo:
  1. O parâmetro zhparser.dict_path aponta para o arquivo correto (/Applications/ServBay/etc/scws/custom_dict.txt)? (o caminho diferencia maiúsculas)
  2. Após definir o caminho, executou SELECT zhprs_reload_dict(); para recarregar o dicionário?
  3. O formato do arquivo está correto (uma palavra por linha)?
  4. Em novas sessões, confirmou a execução novamente de SET zhparser.dict_path = ...; ou adicionou a configuração ao postgresql.conf e reiniciou o PostgreSQL?
  5. O usuário do PostgreSQL tem permissão de leitura no arquivo do dicionário?
• P: Os resultados da busca textual não correspondem ao esperado?
  R: Verifique se a configuração de busca textual (chinese) está corretamente mapeada. Ajuste o parâmetro zhparser.seg_with_duality e teste novamente. Use SELECT to_tsvector('chinese', 'seu texto chinês'); para ver como o texto está sendo segmentado. Confirme se está usando os termos e operadores corretos em to_tsquery (&, |, !).
• P: Performance da busca textual está lenta?
  R: Veja se criou o índice GIN sobre a coluna to_tsvector(...). Para grandes volumetrias, considere também ajustar configurações do PostgreSQL ou pesquisar técnicas avançadas de indexação.

9. Conclusão

Com o ServBay, usar o zhparser no PostgreSQL para buscas textuais em chinês ficou muito simples. Com poucos passos, você habilita a extensão, configura a busca textual e pode aproveitar o scws interno do ServBay para personalizar o dicionário e a segmentação. Dominar o zhparser e suas configurações aumenta significativamente a sua capacidade de trabalhar com dados em chinês em projetos locais, garantindo uma base sólida para criar aplicações em chinês ricas em funcionalidades.