OCR 파이프라인

컨테이너 재시작

cd ~/ls-stack
docker compose --env-file .env up -d
# 로그 확인
docker compose logs -f easyocr

관련 파일 경로

증상

Label Studio에서 Retrieve Predictions 실행 시 EasyOCR 컨테이너에서 에러 발생

401 Unauthorized
Failed to download via get_local_path

수동 curl로 refresh 테스트 → 성공. EasyOCR 컨테이너 내에서도 수동 실행 시 정상 동작. 네트워크 문제는 아님을 확인.

curl -X POST http://localhost:7070/api/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh": "<PAT_TOKEN>"}'
# → 200 OK + access 토큰 반환

docker exec -it easyocr bash -lc "python - <<'PY'
import os, requests
base = os.environ['LABEL_STUDIO_URL'].rstrip('/')
pat  = os.environ.get('LABEL_STUDIO_API_KEY','').strip()

# 1) PAT -> access 토큰
r = requests.post(
    base+'/api/token/refresh',
    json={'refresh': pat}, timeout=10
)
print('refresh STATUS:', r.status_code, r.text[:200])
acc = r.json().get('access')

# 2) access 토큰으로 API 호출
if acc:
    r2 = requests.get(
        base+'/api/projects',
        headers={'Authorization': f'Bearer {acc}'},
        timeout=10
    )
    print('projects STATUS:', r2.status_code, r2.text[:200])
PY"

모델 선정 고민 과정

2023년에 같은 고민을 한 사람이 있었음 — Transformers-Tutorials GitHub Issue #308에서 'LayoutXLM SER + RE'를 언급.

핵심 문제: Donut 등 기존 모델은 key를 미리 정의해야 하지만, 실제 인보이스는 회사마다 필드가 다르고 계속 바뀜. LayoutXLM SER + RE 방식이라면 fixed key 없이 유연하게 key-value를 추출할 수 있음. → 이 방향으로 LayoutLM 채택을 결정.

한 장의 이미지에 대해 전처리부터 추론까지 수행하는 핵심 모듈

사용자는 자동 생성된 박스를 보고: 잘못된 라벨 수정, 박스 위치 조정/삭제, 누락된 토큰 추가 등의 검수 작업 수행.

문서 + LayoutLM은 이미지 + 사각형 박스(RectangleLabels) 구조로 구성

<View>
  <Image name="image" value="$image" />
  <RectangleLabels name="label" toName="image">
    <Label value="QUESTION" background="#1f77b4" />
    <Label value="ANSWER" background="#2ca02c" />
    <Label value="HEADER" background="#ff7f0e" />
    <Label value="OTHER" background="#9467bd" />
  </RectangleLabels>
</View>

layoutlm_preprocess.py를 Label Studio ML Backend로 포장한 핵심 클래스

class LayoutLMv1Backend(LabelStudioMLBase):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.device = torch.device(
            "cuda" if torch.cuda.is_available() else "cpu"
        )
        self.labels = load_labels(LABELS_PATH)
        self.id2label = {i: lab for i, lab in enumerate(self.labels)}
        self.model = model_load(MODEL_PATH, num_labels)
        self.model.to(self.device)
        self.model.eval()

    def predict(self, tasks, **kwargs):
        predictions = []
        for task in tasks:
            image_url = task["data"]["image"]
            image, words, boxes, actual_boxes = preprocess(image_url)
            word_level_predictions, final_boxes = convert_to_features(
                image, words, boxes, actual_boxes, self.model
            )
            img_w, img_h = image.size

            ls_results = []
            for pred_id, box in zip(
                word_level_predictions, final_boxes
            ):
                raw_label = self.id2label[pred_id]
                entity = iob_to_label(raw_label).upper()
                if entity == "":
                    continue

                x0, y0, x1, y1 = box
                # Label Studio는 퍼센트 좌표(0~100) 사용
                result = {
                    "from_name": "label",
                    "to_name": "image",
                    "type": "rectanglelabels",
                    "value": {
                        "x": x0 / img_w * 100,
                        "y": y0 / img_h * 100,
                        "width": (x1 - x0) / img_w * 100,
                        "height": (y1 - y0) / img_h * 100,
                        "rotation": 0,
                        "labels": [entity]
                    }
                }
                ls_results.append(result)

            predictions.append({"result": ls_results})
        return predictions

[Label Studio 컨테이너]  포트 7070
       |
       |  HTTP /predict
       v
[LayoutLM ML 백엔드 컨테이너]  포트 7073 → 9090
       |
       |  내부에서:
       |   - PNG 이미지 로드
       |   - layoutlm_preprocess.py
       |     (pytesseract + bbox + normalize)
       |   - LayoutLM v1 fine-tuned 모델 로드
       |   - 단어별 BIOES 라벨 예측
       |     → RECTANGLE 박스로 변환
       v
Label Studio UI에 자동 박스 + 라벨 노출

API(서버 스크립트)로 처리하면

Tesseract ML Backend를 직접 호출하고 결과를 Label Studio에 업로드하는 함수

