Hub documentation

llama.cpp ile Yerel Ajanlar

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

llama.cpp ile Yerel Ajanlar

Bir kodlama ajanını tamamen kendi donanımınızda, yerel olarak ç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.

Nasıl Çalışır

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

  1. llama.cpp sunucusu — Modeli localhost üzerinde OpenAI ile uyumlu bir API olarak sunar.
  2. Ajanınız — İstemleri yerel sunucuya gönderir, görevler hakkında akıl yürütür ve eylemleri yürütür.
┌─────────┐     API calls     ┌───────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └───────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

llama.cpp sunucusunu yapılandır

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 ile uyumlu GGUF modellerini görüntüleyin. Seçim yapıldıktan sonra modeli donanımınıza indirin.

İlham arıyorsanız, Llama uygulaması donanımınıza uyarlanmış birkaç model önerecektir (Adım 3'e bakın).

3. Llama Uygulamasını yükleyin

llama.cpp'yi makinenize kolayca kurabilirsiniz:

  • Mac ve Windows: sistem tepsinizde yer alan minimalist bir masaüstü uygulaması olan Llama uygulamasını yükleyin Uygulama yüklendikten sonra, sisteminiz için önerilen favori modelinizi kullanmaya başlamak için adımları izleyin. llama app
  • Linux (or if you only want the command line): tek satırlık kurulum komutu:
    curl -LsSf https://llama.app/install.sh | sh

Kurulumu doğrulayın:

llama --version

4. Röter’ı başlatın

Masaüstü uygulamasını yüklediyseniz, llama serve zaten çalışıyor. localhost:9931 adresindeki model listesini görüntüleyerek bunu kontrol edebilirsiniz.

Değilse, llama serve komutunu başlatın. Bir model geçirildiğinde, yönlendirici modu yerine tek model modu başlatılır. Yönlendirici yapılandırması için llama.cpp sunucu kılavuzu'na bakın.

İki seçeneğiniz var:

  • Otomatik yükleme: varsayılan olarak modeller talep üzerine yüklenir.
  • Manuel yükleme: --no-models-autoload ekleyin, ardından modelleri seçmeden önce yüklemek için /llama kullanın.

Otomatik yükleme için yalnızca şunu başlatın:

llama serve

Çoğu durumda, varsayılan değerlerin makul olması nedeniyle ek bayraklara ihtiyacınız yoktur. Gelişmiş kullanım için, ilginizi çekebilecek olası bayraklardan bir örnek aşağıda verilmiştir:

  • -ngl all tüm katmanları GPU'ya taşır. Otomatik GPU taşıma kullanmak için bu parametreyi atlayın.
  • -c 32768, bağlam boyutunu token cinsinden belirler. Modelin tam bağlam penceresi için -c 0 kullanın; bu, önemli ölçüde daha fazla bellek gerektirebilir. Bağlam, paralel sunucu yuvaları arasında paylaşılmaktadır.
  • --models-dir ~/models, özel bir yerel dizinden yerel GGUF dosyalarını bulur.

Yukarıdaki komutun ihtiyacınız olan her şey olması gerekirken, llama serve ile kullanabileceğiniz bazı yaygın bayraklar şunlardır:

BayrakNe işe yarar
-ngl alltüm katmanları GPU'ya taşır
-c 32768token cinsinden bağlam boyutunu ayarlar
--models-dir ~/modelsözel bir yerel dizinden yerel GGUF dosyalarını keşfeder

5. 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

Proje dizininizde Pi'yi başlatın:

pi

llama.cpp yapılandırması:

/login llama.cpp

/llama komutunu çalıştırarak bir model yükleyin, ardından /model komutuyla yüklenen modeli mevcut oturum için seçin.

OpenClaw

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

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

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. ~/.hermes/config.yaml dosyasına aşağıdakileri ekleyin.

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

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
          }
        }
      }
    }
  }
}

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

Update on GitHub