Hub documentation

llama.cpp ile Yerel Ajanlar

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

llama.cpp ile Yerel Ajanlar

Kodlama ajanını tamamen kendi donanımınızda çalıştırabilirsiniz. Birkaç açık kaynaklı ajan, size Claude Code veya Codex'e benzer bir deneyim sunmak için yerel bir llama.cpp sunucusuna bağlanabilir — ancak her şey makinenizde çalışır.

Başlangıç

1. Yerel Donanımınızı Ayarlayın

Yerel donanımınızı yapılandırın; böylece kurulumunuzla uyumlu modelleri görebilirsiniz.

huggingface.co/settings/hardware adresine gidin ve yerel donanım profilinizi yapılandırın. Ardından, kullanacağınız motor bu olacağı için Yerel Uygulamalar ayarlarınızda llama.cpp seçeneğini seçin.

2. Uygun Bir Model Bulun

Llama.cpp ile uyumlu modelleri görüntüleyin.

3. llama.cpp Sunucusunu Başlatın

Model sayfasında “Bu modeli kullan” düğmesine tıklayın ve llama.cpp seçeneğini işaretleyin. Kurulumunuza uygun tam komutlar gösterilir. İlk adım, bir llama.cpp sunucusu başlatmaktır, örneğin

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

Bu, modeli indirir ve makinenizde OpenAI ile uyumlu bir API sunucusu başlatır. Kurulum talimatları için llama.cpp kılavuzuna bakın.

4. Ajanınızı Bağlayın

Aşağıdaki ajanlardan birini seçin ve kurulum talimatlarını izleyin.

Pi

Pi, OpenClaw'ın arkasındaki ajan ve artık Hugging Face'e doğrudan entegre edilmiş durumda; bu sayede binlerce uyumlu modele erişim imkânı sunuyor.

Pi'yi yükleyin:

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

Ardından yerel modelinizi ~/.pi/agent/models.json konumundaki Pi yapılandırma dosyasına ekleyin:

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

Proje dizininizde Pi'yi başlatın:

pi

Pi, yerel llama.cpp sunucunuza bağlanır ve size etkileşimli bir ajan oturumu sağlar.

Demo

Görüntü desteğini etkinleştirme

Görüntü yeteneğine sahip modeller için ~/.pi/agent/models.json dosyasındaki model girdisine "input": ["text", "image"] ekleyin:

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

Pi ile uyumlu görsel-dil modellerini görüntüleyin.

OpenClaw

OpenClaw, llama.cpp ile yerel olarak çalışır. Modelinizi yerleşik komutla ayarlayabilirsiniz:

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

Ayrıca openclaw onboard komutunu etkileşimli olarak çalıştırıp custom-compatibility seçeneğini openai ile seçerek aynı yapılandırmayı iletebilirsiniz.

OpenClaw için Yerel Bellek Araması

Ajanınızın bellek araması için yerel gömme modellerini Llama.cpp ile çalıştırabilirsiniz. Bunu yapmak için node-llama-cpp'ın kurulu olduğundan emin olun.

npm i node-llama-cpp

Yerel bellek araması için quantized EmbeddingGemma-300M çalıştırmak için örnek bir kod parçası aşağıdadır. OpenClaw, aşağıdaki komutla modeli otomatik olarak indirir ve sunar.

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"

Gateway'yi yeniden başlatın ve doğrulayın.

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 Ajan

Hermes Agent, llama.cpp ile yerel olarak çalışır. Varsayılan yapılandırmayı şu şekilde tanımlayın:

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

### Hermes Ajanı için Yerel Bellek Araması

Hermes Agent, anlamsal arama modellerini uç noktalar üzerinden kullanır. Tercih ettiğiniz gömme modelini 8080 numaralı uç noktada llama.cpp veya tercih ettiğiniz çıkarım motoruyla çalıştırdıktan sonra, aşağıdakileri ~/.hermes/config.yaml dosyasına ekleyin.

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

Bunun çalıştığını kontrol edin, none - built-in only başka bir bellek eklentisinin kullanılmadığını gösterir. Aşağıdaki çıktı, yerel sunumun aktif olduğunu gösterir.

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

OpenCode

OpenCode, llama.cpp ile yerel olarak çalışır. ~/.config/opencode/opencode.json tanımlayın:

{
  "$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
          }
        }
      }
    }
  }
}

Nasıl Çalışır

Kurulum, yerel olarak çalışan iki bileşenden oluşur:

llama.cpp sunucusu — Modeli localhost üzerinde OpenAI ile uyumlu bir API olarak sunar.
Ajanınız — Yerel sunucuya istemler gönderen, görevler hakkında akıl yürüten ve eylemleri yürüten ajan süreci.

┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

Alternatif: llama-agent

llama-agent farklı bir yaklaşım benimser — ajan döngüsünü llama.cpp içine, harici bağımlılığı sıfır olan tek bir ikili dosya olarak doğrudan yerleştirir. Node.js yok, Python yok, derleyip çalıştırmanız yeterli:

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

Araç çağrıları HTTP üzerinden değil, süreç içi gerçekleştiği için model ile ajan arasında ağ gecikmesi yoktur. Ayrıca alt ajanları, MCP sunucularını ve bir HTTP API sunucu modunu destekler.

Sonraki Adımlar

Yapay Zeka Modellerini Yerel Olarak Kullanın — Modelleri kendi makinenizde çalıştırma hakkında daha fazla bilgi edinin
llama.cpp Kılavuzu — Detaylı llama.cpp kurulumu ve kullanımı
Hub'daki Ajanlar — Ajanları Hugging Face ekosistemine bağlayın

Update on GitHub

←HF SDK ile ajan oluşturma Ajan Kütüphaneleri→