TESSERACT_ML_URL = "http://localhost:9090"
TESSERACT_MODEL_VERSION = "BBOXOCR-auto"

def run_tesseract_and_upload_prediction(task: dict) -> bool:
    """
    1) Tesseract ML backend /predict 호출
    2) Label Studio /api/predictions 로 업로드
    """
    task_id = task.get("id")
    if not task_id:
        return False

    payload = {"tasks": [task]}

    try:
        r = requests.post(
            f"{TESSERACT_ML_URL}/predict",
            headers={"Content-Type": "application/json"},
            data=json.dumps(payload),
            timeout=300,
        )
        r.raise_for_status()
        pred = r.json()
    except Exception as e:
        print(f"[WARN] task {task_id}: "
              f"tesseract /predict 실패 - {e}")
        return False

    # 결과 파싱 (환경마다 키가 다를 수 있음)
    result_item = None
    if isinstance(pred, dict):
        if isinstance(pred.get("results"), list) \
                and pred["results"]:
            result_item = pred["results"][0]
        elif isinstance(pred.get("predictions"), list) \
                and pred["predictions"]:
            result_item = pred["predictions"][0]

    if not result_item:
        return False

    ls_result = result_item.get("result")
    if not isinstance(ls_result, list) or not ls_result:
        return False

    # Label Studio에 prediction 생성
    post_payload = {
        "task": task_id,
        "result": ls_result,
        "model_version": result_item.get(
            "model_version") or TESSERACT_MODEL_VERSION,
        "score": float(result_item.get("score") or 0.0),
    }

    try:
        resp = requests.post(
            f"{LS_URL}/api/predictions",
            headers=HEADERS,
            data=json.dumps(post_payload),
            timeout=60,
        )
        resp.raise_for_status()
        print(f"[INFO] task {task_id}: "
              f"Tesseract prediction 생성 완료(API)")
        return True
    except Exception as e:
        print(f"[WARN] task {task_id}: "
              f"prediction 업로드 실패 - {e}")
        return False

지금까지 했던 것은 SER(Sequence labeling for Entity Recognition)이고, 다음 단계가 RE(Relation Extraction).

OCR → LayoutLMv1 (SER: QUESTION/ANSWER 분류)
  ↓
RE 모델 (Q–A 관계 매칭)
  ↓
Key–Value Pair 생성

LayoutLMv2 / v3 / LayoutXLM 기반의 'SER+RE' 통합 모델 사용이 베스트이나, 라이센스 제약으로 인해 v1 기반 + 커스텀 RE 로직으로 진행.

"Tesseract가 토큰 뿌려주고, 그 토큰을 LayoutLM이 라벨까지 달아서 한 번에 보여주는" 로직이 필요. Label Studio 입장에서는 bbox+text(OCR 결과)와 label(LayoutLM 예측)이 다 포함된 prediction JSON을 주면 됨.

1. 사용자가 PDF 업로드
2. 전처리 (png변환, 해상도 변경)
3. Tesseract OCR → 토큰 + bbox 추출
4. LayoutLM으로 각 토큰에 라벨 예측
   (INVOICE_NUMBER, CUSTOMER_NAME 등)
5. Label Studio 화면에서
   - 토큰 박스(polygon+text) 보이고
   - LayoutLM이 예측한 라벨이 미리 붙어있는 상태
   - 사람이 잘못된 라벨만 수정/추가
6. 저장된 결과 → S3 → 재학습

Label Studio에서 Cloud Storage sync를 30초마다 배치로 돌리되, 이미 sync가 진행 중이면 skip.

# 스크립트 파일
/home/user/cloudstorage_sync.py
/home/user/run_cloudstorage_sync_loop.sh  # 30초마다, 이미 돌고있으면 skip

# 실행
chmod +x /home/user/run_cloudstorage_sync_loop.sh
nohup /home/user/run_cloudstorage_sync_loop.sh \
  >> /home/user/cloudstorage_sync_loop.log 2>&1 &

# 로그 확인
tail -f /home/user/cloudstorage_sync.log       # 파이썬 상세 로그
tail -f /home/user/cloudstorage_sync_loop.log   # 루프 실행 로그

Retrieve Predictions는 서버 내부에서 task N개를 모아서 ML backend에 전달하고 결과를 저장하는 무거운 작업. 한 번에 크게 보내면 응답이 늦어지고 timeout이 발생하며 retry가 중첩되어 서버에 더 큰 부하가 걸림.

"완전한 장애"라기보단 정상적으로도 자주 나올 수 있는 상황. 다만 과부하/지연이 꽤 있는 상태고, 배치가 불안정해질 가능성이 높음.

[TESS] retrieve ... 대상 10개 뽑음
RETRIEVE_API_CHUNK=5 → 5개씩 POST를 2번
첫 POST에서 Read timed out (read timeout=30) 발생
→ retry 하다가 어떤 attempt에서 status=200 성공
→ "Retrieved 5 predictions"
→ 다음 chunk/다음 run에서 또 timeout 반복

"가장 현실적 + 효과 좋은" 추천 순서: