Hugging Face's logo

Hub documentation

Agen Lokal dengan llama.cpp

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Agen Lokal dengan llama.cpp

Anda dapat menjalankan agen coding sepenuhnya di perangkat keras Anda sendiri. Beberapa agen open-source dapat terhubung ke server llama.cpp lokal untuk memberikan pengalaman serupa dengan Claude Code atau Codex — tetapi semuanya berjalan di mesin Anda.

Memulai

1. Atur Perangkat Keras Lokal Anda

Atur perangkat keras lokal Anda agar dapat menampilkan model mana yang kompatibel dengan konfigurasi Anda.

Buka huggingface.co/settings/hardware dan atur profil perangkat keras lokal Anda. Kemudian pilih llama.cpp di pengaturan Local Apps Anda, karena ini akan menjadi mesin yang Anda gunakan.

2. Temukan Model yang Kompatibel

Jelajahi model yang kompatibel dengan Llama.cpp.

3. Jalankan Server llama.cpp

Di halaman model, klik tombol “Use this model” dan pilih llama.cpp. Anda akan ditampilkan perintah yang tepat untuk konfigurasi Anda. Langkah pertama adalah memulai server llama.cpp, misalnya

llama-server -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

Ini mengunduh model dan memulai server API yang kompatibel dengan OpenAI di mesin Anda. Lihat panduan llama.cpp untuk instruksi pemasangan.

4. Hubungkan Agen Anda

Pilih salah satu agen di bawah ini dan ikuti instruksi pengaturannya.

Pi

Pi adalah agen di balik OpenClaw dan kini terintegrasi langsung ke Hugging Face, memberikan Anda akses ke ribuan model yang kompatibel.

Instal Pi:

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

Lalu tambahkan model lokal Anda ke file konfigurasi Pi di ~/.pi/agent/models.json:

{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ggml-org-gemma-4-26b-4b-gguf"
        }
      ]
    }
  }
}

Mulai Pi di direktori proyek Anda:

pi

Pi terhubung ke server llama.cpp lokal Anda dan memberikan sesi agen interaktif.

Demo

Mengaktifkan dukungan visi

Untuk model yang mendukung visi, tambahkan "input": ["text", "image"] ke entri model di ~/.pi/agent/models.json:

"models": [
  {
    "id": "unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_XL",
    "input": ["text", "image"]
  }
]

Jelajahi model vision-language yang kompatibel dengan Pi.

OpenClaw

OpenClaw berjalan secara lokal dengan llama.cpp. Anda dapat mengatur model Anda melalui perintah bawaan:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "ggml-org-gemma-4-26b-a4b-gguf" \
  --custom-api-key "llama.cpp" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --accept-risk

Anda juga dapat menjalankan openclaw onboard secara interaktif, memilih custom-compatibility dengan openai, dan meneruskan konfigurasi yang sama.

Pencarian Memori Lokal untuk OpenClaw

Anda dapat menjalankan model embedding lokal dengan Llama.cpp untuk pencarian memori agen Anda. Untuk melakukannya, pastikan Anda memiliki node-llama-cpp.

npm i node-llama-cpp

Berikut adalah contoh potongan kode untuk menjalankan EmbeddingGemma-300M terkuantisasi secara lokal untuk pencarian memori. OpenClaw secara otomatis mengunduh dan menyajikan model dengan perintah di bawah ini.

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"

Mulai ulang gateway dan validasi.

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 berjalan secara lokal dengan llama.cpp. Definisikan konfigurasi default sebagai:

model:
  provider: custom
  default: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
  base_url: http://127.0.0.1:8080/v1
  api_key: llama.cpp

custom_providers:
  - name: Local (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
    api_key: llama.cpp
    model: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M

### Pencarian Memori Lokal untuk Hermes Agent

Hermes Agent mengonsumsi model pencarian semantik melalui endpoint. Setelah model embedding pilihan Anda berjalan di endpoint 8080 dengan llama.cpp atau mesin inferensi pilihan Anda, tambahkan berikut ke ~/.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

Periksa apakah ini berfungsi, none - built-in only menunjukkan bahwa tidak ada plug-in memori lain yang digunakan. Output di bawah ini menunjukkan bahwa penyajian lokal aktif.

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

OpenCode

OpenCode berjalan secara lokal dengan llama.cpp. Definisikan ~/.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
          }
        }
      }
    }
  }
}

Cara Kerjanya

Setup ini memiliki dua komponen yang berjalan secara lokal:

  1. llama.cpp server — Menyajikan model sebagai API yang kompatibel dengan OpenAI di localhost.
  2. Ag Anda — Proses agen yang mengirim prompt ke server lokal, melakukan penalaran tentang tugas, dan mengeksekusi aksi.
┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

Alternatif: llama-agent

llama-agent mengambil pendekatan yang berbeda — ia membangun loop agen langsung ke dalam llama.cpp sebagai satu binary dengan nol dependensi eksternal. Tidak ada Node.js, tidak ada Python, cukup compile dan jalankan:

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

Karena pemanggilan alat terjadi dalam proses (in-process) dan bukan melalui HTTP, tidak ada overhead jaringan antara model dan agen. Ia juga mendukung subagen, server MCP, dan mode server API HTTP.

Langkah Selanjutnya

Update on GitHub

←Membangun agen dengan HF SDK Perpustakaan Agen→