Ollama 로컬 모델을 헤르메스 fallback으로 연결하기

반갑습니다. 이번 부록은 주력 모델(클라우드)이 흔들릴 때를 대비한 안전망을 까는 작업입니다.

평소 헤르메스는 여러분이 정해둔 주력 모델(예: gpt-5.5)로 일합니다. 그런데 클라우드 모델은 가끔 요청 한도 초과(rate-limit), 서버 과부하(5xx), 네트워크 끊김으로 응답을 못 줄 때가 있어요. 그럴 때 내 컴퓨터에서 돌아가는 무료 로컬 모델이 그 한 번을 대신 받아주게 만드는 것이 fallback(폴백, 안전망) 모델입니다.

이 가이드는 Mac 유저와 WSL(윈도우의 리눅스) 유저 모두를 대상으로, Ollama 설치부터 헤르메스 연결·검증까지 풀 코스로 다룹니다. 안전망 모델로는 llama3.2:3b(2GB)를 씁니다. 작으면서도 도구 호출(tool calling)을 지원하고, 무엇보다 컨텍스트 창이 128K로 넓어 헤르메스의 요구치를 여유롭게 넘기기 때문입니다(아래 3단계에서 왜 이게 중요한지 설명합니다).

💡 사전 요구사항: 헤르메스 에이전트가 이미 설치되어 동작 중이어야 합니다. 아직이라면 먼저 헤르메스 에이전트 설치 및 첫 실행 가이드를 끝내고 오세요. (Mac은 Mac 유저 환경 준비, Windows는 WSL v2 설치 참고)

먼저 알아둘 것 — fallback은 "평소엔 안 보이는" 안전망입니다

설정을 시작하기 전에, fallback이 언제 작동하는지 정확히 짚어두면 나중에 헷갈리지 않습니다.

• 주력 모델이 실패할 때만 작동합니다. 실패 조건은 rate-limit · 5xx 과부하 · 연결 오류뿐이에요. 주력이 멀쩡하면 fallback은 한 번도 안 불립니다.
• 턴(turn) 단위로 작동합니다. 새 메시지를 보낼 때마다 헤르메스는 항상 주력 모델부터 다시 시도합니다. 그 턴에서 주력이 실패하면 그 턴에 한해 fallback으로 넘어가고(한 턴에 최대 1회), 다음 메시지에서는 다시 주력부터 시작합니다.
• 그래서 등록을 마쳐도 평소 화면에는 아무 변화가 없는 게 정상입니다. 비상시에만 조용히 인계받습니다.

⚠️ 이 가이드에서 쓰는 llama3.2:3b는 어디까지나 "클라우드가 죽었을 때 최소한 일은 굴러가게" 하는 안전망입니다. 주력 모델의 품질을 그대로 대체하지는 못해요. 메모리(RAM)에 여유가 있다면 뒤의 "자주 만나는 문제"에서 더 큰 모델로 올리는 법을 안내합니다.

Mac과 WSL이 다른 점 (설치·서버 실행만 다릅니다)

좋은 소식은, 모델을 만들고(3단계) 헤르메스에 연결하는(5단계) 부분은 두 환경이 완전히 똑같다는 겁니다. 다른 건 처음 설치 방법과 서버를 띄우는 방식뿐이에요.

💡 컨텍스트 길이를 박는 방법은 Modelfile 방식이 Mac·WSL 동일해서, 이 가이드는 그걸 기본으로 씁니다. (서버 환경변수 방식은 OS마다 위치가 달라 헷갈리기 쉬워요.)

1단계. Ollama 설치

1-1. WSL · Linux 유저

curl -fsSL https://ollama.com/install.sh | sh

설치가 끝나면 서버를 띄웁니다. systemd가 켜진 WSL이라면 아래 두 줄을 실행하세요.

sudo systemctl start ollama
sudo systemctl enable ollama

⚠️ WSL에서 System has not been booted with systemd 에러가 나면, 그 WSL은 systemd가 꺼져 있는 겁니다. 두 가지 중 하나로 해결하세요.

• (권장) /etc/wsl.conf에 아래를 추가하고, 윈도우 PowerShell에서 wsl --shutdown 후 다시 들어옵니다.

  [boot]
  systemd=true
  

• (간단) systemd 없이 그냥 서버를 직접 띄웁니다. 터미널 하나를 이 용도로 열어두세요.

  ollama serve
  

1-2. Mac 유저

