AnalyzeSyntaxList 배치 호출 최적화

여러 문장을 한 번에 분석할 때는 AnalyzeSyntaxList를 사용합니다. 이 메서드는 문자열 배열(sentences)을 받아, 입력한 순서를 그대로 유지하며 문장별 분석 결과를 돌려줍니다. 문장 분할을 하지 않으므로 입력 경계가 보존됩니다.

이 문서는 AnalyzeSyntaxList로 처리량을 높이고, 문장 순서와 위치를 안전하게 추적하는 방법을 정리합니다. 요청한 문장의 순서 또는 일련 번호와 결과물을 일치시킬 때 유용합니다.

왜 배치인가요

AnalyzeSyntax를 문장마다 한 번씩 호출하면 네트워크 왕복(round-trip)이 문장 수만큼 발생합니다. AnalyzeSyntaxList는 여러 문장을 한 요청으로 묶어 왕복 횟수를 줄입니다.

graph LR
  subgraph 단건 반복
    A1[문장1] --> S1[요청]
    A2[문장2] --> S2[요청]
    A3[문장3] --> S3[요청]
  end
  subgraph 배치 한 번
    B[문장1,2,3 배열] --> SB[요청 1회]
  end

순서·위치 추적

AnalyzeSyntaxList는 문장 분할을 하지 않으므로, 응답의 i번째 문장은 입력의 i번째 문장과 일대일로 대응합니다. 각 형태소의 TextSpan에 담긴 begin_offset·length는 해당 입력 문장 안에서의 위치이며, encoding_type 설정에 따라 값이 달라집니다.

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...", host="api.bareun.ai", port=443)

sentences = [
    "오늘 회의는 오후 세시에 시작합니다.",
    "내일까지 보고서를 제출해 주세요.",
    "감사합니다.",
]
# 문장 배열을 한 번에 분석합니다(순서 유지).
res = tagger.tags(sentences)
for i, sent in enumerate(res.msg().sentences):
    print(i, sent.text.content)

curl -s -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntaxList \
  -H "Content-Type: application/json" \
  -H "api-key: koba-XXXX-..." \
  -d '{
    "sentences": ["오늘 회의는 오후 세시에 시작합니다.", "감사합니다."],
    "language": "ko_KR",
    "encoding_type": "UTF32"
  }'

처리량을 높이는 팁

• 배치 크기: 너무 큰 배열은 메모리·지연을 키웁니다. 수십~수백 문장 단위로 묶어 적당한 크기를 실측해 정하세요.
• 인코딩 일관성: 클라이언트 언어 관례에 맞춰 encoding_type을 고정하세요 (파이썬은 보통 UTF32, 자바는 UTF16, Go·C++는 UTF8).
• 동시성: 여러 배치를 병렬로 보내면 서버 측 멀티플렉싱으로 처리량이 더 올라갑니다.
• 긴 문장: 분절은 160자 단위로 나누어 처리하므로 한 문장이 길어도 분석됩니다.

자주 묻는 질문

Q. AnalyzeSyntaxList는 문장을 다시 나누나요?

아닙니다. AnalyzeSyntaxList에는 auto_split_sentence 옵션이 없으며, 입력한 문장을 그대로 하나의 문장으로 취급합니다. 입력 순서와 경계가 보존됩니다.

Q. 한 요청에 몇 문장까지 넣을 수 있나요?

명시된 고정 상한 대신, 메모리와 지연을 고려해 적당한 배치 크기를 실측해 정하시길 권장합니다. 수십~수백 문장 단위로 나누어 보내면 왕복을 줄이면서도 응답 지연을 관리할 수 있습니다.

Q. 위치(offset)는 무엇을 기준으로 하나요?

각 형태소의 TextSpan.begin_offset은 해당 입력 문장 안에서의 위치이며, 값은 요청한 encoding_type(UTF8/UTF16/UTF32)에 따라 달라집니다.