ServBay 중국어 전문 검색: zhparser 사용 가이드

zhparser는 중국어 텍스트를 효율적으로 처리하도록 설계된 강력한 서드파티 PostgreSQL 확장 모듈입니다. 이 확장을 활용하면 PostgreSQL 데이터베이스에서 정확한 중국어 형태소 분석과 전문 검색 기능을 구현할 수 있어, 중국어가 포함된 검색 서비스 구축에 이상적입니다. ServBay는 통합 로컬 웹 개발 환경으로, zhparser 확장이 기본 내장되어 있으며, scws(Simple Chinese Word Segmentation) 형태소 분석 라이브러리도 포함되어 있습니다. zhparser는 ServBay 내장 scws를 이용해 사용자 정의 사전 활용이 가능합니다.

이 문서에서는 ServBay 환경에서 zhparser를 설치(활성화) 및 설정하는 방법, 중국어 전문 검색 실행법, 그리고 ServBay 내장 scws를 이용해 사용자 정의 사전을 만들고 적용하는 방법까지 단계별로 안내합니다.

1. 개요

중국어 텍스트가 다량 포함된 시스템(콘텐츠 관리, 포럼, 이커머스 등)에서 효율적이고 정확한 전문 검색 기능은 필수적입니다. PostgreSQL은 기본적으로 전문 검색을 지원하지만, 공백 분리 기반이라 중국어 지원이 미흡합니다. zhparser 확장은 중국어 형태소 분석 기술을 통합해, PostgreSQL이 중국어 텍스트의 단어 경계를 인식할 수 있게 하여 효과적인 중국어 전문 검색을 구현합니다.

ServBay는 개발자를 위해 zhparser를 미리 통합하여 번거로운 수동 컴파일 및 설치 과정 없이, 중국어 전문 검색이 가능한 로컬 개발 환경을 신속하게 구축할 수 있도록 지원합니다.

2. 사전 준비

zhparser 사용 전 다음 사항을 확인하세요:

ServBay가 정상적으로 설치되어 있는지 확인하세요.
ServBay에서 PostgreSQL 패키지가 활성화되어 실행 중이어야 합니다. ServBay 앱 인터페이스에서 패키지 상태를 확인하고 관리할 수 있습니다.

3. zhparser 확장 설치(활성화)

ServBay는 이미 zhparser 모듈 파일을 PostgreSQL이 인식할 수 있는 위치에 배치했습니다. 여러분은 데이터베이스에서 SQL 명령 한 줄로 확장을 활성화할 수 있습니다.

PostgreSQL 데이터베이스에 접속하기: 터미널을 열고, psql 명령줄 도구로 ServBay에서 실행 중인 PostgreSQL 데이터베이스에 접속하세요. servbay-demo 부분은 실제 사용하는 유저명으로, your_database_name 부분은 확장을 활성화할 데이터베이스명으로 바꿔주세요.
bash
```
psql -U servbay-demo -d your_database_name
```
1
기본 데이터베이스(대개 유저명과 동일)로 접속할 경우 -d 옵션을 생략할 수 있습니다.
zhparser 확장 생성:psql 인터페이스에서 아래 SQL 명령을 실행하세요:
sql
```
CREATE EXTENSION zhparser;
```
1
정상적으로 실행되면 오류 메시지가 없습니다. 이미 활성화되어 있다면, 확장 이미 존재한다고 안내가 나올 수 있습니다.
zhparser 설치 확인: 아래 명령으로 데이터베이스에 설치된 확장 목록을 확인할 수 있습니다.
sql
```
\dx
```
1
출력 목록에 zhparser와 버전 정보가 표시되어야 합니다.

4. zhparser 설정

zhparser를 활성화한 후에는 PostgreSQL의 텍스트 검색 기능에 어떻게 zhparser를 활용할지 설정해야 합니다. 이는 주로 텍스트 검색 설정(Text Search Configuration) 생성으로 이루어집니다.

텍스트 검색 설정 생성: 텍스트 검색 설정은 문서를 인덱싱용 tsvector로, 쿼리 문자열을 검색용 tsquery로 어떻게 변환할지 정의합니다. 여기서는 chinese라는 이름의 설정을 만들고, PARSER로 zhparser를 지정합니다.
sql
```
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
```
1
사전 매핑 추가: 텍스트 검색 설정에서는 PARSER(zhparser)가 생성한 다양한 형태의 토큰(token)에 대해 어떤 사전(dictionary)으로 처리할지 지정해야 합니다. zhparser는 명사(n), 동사(v), 형용사(a) 등으로 토큰을 태깅합니다. 여기서는 명사(n), 동사(v), 형용사(a), 독립어(i), 감정어(e), 수량어(l) 등에 대해 모두 simple 사전으로 매핑합니다. simple 사전은 변환 없이 zhparser가 분리한 단어를 그대로 사용합니다.
sql
```
ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
-- 필요에 따라 태그 또는 사전 매핑을 추가/수정할 수 있습니다.
```
1
2
참고: zhparser의 품사 태그는 표준 NLP와 조금 다를 수 있으며, 여기 사용된 것은 일반적인 zhparser 태그입니다.

