ServBay에서 pg_jieba로 PostgreSQL 중국어 전문 검색 구현하기

개요

영어 등 공백과 구두점을 기준으로 분리되는 언어의 경우, PostgreSQL의 내장 전문 검색 기능은 내장된 형태소 분석(lexical analysis)만으로도 충분히 작동합니다. 그러나 중국어는 단어 사이에 공백이 존재하지 않기 때문에, 연속된 한자 문자열을 의미 단위의 단어로 분리하는 분절(Segmentation) 도구가 필수적입니다.

pg_jieba는 PostgreSQL 데이터베이스용 서드파티 확장 모듈로, 인기 있는 Jieba 형태소 분석기를 통합합니다. pg_jieba를 활용하면, PostgreSQL 내에서 중국어 텍스트를 효율적으로 분절하여 강력한 중국어 전문 검색 시스템을 구축할 수 있습니다.

ServBay는 통합형 로컬 웹 개발 환경으로, pg_jieba 확장 프로그램이 사전 설치되어 있어 복잡한 빌드나 설치 과정 없이, 곧바로 로컬 환경에서 중국어 전문 검색 개발 및 테스트를 시작할 수 있습니다.

이 문서에서는 ServBay 환경에서 pg_jieba 확장을 활성화하고 설정 및 활용하는 전체 과정을 안내합니다.

사전 준비 사항

pg_jieba를 사용하기 전에 아래 사항을 준비해 주세요:

1. macOS에 ServBay가 설치되어 있고, PostgreSQL 데이터베이스가 정상적으로 구동 중이어야 합니다.
2. PostgreSQL 기본 명령어와 데이터베이스 연결, SQL문 실행에 대한 기초적인 이해가 필요합니다.

pg_jieba 설치 및 활성화

ServBay에는 PostgreSQL과 함께 pg_jieba 확장 모듈이 번들로 포함되어 있습니다. 별도의 다운로드나 빌드 없이, 간단한 SQL 명령만으로 활성화할 수 있습니다.

활성화 단계는 다음과 같습니다:

1. PostgreSQL 데이터베이스 연결하기
   터미널을 실행하여 psql 명령줄 도구를 사용해 PostgreSQL에 연결합니다. your_username을 실제 PostgreSQL 사용자명으로, your_database를 데이터베이스명으로 바꿔주세요. ServBay의 기본 사용자와 데이터베이스는 대개 servbay 또는 postgres입니다.

   psql -U your_username -d your_database

   예시로, 기본 사용자 및 데이터베이스를 사용할 경우:

   psql -U servbay -d servbay

2. pg_jieba 확장 생성 및 활성화
   psql 환경에서 다음 SQL 명령을 실행합니다:

   CREATE EXTENSION pg_jieba;

   이미 확장이 존재한다면 에러가 날 수 있으나, 이는 정상입니다.

3. pg_jieba 활성화 확인
   다음 명령으로 설치된 확장 목록을 확인합니다:

   \dx

   목록에 pg_jieba가 보인다면 성공적으로 활성화된 것입니다.

pg_jieba로 중국어 전문 검색 환경 설정

확장을 활성화한 뒤, PostgreSQL의 텍스트 검색(Text Search) 기능에 pg_jieba를 형태소 분석기로 적용해 주어야 합니다.

텍스트 검색 구성 만들기

텍스트 검색 구성은 전문 검색 시 문서 처리를 위한 파서(parser) 및 토큰 관리 방식을 정의합니다.

1. 새 텍스트 검색 구성 생성
   pg_jieba를 파서로 지정한 chinese라는 이름의 텍스트 검색 구성을 만듭니다.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);

   이제 PostgreSQL이 해당 구성으로 텍스트를 처리할 때 pg_jieba 분석기를 사용합니다.

