Run Hermes Fully Locally with QVAC | Agent Lab Journal

  AL
  Agent Lab Journal

...

LOCAL AI AGENTS · PRACTICAL DEPLOYMENT

QVAC를 사용하여 Hermes를 완전히 로컬에서 실행하기

      Level: advanced (고급)
      Reading time: 45 minutes (읽기 시간: 45분)
      Result: local Hermes + QVAC + offline verification (결과: 로컬 Hermes + QVAC + 오프라인 검증)

이 가이드를 마칠 때쯤이면, 여러분은 추론 요청을 오직 자신의 기기에서 실행되는 모델로만 보내고, 세션 간 메모리를 보존하며, 제한된 로컬 도구 세트를 호출하고, 인터넷 연결이 차단된 상태에서도 반복 가능한 작업을 완료하는 개인용 Hermes Agent를 갖게 될 것입니다. 운영 중에 클라우드 API 키는 필요하지 않지만, 사전에 소프트웨어와 모델 파일을 다운로드해야 합니다.

우리가 구축하는 시스템

Hermes Agent는 언어 모델 (Language Model) 주변의 에이전트 계층입니다. 이는 대화, 상태 (State), 메모리 (Memory), 기술 (Skills), 도구 설명 (Tool descriptions), 그리고 모델 요청을 실제 행동으로 연결하는 루프 (Loop)를 관리합니다. QVAC는 모델을 로컬에서 실행하고 이를 OpenAI 호환 HTTP 인터페이스를 통해 노출하는 역할을 담당합니다.

User (사용자)
  │
  ▼
...

각 역할은 분리되어 있어야 합니다. 거대 언어 모델 (Large Language Model)은 응답을 생성하거나 함수를 요청합니다. Hermes는 에이전트 루프, 메모리, 권한 및 함수 실행을 제어합니다. QVAC는 모델 가중치 (Model weights)를 로드하고, 모델의 채팅 템플릿 (Chat template)을 적용하며, 로컬 추론 (Local inference)을 수행합니다.

이 가이드에서 "완전히 로컬 (Fully local)"은 정확하고 제한적인 의미를 갖습니다:

• Hermes와 QVAC는 하나의 컴퓨터 또는 격리된 로컬 환경 내에서 실행됩니다.
• 모델 요청은 오직 127.0.0.1로만 전송됩니다.
• 세션, 메모리, 기술, 설정 및 로그는 로컬 저장소에 유지됩니다.
• 수락 테스트 (Acceptance test)에 사용되는 도구들은 외부 서비스를 필요로 하지 않습니다.
• 종속성 (Dependencies)과 가중치를 다운로드한 후에는 인터넷 접속 없이도 시나리오가 통과됩니다.

로컬 모델이 자동으로 보안 시스템을 구축하는 것은 아닙니다. 도구는 여전히 명령을 실행하거나, 관련 없는 파일을 읽거나, 외부 주소로 접속할 수 있습니다. 오프라인 작동은 공격 표면 (Attack surface)의 한 부분을 줄여주지만, 운영 체제 권한 (Operating-system permissions), 경로 검증 (Path validation), 또는 승인 제어 (Approval controls)를 대체하지는 않습니다.

구체적인 사례: 개인적인 결정 저널

단순한 인사는 에이전트가 제대로 작동하는지 증명하기에는 너무 약합니다. 따라서 우리의 수락 사례 (Acceptance case)는 작은 프로젝트 디렉토리를 사용하며 네 가지 독립적인 계층을 테스트합니다: 생성 (Generation), 도구 호출 (Tool calling), 지속성 메모리 (Durable memory), 그리고 필수적인 클라우드 경로의 부재입니다.

Hermes는 다음을 수행해야 합니다:

• 로컬 회의록 읽기;
• 프로젝트, 결정 사항, 그리고 다음 작업 추출하기;
• 허용된 출력 디렉토리 내에 Markdown 요약 작성하기;
• 무해한 서식 선호도 기억하기;
• 새로운 세션에서 해당 선호도 복구하기;
• 외부 네트워킹이 비활성화된 후 새로운 파일 작업 반복하기.

전용 실험실 디렉토리를 생성하세요. 홈 디렉토리, 자격 증명 (Credentials)이 포함된 리포지토리, 또는 클라우드 동기화 폴더에서 시작하지 마십시오.

mkdir -p "$PWD/hermes-local-lab/inbox"
mkdir -p "$PWD/hermes-local-lab/outbox"

...

이 터미널을 열어두거나 LAB_DIR의 절대값을 기록하세요. 에이전트 프롬프트 (Agent prompts)는 불확실한 작업 디렉토리 (Working directory)에 의존하기보다 절대 경로를 사용해야 합니다.

