Búsqueda full-text en chino con ServBay: Guía de uso de zhparser

zhparser es una potente extensión de PostgreSQL de terceros diseñada específicamente para tratar textos en chino de manera eficiente. Proporciona capacidades precisas de segmentación y búsqueda textual en chino en bases de datos PostgreSQL, lo que la convierte en una opción ideal para aplicaciones que requieren búsqueda sobre contenido en chino. ServBay, un entorno de desarrollo web local integral, ya viene con la extensión zhparser preinstalada y lista para usar, junto con la biblioteca de segmentación scws (Simple Chinese Word Segmentation), que permite a zhparser aprovechar diccionarios personalizados.

En esta guía se explicará cómo instalar (habilitar) y configurar zhparser en el entorno ServBay, cómo utilizarlo para búsquedas full-text en chino y cómo crear y utilizar diccionarios personalizados empleando el scws integrado de ServBay.

1. Resumen

En aplicaciones que manejan grandes volúmenes de texto en chino—como sistemas de gestión de contenido, foros o plataformas de e-commerce—lograr una búsqueda full-text precisa y eficiente resulta fundamental. PostgreSQL ofrece funcionalidad de búsqueda de texto de forma nativa, pero su soporte para chino es limitado ya que se basa en separación por espacios, característica poco aplicable al idioma. La extensión zhparser soluciona esto integrando tecnología de segmentación para chino, permitiendo que PostgreSQL identifique los límites léxicos propios del idioma y ejecute búsquedas textuales efectivas.

ServBay integra previamente zhparser, ahorrándote los pasos tediosos de compilación e instalación manual, de modo que puedas montar rápidamente un entorno de desarrollo local con búsqueda full-text en chino.

2. Requisitos previos

Antes de usar zhparser, asegúrate de lo siguiente:

1. Que tienes ServBay correctamente instalado.
2. Que el paquete de PostgreSQL de ServBay está habilitado y en ejecución. Puedes comprobar y manejar el estado de los paquetes desde la interfaz de la aplicación ServBay.

3. Instalación (habilitación) de la extensión zhparser

ServBay ya coloca los archivos de módulo de zhparser en la ubicación correcta reconocida por PostgreSQL. Solo necesitas ejecutar el comando SQL correspondiente en la base de datos de destino.

1. Conéctate a tu base de datos PostgreSQL:

   Abre una terminal y usa la herramienta de línea de comandos psql para conectarte a la instancia de PostgreSQL gestionada por ServBay. Sustituye servbay-demo por tu usuario real y your_database_name por el nombre de la base en la que deseas habilitar zhparser.

   psql -U servbay-demo -d your_database_name

   Si te conectas a la base de datos por defecto (normalmente coincide con el usuario), puedes omitir el parámetro -d.

2. Crea la extensión zhparser:

   En la interfaz interactiva de psql, ejecuta:

   CREATE EXTENSION zhparser;

   Si el comando se realiza con éxito, no aparecerán mensajes de error. Si te indica que la extensión ya existe, significa que ya está habilitada.

3. Verifica la instalación de zhparser:

   Puedes ver las extensiones instaladas con:

   \dx

   Deberías encontrar zhparser y su información de versión en la lista.

4. Configuración de zhparser

Una vez habilitado zhparser, hay que decirle a PostgreSQL cómo emplearlo para segmentar texto en chino, lo que requiere la creación de una configuración de búsqueda textual (Text Search Configuration).

1. Crea la configuración de búsqueda textual:

   Esta configuración define cómo transformar documentos en tsvector (para índices) y cómo transformar las cadenas de búsqueda en tsquery (para consultas). Vamos a crear una configuración llamada chinese que usará zhparser como su parser.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);