2. 분석 결과 맵핑 추가
   pg_jieba는 다양한 품사 태그를 갖는 토큰을 생성합니다. 이 토큰들을 인덱싱 및 검색이 가능하도록 PostgreSQL 내장 simple 사전에 맵핑합니다. simple 사전은 별도의 변환 없이, 분석기(pg_jieba)에서 추출한 토큰을 그대로 사용합니다.

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

   여기서 n,v,a,i,e,l은 pg_jieba가 인식하는 주요 품사 태그입니다. 필요에 따라 품사 태그를 수정/추가할 수 있습니다. 일반적으로 자주 쓰이는 품사들은 아래와 같습니다:

   • n: 명사
   • v: 동사
   • a: 형용사
   • i: 성어(관용구)
   • e: 감탄사
   • l: 관용 표현
   • nr: 인명
   • ns: 지명
   • nt: 기관/단체명
   • nz: 기타 고유명사
   • m: 수사
   • q: 양사
   • t: 시간 관련 단어
   • s: 장소 명사
   • f: 방향 명사
   • p: 전치사
   • c: 접속사
   • u: 조동사/조사
   • xc: 기타 허사
   • w: 구두점
   • eng: 영어
   • x: 형식적/의미 없는 글자

   보통 실질적인 의미가 있는 명사, 동사, 형용사 중심으로 인덱싱 및 검색을 수행하게 됩니다.

pg_jieba 사용 예시

설정이 완료되면, 다음과 같이 pg_jieba를 이용한 중국어 전문 검색을 직접 실행할 수 있습니다.

예제 테이블 및 데이터 생성

먼저, 문서를 저장할 테이블을 만들고 간단한 중국어 문구를 포함한 데이터를 입력합니다.

1. 테이블 생성:

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

2. 예시 데이터 삽입:

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

전문 검색 인덱스 생성

대량 데이터에서 효율적인 검색을 위해서는, 전문 검색용 컬럼에 인덱스 설정이 매우 중요합니다. PostgreSQL의 GIN(Generalized Inverted Index) 인덱스가 여기에 적합합니다.

1. GIN 인덱스 생성:
   to_tsvector 함수와 앞서 만든 chinese 구성을 결합해 content 컬럼에 GIN 인덱스를 추가합니다. to_tsvector('chinese', content)는 해당 텍스트를 pg_jieba 분석기로 처리해 tsvector 타입으로 전환합니다.

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

전문 검색 쿼리 실행

이제 to_tsquery 함수와 @@ 연산자를 이용해 전문 검색 쿼리를 실행할 수 있습니다. to_tsquery('chinese', '검색어')는 검색어를 chinese 구성에 맞는 tsquery로 변환하며, @@ 연산자는 두 결과의 일치 여부를 판단합니다.

1. 검색 쿼리 실행
   “中文(중국어)”와 “分词(분절)” 두 단어가 모두 포함된 문서를 조회합니다.

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

   &는 AND, |는 OR, !는 NOT 논리 연산을 나타냅니다.

   예를 들어, “ServBay” 또는 “开发(개발)”이 포함된 문서 조회:

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

사용자 정의 사전 사용

pg_jieba는 Jieba 엔진의 기본 사전을 사용하지만, 특정 도메인의 고유명사(전문 용어, 상품명 등)를 별도 추가하면 전문 검색 품질을 더욱 높일 수 있습니다.

사용자 정의 사전 파일을 생성하고, pg_jieba에 이를 연결할 수 있습니다.

사용자 정의 단어 추가

1. 사용자 정의 사전 파일 생성
   ServBay 설정 디렉터리에 새로운 텍스트 파일을 생성합니다. 예:

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

   위 경로는 예시이며, 실제 ServBay 설치 위치에 따라 적절히 조정이 필요합니다.

2. 사전 파일에 단어 추가
   텍스트 편집기로 custom_dict.txt 파일을 열고, 한 줄에 한 단어씩 등록합니다. 옵션으로 빈도수(frequency)와 품사(tag)를 공백으로 구분해 추가할 수도 있습니다. 예시는 다음과 같습니다:

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

   3 n은 “自然语言处理”의 빈도수를 3, 품사를 명사(n)로, 5 eng는 “ServBay”의 빈도수를 5, 품사를 영어(eng)로 지정한 예입니다.

