Pesquisa Textual em Chinês no PostgreSQL com pg_jieba no ServBay

Visão Geral

Para idiomas como o inglês, o recurso de busca textual do PostgreSQL funciona bem com análise lexical baseada em espaços e sinais de pontuação. Porém, textos em chinês não possuem espaçamento natural, sendo necessária uma ferramenta especializada de segmentação de palavras para dividir sequências de caracteres chineses em termos semanticamente independentes.

O pg_jieba é uma extensão de terceiros para o PostgreSQL que integra a popular biblioteca Jieba de segmentação de texto chinês. Com o pg_jieba, você pode realizar segmentação de palavras eficiente e precisa em textos chineses diretamente no PostgreSQL, tornando possível construir sistemas robustos de busca textual em chinês.

Como um ambiente local de desenvolvimento web completo, o ServBay já vem pré-instalado com a extensão pg_jieba, poupando você das etapas complicadas de compilação e instalação. Assim, você pode começar rapidamente a desenvolver e testar buscas em chinês no seu ambiente local.

Este artigo mostra como ativar, configurar e utilizar a extensão pg_jieba no ServBay.

Pré-Requisitos

Antes de usar o pg_jieba, verifique se você já:

1. Instalou o ServBay no macOS e tem o banco de dados PostgreSQL rodando corretamente.
2. Tem conhecimento básico em PostgreSQL, incluindo como se conectar e executar comandos SQL.

Instalação e Ativação do pg_jieba

O ServBay inclui a extensão pg_jieba junto com o PostgreSQL, ou seja, não é necessário baixar ou compilar manualmente—basta ativá-la com um simples comando SQL no banco de dados desejado.

Siga os passos abaixo para ativar a extensão pg_jieba:

1. Conecte-se ao seu banco de dados PostgreSQL: Abra o aplicativo Terminal e utilize o utilitário de linha de comando psql para se conectar ao seu banco de dados PostgreSQL. Substitua your_username pelo seu usuário e your_database pelo nome do banco de dados. O padrão no ServBay costuma ser servbay ou postgres.

   psql -U your_username -d your_database

   Por exemplo, utilizando os valores padrão:

   psql -U servbay -d servbay

2. Crie e ative a extensão pg_jieba: No prompt do psql, execute:

   CREATE EXTENSION pg_jieba;

   Se a extensão já estiver criada, executar este comando novamente pode causar um erro, o que é esperado.

3. Verifique se a extensão foi ativada: Liste as extensões instaladas no banco:

   \dx

   Se pg_jieba aparecer na lista, ela está ativa.

Configurando o pg_jieba para Busca Textual em Chinês

Após ativar a extensão pg_jieba, você precisa configurar a busca textual do PostgreSQL para usar o pg_jieba como segmentador de palavras.

Configurando a Busca Textual

A configuração da busca textual define como os documentos são processados para busca, incluindo qual parser realizar a segmentação de palavras e como diferentes tipos de tokens são tratados.

1. Crie uma nova configuração de busca textual: Crie uma configuração chamada chinese e defina o pg_jieba como seu parser.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);

   Isso fará com que o PostgreSQL utilize o pg_jieba para segmentação de palavras em textos.

2. Adicione mapeamentos para os resultados da segmentação: O parser pg_jieba gera diferentes tipos de tokens dependendo da classe gramatical (part of speech). Para que possam ser indexados e pesquisados, esses tokens precisam ser mapeados para um dicionário. Aqui, mapeamos tokens mais comuns (como substantivos n, verbos v, adjetivos a etc.) para o dicionário nativo simple do PostgreSQL, que não altera os tokens, usando-os como são extraídos pelo parser.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;

   Os códigos n,v,a,i,e,l representam possíveis classes gramaticais identificadas pelo pg_jieba. Você pode acrescentar, modificar ou remover conforme necessário. Outras classes comuns:

   • n: Substantivo
   • v: Verbo
   • a: Adjetivo
   • i: Expressão idiomática
   • e: Interjeição
   • l: Expressão coloquial
   • nr: Nome de pessoa
   • ns: Nome de local
   • nt: Instituição/organização
   • nz: Outros nomes próprios
   • m: Numeral
   • q: Classificador
   • t: Palavra temporal
   • s: Palavra de localização
   • f: Palavra direcional
   • p: Preposição
   • c: Conjunção
   • u: Partícula
   • xc: Palavra funcional
   • w: Pontuação
   • eng: Inglês
   • x: Caractere não-radical

   Normalmente, você vai querer indexar e pesquisar substantivos, verbos, adjetivos e outros termos semanticamente relevantes.

Exemplo de Busca Textual com pg_jieba

Após a configuração, já é possível utilizar o pg_jieba para realizar buscas textuais em chinês. Veja um exemplo:

Criando Tabela e Dados de Exemplo

Primeiro, crie uma tabela para armazenar documentos e insira alguns dados de exemplo contendo textos em chinês.

1. Crie a tabela:

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

2. Insira dados de exemplo:

   INSERT INTO documents (content) VALUES
   ('我爱自然语言处理技术'),
   ('中文分词是文本处理的重要步骤'),
   ('pg_jieba是一个很好的中文分词工具，它基于结巴分词库'),
   ('ServBay 让本地开发变得简单高效');

Criando o Índice de Busca Textual

Para melhorar o desempenho, especialmente com grandes volumes de dados, é aconselhável criar um índice na coluna destinada à busca textual. O tipo de índice GIN (Generalized Inverted Index) do PostgreSQL é ideal para esta finalidade.

1. Crie o índice GIN: Use a função to_tsvector com a configuração chinese para criar o índice na coluna content. to_tsvector('chinese', content) converte o texto usando a segmentação chinesa do pg_jieba.

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

Realizando Consultas de Busca Textual