curl ... | sh 스크립트는 리눅스 전용입니다. Mac은 둘 중 하나로 설치하세요.

• (A) 앱으로 설치 (가장 쉬움): ollama.com에서 macOS 버전을 받아 Applications로 드래그한 뒤 실행합니다. 메뉴 막대에 라마 아이콘이 뜨고, 서버(11434 포트)가 자동으로 켜집니다.
• (B) Homebrew로 설치: 터미널이 익숙하면 이게 깔끔합니다.

  brew install ollama
  brew services start ollama   # 부팅 시 자동 실행. 한 번만 띄우려면: ollama serve
  

확인 (Mac · WSL 공통)

서버가 떴는지 확인합니다.

curl http://127.0.0.1:11434/api/tags

JSON 응답({"models":[...]} 형태)이 돌아오면 서버가 살아 있는 겁니다.

2단계. 모델 받기 — 왜 llama3.2인가

안전망용 모델은 세 조건을 모두 만족해야 합니다. ① 작아서 내 PC에서 돌아갈 것, ② 도구 호출(tool calling) 을 지원할 것(헤르메스는 단순 챗봇이 아니라 도구를 드는 에이전트라서요), ③ 컨텍스트 창이 64K 이상일 것(헤르메스의 하드 요구치, 3단계에서 자세히).

llama3.2:3b는 셋 다 만족합니다. 2GB로 가볍고 함수 호출에 파인튜닝돼 있어요. 무엇보다 컨텍스트가 128K(131,072 토큰) 라 64K 관문을 여유롭게 넘습니다.

ollama pull llama3.2:3b
ollama list

ollama list에 llama3.2:3b가 보이면 됩니다.

⚠️ 왜 qwen2.5·qwen3 같은 더 유명한 소형 모델을 안 쓰나요? 작고 도구 호출도 되지만, 컨텍스트 창이 헤르메스 요구치(64K)에 못 미칩니다 (qwen2.5 = 32K, qwen3 = 40K). 그러면 헤르메스가 아예 거부해요(3단계 참고). 그래서 128K짜리 llama3.2 를 씁니다.

3단계. 헤르메스용 64K 컨텍스트 모델 만들기 (Mac · WSL 동일)

여기가 이 가이드에서 가장 중요한 대목이라 왜 인지 꼼꼼히 짚을게요.

헤르메스는 매 요청마다 도구 설명(tool schema) + 시스템 프롬프트라는 큰 고정 분량을 모델에게 먼저 보냅니다. 그래서 컨텍스트 창이 작으면 일을 못 해요. 헤르메스는 최소 64,000 토큰 컨텍스트를 요구하고, 모자라면 다음과 같이 실행 자체를 거부합니다.

Failed to initialize agent: Model ... has a context window of 40,960 tokens,
which is below the minimum 64,000 required by Hermes Agent.

여기서 입문자가 꼭 알아야 할 두 가지가 있습니다.

1. 헤르메스는 모델의 "타고난(native) 컨텍스트"를 봅니다. Ollama에 "이 모델 컨텍스트 얼마야?"라고 물어서(/api/show) 그 값으로 판단해요. 이건 모델이 학습된 한계치라, 사용자가 마음대로 못 올립니다.
2. 그래서 num_ctx로는 64K 관문을 통과시킬 수 없습니다. num_ctx는 "이번에 메모리를 얼마나 쓸까"라는 런타임 설정일 뿐이고, 모델의 타고난 한계(예: qwen3는 40,960)를 넘기면 오히려 그 한계로 깎입니다. 그래서 작은 모델에 num_ctx 64000을 줘도 화면엔 40,960으로 뜨고 거부당해요.

결론은 단순합니다. 타고난 컨텍스트가 64K 이상인 모델을 골라야 합니다. 우리가 2단계에서 llama3.2(128K)를 받은 이유가 이것입니다.

그러면 num_ctx는 왜 설정하냐고요? 헤르메스가 "이 모델 128K나 되네"라고 믿고 긴 컨텍스트로 요청을 보내는데, Ollama의 런타임 기본 컨텍스트는 그보다 훨씬 작아서(보통 수천 토큰) 그냥 두면 대화가 잘립니다. 그래서 런타임 창을 64K로 맞춰 둡니다. llama3.2는 128K가 한계라 64000은 안 깎이고 그대로 적용됩니다.

Modelfile은 딱 두 줄짜리 텍스트 파일입니다. echo로 한 줄씩 만듭니다.

