Hermes에서 9Router를 붙여 쓰는 방법

개요

본 포스트는 9Router를 Hermes 앞단에 두고, 모델 라우팅과 토큰 절약, fallback 구성을 한곳에서 관리하는 과정을 설명합니다. 앞선 포스트에서 설치한 Hermes가 준비되어 있어야 합니다.

9Router는 OpenAI 호환 API 형태로 동작하는 사설 라우터입니다. Hermes는 https://router.example.com/v1 같은 주소 하나만 바라보고, 실제 모델 선택과 fallback, quota 관리는 9Router 쪽에서 처리하게 만들 수 있습니다.

전체 구성 흐름

사용자 → Hermes: 작업 요청.

Hermes → 9Router: OpenAI 호환 형식으로 요청 전송.

9Router → 모델 공급자: 요청된 모델 이름을 보고 뒤쪽 공급자로 분기. RTK Token Saver, fallback, quota tracking을 이 계층에서 처리.

mem0 → 9Router: 같은 주소를 공유하여 Hermes 본체와 메모리 서버의 모델 설정을 한곳에서 관리.

실제 사용 화면

아래 화면은 실제 운영 구성을 블로그용으로 마스킹한 예시입니다. 실제 도메인, API 키, 저장소 경로는 넣지 않고 router.example.com, <API_KEY>, <NFS_PATH> 같은 값으로 바꿨습니다.

실제 문제 상황

Hermes를 오래 쓰다 보면 설정이 먼저 복잡해집니다. 메인 모델은 한 공급자를 보고, approval이나 compression 같은 보조 슬롯은 예전 provider를 그대로 보고, mem0는 또 다른 주소를 보는 식입니다. 이 상태에서는 어느 쪽 quota가 먼저 닳았는지, fallback이 어디서 끊겼는지 확인하는 데 시간이 더 들어갑니다.

여기에 tool result가 긴 작업이 겹치면 입력 토큰도 빠르게 늘어납니다. 제 경우 실제로 자주 막힌 지점은 Hermes 자체가 아니라 모델 이름 불일치와 공급자 분산이었습니다.

1. 9Router를 쓰는 이유

9Router를 앞단에 두면 위 문제를 라우터 계층에서 한 번에 처리합니다. 핵심 장점은 아래 4가지입니다.

• RTK Token Saver: 파일 목록, 검색 결과, git diff, 테스트 로그 같은 긴 tool result를 압축해서 전달. 반복 작업에서 입력 토큰 낭비를 줄임.
• Fallback: 특정 모델의 구독 한도 소진이나 API 지연 시 다른 모델로 전환. Hermes 설정을 바꾸지 않고 라우터에서 순서만 조정.
• Quota tracking: 모델별 사용량과 공급자를 한 화면에서 확인. 어떤 모델을 언제 쓸지 판단하는 근거.
• 중앙 관리: Hermes, mem0, Codex, Cursor 계열 도구가 같은 base URL 하나만 참조. 뒤쪽 모델 분기는 전부 9Router가 담당.

2. 적용 대상

다음 경우에 특히 잘 맞습니다.

• Hermes에서 메인 모델과 보조 모델을 나눠 쓰고 싶을 때
• tool output이 길어서 토큰 사용량이 빨리 늘어날 때
• 모델 하나의 장애나 quota 소진 때문에 작업이 끊기는 일을 줄이고 싶을 때
• mem0, CLI 도구, 에이전트가 같은 모델 라우터를 공유하게 만들고 싶을 때
• 실제 공급자 주소와 키를 각 도구에 흩뿌리고 싶지 않을 때

반대로 모델 하나만 단순하게 쓰고 fallback이나 quota 관리가 필요 없다면, Hermes에서 모델을 직접 지정하는 구성이 더 단순합니다.

3. 설치 전 준비 사항

Kubernetes 기준으로 아래 항목을 준비합니다.

• Kubernetes 클러스터
• ArgoCD 또는 kubectl 배포 환경
• Traefik Ingress Controller
• cert-manager와 TLS issuer
• PVC를 붙일 저장소
• 9Router가 사용할 API key
• 외부 도메인. 예: router.example.com

실도메인, 실서버 주소, API 키는 문서나 블로그에 그대로 쓰지 않습니다. 문서에는 예제 도메인만 쓰고 실제 값은 Secret에만 둡니다.