5. zhparser를 이용한 전문 검색

설정이 완료되면 zhparser를 활용한 중국어 전문 검색을 바로 시작할 수 있습니다. 아래는 간단한 사용 예시입니다.

5.1 예제 테이블 및 데이터 생성

먼저, 중국어 텍스트 저장용 예제 테이블을 만들고 데이터를 삽입합니다.

테이블 생성:

sql

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

예제 데이터 삽입:

sql

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

5.2 전문 검색 인덱스 생성

검색 성능 향상을 위해, 특히 대용량 데이터에서는 전문 검색 대상 컬럼에 인덱스를 생성하는 것이 중요합니다. tsvector 타입에는 GIN(Generalized Inverted Index) 인덱스를 추천합니다.

GIN 인덱스 생성:content 컬럼에 GIN 인덱스를 생성하며, 이때 to_tsvector('chinese', content)로 텍스트를 tsvector로 변환하고, 우리가 만든 chinese 텍스트 검색 설정을 사용해 분할합니다.
sql
```
CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));
```
1

5.3 전문 검색 쿼리 실행

이제 to_tsquery로 검색어를 쿼리 포맷으로 변환한 후, @@ 연산자로 tsvector 인덱스 컬럼과 매칭 검색을 할 수 있습니다.

검색 쿼리 실행: 예를 들어, "中文"과 "分词"가 모두 포함된 문서 검색:
sql
```
SELECT
    id,
    content,
    to_tsvector('chinese', content) AS content_tsvector -- (선택 사항) 형태소 분석 결과 확인
FROM documents
WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');
```
1
2
3
4
5
6
해당 쿼리는 id 2번, 3번 문서를 반환합니다. 이들의 content에는 모두 "中文"과 "分词"가 있습니다.
다른 검색 예시:
- "ServBay"가 포함된 문서 검색:
  sql
```
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay');
```
  1
  (id 4번 문서 반환)
- "自然语言处理"이 포함된 문서 검색:
  sql
```
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '自然语言处理');
```
  1
  (id 1번 문서 반환. 참고: zhparser가 "自然语言处理"을 하나의 단어 또는 분할 처리할 수 있으며, 이는 형태소 분석 모드 및 사전에 따라 달라집니다. 사용자 정의 사전에 해당 단어가 포함되면 검색 효과가 높아집니다.)

6. ServBay 내장 scws로 사용자 정의 사전 구축하기

ServBay는 scws(Simple Chinese Word Segmentation) 라이브러리를 내장하고 있어, zhparser가 scws의 사전 파일(사용자 정의 사전 포함)을 활용해 도메인 고유 단어나 신조어 등 분석 정확도를 높일 수 있습니다.

6.1 사용자 정의 사전 파일 만들기

사용자 정의 사전 파일 생성/편집: ServBay는 scws 사용자 사전을 /Applications/ServBay/etc/scws/ 경로에 보관하는 것을 권장합니다. custom_dict.txt 파일(없으면 새로 만듭니다)을 생성하세요.
bash
```
# 터미널에서 파일을 생성/편집
nano /Applications/ServBay/etc/scws/custom_dict.txt
```
1
2
파일에 단어 추가:custom_dict.txt에 한 줄에 하나씩, zhparser가 분할해야 하는 단어를 기입합니다. 예시:
plaintext
```
自然语言处理
中文分词
ServBay
本地开发环境
```
1
2
3
4
저장 후 파일을 닫으세요.

6.2 zhparser에 사용자 정의 사전 적용

이제 zhparser에 사용자 정의 사전 파일 경로를 지정해야 합니다.

zhparser.dict_path 매개변수 지정: PostgreSQL 세션에서 아래 명령으로 zhparser 사전 경로를 설정합니다.
sql
```
SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
-- 경로가 정확한지, PostgreSQL 유저가 읽기 권한이 있는지 확인하세요.
```
1
2
참고: SET 명령은 해당 데이터베이스 세션에서만 유효합니다. 모든 신규 접속에 적용하려면 PostgreSQL 설정 파일(postgresql.conf)의 zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt' 항목을 수정하고 PostgreSQL을 재시작(ServBay 앱에서 가능)해야 합니다. 개발/테스트 용도라면 SET만으로도 충분합니다.

6.3 사전 재로딩

사전 파일을 수정한 뒤에는 반드시 zhparser에게 변경 사실을 알려야 합니다.

사전 재로딩 함수 호출:
sql
```
SELECT zhprs_reload_dict();
```
1
이 함수를 실행한 이후부터 사용자 사전이 반영된 형태소 분석 결과가 사용됩니다.

