CLI에서 바른 사용하기 (샘플 클라이언트)

바른을 코드 작성 없이 빠르게 확인하고 싶을 때는 샘플 클라이언트와 REST 호출이 편합니다. 명령줄에서 한 줄로 형태소 분석을 호출해, 서버가 잘 떠 있는지·키가 유효한지· 분석 결과가 기대와 맞는지를 바로 점검할 수 있습니다.

이 문서는 CLI에서 바른을 빠르게 테스트하는 방법을 정리합니다.

가장 빠른 방법: REST 호출

REST(HTTP/1.1)는 별도 설치 없이 curl만으로 호출할 수 있어, 첫 점검에 가장 빠릅니다.

curl -s -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
  -H "api-key: koba-XXXX-..." \
  -H "Content-Type: application/json" \
  -d '{"document":{"content":"오늘 날씨가 참 좋네요.","language":"ko_KR"},
       "encoding_type":"UTF8"}'

curl -s -X POST http://localhost:5656/bareun.LanguageService/AnalyzeSyntax \
  -H "api-key: koba-XXXX-..." \
  -H "Content-Type: application/json" \
  -d '{"document":{"content":"오늘 날씨가 참 좋네요.","language":"ko_KR"},
       "encoding_type":"UTF8"}'

Python 샘플 클라이언트

bareunpy를 설치하면 짧은 스크립트로 분석 결과를 출력해볼 수 있습니다.

# quick_check.py — 한 문장을 분석해 형태소/품사를 출력합니다.
from bareunpy import Tagger

tagger = Tagger("koba-XXXX-...", host="api.bareun.ai", port=443)
res = tagger.tags(["바른이 잘 동작하는지 확인합니다."])
print(res.pos())     # [(형태, 품사), ...]

pip install bareunpy
python quick_check.py

어디로 연결하나요

빠른 점검 순서

graph LR
  A[서버 주소 확인] --> B[API 키 설정]
  B --> C[curl 또는 샘플 클라이언트 호출]
  C --> D{정상 응답?}
  D -->|예| OK[연동 시작]
  D -->|아니오| E[키·주소·인코딩 점검]

1. 호출 대상 주소(클라우드/설치본/도커)를 정합니다.
2. koba- API 키를 준비합니다(클라우드 호출 시 필요).
3. curl이나 샘플 클라이언트로 한 문장을 분석해 봅니다.
4. 응답이 비정상이면 키·주소·encoding_type을 점검합니다.

자주 묻는 질문

Q. 코드를 짜지 않고 바른을 테스트할 수 있나요?

네. REST(HTTP/1.1)를 지원하므로 curl 한 줄로 AnalyzeSyntax를 호출해 결과를 볼 수 있습니다. 클라우드는 api.bareun.ai:443, 설치본은 localhost:5656으로 호출합니다.

Q. 설치본은 어떤 포트로 호출하나요?

네이티브 설치본과 도커 배포본 모두 기본 포트는 5656입니다. 클라우드는 443(TLS)입니다.

Q. 샘플 클라이언트로는 무엇을 확인하나요?

서버 가용성, API 키 유효성, 분석 결과(형태소·품사)가 기대와 맞는지를 빠르게 확인합니다. 정상 확인 후 실제 애플리케이션 코드로 옮기는 흐름을 권장합니다.

Q. curl로 바른을 호출할 때 어떤 경로를 써야 하나요?

바른 서버는 connect-go로 한 포트에서 gRPC·connect-web·HTTP+JSON을 처리하므로, REST 호출도 Connect 경로 POST /bareun.LanguageService/AnalyzeSyntax를 씁니다. api-key 헤더에 koba- 키를, 본문에 document를 JSON으로 담아 보내면 됩니다.

Q. 파이썬 샘플 클라이언트는 어떻게 설치하나요?

pip install bareunpy로 설치합니다. 이후 Tagger에 koba- 키와 주소를 넣고 한 문장을 분석해 res.pos()로 형태소·품사를 출력하면 빠르게 동작을 확인할 수 있습니다.