☘ HWPX CLOVIS 사용자 매뉴얼

1제품 개요

HWPX CLOVIS(마스코트 클로비스)는 손글씨·스캔이 섞인 수학 문제지 PDF나 이미지를 받아, 글자와 수식을 정확히 판독하고 풀이·해설까지 붙여 아래아한글에서 그대로 편집할 수 있는 .hwpx 시험지로 자동 생성하는 프로그램입니다.

핵심 처리 단계는 다음과 같습니다.

2준비물과 전제조건

3설치와 실행

HWPX CLOVIS는 전용 파이썬 런타임까지 함께 들어 있는 자기완결 설치본입니다. 별도 설치 과정이 없습니다.

1. 받은 HWPX CLOVIS 폴더를 원하는 위치에 둡니다. (예: C:\HWPX CLOVIS)
2. 폴더 안의 run_hwpx_clovis.bat 파일을 더블클릭합니다.
3. 잠시 후 네온 테마의 검은 창이 뜨면 실행에 성공한 것입니다.

폴더 구조 (참고)

4최초 설정 — 서버 로그인 · API 키 · 저장 폴더

프로그램을 처음 켜면 세 가지를 먼저 지정해야 작업을 시작할 수 있습니다.

1. 화면 가운데의 클로비스 얼굴(마스코트)을 클릭하거나, 왼쪽 아래 LOGIN 버튼을 눌러 설정창을 엽니다.
2. ① 서버 빌드(렌탈)에서 발급받은 아이디·비밀번호로 「서버 로그인」을 합니다. 빌드는 서버에서 수행되므로 로그인(구독)이 있어야 작업이 완료됩니다. (서버 주소는 고정되어 있어 입력할 필요가 없습니다)
3. ② API 사용자 관리에서 「API 키 불러오기」를 누르고, 본인 Gemini 키를 입력합니다. 한 번 등록하면 암호화되어(users.enc) 저장되므로 다음부터는 ID·비밀번호로 불러옵니다.
4. ③ 작업 저장 폴더에서 결과 .hwpx가 저장될 폴더를 지정합니다. (기본값 C:/Autohwp/workspace)
5. 저장을 눌러 설정창을 닫습니다.

5설정창 상세 — ① ~ ⑤

④ 동작 옵션 — 생성 유형·AI 병렬처리 호출 수·역할별 모델

• HWPX 생성 유형 — 시험지 판형을 A4 1단(기본)과 B4 2단 중에서 고릅니다. 어떤 판형이 언제 유리한지는 10장에서 자세히 안내합니다.
• AI 병렬처리 호출 수 — 문제를 한꺼번에 몇 개씩 AI로 보낼지(병렬 처리)입니다. 기본 8, 최대 30. 실제 적용값은 안전을 위해 설정값과 「작업 수 ÷ 2」 중 작은 값이 됩니다.
• 역할별 모델 — 작업 성격에 맞춰 서로 다른 AI 모델을 고를 수 있습니다. 이 선택권은 사용자를 위한 것입니다. 가성비 모델로 비용을 아낄지, 최고 사양으로 가장 안정된 고급 자료를 만들지 — 자료 성격에 맞춰 직접 정하세요.

  역할	용도	어느 작업에 쓰이나
  크롭·검출	영역·문제 검출 단계	크롭 창의 자동검출
  OCR·수식	글자·수식 판독 (해설 없음)	OCR만 작업
  OCR+AI해설	판독 + 풀이 생성 (품질 핵심)	OCR+해설 · AI해설 작업 (2차검수 포함)
  이미지개선	도형 개선용 이미지 모델	도형 개선 옵션(과금)

  작업 버튼을 누르면 위 표대로 자동 연결됩니다 — OCR만 실행하면 OCR·수식 모델이, 해설이 들어가는 작업이면 OCR+AI해설 모델이 쓰이므로, 한 번 정해 두면 매번 바꿀 필요가 없습니다.

6기본 작업 흐름 한눈에

1. PDF·이미지 불러오기 — 메인 화면에서 자료를 엽니다.
2. 크롭 창에서 문제 영역 지정 — 문제 하나하나에 네모 박스를 그립니다. (1박스 = 1문제)
3. 작업 버튼 선택 — OCR / 해설 / 변형 등 원하는 버튼을 누릅니다.
4. 작업 설정 다이얼로그 확인 — 안내문과 옵션(미주·원본삽입·2차검수·도형개선)을 확인하고 Enter로 실행합니다.
5. 병렬 처리 진행 — 여러 문제가 동시에 AI로 처리되며 로그에 진행 상황이 찍힙니다.
6. 완료 — 저장 폴더에 .hwpx가 생성됩니다. 아래아한글로 열어 확인합니다.

7크롭(자르기) 창 사용법

크롭 창은 여러 페이지(이미지·PDF)를 하나로 합쳐 넘겨 보며 문제 영역을 지정하는 작업 공간입니다.

1. 박스 그리기 — 문제 한 개를 감싸도록 드래그해 네모를 만듭니다.
2. 읽기 순서 자동 배지 — 박스를 만들면 번호 배지가 붙습니다. 번호는 2단(컬럼) 읽기 순서 (왼쪽 위 → 왼쪽 아래 → 오른쪽 위 → 오른쪽 아래)로 자동 정렬됩니다.
3. 페이지 이동·패닝 — 마우스 휠과 화살표 키로 화면을 이동합니다.
4. 박스 미세 이동 — Ctrl + 화살표로 선택한 박스를 한 칸씩 옮깁니다.
5. 선택/해제 — 선택한 박스만 누적 번호가 매겨지고, 토글·이동 시 번호가 자동 갱신됩니다.