7. 형태소 분석 모드 조정

zhparser는 다양한 형태소 세분화 모드(분할 단위의 세밀함)를 지원합니다. 대표적인 제어 매개변수는 zhparser.seg_with_duality입니다.

7.1 세분화 모드 설정

zhparser.seg_with_duality 매개변수 설정:
- true로 설정: "이중 분할" 모드 활성화. 더욱 세밀하게 분리하며 검색 포괄성이 높아집니다. 예: "자연어처리" → "자연", "언어", "처리", "자연언어", "언어처리".
  sql
```
SET zhparser.seg_with_duality = true;
```
  1
- false로 설정: 더 굵은 단위로 최대 길이 매칭하며, 검색 정확도가 높아집니다. 예: "자연어처리" → ("자연어처리"가 사전에 있으면 그대로 단일 단어로 인식).
  sql
```
SET zhparser.seg_with_duality = false;
```
  1
어느 모드를 선택할지는 서비스 요구사항(정확도/포괄성 등)에 따라 다릅니다. 전역 설정은 역시 postgresql.conf에서 가능합니다.

8. 자주 묻는 질문 (FAQ)

Q: CREATE EXTENSION zhparser;에서 확장을 찾을 수 없다고 나와요? A: ServBay의 PostgreSQL 패키지가 정상적(설치·실행)인지 다시 확인하세요. ServBay는 zhparser 라이브러리를 자동으로 확장 디렉터리에 복사합니다. 문제가 해결되지 않으면 ServBay와 PostgreSQL 설치상태를 체크하고, ServBay를 재시작해보세요.
Q: 사용자 정의 사전이 적용되지 않아요! A: 아래 사항을 확인하세요.
1. zhparser.dict_path가 정확하게 사용자 사전 경로(/Applications/ServBay/etc/scws/custom_dict.txt)로 세팅되어 있는지(경로 대소문자도 주의).
2. zhparser.dict_path 설정 후 SELECT zhprs_reload_dict();를 실행해 사전을 새로고침했는지.
3. 사용자 사전 파일이 올바른 포맷(행마다 하나의 단어)인지.
4. 새 데이터베이스 세션에서 테스트한다면, SET zhparser.dict_path = ...;를 재실행하거나, postgresql.conf에 추가 후 PostgreSQL 재시작이 필요합니다.
5. PostgreSQL 유저가 해당 사전 파일을 읽을 수 있는 권한이 있는지 확인하세요.
Q: 전문 검색 결과가 예상과 달라요! A: 텍스트 검색 설정(chinese)에서 품사-사전 매핑이 올바른지 점검하세요. 또한 zhparser.seg_with_duality 매개변수를 조절해 결과 변화를 체크하거나, SELECT to_tsvector('chinese', '테스트할 중국어 텍스트'); 명령으로 분리 결과를 직접 확인하면 디버깅에 도움이 됩니다. 검색 쿼리(to_tsquery)의 키워드 및 논리 연산자(&, |, !) 사용도 확인하세요.
Q: 전문 검색 성능이 느려요! A: to_tsvector(...) 컬럼에 반드시 GIN 인덱스를 생성했는지 확인하세요. 데이터량이 많은 경우 PostgreSQL 설정을 추가 조정하거나, 더 진보된 인덱스 기술 도입을 고려해야 할 수 있습니다.

9. 요약

ServBay를 이용하면 PostgreSQL에서 zhparser 기반 중국어 전문 검색을 매우 쉽게 구현할 수 있습니다. 확장 활성화, 텍스트 검색 설정, ServBay 내장 scws를 통한 사용자 정의 사전 적용 등 몇 가지 간단한 단계만으로 완성됩니다. zhparser의 주요 활용법과 설정법을 숙지하면, 로컬 개발 환경에서 중국어 텍스트 데이터를 더욱 효율적으로 다루고, 다양한 중국어 기반 애플리케이션 개발에 튼튼한 기반을 마련할 수 있습니다.

ServBay 중국어 전문 검색: zhparser 사용 가이드 ​

1. 개요 ​

2. 사전 준비 ​

3. zhparser 확장 설치(활성화) ​

4. zhparser 설정 ​

5. zhparser를 이용한 전문 검색 ​

5.1 예제 테이블 및 데이터 생성 ​

5.2 전문 검색 인덱스 생성 ​

5.3 전문 검색 쿼리 실행 ​

6. ServBay 내장 scws로 사용자 정의 사전 구축하기 ​

6.1 사용자 정의 사전 파일 만들기 ​

6.2 zhparser에 사용자 정의 사전 적용 ​

6.3 사전 재로딩 ​

7. 형태소 분석 모드 조정 ​

7.1 세분화 모드 설정 ​

8. 자주 묻는 질문 (FAQ) ​

9. 요약 ​