전제 조건 및 버전 준수

Unix 계열 환경, QVAC를 위한 Node.js 및 npm, 설치할 Hermes 릴리스가 지원하는 Python 환경, Git, curl, 그리고 선택한 모델을 위한 충분한 디스크 공간이 필요합니다. Windows의 경우, 현재 릴리스에서 다른 지원 경로를 명시적으로 문서화하지 않는 한 WSL2를 사용하십시오.

기기를 변경하기 전에 소프트웨어와 사용 가능한 리소스를 기록하세요:

uname -a
node --version
npm --version
...

CLI 플래그(flags), 모델 식별자(model identifiers), 그리고 설정 형식(configuration formats)은 릴리스 간에 변경될 수 있습니다. 아래의 모든 명령어를 설치된 버전에 대한 설정으로 취급해야 하며, 내장된 도움말(--help)을 무시해도 된다는 허가로 간주해서는 안 됩니다. 만약 플래그가 거부된다면, 대체 명령어를 추측하는 대신 중단하고 --help를 통해 확인하십시오.

QVAC를 설치한 후에는 진단 도구를 사용하여 사용 가능한 컴퓨팅 백엔드(compute backend)를 식별하십시오:

qvac doctor

지원되는 GPU 백엔드는 지연 시간(latency)을 줄일 수 있는 반면, CPU 실행은 작은 모델의 경우 여전히 적절할 수 있습니다. 실제 결과는 기기, 모델 빌드, 컨텍스트 길이(context length), 그리고 런타임 버전(runtime version)에 따라 달라집니다. 이 문서는 보편적인 속도나 메모리 측정치를 주장하지 않습니다.

품질을 최적화하기 전에 적합한 모델을 선택하십시오

4비트 양자화 (4-bit quantization)를 사용하는 모델 변형으로 시작하십시오. 양자화 (Quantization)는 가중치 (weights)의 저장 공간과 메모리 비용을 줄여주지만, 런타임 버퍼 (runtime buffers)나 컨텍스트 캐시 (context cache)에 의해 소비되는 메모리를 제거하지는 않습니다.

설치된 릴리스에서 사용 가능한 QVAC 모델 레지스트리 (model registry)가 신뢰할 수 있는 정보원 (source of truth)입니다. 모델 식별자를 설정에 복사하기 전에 해당 레지스트리를 나열하거나 검사하십시오. 만약 다음 식별자들이 귀하의 릴리스에 존재하지 않는다면, 그에 상응하는 지원되는 지시 모델 (instruct model)을 선택하고 정확한 식별자를 사용하십시오.

          배포 프로필 (Deployment profile)
          예시 모델 클래스 (Example model class)
          용도 (Use)
...

전문가 혼합 (Mixture-of-experts, MoE) 모델은 각 토큰(token)에 대해 전문가 네트워크의 일부만 활성화하지만, 가중치와 작업 데이터는 여전히 런타임의 메모리 전략에 맞게 배치되어야 합니다. 운영 체제 (operating system), Hermes, 컨텍스트 (context), 그리고 KV 캐시 (KV cache)를 위한 용량을 남겨두십시오.

가장 작은 모델은 경로를 검증하는 데 유용하지만, 잘못된 함수 인자 (function arguments)를 출력하거나 단계를 건너뛸 수 있습니다. 더 큰 모델은 에이전트 (agent) 동작을 개선할 수 있지만, 어떤 모델 크기도 올바른 도구 사용 (tool use)을 보장하지는 않습니다. 먼저 여유롭게 실행 가능한 모델로 전체 테스트를 완료하십시오. 인프라가 안정된 후에만 대안들을 비교하십시오.

1단계: QVAC CLI 설치

이 단계에서는 패키지를 가져오고, 나중에 모델 가중치 (model weights)를 가져오기 위해 인터넷 접속이 필요합니다.

npm install -g @qvac/cli

command -v qvac
...

만약 전역 npm 설치 시 관리자 권한을 요구한다면, 검토되지 않은 프로세스를 sudo로 파이핑(piping)하여 해결하지 마십시오. 사용자 소유의 npm 접두사 (prefix)를 구성하거나 관리되는 Node.js 설치 환경을 사용하십시오. 발견된 qvac 바이너리가 의도한 설치 항목에 속하는지 확인하십시오.

별도의 QVAC 프로젝트 디렉토리를 생성합니다:

mkdir -p "$PWD/qvac-hermes"
cd "$PWD/qvac-hermes"
pwd

2단계: 모델 선언 및 함수 (functions) 활성화

