목적
파트너사 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 과정에서 생긴 잔재 컨테이너입니다. 이미지 구조를 확인하느라 띄웠다가 멈춘 컨테이너가 몇 개 있는데, 작동에는 영향이 없어 시간 날 때 지우면 되는 정도입니다.
