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

바른의 형태소 분석은 LanguageService 하나에 모두 들어 있습니다. 이 서비스는 Tokenize, AnalyzeSyntax, AnalyzeSyntaxList, AnalyzeSyntaxRaw 네 메서드를 제공합니다. 네 메서드는 같은 모델을 쓰지만, 분석 깊이·입력 형태·후처리 적용 여부가 조금씩 다릅니다.

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

네 메서드 비교

메서드	입력	출력 핵심	문장 분할	후처리	대표 용도
`Tokenize`	단일 문서(`Document`)	어절·토큰 분절 결과	옵션	—	분절·토큰화만 필요할 때
`AnalyzeSyntax`	단일 문서(`Document`)	문장→어절→형태소(47품사)	`auto_split_sentence`	복합명사·동사 분해, 자동 띄어쓰기·붙여쓰기	전체 형태소 분석
`AnalyzeSyntaxList`	문장 배열(`sentences[]`)	입력 순서대로 문장별 분석	분할 안 함	복합명사·동사 분해, 자동 띄어쓰기·붙여쓰기	배치·순서/위치 추적
`AnalyzeSyntaxRaw`	단일 문서(`Document`)	순수 모델 추론 결과	`auto_split_sentence`	없음	모델 성능 평가, BigKinds 재태깅, WSD

공통 요청 옵션

각 메서드별로 지원하는 옵션입니다.

옵션	`AnalyzeSyntax`	`AnalyzeSyntaxList`	`AnalyzeSyntaxRaw`	`Tokenize`
`encoding_type`	✔	✔	✔	✔
`auto_split_sentence`	✔	—	✔	—
`auto_spacing`	✔	✔	—	✔
`auto_jointing`	✔	✔	—	—
`custom_dict_names`	✔	✔	—	—

AnalyzeSyntaxRaw의 사용자 사전·띄어쓰기 옵션

AnalyzeSyntaxRaw는 순수 모델 출력을 보장하기 위해 custom_dict_names, auto_spacing, auto_jointing을 지원하지 않습니다. auto_split_sentence만 작동합니다.

호출 흐름

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

응답 구조

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

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

Morpheme에는 형태(text), 태그(tag, 47품사), 확신도(probability), 단어 출처(out_of_vocab), 사용된 사전 이름(custom_dict_name)이 담깁니다.
Sentence.refined는 띄어쓰기 등을 보정한 결과 문장을 담습니다. (AnalyzeSyntaxRaw는 후처리를 하지 않으므로 이 값이 비어 있을 수 있습니다.)

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

네 메서드 모두 분절(seg-model.onnx)·분절 연동 품사 태깅(slot-tag-model.onnx)·품사 태깅(tag-model.onnx) 같은 모델을 사용합니다. 차이는 "입력을 어떻게 받고, 결과를 어디까지 돌려주느냐"입니다. 그래서 메서드를 바꿔도 분석 품질은 동일하지만, AnalyzeSyntaxRaw는 복합명사·복합동사 분해가 없으므로 AnalyzeSyntax보다 토큰 수가 적을 수 있습니다.

자주 묻는 질문

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

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

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

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

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

custom_dict_names는 AnalyzeSyntax·AnalyzeSyntaxList 요청에만 지정할 수 있습니다. AnalyzeSyntaxRaw는 순수 모델 출력이 목적이므로 사용자 사전을 지원하지 않습니다.

Q. AnalyzeSyntaxRaw는 언제 쓰나요?

복합명사·복합동사 분해나 자동 띄어쓰기 없이 모델이 출력한 그대로를 받아야 할 때 씁니다. 대표 사례는 모델 성능 평가, BigKinds 대용량 말뭉치 재태깅, WSD(단어 의미 중의성 해소) 파이프라인입니다.