2. Añade mapeo de diccionarios:

   La configuración debe indicar a PostgreSQL qué diccionario usar según el tipo de palabra (token) que encuentre el parser (zhparser), el cual etiqueta las palabras según su naturaleza gramatical (por ejemplo, sustantivo n, verbo v, adjetivo a, etc.). Aquí vamos a mapear las etiquetas como sustantivo (n), verbo (v), adjetivo (a), frase independiente (i), palabra emocional (e), cuantificador (l) al diccionario simple. Este diccionario simplemente conserva las palabras tal y como las obtiene zhparser, sin realizar transformaciones adicionales.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
   -- Puedes añadir o modificar las etiquetas y diccionarios según tus necesidades.

   Aviso: Las etiquetas de naturaleza gramatical soportadas por zhparser pueden diferir de algunos estándares de PLN; aquí se muestran las más comunes para este parser.

5. Uso de zhparser para búsqueda full-text

Tras la configuración, puedes comenzar a realizar búsquedas full-text en chino utilizando zhparser. A continuación, se muestra una demostración sencilla.

5.1 Crear tabla y datos de ejemplo

Primero, crea una tabla ejemplo para almacenar textos en chino e inserta algunos registros:

1. Crear la tabla:

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

2. Insertar datos de ejemplo:

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

5.2 Crear un índice para búsqueda full-text

Para mejorar el rendimiento de las búsquedas—especialmente con grandes volúmenes de datos—se recomienda crear un índice sobre la columna que se usará para búsquedas. En columnas tipo tsvector, el índice GIN (Generalized Inverted Index) es el método más indicado por su eficiencia.

1. Crear el índice GIN:

   Crearemos un índice GIN en la columna content, usando to_tsvector('chinese', content) para convertir el texto y especificar el uso de la configuración chinese creada previamente (así, la segmentación será realizada por zhparser).

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

5.3 Realizar consultas de búsqueda full-text

Puedes usar to_tsquery para convertir las palabras de búsqueda en formato de consulta, y luego usar el operador @@ para comparar con la columna indexada.

1. Ejecutar consulta de búsqueda:

   Por ejemplo, para buscar documentos que contengan tanto "中文" como "分词":

   SELECT
       id,
       content,
       to_tsvector('chinese', content) AS content_tsvector -- Opcional: ver resultados de segmentación
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Esta consulta devolverá los documentos con id 2 y 3, pues ambos contienen "中文" y "分词".

   Prueba otras consultas:

   • Buscar documentos que contengan "ServBay":

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

     (Devolverá el documento con id 4).
   • Buscar documentos con "自然语言处理":

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

     (Devuelve el documento con id 1. Nota: según el modo de segmentación y diccionario, zhparser puede segmentar "自然语言处理" como una palabra o dividirlo; si tu diccionario personalizado la incluye, funcionará incluso mejor).

6. Crear diccionarios personalizados con el scws integrado en ServBay

ServBay incluye la biblioteca scws, la cual puede ser utilizada por zhparser para cargar diccionarios personalizados, mejorando la precisión de la segmentación—especialmente útil para términos específicos de un dominio o palabras nuevas.

6.1 Creación del archivo de diccionario personalizado

1. Crea o edita el archivo de diccionario personalizado:

   Se recomienda guardar los diccionarios personalizados de scws en /Applications/ServBay/etc/scws/. Crea un archivo llamado custom_dict.txt (si aún no existe).

   # En terminal, crear o editar el archivo
   nano /Applications/ServBay/etc/scws/custom_dict.txt

2. Agrega las palabras al archivo:

   En custom_dict.txt, coloca una palabra por línea que quieras que zhparser reconozca como término individual. Por ejemplo:

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

   Guarda y cierra el archivo.

6.2 Configurar zhparser para usar el diccionario personalizado

Hay que informar a zhparser sobre la nueva ruta al diccionario.

1. Establece el parámetro zhparser.dict_path:

   En tu sesión de PostgreSQL, ejecuta:

   SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
   -- Asegúrate de que la ruta es correcta y de que el usuario de PostgreSQL tiene permisos de lectura.

   Aviso: El comando SET solo afecta a la sesión actual. Para aplicarlo a todas las conexiones nuevas, deberás modificar el archivo de configuración postgresql.conf, añadiendo la línea zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt', y reiniciar el servicio PostgreSQL (puedes hacerlo desde el panel de ServBay). Para desarrollo y pruebas locales, normalmente es suficiente con SET.