HTTP 서버는 serve.models 아래에 선언된 모델들을 로드합니다. 객체 키 (object key)는 클라이언트에게 보이는 모델 이름이 됩니다. 안정적인 별칭 (alias)을 사용하면 Hermes를 기반이 되는 레지스트리 식별자 (registry identifier)로부터 독립적으로 유지할 수 있습니다.

현재 디렉토리에 qvac.config.json을 생성합니다:

{
  "serve": {
    "models": {
...

더 작은 모델을 사용하려면, 모델 값만 설치된 QVAC 레지스트리에서 확인된 식별자로 변경하십시오. 예를 들어:

"QWEN3_5_4B_MULTIMODAL_Q4_K_M"

또는:

"QWEN3_5_9B_MULTIMODAL_Q4_K_M"

ctx_size는 런타임이 유지하려고 시도하는 최대 컨텍스트 (context)입니다. Hermes는 사용자의 작업이 시작되기 전에 대규모 시스템 지침 (system instruction)과 여러 도구 스키마 (tool schemas)를 보낼 수 있습니다. 컨텍스트가 작으면 조기에 오버플로 (overflow)가 발생할 수 있는 반면, 토큰 제한이 크면 KV-캐시 (KV-cache) 메모리가 증가합니다.

65,536 토큰이 수용되지 않는다면, 값을 낮추고, 더 적은 수의 도구를 노출하며, 동일한 유효 제한값으로 Hermes를 구성하십시오. QVAC가 실제로 제공할 수 있는 것보다 더 큰 컨텍스트를 Hermes에 광고하지 마십시오.

tools 옵션은 선택된 모델에 대한 함수 처리 (function handling)를 활성화합니다. 이 옵션이 없으면, 일반적인 채팅은 성공할 수 있지만 에이전트가 구조화된 호출 (structured call) 대신 산문 (prose)을 반환할 수 있습니다.

3단계: OpenAI 호환 서버 시작

다른 장치들이 LAN을 통해 포트에 접근할 수 없도록 QVAC를 루프백 인터페이스 (loopback interface)에 바인딩하십시오.

cd /absolute/path/to/qvac-hermes

qvac serve openai \
...

이 프로세스를 전용 터미널에서 계속 실행하십시오. 처음 시작할 때는 메모리에 로드하기 전에 가중치 (weights)를 다운로드할 수 있습니다. 서버 초기화가 완료될 때까지 기다리십시오.

다른 터미널에서 모델 엔드포인트 (endpoint)를 점검하십시오:

curl --fail --silent --show-error \
  http://127.0.0.1:11434/v1/models

반환된 JSON에는 클라이언트용 식별자인 hermes-local이 포함되어 있어야 합니다. 빈 리스트는 보통 모델이 준비되지 않았음을 의미합니다. 404 오류는 경로 (route), 설정 (configuration), 또는 CLI 버전 불일치를 나타냅니다.

이제 최소한의 완성 (completion) 요청을 보냅니다:

curl --fail --silent --show-error \
  http://127.0.0.1:11434/v1/chat/completions \
  -H 'Content-Type: application/json' \
...

구두점이나 대소문자보다는 응답 구조를 검증하십시오. 응답은 반드시 어시스턴트 (assistant) 메시지가 포함된 choices 배열을 포함해야 합니다. HTTP는 성공했지만 내용이 비어 있다면, 상세한 QVAC 로그를 점검하여 선택된 레지스트리 (registry) 항목이 채팅이 가능한 인스트럭트 (instruct) 모델인지 확인하십시오.

단계 4: Hermes를 설치하기 전에 함수 출력 테스트하기

이 테스트는 QVAC 및 모델의 동작을 에이전트 런타임 (agent runtime)과 분리합니다. 설명된 함수는 아무런 동작도 수행하지 않으며, 요청은 모델에게 구조화된 의도 (intention)를 반환하도록 요구할 뿐입니다.

curl --fail --silent --show-error \
  http://127.0.0.1:11434/v1/chat/completions \
  -H 'Content-Type: application/json' \
...

성공적인 결과는 주장된 바이트 수 (byte count)가 아닙니다. 그것은 message.tool_calls 내의 항목으로서, 함수 이름이 get_file_size이고 인자 (arguments) 값이 요청된 경로를 포함하는 유효한 JSON이어야 합니다.

다음의 경우 테스트를 실패로 간주합니다:

• 모델이 함수를 호출하겠다고 말하지만 tool_calls를 반환하지 않는 경우;

• 함수 이름이 변경된 경우;

• 인자 (arguments)를 JSON으로 파싱할 수 없는 경우;

• 모델이 파일 크기를 임의로 만들어내는 경우;

• 요청된 경로가 다른 경로로 대체된 경우.

이 경계(boundary)가 정상적으로 작동할 때까지 Hermes를 설치하거나 디버깅하지 마십시오. "tools": true가 활성화되어 있는지 확인하고, 설정 변경 후에는 QVAC를 재시작하며, 필요한 경우 더 성능이 뛰어난 모델로 테스트하십시오. 채팅이 성공적으로 완료되었다고 해서 함수 호출 (function calling)이 성공했다는 증거는 아닙니다.

단계 5: Hermes Agent 설치

원격 설치 스크립트를 실행하기 전에 반드시 검토하십시오. 주의가 필요한 일반적인 순서는 다음과 같습니다:

curl --fail --silent --show-error \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \
  -o /tmp/hermes-install.sh
...

사용자의 환경이 원격 설치 스크립트를 금지하는 경우, 선택한 릴리스 (release)에 대한 수동 설치 절차를 따르십시오. 시스템 Python 패키지를 관련 없는 가상 환경 (virtual environments)과 혼용하지 마십시오.

설치 프로그램이 PATH를 변경했다면 새 터미널을 열고, 다음 명령어로 확인하십시오:

command -v hermes
hermes --help

Hermes는 일반적으로 ~/.hermes/ 아래에 사용자 상태 (user state)를 저장합니다. 해당 디렉토리에는 세션 (sessions), 메모리 (memory), 기술 (skills), 로그 (logs) 및 제공자 설정 (provider configuration)이 포함될 수 있습니다. 이를 공개하거나 Git에 커밋하지 마십시오.

find "$HOME/.hermes" -maxdepth 2 -type d -print 2>/dev/null

단계 6: Hermes를 QVAC에 연결하기

Hermes의 대화형 모델 설정 (interactive model configuration)을 사용하여 설치된 릴리스가 자체적으로 지원하는 구성 구조를 작성하도록 합니다:

hermes model

사용자 정의 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)를 선택하고 다음을 입력하십시오:

API base URL: http://127.0.0.1:11434/v1
API key: local-qvac
Model name: hermes-local
...

QVAC가 API 키 요구 사항 없이 시작된 경우, local-qvac는 단지 값을 요구하는 클라이언트를 위한 비어 있지 않은 로컬 플레이스홀더 (placeholder)일 뿐입니다. 이는 클라우드 자격 증명 (cloud credential)이 아니며 실제 계정에서 복사해서는 안 됩니다.

해당 구성은 개념적으로 다음과 동일합니다:

model:
  default: hermes-local
  provider: custom
...

정확한 YAML 구조는 변경될 수 있습니다. 이 짧은 예시로 Hermes 구성 전체를 교체하지 마십시오. 기존 파일에는 메모리 (memory), 채널 (channel) 및 기술 (skill) 설정이 포함되어 있을 수 있습니다.

자격 증명 (credential) 필드를 출력하지 않고 저장된 경로를 확인합니다:

grep -nE 'provider:|base_url:|default:' \\
  "$HOME/.hermes/config.yaml"

기본 URL (base URL)은 http://127.0.0.1:11434/v1로 시작해야 하며, 활성 모델 설정 (active model configuration)에 클라우드 제공업체 (cloud provider) 도메인이 나타나지 않아야 합니다.

7단계: 위험한 도구 없이 첫 실행 수행

hermes

생성 전용 (generation-only) 요청으로 시작합니다:

설정된 모델 이름 (model name)과 기본 URL (base URL)을 말해줘.
도구를 사용하지 말고 네트워크에 접속하지 마.

모델의 답변은 권위가 없습니다. 프롬프트 텍스트를 반복하거나 설정을 환각 (hallucinate) 할 수 있습니다. 신뢰할 수 있는 정보원 (sources of truth)은 Hermes 설정 (configuration), QVAC 요청 로그 (request logs), 그리고 네트워크 관찰 (network observation)입니다.

다음으로, 명시적인 작업 경계 (working boundary)를 설정합니다:

작업 디렉토리 (Working directory): /absolute/path/hermes-local-lab
당신은 inbox에서만 읽을 수 있습니다.
당신은 outbox에만 쓸 수 있습니다.
...

만약 에이전트 (agent)가 즉시 파일을 변경한다면, 중단하십시오. 프롬프트는 모델의 행동에 영향을 미치지만 격리 경계 (isolation boundary)를 생성하지는 않습니다. 파일 권한 (file permissions) 및 도구 수준의 검증 (tool-level validation)이 동일한 정책을 강제해야 합니다.

8단계: 파일 도구 제한