echo 'FROM llama3.2:3b' > llama3.2-3b-64k.Modelfile
echo 'PARAMETER num_ctx 64000' >> llama3.2-3b-64k.Modelfile

💡 왜 echo 두 줄로 만드나요? 인터넷에 흔한 cat > 파일 <<'EOF' ... EOF (heredoc) 방식은 터미널에 붙여넣을 때 자주 깨집니다. cat이 입력 대기 상태로 멈추고([1]+ Stopped), 뒤이은 FROM·PARAMETER 줄이 따로 실행돼 command not found가 나면서 빈 파일이 만들어져요. echo 두 줄은 각각 독립 명령이라 붙여넣기에서 안 깨집니다. (에디터에 익숙하면 nano llama3.2-3b-64k.Modelfile로 직접 두 줄을 적어도 됩니다.)

내용이 제대로 들어갔는지 확인하고, 모델을 굽습니다.

cat llama3.2-3b-64k.Modelfile     # FROM / PARAMETER 두 줄이 보이면 OK
ollama create llama3.2-3b-64k -f llama3.2-3b-64k.Modelfile

⚠️ Error: no FROM line이 나면 Modelfile이 비어 있다는 뜻입니다. 위 cat으로 두 줄이 보이는지 먼저 확인하세요(heredoc으로 만들다 깨진 경우가 대부분). 빈 파일이면 echo 두 줄을 다시 실행해 만들면 됩니다.

4단계. OpenAI 호환 엔드포인트 확인

Ollama는 11434 포트에서 OpenAI 호환 API(/v1) 도 함께 엽니다. 헤르메스는 바로 이 경로로 로컬 모델과 대화합니다.

curl http://127.0.0.1:11434/v1/models

목록에 llama3.2-3b-64k가 보여야 합니다. 실제 응답까지 확인하고 싶다면 아래처럼 호출합니다.

curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.2-3b-64k","messages":[{"role":"user","content":"OK라고만 답해"}]}'

choices[0].message.content에 응답이 들어오면 엔드포인트가 정상입니다.

5단계. 헤르메스 fallback 체인에 등록

이제 헤르메스에게 "주력이 실패하면 이 로컬 모델을 써라"라고 알려줍니다.

먼저 설정 파일 위치를 확인합니다.

hermes config path

출력된 config.yaml을 엽니다(hermes config edit로 에디터로 열거나, 위 경로를 직접 편집해도 됩니다). 파일 맨 위 레벨(들여쓰기 없는 위치) 에 아래 블록을 추가합니다.

fallback_providers:
  - provider: custom
    model: llama3.2-3b-64k
    base_url: http://127.0.0.1:11434/v1

각 줄의 의미입니다.

• provider: custom — OpenAI 호환 임의 엔드포인트라는 뜻입니다. (ollama·vllm·llamacpp도 모두 내부적으로 custom으로 매핑됩니다.)
• model: — 3단계에서 만든 64K 모델 이름.
• base_url: — 로컬 Ollama의 OpenAI 호환 주소. 이 값이 있으면 provider보다 우선해 여기로 요청을 보냅니다.

💡 API 키는 넣지 않습니다. Ollama는 인증이 필요 없고, 헤르메스는 키 없는 로컬 엔드포인트를 만나면 자동으로 임시 placeholder를 채워 보냅니다. (api_mode도 기본값이 chat_completions라 적을 필요가 없습니다.)

이미 fallback_providers가 있다면, 새로 만들지 말고 리스트 맨 아래에 항목(- provider: ...)만 추가하세요. 위에서부터 순서대로 시도됩니다.

💡 인터랙티브 대안: hermes fallback add를 치면 모델 선택 화면이 뜹니다. 다만 로컬 엔드포인트는 위처럼 YAML에 직접 적는 편이 명확해서 권장합니다.

6단계. 확인

등록이 됐는지 봅니다.

hermes fallback list