8작업 버튼 6종

왼쪽은 변형 문제 생성, 오른쪽은 판독·해설 작업입니다. 각 버튼은 누르면 안내 다이얼로그가 먼저 뜹니다.

9옵션 4종 상세

2차 검수가 품질을 올리는 원리

1단계에서 OCR만 수행해 깨끗한 문제 본문을 확보한 뒤, 2단계 해설은 그 깨끗한 텍스트를 권위 있는 입력으로 받습니다 (원본 이미지는 도형 참고용으로만 사용). 한 번에 판독·해설을 동시에 시키는 단일 처리의 부하와 오독 전파를 제거하므로, 지저분한 고난도 문제에서 특히 정확합니다.

10시험지 형태 — A4 1단 · B4 2단 · 원본삽입

같은 판독 결과라도 어떤 판형에 담느냐에 따라 쓰임새가 완전히 달라집니다. 설정창 ④ HWPX 생성 유형에서 판형을 고르고, 작업 다이얼로그에서 원본 이미지 삽입을 조합하면 해설지·실전 시험지·검수용 자료를 한 프로그램에서 모두 뽑을 수 있습니다.

111빌드당 문항(박스) 수 안내

한 번의 빌드에 담는 문항(박스) 수에는 옵션 조합별 권장 상한이 있습니다. 이는 사용을 막으려는 제한이 아니라, 1빌드당 최상의 품질을 보장하고 오류를 줄이기 위한 최적화 장치입니다. 작업이 정교할수록 상한이 낮아지는 것이 핵심입니다.

왜 상한이 있나요?

해설·도형개선·2차점검처럼 작업이 정교할수록 문항 하나에 드는 AI 처리량이 커집니다. 한 번에 너무 많이 담으면 누락·오독·시간초과가 늘어 오히려 다시 손봐야 하는 일이 생깁니다. 옵션별 상한은 "한 번에 깔끔하게 끝나는" 안전 구간으로 맞춰져 있어, 양이 많을 땐 나눠서 두 번 돌리는 편이 결과적으로 더 빠르고 정확합니다.

실시간으로 확인하는 법

• 크롭 창의 🔎 자동검출 버튼에 마우스를 올리면 위 상한표가 즉시 표시됩니다.
• 선택한 문항 수는 「선택 N/N」 카운터로 실시간 표시되며, 100을 넘으면 빨간 경고가 뜹니다.
• 학생 시험지 원본(손글씨·촬영본)은 자동검출보다 수동 선택을 권합니다. 불필요한 영역을 빼면 품질과 문항 수를 함께 관리할 수 있습니다.

12복합융합 문제 만들기

1. 크롭 창에서 묶고 싶은 문제들에 박스를 매긴 뒤 메인으로 돌아옵니다.
2. 복합융합문제 버튼을 누르면 전용 설정 패널이 펼쳐집니다.
3. 패널 상단의 빨간 경고 배너(검수 필요)를 확인합니다.
4. 필요 시 원본 삽입 옵션을 켭니다. 융합 해설은 기본적으로 본문 인라인으로 들어갑니다.
5. 실행하면 배지 번호 순서대로 묶여 하나의 융합 문제로 재구성됩니다.

13결과 확인과 후처리

1. 작업이 끝나면 설정창 ③ 작업 저장 폴더에서 지정한 폴더에 .hwpx 파일이 생깁니다. (윈도우 탐색기로 그 폴더를 열어 확인)
2. 파일을 아래아한글로 엽니다. 수식은 편집 가능한 한글 수식으로 들어가 있어 그대로 수정할 수 있습니다.
3. 한글이 설치돼 있으면 열 때 수식 히트박스(클릭 영역)가 자동 보정됩니다.
4. 변형·융합·해설 결과는 사람이 검수한 뒤 사용하십시오.

14안정성 · 검토필요 폴백

대량 처리 중 일부 문제가 실패하더라도 작업 전체가 멈추지 않도록 설계되어 있습니다.

• 검토필요 폴백 — 판독에 실패하거나 시간이 초과된 문제는 버려지지 않고, 원본 이미지 + 【검토 필요】 주석으로 문서에 들어갑니다. 동시에 검토필요_목록.txt 요약 파일이 생성됩니다.
• 자동 재시도 — 일시적 한도 초과(429)는 권장 대기 시간을 읽어 자동 재시도하고, 남은 실패는 한 번 더 일괄 재처리합니다.
• 타임아웃 보호 — 한 문제가 120초를 넘기면 무한 대기 대신 곧바로 검토필요로 처리합니다.
• 중단(STOP) — 진행 중 중단해도 그때까지의 결과는 보존되어 빌드됩니다.

15서버 빌드(렌탈) — 구독 로그인

최종 .hwpx 빌드는 항상 서버에서 수행됩니다(빌드 엔진 보호). 따라서 작업을 완료하려면 서버 로그인(구독)이 반드시 필요합니다.

1. 설정창 ① 서버 빌드(렌탈)를 엽니다. 서버 주소는 고정되어 있어 따로 입력할 필요가 없습니다(오타 방지).
2. 발급받은 아이디·비밀번호를 입력하고 「서버 로그인」을 누릅니다.
3. 성공하면 ✓ 연결됨이 표시됩니다. 이후 모든 빌드가 자동으로 서버에서 처리됩니다.

16트러블슈팅 FAQ

실행 / 설정

품질 / 처리

가장 흔한 함정 — 코드 변경 후 앱 재시작