Agora você pode usar a função to_tsquery combinada com o operador @@ para buscar palavras/textos. to_tsquery('chinese', 'sua consulta') converte sua frase usando a configuração chinese, criando um tipo tsquery. O operador @@ verifica se um tsvector corresponde a determinado tsquery.

1. Execute a consulta de busca: Busque documentos contendo as palavras “中文” e “分词”.

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   O símbolo & significa "E" lógico no tsquery. Você também pode usar | (OU lógico) e ! (NÃO lógico).

   Exemplo de busca por documentos com “ServBay” ou “开发”:

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay | 开发');

Dicionário Personalizado

O pg_jieba utiliza o dicionário padrão da biblioteca Jieba. Em alguns casos, pode ser necessário adicionar termos personalizados (como jargões ou nomes de produto) para segmentação mais precisa.

Você pode criar um arquivo de dicionário personalizado e configurar o pg_jieba para usá-lo.

Adicionando Termos Personalizados

1. Crie um arquivo de dicionário personalizado: No diretório de configuração do ServBay, crie um arquivo texto, por exemplo:

   /Applications/ServBay/etc/pg_jieba/custom_dict.txt

   Este é apenas um caminho sugerido; ajuste de acordo com a estrutura de instalação do seu ServBay.

2. Inclua termos no arquivo de dicionário personalizado: Abra o arquivo custom_dict.txt em um editor de texto e coloque um termo por linha. É possível, opcionalmente, definir a frequência (frequency) e a classe gramatical (tag), separados por espaço. O formato é: termo [frequência [tag]]. Quanto maior a frequência, maior a chance do termo ser identificado como palavra independente.

   自然语言处理 3 n
   ServBay 5 eng
   结巴分词库 3 n

   Aqui, 3 n indica que “自然语言处理” possui frequência 3 e é um substantivo (n); 5 eng sinaliza que “ServBay” tem frequência 5 e tag “eng” (inglês).

3. Configure o pg_jieba para utilizar o dicionário personalizado: Na sessão do PostgreSQL, ajuste o parâmetro pg_jieba.dict_path para apontar para o diretório do seu dicionário personalizado. Atenção: normalmente, pg_jieba.dict_path aponta para o diretório dos dicionários, não o arquivo em si. Se o arquivo personalizado estiver junto com o arquivo principal, pode não ser necessário mudar nada, ou siga instruções específicas do ServBay.

   O comando abaixo é baseado na documentação original; ajuste conforme seu ambiente:

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- Supondo que custom_dict.txt esteja neste diretório

   Ou, se seu pg_jieba permitir apontar diretamente para o arquivo (comportamento não padrão, apenas se necessário):

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- Use com cuidado e verifique conforme seu ServBay

   Importante: O comando SET só é válido para a sessão atual. Para uso permanente, altere o arquivo postgresql.conf e defina o parâmetro pg_jieba.dict_path com o caminho desejado.

Recarregando o Dicionário

Após modificar o arquivo de dicionário personalizado ou alterar o parâmetro pg_jieba.dict_path, é necessário pedir ao pg_jieba para recarregar o dicionário.

1. Recarregue o dicionário: Execute a seguinte função SQL:

   SELECT jieba_reload_dict();

   Após a execução, operações de segmentação usarão o novo dicionário.

Perguntas Frequentes (FAQ)

• Pergunta: Ao executar CREATE EXTENSION pg_jieba;, aparece o erro "extension 'pg_jieba' is not available". O que fazer? Resposta: Isso geralmente indica que o arquivo da extensão não está instalado corretamente no diretório de extensões do PostgreSQL ou não foi localizado. No ServBay, o pg_jieba já deve vir pré-instalado. Verifique se você está conectado ao PostgreSQL do ServBay e se a instalação não está corrompida. Se o problema persistir, reinicie o ServBay ou verifique os logs da plataforma.

• Pergunta: Meu dicionário personalizado não está funcionando. E agora? Resposta: Verifique:

  1. O caminho do arquivo do dicionário personalizado está correto e o usuário do PostgreSQL tem permissão de leitura.
  2. O formato do arquivo está adequado—um termo por linha e, se quiser, frequência e tag, separados por espaço.
  3. O parâmetro pg_jieba.dict_path foi configurado corretamente. Lembre-se que o comando SET é válido apenas para a sessão atual; para persistência, ajuste o postgresql.conf.
  4. A função SELECT jieba_reload_dict(); foi executada para recarregar o dicionário.
  5. Se editou o postgresql.conf, reinicie o PostgreSQL.

• Pergunta: Os resultados da busca textual estão imprecisos. O que posso fazer? Resposta: A precisão da busca textual depende tanto da segmentação quanto da formulação da consulta.

  1. Revise a segmentação: Use ts_debug('chinese', 'seu texto') para inspecionar como determinado texto foi segmentado pela configuração chinese e se o dicionário personalizado está funcionando.
  2. Ajuste o mapeamento da configuração: No comando ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple;, inclua apenas as classes gramaticais relevantes (remova partículas, pontuações etc).
  3. Melhore a consulta: Certifique-se que palavras-chave e operadores lógicos (&, |, !) em to_tsquery estão de acordo com sua intenção de busca.

Conclusão

O pg_jieba é uma poderosa ferramenta para implementar busca textual em chinês no PostgreSQL. Com a extensão já pré-instalada pelo ServBay, os desenvolvedores podem ativar e configurar facilmente a segmentação de palavras em ambientes locais. Seguindo este guia, você aprendeu a instalar o pg_jieba, criar e configurar buscas textuais, realizar consultas básicas e utilizar dicionários personalizados para otimizar os resultados. Aplicando essas técnicas em seus projetos, você potencializa significativamente a capacidade de busca de conteúdos em chinês.