Fallback chain에 llama3.2-3b-64k (via custom)과 [http://127.0.0.1:11434/v1]이 보이면 등록 완료입니다.

그런데 앞에서 말했듯, 주력 모델이 멀쩡하면 fallback은 평소에 안 불립니다. 그래서 "정말 로컬 모델이 도는지" 눈으로 보고 싶다면, 테스트용 별칭(alias)을 잠깐 만들어 직접 한 번 태워봅니다. config.yaml에 아래를 추가하세요.

model_aliases:
  llama-local:
    model: llama3.2-3b-64k
    provider: custom
    base_url: http://127.0.0.1:11434/v1

그리고 이 별칭으로 일회성 호출을 합니다.

hermes -m llama-local -z "OK라고만 답해줘"

has a context window... 에러 없이 로컬 모델이 답하면 연결이 정상입니다. 이 model_aliases 블록은 테스트용이라, 확인이 끝나면 지워도 fallback 동작에는 영향이 없습니다.

추천 최종 구성

입문자용으로 정리하면 config.yaml은 이런 모습이 됩니다.

model:
  provider: openai-codex # ← 본인의 기존 주력 provider
  default: gpt-5.5 # ← 본인의 기존 주력 모델

fallback_providers:
  - provider: custom
    model: llama3.2-3b-64k
    base_url: http://127.0.0.1:11434/v1

model: 블록은 손대지 말고(여러분이 이미 쓰던 값), 아래에 fallback_providers:만 더해주면 됩니다.

자주 만나는 문제

has a context window of N tokens, which is below the minimum 64,000 에러가 뜨면, 그 모델의 타고난 컨텍스트가 64K 미만이라 헤르메스가 거부한 겁니다. num_ctx로는 못 올립니다(모델의 학습 한계라서요). 대표적으로 qwen2.5(32K)·qwen3(40K)이 여기 걸립니다. 해결책은 타고난 컨텍스트가 64K 이상인 모델로 바꾸는 것뿐입니다. 이 가이드의 llama3.2(128K)가 그래서 안전합니다.

address already in use (포트 11434) 가 떠도 정상입니다. systemd 서비스나 brew 서비스, 또는 Mac 앱이 이미 서버를 띄운 상태라는 뜻이에요. ollama serve를 또 칠 필요가 없습니다.

(WSL) System has not been booted with systemd 가 나오면, 그 WSL은 systemd가 꺼져 있는 겁니다. 1-1단계의 wsl.conf 설정을 적용하거나, 간단히 ollama serve를 별도 터미널에 띄워두세요.

Error: no FROM line 은 Modelfile이 비어 있다는 뜻입니다(heredoc으로 만들다 깨진 경우가 대부분). cat llama3.2-3b-64k.Modelfile로 두 줄이 보이는지 확인하고, 비었으면 3단계의 echo 두 줄을 다시 실행하세요.

메모리 부족(OOM)으로 모델이 죽는 경우. llama3.2:3b는 2GB로 가볍지만, 컨텍스트를 64K로 키우면 실행 중 메모리가 더 듭니다. RAM이 빠듯하면 더 작은 llama3.2:1b(약 1.3GB, 똑같이 128K 컨텍스트)로 같은 방식(3단계 Modelfile의 FROM만 llama3.2:1b로 교체)으로 구워 쓰면 됩니다. (WSL은 C:\Users\<유저>\.wslconfig의 memory= 값으로 할당 메모리 상한을 조정할 수 있습니다.)

fallback이 불렸는데 답 품질이 떨어질 때. 3b는 비상용 소형 모델이라 주력만큼의 품질은 기대하기 어렵습니다. RAM에 여유가 있으면 llama3.1:8b(약 4.7GB, 128K 컨텍스트, tool calling 지원)를 받아 같은 방식으로 64K 모델을 구워 쓰면 더 든든합니다. (반대로 qwen 계열은 컨텍스트가 64K에 못 미쳐 fallback에는 부적합합니다.)

마무리, 한 장 요약

• fallback = 클라우드 주력 모델이 흔들릴 때의 안전망. 평소엔 안 보이지만, rate-limit·장애 때 그 턴만 자동으로 로컬 모델이 인계받습니다.
• 로컬 Ollama라서 무료 · 오프라인 · API 키 불필요. 모델은 컨텍스트 128K + 도구 호출 + 소형인 llama3.2:3b를 골랐습니다.
• 핵심은 딱 세 가지입니다.
  1. 타고난 컨텍스트 ≥ 64K 모델 고르기 — 헤르메스의 하드 요구치. num_ctx로는 못 올리니 llama3.2(128K)처럼 native로 넓은 모델을 쓴다.
  2. config.yaml의 fallback_providers — provider: custom + base_url로 로컬 엔드포인트를 가리킨다 (키 없음). 런타임 창은 Modelfile num_ctx 64000으로 맞춘다.
  3. hermes fallback list — 등록을 확인한다 (실제 호출 테스트는 model_aliases 별칭으로).

진행하시다가 막히는 부분이 생기면 언제든 인프런 Q&A에 질문 남겨주세요.