본문으로 건너뛰기

hermes-agent customizing guide: PaddleOCR-VL부터 운영 룰까지

정혜지

2026.05.25

목적

파트너사 archives 자료를 OCR·정리하는 작업에 LLM 에이전트를 결합하려는 의도로 시작했습니다. 공익 목적의 PDF 341건이 대상이고, 텍스트만 뽑는 데서 끝내지 않고 분류·정정·메타데이터 작성까지 에이전트가 이어받게 하려는 구성이었습니다.

이를 위해 호스트 macOS에서 돌리는 PaddleOCR-VL MLX 서버(MCP)와, 도커 컨테이너 안에서 작동하는 hermes-agent(Nous Research)를 연결했습니다. OCR은 로컬에서 GPU 가속을 살리고, LLM 에이전트는 격리된 도커 환경에서 돌리는 두 영역으로 분리한 구성입니다.

마지막 결정은 파트너사가 제공하기로 한 Anthropic API 키의 사용 범위였습니다. 키가 도착하기 전에 계약 범위 안에서만 쓰도록 운영 룰을 미리 확정했고, 인스턴스 자체를 분리해 다른 작업과 섞일 가능성을 차단했습니다.

구축 방법 및 구조

호스트는 macOS·MLX 전용으로 두고, 그 위에 PaddleOCR-VL MLX 서버와 MCP 서버(HTTP)를 올렸습니다. MLX 기반 OCR은 Apple Silicon GPU를 활용해야 성능이 제대로 나오기 때문에, 도커로 묶지 않고 호스트에서 직접 작동시켰습니다.

도커 쪽에서는 nousresearch/hermes-agent:latest 컨테이너를 띄우고, 전용 데이터 디렉토리를 /opt/data로 마운트했습니다. 컨테이너 안에서 생성·수정되는 설정, 로그, 작업 내역은 이 마운트 지점에 모이도록 통일했습니다.

두 영역의 연결은 컨테이너에서 host.docker.internal 주소로 호스트 MCP 서버를 호출하는 형태입니다. 컨테이너 자체에는 OCR 엔진을 두지 않고, 호스트 MCP 서버에 필요할 때마다 요청을 보내는 구성입니다.

키 관리는 컨테이너 설정 파일과 키 값을 분리해 환경변수로 참조하도록 했습니다. 디버깅이나 문제 보고를 위해 설정 파일을 외부와 공유해야 할 때도 키가 노출되지 않게 한 조치입니다.

진행 순서 및 절차

먼저 5월 22일, PaddleOCR-VL MCP 서버를 HTTP로 변환하고 작동을 검증했습니다. 컨테이너에서 외부로 호출해야 하므로, 기존 stdio 방식을 HTTP 엔드포인트로 바꾼 단계였습니다.

다음으로 hermes 도커 이미지를 받아 setup을 대화형 Quick 모드로 실행했습니다. 최대한 보수적으로 사용할 계획이기 때문에 Provider는 Nous Portal(무료), OpenClaw 가져오기는 N, Terminal은 Local, Sudo는 N, Messaging은 Skip으로 선택했습니다.

setup이 끝난 뒤에는 컨테이너 설정 파일에 MCP 서버 항목을 추가해 호스트 OCR 서버를 인식시켰습니다. 이로써 hermes 에이전트가 대화 중에 OCR이 필요하면 호스트 쪽으로 요청을 보낼 수 있게 됐습니다.

OCR을 실제로 사용할 때의 기동 순서는 호스트가 먼저, 컨테이너가 다음입니다. 호스트에서 MLX 서버와 MCP 서버를 띄운 다음 hermes 컨테이너를 실행해야, 컨테이너 안 에이전트가 첫 호출부터 OCR을 쓸 수 있습니다.

이후 파트너사 키 도착에 대비해 archives 전용 인스턴스를 별도로 설계했습니다. 개인용 인스턴스와 데이터 디렉토리·설정을 분리하고, 키가 다른 작업으로 새지 않게 잡아두는 가드 체크리스트도 미리 작성해뒀습니다.

결과 및 향후 계획

현재 메인 hermes 인스턴스는 개인용 setup이 진행 중이고, Provider는 무료인 Nous Portal로 잡혀 있습니다. 우선 동작 검증과 워크플로 다듬기에 쓰는 용도입니다.

archives 전용 인스턴스는 파트너사 키가 도착하면 별도로 셋업할 예정입니다. 키 도착 즉시 작업을 시작할 수 있도록 체크리스트와 폴더 구조까지 미리 정리해둔 상태입니다.

운영 룰은 파트너사 키를 archives 자료에만 쓰는 것으로 확정했습니다. 인스턴스 분리와 환경변수 참조 방식을 함께 묶어, 실수로 다른 작업에 키가 섞일 가능성을 줄였습니다.

남은 정리 작업은 setup 과정에서 생긴 잔재 컨테이너입니다. 이미지 구조를 확인하느라 띄웠다가 멈춘 컨테이너가 몇 개 있는데, 작동에는 영향이 없어 시간 날 때 지우면 되는 정도입니다.

5

함께 이야기해요 5

로그인하고 댓글을 남겨 주세요

MC맥돌 프로필 이미지
MC맥돌2026.05.27

PaddleOCR-VL (기반 모델): 이 모델의 원작자인 바이두(Baidu)는 핵심 프로젝트들을 Apache 2.0 라이선스로 공개하고 있습니다. 상업적 이용, 수정, 배포가 모두 자유롭고 특허 침해 걱정 없이 쓸 수 있는 매우 관대한 라이선스입니다.

이 모델을 MCP 로 연결해서 사용하시는 거죠?

다운받아서 로컬에서 돌릴수 있는건가요? 아니면 클라우드로 연결시켜서 사용하시는 방식인건가요?

자연어회계처리 프로필 이미지

Ocr인식이 대략 몇% 정도 까지 되시는지 궁금합니다!!

정혜지 프로필 이미지
정혜지2026.05.25

이정도로 나왔고, 그전에 30% 정도 Claude code + 수기 검수로 뽑은 게 있었어요. 검수 시에 먹일 수 있는 데이터가 있었어서 조금 더 높게 나온 것 같아요.

판정은 무슨 뜻인지는 저도 좀 헷갈리는데, 기준점 만들어놓고 해당 기준 넘어가면 통과로 치는 것 같네요;

분류

유사도

판정

본문 (5p)

0.978~0.993 (평균 0.984)

✅ Claude v4와 차이가 거의 없음 → 통과

단순 수치표 (5p)

0.910~0.998 (HTML→md 변환 후)

✅ Paddle이 HTML <table>로 뱉는데 → md 변환 거치면 통과

복잡 표·연표 (5p)

0.13~0.77

❌ 실패 (병합셀·연표 구조 소실, 단어 반복 퇴화)

자연어회계처리 프로필 이미지

@정혜지

오오 과거에 ocr인식률 낮다 이랫는데 많이 높아졋네요 이정도면 거히 다된다는건데

정혜지 프로필 이미지
정혜지2026.05.25

@자연어회계처리

여전히 손글씨, 스캔 품질 낮은 건 0.3~0.6따리에요 ㅎ 과거 인식률보다는 훨 나은데 한글 특성상 필기나 20세기 문서는 고민이에요. RAG도 해봤는데 영..ㅎㅎ

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기