4. Kubernetes에 올리는 방법

Kubernetes 배포는 크게 네 조각입니다.

• Deployment: 9Router 컨테이너 실행
• Service: 내부 포트 20128 노출
• Ingress: router.example.com을 Service로 연결
• PVC: /app/data 데이터 저장 경로 유지

보조 프록시를 같이 쓰려면 Headroom도 별도 Deployment와 Service로 띄웁니다. 9Router 환경값에는 HEADROOM_URL=http://headroom:8787처럼 넣어주시면 됩니다.

운영 시 확인할 값은 아래와 같습니다.

• Service port: 20128
• Ingress host: router.example.com
• TLS secret: 예: nine-router-tls
• PVC mount path: /app/data
• API key: Kubernetes Secret 또는 외부 secret store에서 주입

5. 먼저 API 호출로 확인하기

9Router는 OpenAI 호환 API처럼 호출합니다. Hermes에 붙이기 전에 /v1/models부터 확인합니다.

curl https://router.example.com/v1/models -H "Authorization: Bearer <API_KEY>"

응답에 Codex, Approval, Mini 같은 등록 모델 이름이 내려오면 인증과 라우터 연결은 정상입니다.

대화 호출은 아래 형식으로 보냅니다. 모델 이름은 9Router에 등록한 이름과 정확히 맞춰야 합니다.

curl https://router.example.com/v1/chat/completions -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" -d '{"model": "Codex", "messages": [{"role": "user", "content": "hello"}]}'

6. Hermes에 붙이는 방법

Hermes에서는 ~/.hermes/config.yaml에 custom provider를 등록합니다.

핵심 값은 아래와 같습니다.

• provider: custom
• base_url: https://router.example.com/v1
• api_key: 9Router API 키 또는 환경 변수
• 기본 모델: 예: Codex
• fallback 모델: 예: Mini
• provider 이름: 예: nine-router

보조 기능도 같은 주소를 보게 만들 수 있습니다. approval은 Approval, compression은 Mini, title generation은 Mini처럼 역할별로 나눠주시면 됩니다. 이후 모델 구성 변경은 Hermes 설정을 건드리지 않고 9Router 쪽에서만 처리하면 됩니다.

7. mem0와 같이 쓰는 방법

mem0도 OpenAI 호환 API를 쓸 수 있으므로 9Router를 같이 붙일 수 있습니다.

mem0 설정에서 바꿀 값은 아래와 같습니다.

• OPENAI_BASE_URL: https://router.example.com/v1
• OPENAI_API_KEY: 9Router API 키
• 기본 LLM 모델: 예: Approval
• 임베딩 모델: 별도 지정

이렇게 하면 Hermes 본체와 mem0가 같은 라우터 계층을 공유하고, 모델 공급자 설정이 여러 군데로 흩어지지 않습니다.

8. 설치 후 확인

아래 순서로 확인합니다.

• https://router.example.com/v1/models 응답 확인
• 모델 목록에 Hermes에서 쓸 이름이 있는지 확인
• chat completions 호출 성공 확인
• Hermes 새 세션에서 실제 작업 실행
• approval, compression, title generation 보조 슬롯의 모델 확인

다섯 가지가 모두 통과하면 정상적으로 연동된 것입니다.

주요 오류 및 해결 방안

404: Ingress가 Service로 연결되지 않은 경우입니다. host, service name, service port를 확인합니다.

401 또는 403: API key 문제입니다. 실제 키는 환경 변수나 Secret으로 관리합니다.

모델 없음 오류: 제 경우 이 오류가 가장 잦았는데, 대부분 Hermes 쪽 문제가 아니라 Hermes 설정에 적은 Codex, Approval, Mini 이름이 9Router에 등록된 이름과 대소문자까지 일치하지 않은 경우였습니다. 라우터 모델 목록부터 비교하면 빠르게 해결됩니다.

토큰 절약 효과가 없음: tool output이 짧은 작업에서는 차이가 잘 안 보입니다. 긴 tool result가 많은 작업일수록 효과가 커집니다.

보조 슬롯이 예전 provider를 봄: 설정 변경 후 메인 모델만 9Router를 보고 approval, compression은 이전 provider를 보는 경우가 있습니다. 메인 모델, fallback 모델, approval, compression을 같이 확인합니다.