내가 쓰는 책 원고, 한국어 맞춤법 자동 검사기 만들기 (네이버·부산대 엔진)
소개
책을 집필하고 있는데, 원고 전체의 맞춤법을 편하게 검사할 방법을 찾고 싶었습니다. 처음엔 단순하게 "국립국어원 어문 규정 사이트를 통째로 지식 데이터로 넣으면 맞춤법 검사가 되지 않을까?" 하는 생각에서 출발했어요. 그런데 파고들다 보니 생각보다 고려할 게 많았습니다. 규정 문서만으로는 검사가 안 되고, 쓸 만한 맞춤법 API도 상황이 계속 바뀌고 있더라고요.
그래서 목표를 이렇게 잡았습니다. 워드(.docx) 원고를 넣으면 자동으로 맞춤법을 검사해서, 어디가 어떻게 틀렸는지 보기 좋게 정리해주는 스크립트를 만드는 것. 최종적으로 네이버 엔진 버전과 부산대 엔진 버전, 두 가지를 완성했습니다.
진행 방법
사용 도구: Claude (Cowork 모드) — 자료 조사, 코드 작성, 검증까지 대화로 진행했습니다.
1단계 — 방향 잡기 (질문으로 시작)
제가 던진 첫 프롬프트는 이거였습니다.
https://korean.go.kr/kornorms/regltn/regltnView.do#a
이 사이트 하위페이지까지 접근 가능해?
맞춤법 검사를 위해 지식데이터로 사용하려고 너무 분량이 많을까?
또는 한국어 맞춤법 검사를 위한 API 있어?
여기서 배운 핵심: 국립국어원 규정 텍스트는 분량이 문제가 아니라(수백 KB라 가벼움), 애초에 "판정 데이터"가 아니라는 것. 규정은 "왜 이렇게 적는가"를 설명하는 원리 문서라서, 실제 검사에는 방대한 표준어 사전과 형태소 분석기가 필요합니다. 규정은 근거 참고용으로는 훌륭하지만 검사 엔진 본체가 될 수는 없었어요.
API 조사 결과도 정리하면: 부산대(바른한글) 검사기가 정확도 최상이지만 비상업·연구용 위주, 네이버는 공식 API가 아니라 내부 엔드포인트라 자주 막힘, 카카오(다음) 오픈 API는 중단됨.
2단계 — 네이버 엔진 버전 만들기
py-hanspell 같은 비공식 파이썬 래퍼를 써보기로 했습니다. 그런데 중요한 함정이 있었어요.
py-hanspell 같은 비공식 파이썬 래퍼 이거 써보고 싶어.
내가 집필하는 책 맞춤법 검사할꺼야 괜찮을 듯~
확인해보니 원조 py-hanspell은 지금 그대로는 안 돌아갑니다. 네이버가 passportKey라는 파라미터를 요구하도록 바꾸면서 KeyError: 'result' 오류가 나거든요(GitHub 이슈 #38, #47, #48). 그래서 이 문제를 반영한 유지보수 포크인 py-aiohanspell을 사용했습니다.
핵심 사용법은 이렇게 간단합니다.
from aiohanspell import spell_checker
result = await spell_checker.check("안녕 하세요. 저는 한국인 입니다.")
print(result.checked) # 교정된 문장
print(result.errors) # 오류 개수
print(result.words) # 단어별 교정 유형
여기에 ① 워드 파일 읽기(python-docx) ② 네이버 500자 제한에 맞춰 문단 자르기 ③ 차단 방지용 딜레이 ④ 변경된 부분만 빨강/초록으로 하이라이트한 HTML 리포트 생성을 붙여서 완성했습니다.
3단계 — 부산대 엔진 버전 만들기 (더 정밀)
부산대 엔진 버전도 하나 더 만들어
부산대 검사기는 오류 위치(start/end), 교정 후보, 그리고 "왜 틀렸는지 도움말 설명"까지 돌려주기 때문에 훨씬 정밀합니다. 핵심 원리는 검사기 웹페이지가 서버로 보내는 요청을 그대로 흉내 내는 것이에요.
import requests, json
url = "https://nara-speller.co.kr/speller/results"
resp = requests.post(url, data={"text1": "되요 외않되".encode("utf-8")})
# 응답 HTML 안에 박혀 있는 data = [ ... ] 덩어리를 뽑아냄
body = resp.text
start = body.find("data = [") + len("data = ")
end = body.find("];", start) + 1
data = json.loads(body[start:end])
for entry in data:
for err in entry["errInfo"]:
print(err["orgStr"], "→", err["candWord"].split("|")) # 틀린말 → 후보들
print("도움말:", err["help"])
이걸로 오류 위치에 첫 번째 후보를 정확히 끼워 넣어 교정본을 만들고, 각 오류의 유형·후보·도움말을 리포트에 담았습니다.
⚠️ 알아둘 점: 부산대 검사기 주소가 최근 옮겨다녔습니다(예전 speller.cs.pusan.ac.kr → 현재 nara-speller.co.kr). 그래서 스크립트 상단에 여러 주소를 넣고 순서대로 시도하도록 만들었어요.
(여기에 실행 화면 / HTML 리포트 캡처 삽입)
결과와 배운 점
완성한 것: 워드 원고를 넣으면 교정리포트.html(검토용, 변경점 하이라이트 + 오류별 설명)과 교정본.docx(교정 반영본)를 자동 생성하는 스크립트 2종(네이버 / 부산대).
배운 점과 꿀팁
첫째, 규정 문서 ≠ 맞춤법 검사기. 국립국어원 규정을 지식으로 넣는 건 "근거 설명"엔 좋지만, 실제 오류 판정은 사전·형태소 분석기가 있는 전용 검사기가 해야 합니다.
둘째, 비공식 래퍼는 "공식 약속"이 아니라 언제든 깨집니다. 검사기는 결국 남의 서버에 심부름 보내는 방식이라, 그쪽이 내부 주소나 파라미터를 바꾸면 멈춥니다(네이버 passportKey 추가, 부산대 주소 이전이 대표 사례). 그래서 홈페이지 주소만 아는 걸로는 부족하고, ①내부 요청 주소 ②파라미터 이름 ③응답 형식, 이 세 가지를 알아야 합니다.
셋째, 대량 호출은 딜레이 필수. 네이버는 요청당 500자 제한이 있어 문단을 잘라 보내야 하고, 너무 빠르게 연속 호출하면 IP가 잠깐 차단됩니다. 요청 사이에 0.6~1.5초 딜레이를 두고, 원고가 길면 장(章)별로 나눠 돌리는 게 안전해요.
시행착오
py-hanspell을 그냥 쓰려다 KeyError: 'result'로 막혔고(→ py-aiohanspell로 해결), 부산대는 옛 주소가 죽어 있어 새 주소로 갈아탔습니다. 또 하나, 클라우드 환경(Claude가 도는 샌드박스)에서는 네이버·부산대 서버 접속이 막혀 있어서 결국 검사는 내 PC에서 직접 돌려야 한다는 것도 알게 됐습니다.
앞으로의 계획 / 도움이 필요한 부분
내 컴퓨터에서 한 챕터씩 두 버전을 다 돌려보고, 교정 품질이 더 나은 쪽으로 정착할 계획입니다. 부산대 엔드포인트가 또 바뀔까 봐 그게 가장 불안한데, 혹시 최신 접속 주소나 더 안정적인 방법을 아시는 분 있으면 공유 부탁드려요. 장기적으로는 LLM + 국립국어원 규정(RAG) 방식과 규칙 기반 검사기를 함께 쓰는 조합도 실험해볼 생각입니다.
도움 받은 글 (옵션)
국립국어원 어문 규정: https://korean.go.kr/kornorms/regltn/regltnView.do
부산대 한국어 맞 춤법/문법 검사기(바른한글): https://nara-speller.co.kr/speller/
py-hanspell (원조, 현재 passportKey 이슈): https://github.com/ssut/py-hanspell
파이썬으로 부산대 검사기 사용하기 (아무튼 블로그): https://hleecaster.github.io/posts/speller_cs_pusan_ac_kr/
카카오 맞춤법 API 중단 안내: https://blog.creation.net/602
