LanguageService 메서드 한눈에

LanguageService 메서드 한눈에 (Tokenize/AnalyzeSyntax/AnalyzeSyntaxList)

바른의 형태소 분석은 LanguageService 하나에 모두 들어 있습니다. 이 서비스는 Tokenize, AnalyzeSyntax, AnalyzeSyntaxList 세 메서드를 제공합니다. 세 메서드는 같은 입력 문서를 받지만, 분석 깊이와 입력 형태가 조금씩 다릅니다.

이 문서는 세 메서드의 입력·출력·용도를 한 표로 정리해, 상황에 맞는 메서드를 빠르게 고를 수 있도록 돕습니다.

세 메서드 비교

메서드	입력	출력 핵심	문장 분할	대표 용도
Tokenize	단일 문서(Document)	어절·토큰 분절 결과	옵션	분절·토큰화만 필요할 때
AnalyzeSyntax	단일 문서(Document)	문장→어절→형태소(47품사)	auto_split_sentence	전체 형태소 분석
AnalyzeSyntaxList	문장 배열(sentences[])	입력 순서대로 문장별 분석	분할 안 함	배치·순서/위치 추적

공통 요청 옵션

세 메서드는 아래 옵션을 공유합니다(메서드별로 일부만 해당).

옵션	설명
encoding_type	위치(offset) 계산 기준. NONE/UTF8/UTF16/UTF32
auto_spacing	띄어쓰기 보정(예: 아름다운강산 → 아름다운 강산)
auto_jointing	붙여쓰기 보정(예: 떨여 졌는데 → 떨어졌는데)
custom_dict_names	사용자 사전 여러 개 지정. 먼저 나온 사전이 우선
auto_split_sentence	AnalyzeSyntax만 해당. false면 LF 기준 분할

호출 흐름

graph TD
  D[입력 텍스트] --> C{무엇이 필요한가?}
  C -->|분절/토큰만| TK[Tokenize]
  C -->|품사까지 단일 문서| AS[AnalyzeSyntax]
  C -->|문장 배열·순서 유지| AL[AnalyzeSyntaxList]
  AS --> R[Sentence → Token → Morpheme]
  AL --> R

응답 구조

AnalyzeSyntax·AnalyzeSyntaxList의 응답은 동일한 계층 구조입니다. 문장(Sentence)은 어절(Token)의 배열이고, 어절은 형태소(Morpheme)의 배열입니다. 각 조각은 위치 정보를 담은 TextSpan(content, begin_offset, length)으로 표현됩니다.

service LanguageService {
  rpc AnalyzeSyntax(AnalyzeSyntaxRequest) returns (AnalyzeSyntaxResponse);
  rpc AnalyzeSyntaxList(AnalyzeSyntaxListRequest) returns (AnalyzeSyntaxListResponse);
  rpc Tokenize(TokenizeRequest) returns (TokenizeResponse);
}

• Morpheme에는 형태(text), 태그(tag, 47품사), 확신도(probability), 단어 출처(out_of_vocab), 사용된 사전 이름(custom_dict_name)이 담깁니다.
• Sentence.refined는 띄어쓰기 등을 보정한 결과 문장을 담습니다.

세 메서드는 같은 모델을 씁니다

세 메서드 모두 분절(seg-model.onnx)·품사 태깅(tag-model.onnx) 같은 모델을 사용합니다. 차이는 "입력을 어떻게 받고, 결과를 어디까지 돌려주느냐"입니다. 그래서 메서드를 바꿔도 분석 품질은 동일합니다.

자주 묻는 질문

Q. AnalyzeSyntax와 AnalyzeSyntaxList는 무엇이 다른가요?

AnalyzeSyntax는 단일 문서를 받아 내부에서 문장을 분할(auto_split_sentence)할 수 있습니다. AnalyzeSyntaxList는 이미 나뉜 문장 배열을 받아 입력 순서를 그대로 유지합니다. 입력 문장의 순서·위치 추적이 중요하면 AnalyzeSyntaxList가 적합합니다.

Q. Tokenize만으로 품사를 알 수 있나요?

Tokenize는 분절·토큰화에 초점이 있습니다. 47품사 형태소 분석 결과가 필요하면 AnalyzeSyntax나 AnalyzeSyntaxList를 사용하세요.

Q. 사용자 사전은 모든 메서드에서 쓸 수 있나요?

custom_dict_names는 AnalyzeSyntax·AnalyzeSyntaxList 요청에 공통으로 지정합니다. 여러 개를 넣으면 먼저 지정한 사전이 우선 적용됩니다.

도움이 되었나요?

의견 보내기