6.3 Recargar el diccionario

Si modificas el diccionario, deberás recargarlo para que los cambios tengan efecto.

1. Llama a la función de recarga:

   SELECT zhprs_reload_dict();

   Tras esto, todas las segmentaciones futuras emplearán el diccionario actualizado.

7. Ajuste del modo de segmentación

zhparser ofrece diversos modos de segmentación, que afectan el nivel de granularidad de las palabras extraídas. Uno de los parámetros principales es zhparser.seg_with_duality.

7.1 Configura el modo de segmentación

1. Ajustar el parámetro zhparser.seg_with_duality:

   • Si lo ajustas a true: activa el modo de segmentación binaria, generando palabras de menor tamaño (mayor granularidad). Esto puede mejorar el recall (encontrarás más documentos relacionados). Por ejemplo, "自然语言处理" podría segmentarse en "自然", "语言", "处理", "自然语言" y "语言处理".

     SET zhparser.seg_with_duality = true;

   • Si lo pones en false: privilegiará la segmentación de mayor tamaño, normalmente basada en la coincidencia más larga del diccionario, lo que puede mejorar la precisión. Así, "自然语言处理" se segmentaría como una sola palabra (si está en el diccionario).

     SET zhparser.seg_with_duality = false;

   Elige el modo en función de tu caso de uso. También puedes establecerlo globalmente en postgresql.conf.

8. Preguntas frecuentes (FAQ)

• ¿Por qué el comando CREATE EXTENSION zhparser; arroja error de extensión no encontrada? Asegúrate de que el paquete de PostgreSQL de ServBay está correctamente instalado y ejecutándose. ServBay debe haber ubicado la biblioteca de zhparser en el directorio de extensiones de PostgreSQL. Si el problema persiste, revisa la integridad de la instalación de ServBay y PostgreSQL, o intenta reiniciar ServBay.
• ¿Por qué el diccionario personalizado no tiene efecto? Revisa estos puntos:
  1. ¿El parámetro zhparser.dict_path apunta correctamente a tu archivo (/Applications/ServBay/etc/scws/custom_dict.txt)? Recuerda que la ruta es sensible a mayúsculas.
  2. ¿Has ejecutado SELECT zhprs_reload_dict(); después de cambiar la ruta del diccionario?
  3. ¿La sintaxis del archivo es correcta (un término por línea)?
  4. Si abriste una nueva sesión de base de datos, ¿volviste a ejecutar el comando SET zhparser.dict_path = ...;, o editaste postgresql.conf y reiniciaste PostgreSQL?
  5. Asegúrate de que el usuario de PostgreSQL tiene permisos de lectura sobre el archivo.
• ¿Por qué los resultados no son los esperados en la búsqueda full-text? Comprueba que la configuración (chinese) mapea correctamente las etiquetas de segmentación a los diccionarios. Prueba a modificar el parámetro zhparser.seg_with_duality y examina los resultados. Usa SELECT to_tsvector('chinese', 'tu texto en chino'); para ver cómo se segmenta el texto (esto es útil para depurar). Verifica también que la consulta (to_tsquery) usa las palabras y operadores lógicos correctos (&, |, !).
• ¿El rendimiento de las búsquedas full-text es bajo? Asegúrate de tener un índice GIN sobre la columna resultado de to_tsvector(...). Para datasets muy grandes, puedes optimizar aún más la configuración de PostgreSQL o considerar técnicas avanzadas de indexación.

9. Resumen

Gracias a ServBay, implementar búsqueda full-text en chino dentro de PostgreSQL usando zhparser es rápido y sencillo. Solo necesitas unos pocos pasos para habilitar la extensión, configurar la búsqueda y emplear los diccionarios personalizados gracias a la integración de scws de ServBay. Dominar los ajustes y parámetros básicos de zhparser potenciará en gran medida tu entorno de desarrollo local para manejar datos en chino, sentando las bases para aplicaciones en este idioma más completas y profesionales.