3. pg_jieba에 사용자 사전 연결하기
   PostgreSQL 세션에서 pg_jieba.dict_path 매개변수를 사용자 사전이 위치한 디렉터리로 설정합니다.
   주의: 일반적으로 pg_jieba.dict_path는 사전 파일이 아닌, 해당 파일이 포함된 디렉터리 경로입니다. 만약 ServBay의 기본 사전 경로 또는 설정과 일치한다면 별도 설정 없이도 적용될 수 있습니다.

   예시(사전 디렉터리 지정):

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- ServBay의 주 사전 디렉터리와 일치할 때

   혹은(주의: 파일 지정이 허용되는 특수 환경일 경우):

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- 필요시 ServBay 문서 참고

   중요: SET 명령은 현재 데이터베이스 세션에서만 유효합니다. 항상 적용하려면 PostgreSQL의 postgresql.conf에서 직접 설정해야 합니다.

사전 재로드

사용자 사전 파일이나 dict_path 설정을 변경한 뒤에는 반드시 pg_jieba가 새로운 사전을 불러오게 해야 합니다.

1. 새 사전 접수시키기
   다음 SQL 함수를 실행하면 됩니다:

   SELECT jieba_reload_dict();

   성공했다면, 이후 형태소 분석부터 수정된 사전이 반영됩니다.

자주 묻는 질문 (FAQ)

• Q: CREATE EXTENSION pg_jieba; 실행 시 "extension 'pg_jieba' is not available" 오류가 발생합니다.
  A: 이는 대부분, pg_jieba 확장 파일이 PostgreSQL 확장 디렉터리에 올바르게 설치되지 않았거나, 서버에서 해당 확장을 인식하지 못해서 생깁니다. ServBay에서는 기본적으로 확장이 설치되어 있어야 하므로, ServBay의 PostgreSQL 인스턴스에 연결 중인지와 ServBay가 정상적으로 설치되어 있는지 확인하세요. 문제가 계속되면, ServBay를 재시작하거나, 로그 파일을 점검해 보세요.

• Q: 사용자 정의 사전이 적용되지 않습니다.
  A: 아래 항목을 점검해 보세요:

  1. 사전 파일 경로가 올바른지와 해당 파일에 대한 PostgreSQL 사용자의 읽기 권한이 있는지 확인
  2. 사전 파일에서 단어 및 옵션(빈도, 품사) 구분을 공백으로 했는지 확인 (한 줄에 하나씩)
  3. pg_jieba.dict_path 매개변수 설정이 올바른지, SET 적용 범위(세션 한정)에 유의
  4. SELECT jieba_reload_dict();를 실행했는지 확인
  5. 만약 postgresql.conf를 수정했다면, PostgreSQL 서비스를 재시작해야 함

• Q: 전문 검색 결과가 기대와 다르게 나옵니다.
  A: 검색 정확도는 형태소 분석과 쿼리 작성 방식에 직접적으로 영향을 받습니다.

  1. 형태소 분석 결과 점검: ts_debug('chinese', '여러분의 텍스트') 함수를 이용해, 검색 구성이 제대로 동작하는지 확인
  2. 품사 맵핑 개선: ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple;의 품사 범위를 조정해 불필요한 품사 제외
  3. 검색 쿼리 개선: to_tsquery의 검색어와 논리 연산자(&, |, !)가 검색 의도에 맞게 입력됐는지 확인

요약

pg_jieba는 PostgreSQL에서 중국어 전문 검색을 구현할 때 매우 강력한 도구입니다. ServBay에 사전설치된 pg_jieba 확장 덕분에, 개발자는 로컬 환경에서 손쉽게 중국어 형태소 분석 및 전문 검색 시스템을 구축할 수 있습니다. 본 문서의 단계를 따라 설치, 텍스트 검색 구성, 쿼리 실행, 사용자 사전 등록 등 전체 워크플로우를 익히고, 이를 프로젝트에 적용하면 중국어 콘텐츠의 검색 품질을 한층 끌어올릴 수 있습니다.