Hermes 에이전트 로컬 LLM 연동법: Ollama·vLLM·SGLang 커스텀 엔드포인트 설정 정리

핵심 메시지

• Hermes에는 아직 로컬 Ollama 전용 프로바이더가 없어, 목록 아래쪽의 커스텀 엔드포인트로 직접 등록해야 한다.
• Hermes가 WSL에 있고 Ollama가 윈도우에 있으면 루프백 주소로는 접근되지 않는다. Ollama가 외부 접속을 받도록 환경 변수를 설정한 뒤 PC의 IP를 Base URL 호스트로 넣어야 한다.
• API 호환 모드를 잘못 고르면 통신 자체가 되지 않는다. 자동 감지, OpenAI 채팅 컴플리션, OpenAI 응답 API, Anthropic API 네 가지 중 대개는 자동 감지로 해결된다.
• vLLM과 SGLang을 붙일 때는 실행 인자가 핵심이다. 최대 컨텍스트 길이, 쓰는 모델에 맞는 툴 콜 파서와 추론 파서, 그리고 Hermes 쪽에 입력할 모델 이름을 정하는 인자를 맞춰야 한다.
• 이미 등록한 프로바이더의 값을 일부만 고치려면 설정 파일을 편집해야 하는데, 영상은 지우고 다시 등록하는 편이 간단하다고 권한다.

쉽게 이해하기

Hermes는 OpenClaw 대안으로 주목받는 에이전트지만 안내 문서가 불친절해 로컬 LLM을 붙이려다 막히는 사람이 많다. 영상은 개인이 가장 많이 쓰는 Ollama 연동부터 시작해, 하드웨어를 바꾸지 않고도 추론 속도를 끌어올릴 수 있는 vLLM과 SGLang까지 함께 다룬다. 목표는 단순히 로컬 모델을 붙이는 데서 끝내지 않고 서빙 엔진 선택의 폭을 넓히는 것이다. 시연은 Hermes를 WSL에 설치한 리눅스 환경에서 진행된다.

Ollama 연동은 프로바이더 등록 명령을 실행하는 데서 시작한다. 목록에 보이는 클라우드 항목은 다른 서비스이므로 내 PC의 Ollama를 쓰려면 커스텀 엔드포인트를 골라야 한다. Base URL에 Ollama의 기본 주소와 포트를 넣고 뒤에 /v1을 붙이며, API 키는 비워 둔다. 이어서 API 호환 모드를 고르는데 네 선택지는 URL 패턴으로 형식을 자동 판별하는 방식, 대부분의 서빙 엔진이 지원하는 OpenAI 채팅 컴플리션 형식, GPT 계열이 주로 쓰는 OpenAI 응답 API, 그리고 Claude 계열을 붙일 때 쓰는 Anthropic API다. 영상은 호환이 잘 되는 자동 감지를 권한다.

여기서 가장 걸리기 쉬운 지점이 주소다. Hermes와 Ollama가 같은 WSL에 있으면 루프백 주소를 그대로 써도 되지만, Hermes는 WSL에 있고 Ollama는 윈도우에 있으면 Ollama가 기본적으로 루프백에만 묶여 있어 접근할 수 없다. 환경 변수로 외부 접속 바인딩을 허용하고, 명령 프롬프트에서 확인한 PC의 IP를 Base URL 호스트로 넣어야 한다. 모델 이름은 Ollama 프로세스가 켜져 있으면 등록된 목록이 함께 보이고, 컨텍스트 크기는 엔터만 눌러 자동 감지에 맡길 수 있다. 다만 Hermes가 64,000 이상을 요구하므로 부족하다고 표시되면 직접 값을 지정한다.

vLLM 연동은 두 단계로 나뉘는데 첫 단계인 실행 인자 설정이 특히 중요하다. 영상은 도커로 vLLM을 띄우고 최대 컨텍스트 길이를 65536으로 지정하며, 쓰는 모델에 맞춘 툴 콜 파서와 추론 파서를 함께 넘긴다. 파서 값은 모델 계열마다 다르므로 문서의 표를 확인해야 한다. 마지막으로 지정하는 제공 모델 이름 인자는 나중에 Hermes에 모델 이름으로 입력할 값이다. Hermes 쪽 등록은 Ollama와 같은 커스텀 엔드포인트 방식이고, 컨테이너를 8000 포트에 묶었으므로 그 주소 뒤에 /v1을 붙인다.

SGLang도 도커로 띄우며 절차가 vLLM과 거의 같다. 최대 컨텍스트 크기를 정하는 인자 이름이 다르다는 점 정도가 차이이고, 툴 콜 파서와 추론 파서 지정 방식도 비슷하다. SGLang 프로세스를 미리 켜 둔 상태로 등록을 진행하면 Hermes가 엔진과 통신해 사용할 모델 이름을 먼저 제안해 주는 모습도 확인된다. 프로바이더 값을 일부만 수정하려면 설정 파일을 편집기로 열어야 해서, 영상은 그냥 삭제하고 다시 만드는 방법을 추천한다. AMD GPU나 맥 애플 실리콘 환경은 설치 방식이 달라 별도 문서를 참고하라고 안내한다.

주요 인사이트

• 로컬 LLM을 붙이는 작업의 난이도는 모델이 아니라 경계에 있다. WSL과 윈도우 사이의 루프백 주소 문제, 주소 뒤에 붙이는 /v1, API 호환 모드 선택이 실제로 통신을 막는 지점이다.
• 서빙 엔진 선택 자체가 성능 레버가 된다. 같은 하드웨어에서도 Ollama 대신 vLLM이나 SGLang을 쓰면 추론 속도를 높일 수 있다는 것이 영상이 세 엔진을 함께 다루는 이유다.
• 에이전트가 도구를 쓰게 하려면 툴 콜 파서를 모델에 맞게 지정해야 한다. 파서 값은 모델 계열마다 달라서 문서의 표를 확인하지 않으면 도구 호출이 동작하지 않는다.
• Hermes는 최소 64,000 토큰 이상의 컨텍스트를 요구한다. 자동 감지 결과가 부족하다고 나오면 값을 직접 지정해야 하므로, 작은 모델을 쓸 때 확인이 필요하다.
• 붙는 것과 잘 쓰이는 것은 다르다. 시연에서 파라미터가 작은 모델은 답변에 중국어가 섞여 나왔지만 도구 호출 자체는 정상적으로 동작했다.

자주 묻는 질문

관련 AI 소식