Hub documentation

llama.cpp를 활용한 로컬 에이전트

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

llama.cpp를 활용한 로컬 에이전트

코딩 에이전트를 로컬에서, 전적으로 자체 하드웨어만으로 실행할 수 있습니다. 여러 오픈소스 에이전트가 로컬 llama.cpp 서버에 연결하여 Claude Code나 Codex와 유사한 경험을 제공하지만, 모든 작업은 사용자의 머신에서 수행됩니다.

작동 방식

설정은 로컬에서 실행되는 두 가지 구성 요소로 이루어져 있습니다:

  1. llama.cpp 서버 — localhost에서 모델을 OpenAI 호환 API로 제공합니다.
  2. 에이전트 — 로컬 서버에 프롬프트를 전송하고, 작업을 추론하며, 작업을 실행합니다.
┌─────────┐     API calls     ┌───────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └───────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

llama.cpp 서버 설정

1. 로컬 하드웨어 설정

로컬 하드웨어를 설정하여 설정과 호환되는 모델을 표시하도록 하세요.

huggingface.co/settings/hardware로 이동하여 로컬 하드웨어 프로필을 설정하세요. 그런 다음 Local Apps 설정에서 llama.cpp를 선택하세요. 이 엔진을 사용할 것이기 때문입니다.

2. 호환 가능한 모델 찾기

Llama와 호환되는 GGUF 모델을 찾아보세요. 선택 후 해당 모델을 하드웨어에 다운로드하세요.

영감이 필요하시다면, Llama 앱은 하드웨어 장치에 맞게 조정된 몇 가지 모델을 제안합니다(3단계 참조).

3. Llama 앱 설치

llama.cpp를 머신에 쉽게 설치할 수 있습니다:

  • Mac 및 Windows: 시스템 트레이에 상주하는 미니멀한 데스크톱 앱인 Llama 앱을 설치합니다. 앱 설치 후, 시스템에 권장되는 선호 모델을 사용하도록 안내된 단계를 따르세요. llama app
  • Linux (or if you only want the command line): 한 줄 설치 명령어:
    curl -LsSf https://llama.app/install.sh | sh

설정을 확인합니다:

llama --version

4. 라우터 시작

데스크톱 앱을 설치했다면 llama serve가 이미 실행 중입니다. localhost:9931에서 모델 목록을 확인하여 이를 검증할 수 있습니다.

아니면 llama serve를 시작합니다. 모델을 전달하면 라우터 모드 대신 단일 모델 모드가 시작됩니다. 라우터 구성에 대한 내용은 llama.cpp 서버 가이드를 참조하세요.

두 가지 옵션이 있습니다:

  • 자동 로딩: 기본적으로 모델은 필요할 때 로드됩니다.
  • 수동 로딩: --no-models-autoload를 추가한 후, 모델을 선택하기 전에 /llama를 사용하여 모델을 로드합니다.

자동 로딩을 사용하려면 다음을 실행하세요:

llama serve

대부분의 경우 기본값이 적절하므로 추가 플래그가 필요하지 않습니다. 고급 사용법에 관심이 있으시다면, 아래에 몇 가지 유용한 플래그 예시를 소개합니다:

  • -ngl all은 모든 레이어를 GPU로 오프로드합니다. 자동 GPU 오프로드를 사용하려면 생략하세요.
  • -c 32768은 토큰 단위의 컨텍스트 크기를 설정합니다. 모델의 전체 컨텍스트 윈도우를 사용하려면 -c 0을 사용하세요. 이 경우 훨씬 더 많은 메모리가 필요할 수 있습니다. 컨텍스트는 병렬 서버 슬롯 간에 공유됩니다.
  • --models-dir ~/models는 사용자 지정 로컬 디렉터리에서 로컬 GGUF 파일을 검색합니다.

위 명령만으로도 충분하지만, llama serve와 함께 사용할 수 있는 일반적인 플래그는 다음과 같습니다:

플래그기능
-ngl all모든 레이어를 GPU로 offload합니다
-c 32768토큰 단위의 컨텍스트 크기를 설정합니다
--models-dir ~/modelsdiscovers local GGUF files from a custom local directory

5. 에이전트 연결

아래 에이전트 중 하나를 선택하고 설정 지침을 따르세요.

Pi

Pi는 OpenClaw의 에이전트로, 이제 Hugging Face에 직접 통합되어 수천 개의 호환 모델을 사용할 수 있습니다.

Pi 설치:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

프로젝트 디렉터리에서 Pi를 시작합니다:

pi

llama.cpp 구성:

/login llama.cpp

/llama를 실행하여 모델을 로드한 다음, /model을 실행하여 현재 세션에 로드된 모델을 선택합니다.

OpenClaw

OpenClaw는 llama.cpp와 함께 로컬에서 작동합니다. 온보드 명령을 통해 모델을 설정할 수 있습니다:

openclaw plugins install @openclaw/llama-cpp-provider
openclaw onboard

OpenClaw용 로컬 메모리 검색

Llama.cpp를 사용하여 에이전트의 메모리 검색에 로컬 임베딩 모델을 실행할 수 있습니다. 이를 위해 node-llama-cpp가 설치되어 있는지 확인하세요.

npm i node-llama-cpp 

메모리 검색을 위해 quantized EmbeddingGemma-300M을 로컬에서 실행하는 예시 스니펫입니다. OpenClaw는 아래 명령어로 모델을 자동으로 다운로드하고 서빙합니다.

openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"

게이트웨이를 다시 시작하고 검증합니다.

openclaw gateway restart
openclaw memory status
# Memory Search (main)
# Provider: local (requested: local)
# Model: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf

Hermes Agent

Hermes Agent는 llama.cpp와 함께 로컬에서 작동합니다. ~/.hermes/config.yaml에 다음을 추가하세요.

custom_providers:
  - name: llama cpp (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1

Hermes Agent를 위한 로컬 메모리 검색

Hermes Agent는 엔드포인트를 통해 시맨틱 검색 모델을 사용합니다. 선호하는 임베딩 모델을 llama.cpp 또는 원하는 추론 엔진으로 8080 엔드포인트에 배포한 후, ~/.hermes/config.yaml에 다음을 추가하세요.

auxiliary:
  session_search:
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "no-key-required"
    model: "local-llama" # your model alias
    timeout: 90
    max_concurrency: 1

none - built-in only가 표시되면 다른 메모리 플러그인이 사용되지 않는다는 의미입니다. 아래 출력은 로컬 서빙이 활성화되어 있음을 보여줍니다.

$ hermes memory status
# Memory status
#────────────────────────────────────────
#  Built-in:  always active
#  Provider:  (none — built-in only)

OpenCode

OpenCode는 llama.cpp와 함께 로컬에서 작동합니다. ~/.config/opencode/opencode.json을 정의합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "gemma-4-26b-4b-it": {
          "name": "Gemma 4 (local)",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

대안: llama-agent

llama-agent은 다른 접근 방식을 취합니다. llama.cpp에 에이전트 루프를 직접 내장하여 외부 의존성이 전혀 없는 단일 바이너리로 구성합니다. Node.js도, Python도 필요하지 않으며 컴파일 후 바로 실행할 수 있습니다:

git clone https://github.com/gary149/llama-agent.git
cd llama-agent

# Build
cmake -B build
cmake --build build --target llama-agent

# Run (downloads the model automatically)
./build/bin/llama-agent -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

도구 호출은 HTTP가 아닌 프로세스 내에서 수행되므로 모델과 에이전트 사이에 네트워크 오버헤드가 없습니다. 또한 서브 에이전트, MCP 서버, HTTP API 서버 모드를 지원합니다.

다음 단계

Update on GitHub